# coco_parser

Python API: `luxonis_ml.data.parsers.coco_parser`

## Classes

### COCOParser

Parse a directory with COCO annotations into LDF.

Expected formats:

```text
dataset_dir/
├── train/
│   ├── data/
│   │   ├── img1.jpg
│   │   ├── img2.jpg
│   │   └── ...
│   └── labels.json
├── validation/
│   ├── data/
│   └── labels.json
└── test/
    ├── data/
    └── labels.json

This is default format returned when using FiftyOne package.
```

or:

```text
dataset_dir/
    ├── train/
    │   ├── img1.jpg
    │   ├── img2.jpg
    │   └── ...
    │   └── _annotations.coco.json
    ├── valid/
    └── test/

This is one of the formats that Roboflow can generate.
```

#### Methods

##### discover_dir_splits

```python
def discover_dir_splits(dataset_dir: Path) -> dict[str, dict[str, Any]]:
```

Return present and valid split directories keyed by their canonical split names.

##### from_dir

```python
def from_dir(dataset_dir: Path, use_keypoint_ann: bool = False, keypoint_ann_paths: dict[str, str] | None = None, split_val_to_test: bool = True) -> tuple[list[Path], list[Path], list[Path]]:
```

Parse all COCO splits in a source dataset directory.

Parameters

 * `dataset_dir` (`Path`): Source dataset directory.
 * `use_keypoint_ann` (`bool`): Whether to use separate COCO keypoint annotation files for FiftyOne-style datasets.
 * `keypoint_ann_paths` (`dict[str, str] | None`): Optional paths to keypoint annotation files, relative to `dataset_dir` and
   keyed by `"train"`, `"val"`, and `"test"`.
 * `split_val_to_test` (`bool`): Whether to split validation images 50 ⁄ 50 into validation and test when no test annotations are
   available.

Returns

 * `tuple[list[Path], list[Path], list[Path]]`: Added images for the train, validation, and test splits.

Raises

 * `ValueError`: If the dataset directory, train split, validation split, or present test split is not in a recognized COCO
   layout.

##### from_split

```python
def from_split(image_dir: Path, annotation_path: Path) -> ParserOutput:
```

Parse COCO annotations into LDF records.

Annotations include classification, segmentation, object detection, and keypoints when present.

Parameters

 * `image_dir` (`Path`): Directory with images.
 * `annotation_path` (`Path`): Annotation JSON file.

Returns

 * `ParserOutput`: Parser output containing annotation records, skeleton metadata, and added images.

##### validate

```python
def validate(dataset_dir: Path) -> bool:
```

Validate whether the dataset directory has the expected format.

Parameters

 * `dataset_dir` (`Path`): Source dataset directory.

Returns

 * `bool`: Whether the dataset is in the expected format.

##### validate_split

```python
def validate_split(split_path: Path) -> dict[str, Any] | None:
```

Validate whether a split directory has the expected format.

Parameters

 * `split_path` (`Path`): Path to a split directory.

Returns

 * `dict[str, Any] | None`: Keyword arguments for `from_split`, or `None` if the split is not in the expected format.

## Functions

### clean_annotations

```python
def clean_annotations(annotation_path: Path) -> Path:
```

Remove COCO images that are known to cause parsing issues.

Parameters

 * `annotation_path` (`Path`): Annotation JSON file.

Returns

 * `Path`: Path to the cleaned annotation JSON file.