Python API reference

This page documents the supported library API for programmatic use.

Canonical imports use argus.core:

from argus.core import (
    COCODataset,
    MaskDataset,
    YOLODataset,
    convert_mask_to_yolo_labels,
    convert_mask_to_yolo_seg,
    convert_yolo_seg_to_coco,
    convert_yolo_seg_to_roboflow_coco,
    convert_yolo_seg_to_roboflow_coco_rle,
    filter_coco_dataset,
    filter_mask_dataset,
    filter_yolo_dataset,
    mask_to_polygons,
    split_coco_dataset,
    split_mask_dataset,
    split_yolo_dataset,
    unsplit_coco_dataset,
    unsplit_mask_dataset,
    unsplit_yolo_dataset,
)

Dataset classes

`YOLODataset`

Bases: Dataset

YOLO format dataset.

Supports detection, segmentation, and classification tasks.

Structure (detection/segmentation): dataset/ ├── data.yaml (or .yaml/.yml with 'names' key) ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/

Structure (classification): dataset/ ├── images/ │ ├── train/ │ │ ├── class1/ │ │ │ ├── img1.jpg │ │ │ └── img2.jpg │ │ └── class2/ │ │ └── img1.jpg │ └── val/ │ ├── class1/ │ └── class2/

`detect(path)` `classmethod`

Detect if the given path contains a YOLO dataset.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Directory path to check for dataset.	required

Returns:

Type	Description
`YOLODataset \| None`	YOLODataset instance if detected, None otherwise.

`get_annotations_for_image(image_path)`

Get annotations for a specific image.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`list[dict]`	List of annotation dicts with bbox/polygon in absolute coordinates.

`get_image_counts()`

Get image counts per split, including background images.

For detection/segmentation: Scans the images directory and derives the label path for each image. Images whose label file is missing or empty are counted as background, matching ultralytics behaviour.

For classification: Counts total images across all class directories. Background count is always 0 (no background concept in classification).

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict with "total" and "background" counts.

`get_image_paths(split=None)`

Get all image file paths for a split or the entire dataset.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to get images from. If None, returns all images.	`None`

Returns:

Type	Description
`list[Path]`	List of image file paths sorted alphabetically.

`get_images_by_class(split=None)`

Get images grouped by class for classification datasets.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to get images from. If None, uses first available split or all images for flat structure.	`None`

Returns:

Type	Description
`dict[str, list[Path]]`	Dictionary mapping class name to list of image paths.

`get_instance_counts()`

Get the number of annotation instances per class, per split.

For detection/segmentation: Scans images and reads the corresponding label file (derived by replacing images with labels and the extension with .txt). Orphaned label files without a matching image are ignored, matching ultralytics behaviour.

For classification: Counts images in each class directory (1 image = 1 instance).

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict of class name to instance count.

`get_split_dirs(split)`

Get the images and labels directories for a given split.

Handles both standard YOLO layout (images/{split}/, labels/{split}/) and Roboflow layout ({split}/images/, {split}/labels/).

Parameters:

Name	Type	Description	Default
`split`	`str`	Split name (e.g. "train", "val", "test").	required

Returns:

Type	Description
`tuple[Path, Path]`	Tuple of (images_dir, labels_dir).

`COCODataset`

Bases: Dataset

COCO format dataset.

Supports detection and segmentation tasks.

Structure

dataset/ ├── annotations/ │ ├── instances_train.json │ └── instances_val.json └── images/ ├── train/ └── val/

`is_roboflow_layout` `property`

Return True when the dataset uses Roboflow COCO layout.

`detect(path)` `classmethod`

Detect if the given path contains a COCO dataset.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Directory path to check for dataset.	required

Returns:

Type	Description
`COCODataset \| None`	COCODataset instance if detected, None otherwise.

`get_annotations_for_image(image_path)`

Get annotations for a specific image.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`list[dict]`	List of annotation dicts with bbox/polygon in absolute coordinates.

`get_class_mapping()`

Return class ID to name mapping from annotation files.

When ignore_index is None (i.e. category 0 is used by a real class), all category IDs are shifted by +1 so that 0 is reserved for background in the mask.

Returns:

