Struct COCO 

pub struct COCO {
    pub dataset: Dataset,
    /* private fields */
}

The COCO dataset API for loading, querying, and indexing annotations.

Fields

dataset: Dataset

Implementations

impl COCO

pub fn new(annotation_file: &Path) -> Result<Self>

Load a COCO annotation JSON file and build indices.

pub fn from_dataset(dataset: Dataset) -> Self

Build a COCO object from an already-loaded Dataset.

pub fn get_ann_ids( &self, img_ids: &[u64], cat_ids: &[u64], area_rng: Option<[f64; 2]>, is_crowd: Option<bool>, ) -> Vec<u64>

Get annotation IDs matching the given filters.

All filter parameters are optional (pass empty slices / None to skip).

pub fn get_cat_ids( &self, cat_nms: &[&str], sup_nms: &[&str], cat_ids: &[u64], ) -> Vec<u64>

Get category IDs matching the given filters.

pub fn get_img_ids(&self, img_ids: &[u64], cat_ids: &[u64]) -> Vec<u64>

Get image IDs matching the given filters.

pub fn load_anns(&self, ids: &[u64]) -> Vec<&Annotation>

Load annotations by IDs.

pub fn load_cats(&self, ids: &[u64]) -> Vec<&Category>

Load categories by IDs.

pub fn load_imgs(&self, ids: &[u64]) -> Vec<&Image>

Load images by IDs.

pub fn get_ann(&self, id: u64) -> Option<&Annotation>

Get a single annotation by ID.

pub fn get_img(&self, id: u64) -> Option<&Image>

Get a single image by ID.

pub fn get_cat(&self, id: u64) -> Option<&Category>

Get a single category by ID.

pub fn get_ann_ids_for_img_cat(&self, img_id: u64, cat_id: u64) -> &[u64]

Get annotation IDs for a specific (image, category) pair.

Single HashMap lookup — much faster than get_ann_ids with filtering.

pub fn get_ann_ids_for_img(&self, img_id: u64) -> &[u64]

Get annotation IDs for a specific image.

pub fn nonempty_img_cat_pairs(&self) -> impl Iterator<Item = (u64, u64)> + '_

Returns (img_id, cat_id) pairs that have at least one annotation.

Used by COCOeval to enumerate only non-empty pairs instead of the full Cartesian product, which is critical for large-scale datasets.

pub fn nonempty_img_ids(&self) -> impl Iterator<Item = u64> + '_

Returns image IDs that have at least one annotation (any category).

Used by COCOeval when use_cats = false (all categories treated as one).

pub fn load_res(&self, res_file: &Path) -> Result<COCO>

Load detection/result annotations into a new COCO object.

The result file can be a JSON array of annotation dicts, or a JSON object with an annotations field. The result COCO object shares the images and categories from self.

pub fn load_res_anns(&self, anns: Vec<Annotation>) -> Result<COCO>

Load detection results from an already-parsed list of annotations.

This is the in-memory equivalent of load_res. It applies the same area, segmentation, and bbox fixups and returns a new COCO object sharing the images and categories from self.

Prefer this over load_res when results are already in memory — it avoids a round-trip through the filesystem. The Python binding uses this internally when load_res is called with a list of dicts or a numpy array.

pub fn ann_to_rle(&self, ann: &Annotation) -> Option<Rle>

Convert an annotation’s segmentation to RLE.

pub fn ann_to_mask(&self, ann: &Annotation) -> Option<Vec<u8>>

Convert an annotation to a binary mask.

pub fn filter( &self, cat_ids: Option<&[u64]>, img_ids: Option<&[u64]>, area_rng: Option<[f64; 2]>, drop_empty_images: bool, ) -> Dataset

Filter the dataset, returning a new Dataset with matching images, annotations, and categories.

Annotations are kept when they match all provided criteria. If drop_empty_images is true, images with no matching annotations are removed; otherwise all images are kept (intersected with img_ids if provided).

pub fn merge(datasets: &[&Dataset]) -> Result<Dataset>

Merge multiple datasets into one.

All datasets must share the same category taxonomy (same names + supercategories). Image and annotation IDs are remapped to ensure global uniqueness.

pub fn split( &self, val_frac: f64, test_frac: Option<f64>, seed: u64, ) -> (Dataset, Dataset, Option<Dataset>)

Split the dataset into train/val (and optionally test) subsets.

Images are shuffled deterministically using seed, then partitioned. All splits share the full category list.

pub fn sample(&self, n: Option<usize>, frac: Option<f64>, seed: u64) -> Dataset

Sample a random subset of images (with their annotations).

Provide either n (exact count) or frac (fraction of images). The sample is deterministic given the same seed.

pub fn stats(&self) -> DatasetStats

Compute dataset health-check statistics.

pub fn healthcheck(&self) -> HealthReport

Run a health check on this dataset.

pub fn healthcheck_compatibility(&self, dt: &COCO) -> HealthReport

Run a health check including GT/DT compatibility.