Plugins¶

def gen_name(self, origin: str, source: str | None, image_id: str, /) -> str:
    """Generate a new file name.

    Args:
        origin: Original file name (e.g., "image001.jpg").
        source: Source name if available (e.g., "camera1"), None otherwise.
        image_id: Unique image identifier (e.g., "img_12345").

    Returns:
        Generated file name as a string.

    Example:
        ```python
        strategy = MyNamingStrategy()
        new_name = strategy.gen_name(
            origin="photo.jpg",
            source="camera_front",
            image_id="001",
        )
        print(new_name)  # Output depends on implementation
        ```
    """

@abc.abstractmethod
def load(
    self,
    path: str | os.PathLike[str],
    name: str | None = None,
    **kwargs: t.Any,
) -> Dataset:
    """Load dataset from path.

    This method should parse the dataset file(s) at the given path and
    construct a Dataset object with all images, annotations, and categories.

    Args:
        path: Path to dataset file or directory. Can be a JSON file,
            YAML file, or directory containing dataset files.
        name: Name to assign to the loaded Dataset instance.
        **kwargs: Additional loader-specific parameters. Common options:
            - image_root (str): Root directory for image files
            - source_name (str): Name to tag this data source
            - strict (bool): Whether to fail on parse errors

    Returns:
        A populated Dataset instance containing all loaded data.

    Raises:
        FileNotFoundError: If the specified path doesn't exist.
        ValueError: If the dataset format is invalid or corrupted.
        PermissionError: If files cannot be read due to permissions.

    Example:
        ```python
        class COCOLoader(LoaderPlugin):
            def load(self, path, **kwargs):
                dataset = Dataset(name="coco")
                image_root = kwargs.get("image_root", ".")

                with open(path) as f:
                    data = json.load(f)

                # Load categories
                for cat in data["categories"]:
                    dataset.add_category(cat["id"], cat["name"])

                # Load images and annotations
                # ... implementation details ...

                return dataset


        # Usage
        loader = COCOLoader()
        dataset = loader.load(
            "annotations.json",
            image_root="/data/images",
            source_name="train2017",
        )
        ```
    """

def validate(self, path: str | os.PathLike[str]) -> bool:
    """Check if this loader can handle the given path.

    Performs basic validation to determine if the file or directory at the
    given path appears to be in a format this loader can handle. This is
    typically used for automatic format detection.

    Args:
        path: Path to validate. Can be a file or directory.

    Returns:
        True if this loader can likely handle the path, False otherwise.

    Note:
        This method performs basic checks (existence, extension). It does not
        guarantee that load() will succeed, as it doesn't validate the full
        file contents.

    Example:
        ```python
        loader = COCOLoader()

        if loader.validate("dataset.json"):
            dataset = loader.load("dataset.json")
        else:
            print("Not a valid COCO format file")
        ```

    Example:
        Custom validation logic:

        ```python
        class YOLOLoader(LoaderPlugin):
            def validate(self, path):
                # Call parent validation first
                if not super().validate(path):
                    return False

                # Additional YOLO-specific checks
                path = pathlib.Path(path)
                if path.is_file() and path.suffix in [
                    ".yaml",
                    ".yml",
                ]:
                    # Check for YOLO-specific keys
                    with open(path) as f:
                        data = yaml.safe_load(f)
                        return "names" in data and "path" in data

                return False
        ```
    """
    import pathlib

    path = pathlib.Path(path)

    if not path.exists():
        return False

    # Check file extension if supported_extensions is defined
    if self.supported_extensions:
        return path.suffix.lower() in self.supported_extensions

    return True