Type	Description
`dict[int, str]`	Dictionary mapping mask class IDs to category names.

`get_image_counts()`

Get image counts per split, including background images.

Counts images in annotation files. Images with no annotations are counted as background images.

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict with "total" and "background" counts.

`get_image_paths(split=None)`

Get all image file paths for a split or the entire dataset.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to get images from. If None, returns all images.	`None`

Returns:

Type	Description
`list[Path]`	List of image file paths sorted alphabetically.

`get_instance_counts()`

Get the number of annotation instances per class, per split.

Parses all annotation JSON files and counts category_id occurrences.

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict of class name to instance count.

`get_split_dir_name(split)`

Map canonical split names to on-disk split directory names.

`load_mask(image_path)`

Load a combined class-ID mask for the given image.

Finds all annotations for the image, decodes each segmentation (RLE via _decode_rle, polygon via cv2.fillPoly), and combines them into a single mask where each pixel holds its class ID (background = 0).

When ignore_index is None (category 0 is a real class), all category IDs are shifted by +1 so that 0 stays background.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`ndarray \| None`	Mask array of shape (H, W) with class IDs, or None if
`ndarray \| None`	the image is not found in any annotation file.

`MaskDataset`

Bases: Dataset

Dataset format for folder-based semantic segmentation masks.

Supports directory structures like

images/ + masks/
img/ + gt/
leftImg8bit/ + gtFine/ (Cityscapes-style)

Each pattern expects parallel split subdirectories

dataset/ ├── images/ │ ├── train/ │ └── val/ ├── masks/ │ ├── train/ │ └── val/ └── classes.yaml # Optional for grayscale, required for RGB

`detect(path)` `classmethod`

Detect if the given path contains a mask dataset.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Directory path to check for dataset.	required

Returns:

Type	Description
`MaskDataset \| None`	MaskDataset instance if detected, None otherwise.

`get_annotations_for_image(image_path)`

Get annotations for a specific image.

