PyTorch Adapter¶

def build_torchdataset(
    dataset: Dataset,
    image_size: int | tuple[int, int] | None = None,
    augment: bool = False,
    normalize: bool = False,
    *transforms: t.Callable[..., t.Any],
    return_format: t.Literal["xyxy", "xywh", "cxcywh"] = "xyxy",
) -> TorchDatasetAdapter:
    """Create a PyTorch-compatible dataset with standard transforms.

    This convenience function builds a TorchDatasetAdapter with commonly used
    transforms for object detection, including resizing, augmentation, and
    normalization.

    Args:
        dataset: Source BoxLab Dataset instance.
        image_size: Target image size. Can be:
            - int: Square resize (size, size)
            - tuple: (height, width)
            - None: No resizing
        augment: Whether to apply data augmentation. Includes:
            - Random horizontal flip (p=0.5)
            - Color jitter (brightness, contrast, saturation, hue)
            - Random affine (rotation, translation, scale)
        normalize: Whether to normalize images using ImageNet statistics:
            - mean=[0.485, 0.456, 0.406]
            - std=[0.229, 0.224, 0.225]
        *transforms: Additional user-defined transforms to append.
        return_format: Bounding box format ("xyxy", "xywh", or "cxcywh").

    Returns:
        TorchDatasetAdapter instance with configured transforms.

    Note:
        This function requires torch, torchvision, and pillow to be installed.
        Install with: `pip install torch torchvision pillow`

    Raises:
        RequiredModuleNotFoundError: If required packages are not installed.

    Example:
        ```python
        from boxlab.dataset import Dataset
        from boxlab.dataset.torchadapter import build_torchdataset
        from torch.utils.data import DataLoader

        # Create dataset
        dataset = Dataset(name="my_dataset")
        # ... populate dataset ...

        # Build training dataset with augmentation
        train_dataset = build_torchdataset(
            dataset,
            image_size=640,
            augment=True,
            normalize=True,
            return_format="xyxy",
        )

        # Build validation dataset without augmentation
        val_dataset = build_torchdataset(
            dataset,
            image_size=640,
            augment=False,
            normalize=True,
            return_format="xyxy",
        )

        # Create DataLoaders
        train_loader = DataLoader(
            train_dataset,
            batch_size=16,
            shuffle=True,
            collate_fn=train_dataset.collate,
        )

        val_loader = DataLoader(
            val_dataset,
            batch_size=16,
            shuffle=False,
            collate_fn=val_dataset.collate,
        )
        ```

    Example:
        ```python
        # Add custom transforms
        from torchvision import transforms as T

        custom_transform = T.GaussianBlur(kernel_size=3)

        torch_dataset = build_torchdataset(
            dataset,
            image_size=640,
            augment=True,
            normalize=True,
            custom_transform,  # Added after normalization
            return_format="cxcywh"
        )
        ```

    Example:
        ```python
        # Different image sizes
        torch_dataset = build_torchdataset(
            dataset,
            image_size=(800, 600),  # height x width
            augment=False,
            normalize=False,
        )
        ```
    """
    logger.info(
        f"Building PyTorch dataset: size={image_size}, augment={augment}, "
        f"normalize={normalize}, format={return_format}"
    )

    transform_list: list[t.Callable[..., t.Any]] = []

    # Resize
    if image_size is not None:
        if isinstance(image_size, int):
            image_size = (image_size, image_size)
        transform_list.append(T.Resize(image_size))

    # Augmentation
    if augment:
        transform_list.extend([
            T.RandomHorizontalFlip(p=0.5),
            T.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2, hue=0.1),
            T.RandomAffine(degrees=10, translate=(0.1, 0.1), scale=(0.9, 1.1)),
        ])

    # Convert to tensor (must be before normalization)
    transform_list.append(T.ToTensor())

    # Normalization (must be after ToTensor)
    if normalize:
        transform_list.append(T.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]))

    # Additional user-defined transforms
    transform_list.extend(transforms)

    # Compose all transforms
    transform = T.Compose(transform_list)

    return TorchDatasetAdapter(
        dataset=dataset,
        transform=transform,
        return_format=return_format,
    )