@abc.abstractmethod
def export(
    self,
    dataset: Dataset,
    output_dir: str | os.PathLike[str],
    split_ratio: SplitRatio | None = None,
    seed: int | None = None,
    naming_strategy: NamingStrategy | None = None,
    copy_images: bool = True,
    **kwargs: t.Any,
) -> None:
    """Export dataset to output directory.

    This method should write the dataset to disk in the format supported by
    this exporter. It should handle creating output directories, optionally
    splitting the dataset, copying images, and writing annotation files.

    Args:
        dataset: The Dataset instance to export.
        output_dir: Path to the output directory. Will be created if it
            doesn't exist.
        split_ratio: Optional SplitRatio object defining train/val/test
            proportions. If None, exports entire dataset without splitting.
        seed: Random seed for reproducible splits. Only used if split_ratio
            is provided.
        naming_strategy: Optional NamingStrategy instance for generating
            image file names. If None, uses original file names.
        copy_images: If True, copies image files to output directory.
            If False, only writes annotation files.
        **kwargs: Additional exporter-specific parameters. Common options:
            - indent (int): JSON indentation level
            - include_metadata (bool): Whether to include extra metadata
            - compress (bool): Whether to compress output files

    Raises:
        ValueError: If export parameters are invalid (e.g., invalid split_ratio).
        OSError: If file operations fail (permission denied, disk full, etc.).
        DatasetError: If dataset is empty or malformed.

    Example:
        ```python
        from boxlab.dataset import Dataset, SplitRatio
        from pathlib import Path


        class COCOExporter(ExporterPlugin):
            def export(
                self,
                dataset,
                output_dir,
                split_ratio=None,
                seed=None,
                naming_strategy=None,
                copy_images=True,
                **kwargs,
            ):
                output_dir = Path(output_dir)
                output_dir.mkdir(parents=True, exist_ok=True)

                # Handle splits
                if split_ratio:
                    splits = dataset.split(split_ratio, seed=seed)
                else:
                    splits = {"all": list(dataset.images.keys())}

                # Export each split
                for split_name, image_ids in splits.items():
                    # Create COCO format dictionary
                    coco_data = {
                        "images": [],
                        "annotations": [],
                        "categories": [],
                    }

                    # Add categories
                    for (
                        cat_id,
                        cat_name,
                    ) in dataset.categories.items():
                        coco_data["categories"].append({
                            "id": cat_id,
                            "name": cat_name,
                        })

                    # Add images and annotations
                    # ... implementation ...

                    # Write JSON
                    output_file = output_dir / f"{split_name}.json"
                    with open(output_file, "w") as f:
                        json.dump(coco_data, f, indent=2)

                    # Copy images if requested
                    if copy_images:
                        # ... copy logic ...
                        pass


        # Usage
        exporter = COCOExporter()
        exporter.export(
            dataset=my_dataset,
            output_dir="output/coco",
            split_ratio=SplitRatio(train=0.8, val=0.1, test=0.1),
            seed=42,
            copy_images=True,
            indent=4,
        )
        ```

    Example:
        Exporting without splits:

        ```python
        exporter = COCOExporter()
        exporter.export(
            dataset=my_dataset,
            output_dir="output/full_dataset",
            copy_images=False,  # Only export annotations
        )
        ```
    """

def get_default_config(self) -> dict[str, t.Any]:
    """Get default configuration for this exporter.

    Returns:
        Dictionary of default configuration values that will be used
        if not overridden in export() call.

    Note:
        Subclasses can override this to provide format-specific defaults.

    Example:
        ```python
        class YOLOExporter(ExporterPlugin):
            def get_default_config(self) -> dict[str, t.Any]:
                return {
                    "copy_images": True,
                    "naming_strategy": "original",
                    "normalize_coords": True,
                    "include_yaml": True,
                }


        # Usage
        exporter = YOLOExporter()
        config = exporter.get_default_config()
        print(config["normalize_coords"])  # True
        ```

    Example:
        Using default config in export:

        ```python
        class CustomExporter(ExporterPlugin):
            def get_default_config(self) -> dict[str, t.Any]:
                return {
                    "copy_images": True,
                    "naming_strategy": "original",
                    "compression": "zip",
                }

            def export(self, dataset, output_dir, **kwargs):
                # Merge with defaults
                config = self.get_default_config()
                config.update(kwargs)

                # Use configuration
                if config["compression"] == "zip":
                    # ... compression logic ...
                    pass
        ```
    """
    return {
        "copy_images": True,
        "naming_strategy": "original",
    }