For mask datasets, this returns an empty list since annotations are stored as pixel masks rather than discrete objects. Use get_mask_path() to get the mask file directly.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`list[dict]`	Empty list (masks don't have discrete annotations).

`get_class_mapping()`

Return class ID to name mapping.

Returns:

Type	Description
`dict[int, str]`	Dictionary mapping class IDs to class names.

`get_image_class_presence(split=None)`

Return count of images containing each class.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to analyze. If None, analyzes all splits.	`None`

Returns:

Type	Description
`dict[int, int]`	Dictionary mapping class ID to count of images containing that class.

`get_image_counts()`

Get image counts per split.

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict with "total" and "background" counts.
`dict[str, dict[str, int]]`	For mask datasets, "background" is always 0.

`get_image_paths(split=None)`

Get all image file paths for a split or the entire dataset.

Only returns images that have corresponding masks.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to get images from. If None, returns all images.	`None`

Returns:

Type	Description
`list[Path]`	List of image file paths sorted alphabetically.

`get_instance_counts()`

Get pixel counts per class, per split.

For mask datasets, this returns the total number of pixels for each class across all masks in each split.

Returns:

Type	Description
`dict[str, dict[str, int]]`	Dictionary mapping split name to dict of class name to pixel count.

`get_mask_path(image_path)`

Return corresponding mask path for an image.

Tries multiple naming conventions in order: 1. Exact stem match: image.jpg -> image.png 2. With _mask suffix: image.jpg -> image_mask.png 3. With _gt suffix: image.jpg -> image_gt.png

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`Path \| None`	Path to corresponding mask, or None if not found.

`get_pixel_counts(split=None)`

Return total pixel count per class ID.

Parameters:

Name	Type	Description	Default
`split`	`str \| None`	Specific split to analyze. If None, analyzes all splits.	`None`

Returns:

Type	Description
`dict[int, int]`	Dictionary mapping class ID to total pixel count.

`load_mask(image_path)`

Load the mask for a given image.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`ndarray \| None`	Mask as numpy array (grayscale), or None if not found.

`validate_dimensions(image_path)`

Check if image and mask dimensions match.

Parameters:

Name	Type	Description	Default
`image_path`	`Path`	Path to the image file.	required

Returns:

Type	Description
`tuple[bool, tuple[int, int] \| None, tuple[int, int] \| None]`	Tuple of (dimensions_match, image_shape, mask_shape).

Split operations

`split_yolo_dataset`

Split a YOLO dataset into train/val/test subsets.

`split_coco_dataset`

Split a COCO dataset into train/val/test annotation files and images.

`split_mask_dataset`

Split a mask dataset into train/val/test subsets.

`unsplit_yolo_dataset`

Merge a split YOLO dataset into a single unsplit dataset.

`unsplit_coco_dataset`

Merge split COCO annotations and images into one unsplit dataset.

`unsplit_mask_dataset`

Merge a split mask dataset into flat images/masks layout.

Filter operations

`filter_yolo_dataset`

Filter a YOLO dataset by class names.

Parameters:

Name	Type	Description	Default
`dataset`	`YOLODataset`	Source YOLODataset to filter.	required
`output_path`	`Path`	Directory to write filtered dataset.	required
`classes`	`list[str]`	List of class names to keep.	required
`no_background`	`bool`	If True, exclude images with no annotations after filtering.	`False`
`use_symlinks`	`bool`	If True, create symlinks instead of copying images.	`False`
`progress_callback`	`Callable[[int, int], None] \| None`	Optional callback for progress updates (current, total).	`None`

Returns:

Type	Description
`dict[str, int]`	Dictionary with statistics: images, labels, skipped.

`filter_coco_dataset`

Filter a COCO dataset by class names.

Parameters:

Name	Type	Description	Default
`dataset`	`COCODataset`	Source COCODataset to filter.	required
`output_path`	`Path`	Directory to write filtered dataset.	required
`classes`	`list[str]`	List of class names to keep.	required
`no_background`	`bool`	If True, exclude images with no annotations after filtering.	`False`
`use_symlinks`	`bool`	If True, create symlinks instead of copying images.	`False`
`progress_callback`	`Callable[[int, int], None] \| None`	Optional callback for progress updates (current, total).	`None`

Returns:

Type	Description
`dict[str, int]`	Dictionary with statistics: images, annotations, skipped.

`filter_mask_dataset`

Filter a mask dataset by class names.

Parameters:

Name	Type	Description	Default
`dataset`	`MaskDataset`	Source MaskDataset to filter.	required
`output_path`	`Path`	Directory to write filtered dataset.	required
`classes`	`list[str]`	List of class names to keep.	required
`no_background`	`bool`	If True, exclude images with no annotations after filtering.	`False`
`use_symlinks`	`bool`	If True, create symlinks instead of copying images.	`False`
`progress_callback`	`Callable[[int, int], None] \| None`	Optional callback for progress updates (current, total).	`None`

Returns:

Type	Description
`dict[str, int]`	Dictionary with statistics: images, masks, skipped.

Convert operations

`mask_to_polygons`

Convert a binary mask to simplified polygons.

Parameters:

Name	Type	Description	Default
`mask`	`NDArray[uint8]`	Binary mask (255 for foreground, 0 for background).	required
`params`	`ConversionParams \| None`	Conversion parameters. Uses defaults if None.	`None`

Returns:

Type	Description
`list[Polygon]`	List of Polygon objects with normalized coordinates.

`convert_mask_to_yolo_labels`

Convert a multi-class mask to YOLO label lines.

Parameters:

Name	Type	Description	Default
`mask`	`ndarray`	Grayscale mask where pixel values represent class IDs.	required
`class_ids`	`list[int]`	List of class IDs to extract (excluding ignore index).	required
`epsilon_factor`	`float`	Douglas-Peucker simplification factor.	`0.005`
`min_area`	`float`	Minimum contour area in pixels.	`100.0`

Returns:

Type	Description
`list[str]`	List of YOLO format label strings.

`convert_mask_to_yolo_seg`

Convert a MaskDataset to YOLO segmentation format.

Parameters:

Name	Type	Description	Default
`dataset`	`MaskDataset`	Source MaskDataset to convert.	required
`output_path`	`Path`	Output directory for YOLO dataset.	required
`epsilon_factor`	`float`	Douglas-Peucker simplification factor.	`0.005`
`min_area`	`float`	Minimum contour area in pixels.	`100.0`
`progress_callback`	`Callable[[int, int], None] \| None`	Optional callback(current, total) for progress updates.	`None`

Returns:

Type	Description
`dict[str, int]`	Dictionary with conversion statistics:
`dict[str, int]`	"images": Total images processed
`dict[str, int]`	"labels": Total label files created
`dict[str, int]`	"polygons": Total polygons extracted
`dict[str, int]`	"skipped": Images skipped (no mask or empty)
`dict[str, int]`	"warnings": Number of warnings (dimension mismatch, etc.)

`convert_yolo_seg_to_coco`

Convert a YOLO segmentation dataset to standard COCO layout.

Output structure

output/ ├── annotations/instances_{split}.json └── images/{split}/*.jpg

`convert_yolo_seg_to_roboflow_coco`

Convert a YOLO segmentation dataset to Roboflow COCO layout.

Output structure

output/ ├── train/_annotations.coco.json ├── valid/_annotations.coco.json └── test/_annotations.coco.json

`convert_yolo_seg_to_roboflow_coco_rle`

Convert a YOLO segmentation dataset to Roboflow COCO layout with RLE.

Output structure

output/ ├── train/_annotations.coco.json ├── valid/_annotations.coco.json └── test/_annotations.coco.json

Python API reference

Dataset classes

YOLODataset

detect(path) classmethod

get_annotations_for_image(image_path)

get_image_counts()

get_image_paths(split=None)

get_images_by_class(split=None)

get_instance_counts()

get_split_dirs(split)

COCODataset

is_roboflow_layout property

detect(path) classmethod

get_annotations_for_image(image_path)

get_class_mapping()

get_image_counts()

get_image_paths(split=None)

get_instance_counts()

get_split_dir_name(split)

load_mask(image_path)

MaskDataset

detect(path) classmethod

get_annotations_for_image(image_path)

get_class_mapping()

get_image_class_presence(split=None)

get_image_counts()

get_image_paths(split=None)

get_instance_counts()

get_mask_path(image_path)

get_pixel_counts(split=None)

load_mask(image_path)

validate_dimensions(image_path)

Split operations

split_yolo_dataset

split_coco_dataset

split_mask_dataset

unsplit_yolo_dataset

unsplit_coco_dataset

unsplit_mask_dataset

Filter operations

filter_yolo_dataset

filter_coco_dataset

filter_mask_dataset

Convert operations

mask_to_polygons

convert_mask_to_yolo_labels

convert_mask_to_yolo_seg

convert_yolo_seg_to_coco

convert_yolo_seg_to_roboflow_coco

convert_yolo_seg_to_roboflow_coco_rle

`YOLODataset`

`detect(path)` `classmethod`

`get_annotations_for_image(image_path)`

`get_image_counts()`

`get_image_paths(split=None)`

`get_images_by_class(split=None)`

`get_instance_counts()`

`get_split_dirs(split)`

`COCODataset`

`is_roboflow_layout` `property`

`detect(path)` `classmethod`

`get_annotations_for_image(image_path)`

`get_class_mapping()`

`get_image_counts()`

`get_image_paths(split=None)`

`get_instance_counts()`

`get_split_dir_name(split)`

`load_mask(image_path)`

`MaskDataset`

`detect(path)` `classmethod`

`get_annotations_for_image(image_path)`

`get_class_mapping()`

`get_image_class_presence(split=None)`

`get_image_counts()`

`get_image_paths(split=None)`

`get_instance_counts()`

`get_mask_path(image_path)`

`get_pixel_counts(split=None)`

`load_mask(image_path)`

`validate_dimensions(image_path)`

`split_yolo_dataset`

`split_coco_dataset`

`split_mask_dataset`

`unsplit_yolo_dataset`

`unsplit_coco_dataset`

`unsplit_mask_dataset`

`filter_yolo_dataset`

`filter_coco_dataset`

`filter_mask_dataset`

`mask_to_polygons`

`convert_mask_to_yolo_labels`

`convert_mask_to_yolo_seg`

`convert_yolo_seg_to_coco`

`convert_yolo_seg_to_roboflow_coco`

`convert_yolo_seg_to_roboflow_coco_rle`