nithinmanoj10/CatanSynth-Meridian-v1-50K

CatanSynth Meridian v1 (50k)

50,000 procedurally-generated synthetic images of Settlers of Catan boards, labeled for YOLO pose/keypoint estimation of the hexagonal terrain tiles. Generated by the `catan-in-silico` synthetic data engine, which composites terrain/token/road/settlement/city/robber assets over randomized table backgrounds with camera-style augmentations (lighting, perspective, blur, noise).

Task

Single-class keypoint detection: every hexagonal terrain tile on the board is one object instance.

• —Class (`nc=1`): terrain_hex
• —Keypoints (`kpt_shape: [6, 3]`): 6 keypoints per hex (the tile's 6 corners), each as (x, y, visibility). Visibility 0 = not labeled (occluded/out of frame, coordinates zeroed), 2 = labeled and visible.
• —Bounding box: standard YOLO (cx, cy, w, h), normalized 0–1.

A board typically contains multiple terrain_hex instances (up to 19 for a full board), so each image has multiple label rows / multiple entries in the objects list.

Splits

Each split's images (and matching YOLO labels/*.txt) are chunked into chunk_000/, chunk_001/, … subfolders of ≤8,000 files each, to stay under Hugging Face's recommended ~10k-files-per-folder limit. An image and its label always share the same chunk index, e.g. images/train/chunk_002/catan_board_00001.jpg ↔ labels/train/chunk_002/catan_board_00001.txt.

Format

Two parallel representations are included:

1. 1.Raw YOLO pose format (labels/<split>/chunk_*/*.txt) — for training directly with Ultralytics:

   class cx cy w h  x1 y1 v1  x2 y2 v2  x3 y3 v3  x4 y4 v4  x5 y5 v5  x6 y6 v6

1. 1.`metadata.jsonl` (one per split, next to images/<split>/) — for the Hugging Face imagefolder loader / Dataset Viewer, so each row's bbox and keypoints show up as structured columns rather than a plain image gallery:

   {"file_name": "chunk_002/catan_board_00001.jpg", "objects": [{"category": "terrain_hex", "bbox": [0.46, 0.44, 0.36, 0.37], "keypoints": [[0.50, 0.25, 2.0], ...]}, ...]}

Note on the Viewer: the auto-generated preview shows image thumbnails plus the parsed bbox/keypoints values as JSON columns — it does not draw keypoint overlays on the image itself (Hugging Face's stock viewer has no built-in renderer for arbitrary keypoint tasks).

Loading

from datasets import load_dataset

ds = load_dataset("nithinmanoj10/CatanSynth-Meridian-v1-50K")
ds["train"][0]  # {"image": <PIL.Image>, "objects": [...]}

To train with Ultralytics directly, download the repo and point a dataset.yaml at the images//labels/ folders (kpt_shape: [6, 3], nc: 1, names: ['terrain_hex']).

License

MIT