# coco_parser

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

## Classes

| Name | Description |
| --- | --- |
|
[`COCOParser`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Parse a directory with COCO annotations into LDF. |

### class `COCOParser`

```python
class COCOParser(BaseParser)
```

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

| Name | Description |
| --- | --- |
|
[`discover_dir_splits`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Return present and valid split directories keyed by their canonical split names. |
|
[`from_dir`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Parse all COCO splits in a source dataset directory. |
|
[`from_split`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Parse COCO annotations into LDF records. |
|
[`validate`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Validate whether the dataset directory has the expected format. |
|
[`validate_split`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Validate whether a split directory has the expected format. |

#### class method `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.

#### method `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.

Args

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

Returns

| Type | Description |
| --- | --- |
| `tuple[list[Path], list[Path], list[Path]]` | Added images for the train, validation, and test splits. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If the dataset directory, train split, validation split, or present test split is not in a recognized COCO
layout. |

#### method `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.

The method also builds the skeleton metadata. It reads every category that holds both a `keypoints` field and a `skeleton` field.
It uses `keypoints` as the keypoint labels, and it converts the `skeleton` pairs to edges. COCO numbers the skeleton joints from
1, so the method subtracts 1 from each index.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `image_dir` | `Path` | Directory with images. | required |
| `annotation_path` | `Path` | Annotation JSON file. | required |

Returns

| Type | Description |
| --- | --- |
| `ParserOutput` | Parser output containing annotation records, skeleton metadata, and added images. |

#### class method `validate`

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

Validate whether the dataset directory has the expected format.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_dir` | `Path` | Source dataset directory. | required |

Returns

| Type | Description |
| --- | --- |
| `bool` | Whether the dataset is in the expected format. |

#### static method `validate_split`

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

Validate whether a split directory has the expected format.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `split_path` | `Path` | Path to a split directory. | required |

Returns

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

## Functions

| Name | Description |
| --- | --- |
|
[`clean_annotations`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/parsers/coco_parser.md)
| Remove COCO images that are known to cause parsing issues. |

### function `clean_annotations`

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

Remove COCO images that are known to cause parsing issues.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `annotation_path` | `Path` | Annotation JSON file. | required |

Returns

| Type | Description |
| --- | --- |
| `Path` | Path to the cleaned annotation JSON file. |
