Prepare a Dataset
SUMMARY
Iris loads COCO detection and instance-segmentation data, preserves original category IDs, supports explicit or deterministic validation splits, and applies model-provided target-aware transforms.
Supported Layouts
A split may use separate images and annotations:
dataset/train/
├── images/
│ ├── image-001.jpg
│ └── image-002.jpg
└── annotations.jsonOr a Roboflow-style directory:
dataset/train/
├── image-001.jpg
├── image-002.jpg
└── _annotations.coco.jsonFor an explicit validation set, add dataset/valid/ or dataset/val/ in Roboflow format. Do not provide both. An explicit split takes precedence over validation_split.
Load and Inspect a Split
Create inspect_training_dataset.py
"""Load and inspect a COCO dataset."""
import argparse
from pathlib import Path
from loguru import logger
from torch.utils.data import DataLoader
from telekinesis.iris.dataset import COCODataset
def parse_args() -> argparse.Namespace:
"""Parse command-line arguments."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--dataset-dir",
type=Path,
required=True,
help="Path to the COCO dataset directory.",
)
return parser.parse_args()
def inspect_training_dataset(args: argparse.Namespace) -> None:
"""Load a COCO dataset and inspect individual and batched samples."""
# ===================== Load Dataset ===================================
dataset = COCODataset(
dataset_dir=args.dataset_dir,
)
# ===================== Inspect Sample =================================
logger.info(f"Dataset size: {len(dataset)}")
image, target = dataset[0]
logger.info("Single sample:")
logger.info(f" image shape: {image}")
logger.info(f" boxes: {target['boxes']}")
logger.info(f" labels: {target['labels']}")
logger.info(f" image_id: {target['image_id']}")
def collate_fn(batch):
"""Group dataset samples into image and target tuples."""
return tuple(zip(*batch))
# ===================== Create Data Loader =============================
dataloader = DataLoader(
dataset,
batch_size=4,
shuffle=True,
num_workers=0,
collate_fn=collate_fn,
)
# ===================== Inspect Batch ==================================
images, targets = next(iter(dataloader))
logger.info("")
logger.info("Batch:")
logger.info(f" images: {len(images)}")
logger.info(f" targets: {len(targets)}")
if __name__ == "__main__":
inspect_training_dataset(parse_args())Run the Inspection
python inspect_training_dataset.py --dataset-dir dataset/trainThe script reports the same dataset metadata and sample fields available through the API:
training = COCODataset("dataset/train", include_masks=False)
print(training.num_images)
print(training.category_ids)
print(training.categories) # {category_id: category_name}
image, target = training[0]
print(image.shape, image.dtype)
print(target["boxes"], target["labels"])Images are RGB float32 tensors in CHW layout and [0, 1]. Each target contains:
| Key | Contract |
|---|---|
boxes | Absolute xyxy tensor (N, 4) |
labels | Original COCO category IDs (N,) |
image_id | COCO image ID |
original_size | (height, width) before transforms |
area | COCO object areas |
iscrowd | COCO crowd flags |
masks | Optional uint8 masks (N, H, W) |
num_classes is the largest category ID, which is the head size expected by RF-DETR. YOLOX instead uses the explicit category_ids tuple to map arbitrary COCO IDs to contiguous internal indices.
Segmentation Annotations
With include_masks=True, every annotation must contain a non-empty COCO polygon or RLE segmentation.
Prepare Training and Validation Data
Always pass the transforms and mask requirement from the model wrapper:
from telekinesis.iris import dataset
training_dataset, validation_dataset = dataset.prepare_coco_datasets(
dataset_dir="dataset",
validation_split=0.2,
seed=42,
train_transforms=model.train_transforms,
val_transforms=model.val_transforms,
include_masks=model.requires_masks,
)If no valid or val directory exists, Iris makes a deterministic subset using validation_split. Set it to 0.0 for no validation dataset. Explicit training and validation splits must define identical category mappings.
Augmentation
Model configs accept an AugmentationPreset, its string value, or an ordered sequence of declarative transform mappings.
| Preset | Value | Intended use |
|---|---|---|
RFDETR_DEFAULTS | "rfdetr_defaults" | Scale jitter, resize, and horizontal flip |
RFDETR_EXTRA | "rfdetr_extra" | RF-DETR defaults plus crop, color, blur, noise, sharpness, and JPEG transforms |
YOLOX_DEFAULTS | "yolox_defaults" | Flip, color distortion, Mosaic, MixUp, and letterbox |
from telekinesis.iris import models
config = models.RFDETRConfig(
variant="small",
num_classes=3,
augmentation=(
{"name": "resize"},
{"name": "horizontal_flip", "probability": 0.5},
{"name": "gamma", "probability": 0.25, "gamma_range": (0.8, 1.2)},
),
)Built-in transform names are horizontal_flip, photometric_distort, gamma, gaussian_blur, gaussian_noise, sharpness, jpeg_compression, random_scale_crop, rfdetr_scale_jitter, and resize. Dataset-composition names are mosaic, mixup, and letterbox; the YOLOX adapter applies these through MultiImageAugmentationDataset.
Use register_augmentation(name, factory, overwrite=False) to add a target-aware transform, or register_augmentation_preset(name, specifications, overwrite=False) to register a reusable pipeline. build_training_transforms(resolution, augmentation, scale_step=None) resolves a pipeline manually when building a custom TrainableModel.
Next Step
Continue with Train RFDETR, Train SAM3-LoRA, or Train YOLOX.