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

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

@@ -2,6 +2,14 @@
 
 <!-- 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-cv
-Version: 1.5.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.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.5.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.5.0 → argus_cv-1.5.1}/pyproject.toml

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

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

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

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

@@ -20,6 +20,11 @@ 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,
@@ -781,6 +786,196 @@ def convert_dataset(
     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.0 → argus_cv-1.5.1}/src/argus/core/__init__.py

@@ -9,6 +9,11 @@ from argus.core.convert import (
     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
@@ -21,6 +26,9 @@ __all__ = [
     "ConfigurationError",
     "split_coco_dataset",
     "split_yolo_dataset",
+    "filter_yolo_dataset",
+    "filter_coco_dataset",
+    "filter_mask_dataset",
     "ConversionParams",
     "Polygon",
     "mask_to_polygons",