Skip to content

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:

text
dataset/train/
├── images/
│   ├── image-001.jpg
│   └── image-002.jpg
└── annotations.json

Or a Roboflow-style directory:

text
dataset/train/
├── image-001.jpg
├── image-002.jpg
└── _annotations.coco.json

For 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 ​

python
"""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 ​

bash
python inspect_training_dataset.py --dataset-dir dataset/train

The script reports the same dataset metadata and sample fields available through the API:

python
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:

KeyContract
boxesAbsolute xyxy tensor (N, 4)
labelsOriginal COCO category IDs (N,)
image_idCOCO image ID
original_size(height, width) before transforms
areaCOCO object areas
iscrowdCOCO crowd flags
masksOptional 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:

python
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.

PresetValueIntended 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
python
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.