argus-cv 1.4.0__tar.gz → 1.5.1__tar.gz

{argus_cv-1.4.0 → argus_cv-1.5.1}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v1.5.1 (2026-01-28)
+
+### Bug Fixes
+
+- Add missing documentation for filter command
+  ([`dc41fbb`](https://github.com/pirnerjonas/argus/commit/dc41fbb724faf2024ec9f1430e2af0a6af000d21))
+
+
+## v1.5.0 (2026-01-28)
+
+### Features
+
+- Support Roboflow COCO format and improve YOLO classification detection
+  ([`902a59f`](https://github.com/pirnerjonas/argus/commit/902a59fbb506aa586d8677312d21ae240585b511))
+
+
 ## v1.4.0 (2026-01-26)
 
 ### Features

{argus_cv-1.4.0 → argus_cv-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-cv
-Version: 1.4.0
+Version: 1.5.1
 Summary: CLI tool for working with vision AI datasets
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.24.0

{argus_cv-1.4.0 → argus_cv-1.5.1}/docs/guides/datasets.md

@@ -59,6 +59,26 @@ dataset/
 If your annotation filenames include `train`, `val`, or `test`, Argus will treat
 those as splits. Otherwise it defaults to `train`.
 
+### Roboflow COCO
+
+Argus also supports the Roboflow variant of COCO format, where annotations live
+inside split directories:
+
+```text
+dataset/
+├── train/
+│   ├── _annotations.coco.json
+│   └── *.jpg
+├── valid/
+│   ├── _annotations.coco.json
+│   └── *.jpg
+└── test/
+    ├── _annotations.coco.json
+    └── *.jpg
+```
+
+Splits are detected from directory names (`train`, `valid`/`val`, `test`).
+
 ## Mask (semantic segmentation)
 
 Mask datasets are simple image + mask folders. Argus detects a few common

argus_cv-1.5.1/docs/guides/filtering.md

@@ -0,0 +1,101 @@
+# Filtering datasets
+
+Use `argus-cv filter` to create a filtered copy of a dataset containing only specified classes.
+
+## Basic usage
+
+```bash
+argus-cv filter -d /datasets/coco -o /datasets/coco_filtered --classes person,car
+```
+
+This creates a new dataset with only the `person` and `car` classes. Class IDs are automatically remapped to sequential values (0, 1, 2, ...).
+
+## Filter to a single class
+
+```bash
+argus-cv filter -d /datasets/yolo -o /datasets/yolo_balls --classes ball
+```
+
+## Exclude background images
+
+By default, images without annotations (after filtering) are kept. Use `--no-background` to exclude them:
+
+```bash
+argus-cv filter -d /datasets/coco -o /datasets/coco_filtered --classes dog --no-background
+```
+
+This is useful when you want a dataset with only images that contain your target class.
+
+## Use symlinks for faster filtering
+
+For large datasets, use `--symlinks` to create symbolic links instead of copying images:
+
+```bash
+argus-cv filter -d /datasets/large -o /datasets/filtered --classes cat --symlinks
+```
+
+This saves disk space and speeds up the filtering process significantly.
+
+## Supported formats
+
+The filter command works with all dataset formats:
+
+| Format | Supported | Notes |
+|--------|-----------|-------|
+| YOLO Detection | Yes | Labels remapped to new class IDs |
+| YOLO Segmentation | Yes | Polygon annotations preserved |
+| YOLO Classification | Yes | Only selected class directories copied |
+| COCO | Yes | Annotations and category IDs remapped |
+| Mask | Yes | Pixel values remapped to new class IDs |
+
+## Output layout
+
+The output preserves the original dataset structure with train/val/test splits.
+
+YOLO output:
+
+```text
+output/
+├── data.yaml
+├── images/
+│   ├── train/
+│   ├── val/
+│   └── test/
+└── labels/
+    ├── train/
+    ├── val/
+    └── test/
+```
+
+COCO output:
+
+```text
+output/
+├── annotations/
+│   ├── instances_train.json
+│   ├── instances_val.json
+│   └── instances_test.json
+└── images/
+    ├── train/
+    ├── val/
+    └── test/
+```
+
+## Class ID remapping
+
+When filtering, class IDs are remapped to start from 0 and be sequential. For example:
+
+| Original | Filtered |
+|----------|----------|
+| 0: person | (removed) |
+| 1: car | 0: car |
+| 2: dog | 1: dog |
+| 3: cat | (removed) |
+
+If you filter to keep only `car` and `dog`, the new dataset will have `car` as class 0 and `dog` as class 1.
+
+## Common errors
+
+- "No classes specified": You must provide at least one class name with `--classes`.
+- "Classes not found in dataset": Check the class names match exactly (case-sensitive). Use `argus-cv stats` to see available classes.
+- "Output directory already exists": The output directory must be empty or non-existent.

{argus_cv-1.4.0 → argus_cv-1.5.1}/mkdocs.yml

@@ -64,5 +64,6 @@ nav:
       - Stats and counts: guides/stats.md
       - Visual inspection: guides/viewer.md
       - Splitting datasets: guides/splitting.md
+      - Filtering datasets: guides/filtering.md
   - Reference:
       - CLI reference: reference/cli.md

{argus_cv-1.4.0 → argus_cv-1.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "argus-cv"
-version = "1.4.0"
+version = "1.5.1"
 description = "CLI tool for working with vision AI datasets"
 readme = "README.md"
 requires-python = ">=3.10"

{argus_cv-1.4.0 → argus_cv-1.5.1}/src/argus/__init__.py

@@ -1,3 +1,3 @@
 """Argus - Vision AI dataset toolkit."""
 
-__version__ = "1.4.0"
+__version__ = "1.5.1"

{argus_cv-1.4.0 → argus_cv-1.5.1}/src/argus/cli.py

@@ -8,11 +8,23 @@ import cv2
 import numpy as np
 import typer
 from rich.console import Console
-from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+)
 from rich.table import Table
 
 from argus.core import COCODataset, Dataset, MaskDataset, YOLODataset
 from argus.core.base import DatasetFormat, TaskType
+from argus.core.convert import convert_mask_to_yolo_seg
+from argus.core.filter import (
+    filter_coco_dataset,
+    filter_mask_dataset,
+    filter_yolo_dataset,
+)
 from argus.core.split import (
     is_coco_unsplit,
     parse_ratio,
@@ -632,6 +644,338 @@ def split_dataset(
     )
 
 
+@app.command(name="convert")
+def convert_dataset(
+    input_path: Annotated[
+        Path,
+        typer.Option(
+            "--input-path",
+            "-i",
+            help="Path to the source dataset.",
+        ),
+    ] = Path("."),
+    output_path: Annotated[
+        Path,
+        typer.Option(
+            "--output-path",
+            "-o",
+            help="Output directory for converted dataset.",
+        ),
+    ] = Path("converted"),
+    to_format: Annotated[
+        str,
+        typer.Option(
+            "--to",
+            help="Target format (currently only 'yolo-seg' is supported).",
+        ),
+    ] = "yolo-seg",
+    epsilon_factor: Annotated[
+        float,
+        typer.Option(
+            "--epsilon-factor",
+            "-e",
+            help="Polygon simplification factor (Douglas-Peucker algorithm).",
+            min=0.0,
+            max=1.0,
+        ),
+    ] = 0.005,
+    min_area: Annotated[
+        float,
+        typer.Option(
+            "--min-area",
+            "-a",
+            help="Minimum contour area in pixels to include.",
+            min=0.0,
+        ),
+    ] = 100.0,
+) -> None:
+    """Convert a dataset from one format to another.
+
+    Currently supports converting MaskDataset to YOLO segmentation format.
+
+    Example:
+        uvx argus-cv convert -i /path/to/masks -o /path/to/output --to yolo-seg
+    """
+    # Validate format
+    if to_format != "yolo-seg":
+        console.print(
+            f"[red]Error: Unsupported target format '{to_format}'.[/red]\n"
+            "[yellow]Currently only 'yolo-seg' is supported.[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    # Resolve and validate input path
+    input_path = input_path.resolve()
+    if not input_path.exists():
+        console.print(f"[red]Error: Path does not exist: {input_path}[/red]")
+        raise typer.Exit(1)
+    if not input_path.is_dir():
+        console.print(f"[red]Error: Path is not a directory: {input_path}[/red]")
+        raise typer.Exit(1)
+
+    # Detect source dataset - must be MaskDataset for yolo-seg conversion
+    dataset = MaskDataset.detect(input_path)
+    if not dataset:
+        console.print(
+            f"[red]Error: No MaskDataset found at {input_path}[/red]\n"
+            "[yellow]Ensure the path contains images/ + masks/ directories "
+            "(or equivalent patterns like img/+gt/ or leftImg8bit/+gtFine/).[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    # Resolve output path
+    if not output_path.is_absolute():
+        output_path = input_path.parent / output_path
+    output_path = output_path.resolve()
+
+    # Check if output already exists
+    if output_path.exists() and any(output_path.iterdir()):
+        console.print(
+            f"[red]Error: Output directory already exists and is not empty: "
+            f"{output_path}[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Show conversion info
+    console.print("[cyan]Converting MaskDataset to YOLO segmentation format[/cyan]")
+    console.print(f"  Source: {input_path}")
+    console.print(f"  Output: {output_path}")
+    console.print(f"  Classes: {dataset.num_classes}")
+    splits_str = ", ".join(dataset.splits) if dataset.splits else "unsplit"
+    console.print(f"  Splits: {splits_str}")
+    console.print()
+
+    # Run conversion with progress bar
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Processing images...", total=None)
+
+        def update_progress(current: int, total: int) -> None:
+            progress.update(task, completed=current, total=total)
+
+        try:
+            stats = convert_mask_to_yolo_seg(
+                dataset=dataset,
+                output_path=output_path,
+                epsilon_factor=epsilon_factor,
+                min_area=min_area,
+                progress_callback=update_progress,
+            )
+        except Exception as exc:
+            console.print(f"[red]Error during conversion: {exc}[/red]")
+            raise typer.Exit(1) from exc
+
+    # Show results
+    console.print()
+    console.print("[green]Conversion complete![/green]")
+    console.print(f"  Images processed: {stats['images']}")
+    console.print(f"  Labels created: {stats['labels']}")
+    console.print(f"  Polygons extracted: {stats['polygons']}")
+
+    if stats["skipped"] > 0:
+        skipped = stats["skipped"]
+        console.print(f"  [yellow]Skipped: {skipped} (no mask or empty)[/yellow]")
+    if stats["warnings"] > 0:
+        console.print(f"  [yellow]Warnings: {stats['warnings']}[/yellow]")
+
+    console.print(f"\n[cyan]Output dataset: {output_path}[/cyan]")
+
+
+@app.command(name="filter")
+def filter_dataset(
+    dataset_path: Annotated[
+        Path,
+        typer.Option(
+            "--dataset-path",
+            "-d",
+            help="Path to the dataset root directory.",
+        ),
+    ] = Path("."),
+    output_path: Annotated[
+        Path,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output directory for filtered dataset.",
+        ),
+    ] = Path("filtered"),
+    classes: Annotated[
+        str,
+        typer.Option(
+            "--classes",
+            "-c",
+            help="Comma-separated list of class names to keep.",
+        ),
+    ] = "",
+    no_background: Annotated[
+        bool,
+        typer.Option(
+            "--no-background",
+            help="Exclude images with no annotations after filtering.",
+        ),
+    ] = False,
+    use_symlinks: Annotated[
+        bool,
+        typer.Option(
+            "--symlinks",
+            help="Use symlinks instead of copying images.",
+        ),
+    ] = False,
+) -> None:
+    """Filter a dataset by class names.
+
+    Creates a filtered copy of the dataset containing only the specified classes.
+    Class IDs are remapped to sequential values (0, 1, 2, ...).
+
+    Examples:
+        argus-cv filter -d dataset -o output --classes ball --no-background
+        argus-cv filter -d dataset -o output --classes ball,player
+        argus-cv filter -d dataset -o output --classes ball --symlinks
+    """
+    # Resolve path and validate
+    dataset_path = dataset_path.resolve()
+    if not dataset_path.exists():
+        console.print(f"[red]Error: Path does not exist: {dataset_path}[/red]")
+        raise typer.Exit(1)
+    if not dataset_path.is_dir():
+        console.print(f"[red]Error: Path is not a directory: {dataset_path}[/red]")
+        raise typer.Exit(1)
+
+    # Parse classes
+    if not classes:
+        console.print(
+            "[red]Error: No classes specified. "
+            "Use --classes to specify classes to keep.[/red]"
+        )
+        raise typer.Exit(1)
+
+    class_list = [c.strip() for c in classes.split(",") if c.strip()]
+    if not class_list:
+        console.print("[red]Error: No valid class names provided.[/red]")
+        raise typer.Exit(1)
+
+    # Detect dataset
+    dataset = _detect_dataset(dataset_path)
+    if not dataset:
+        console.print(
+            f"[red]Error: No dataset found at {dataset_path}[/red]\n"
+            "[yellow]Ensure the path points to a dataset root containing "
+            "data.yaml (YOLO), annotations/ folder (COCO), or "
+            "images/ + masks/ directories (Mask).[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    # Validate classes exist in dataset
+    missing_classes = [c for c in class_list if c not in dataset.class_names]
+    if missing_classes:
+        available = ", ".join(dataset.class_names)
+        missing = ", ".join(missing_classes)
+        console.print(
+            f"[red]Error: Classes not found in dataset: {missing}[/red]\n"
+            f"[yellow]Available classes: {available}[/yellow]"
+        )
+        raise typer.Exit(1)
+
+    # Resolve output path
+    if not output_path.is_absolute():
+        output_path = dataset_path.parent / output_path
+    output_path = output_path.resolve()
+
+    # Check if output already exists
+    if output_path.exists() and any(output_path.iterdir()):
+        console.print(
+            f"[red]Error: Output directory already exists and is not empty: "
+            f"{output_path}[/red]"
+        )
+        raise typer.Exit(1)
+
+    # Show filter info
+    console.print(f"[cyan]Filtering {dataset.format.value.upper()} dataset[/cyan]")
+    console.print(f"  Source: {dataset_path}")
+    console.print(f"  Output: {output_path}")
+    console.print(f"  Classes to keep: {', '.join(class_list)}")
+    console.print(f"  Exclude background: {no_background}")
+    console.print(f"  Use symlinks: {use_symlinks}")
+    console.print()
+
+    # Run filtering with progress bar
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Filtering dataset...", total=None)
+
+        def update_progress(current: int, total: int) -> None:
+            progress.update(task, completed=current, total=total)
+
+        try:
+            if dataset.format == DatasetFormat.YOLO:
+                assert isinstance(dataset, YOLODataset)
+                stats = filter_yolo_dataset(
+                    dataset=dataset,
+                    output_path=output_path,
+                    classes=class_list,
+                    no_background=no_background,
+                    use_symlinks=use_symlinks,
+                    progress_callback=update_progress,
+                )
+            elif dataset.format == DatasetFormat.COCO:
+                assert isinstance(dataset, COCODataset)
+                stats = filter_coco_dataset(
+                    dataset=dataset,
+                    output_path=output_path,
+                    classes=class_list,
+                    no_background=no_background,
+                    use_symlinks=use_symlinks,
+                    progress_callback=update_progress,
+                )
+            elif dataset.format == DatasetFormat.MASK:
+                assert isinstance(dataset, MaskDataset)
+                stats = filter_mask_dataset(
+                    dataset=dataset,
+                    output_path=output_path,
+                    classes=class_list,
+                    no_background=no_background,
+                    use_symlinks=use_symlinks,
+                    progress_callback=update_progress,
+                )
+            else:
+                console.print(
+                    f"[red]Error: Unsupported dataset format: {dataset.format}[/red]"
+                )
+                raise typer.Exit(1)
+        except ValueError as exc:
+            console.print(f"[red]Error: {exc}[/red]")
+            raise typer.Exit(1) from exc
+        except Exception as exc:
+            console.print(f"[red]Error during filtering: {exc}[/red]")
+            raise typer.Exit(1) from exc
+
+    # Show results
+    console.print()
+    console.print("[green]Filtering complete![/green]")
+    console.print(f"  Images: {stats.get('images', 0)}")
+    if "labels" in stats:
+        console.print(f"  Labels: {stats['labels']}")
+    if "annotations" in stats:
+        console.print(f"  Annotations: {stats['annotations']}")
+    if "masks" in stats:
+        console.print(f"  Masks: {stats['masks']}")
+    if stats.get("skipped", 0) > 0:
+        skipped = stats["skipped"]
+        console.print(f"  [yellow]Skipped: {skipped} (background images)[/yellow]")
+
+    console.print(f"\n[cyan]Output dataset: {output_path}[/cyan]")
+
+
 class _ImageViewer:
     """Interactive image viewer with zoom and pan support."""
 

argus_cv-1.5.1/src/argus/core/__init__.py

@@ -0,0 +1,37 @@
+"""Core dataset detection and handling."""
+
+from argus.core.base import Dataset
+from argus.core.coco import COCODataset
+from argus.core.convert import (
+    ConversionParams,
+    Polygon,
+    convert_mask_to_yolo_labels,
+    convert_mask_to_yolo_seg,
+    mask_to_polygons,
+)
+from argus.core.filter import (
+    filter_coco_dataset,
+    filter_mask_dataset,
+    filter_yolo_dataset,
+)
+from argus.core.mask import ConfigurationError, MaskDataset
+from argus.core.split import split_coco_dataset, split_yolo_dataset
+from argus.core.yolo import YOLODataset
+
+__all__ = [
+    "Dataset",
+    "YOLODataset",
+    "COCODataset",
+    "MaskDataset",
+    "ConfigurationError",
+    "split_coco_dataset",
+    "split_yolo_dataset",
+    "filter_yolo_dataset",
+    "filter_coco_dataset",
+    "filter_mask_dataset",
+    "ConversionParams",
+    "Polygon",
+    "mask_to_polygons",
+    "convert_mask_to_yolo_labels",
+    "convert_mask_to_yolo_seg",
+]