# ultralytics_ndjson_parser

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

## Classes

### UltralyticsNDJSONParser

Parse Ultralytics NDJSON datasets into LDF.

NDJSON records may carry their own split names. When no split is present on an image record, the image is assigned to `"train"`.
`"valid"` and `"validation"` are normalized to `"val"`.

#### Methods

##### from_dir

```python
def from_dir(dataset_dir: Path, reuse_cached: bool = True, **kwargs) -> tuple[list[Path], list[Path], list[Path]]:
```

Parse an Ultralytics NDJSON file into dataset records.

Parameters

 * `dataset_dir` (`Path`): Directory containing exactly one `.ndjson` file, or a direct path to an `.ndjson` file.
 * `reuse_cached` (`bool`): Whether to reuse cached remote images if they already exist.
 * `**kwargs`: Parser-specific arguments.

Returns

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

Raises

 * `ValueError`: If no NDJSON dataset file can be resolved, the resolved file has an invalid header, a remote image download
   directory already exists, or pose annotations cannot infer keypoint dimensionality.

##### from_split

```python
def from_split(ndjson_path: Path, reuse_cached: bool = True) -> ParserOutput:
```

Parse a single Ultralytics NDJSON file.

Parameters

 * `ndjson_path` (`Path`): Path to an Ultralytics NDJSON file.
 * `reuse_cached` (`bool`): Whether to reuse cached remote images if they already exist.

Returns

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

Raises

 * `ValueError`: If the file has an invalid header, a remote image download directory already exists, or pose annotations cannot
   infer keypoint dimensionality.

##### parse_dir

```python
def parse_dir(dataset_dir: Path, reuse_cached: bool = True, **kwargs) -> BaseDataset:
```

Parse a full NDJSON dataset and preserve record-level splits.

Parameters

 * `dataset_dir` (`Path`): Directory containing exactly one `.ndjson` file, or a direct path to an `.ndjson` file.
 * `reuse_cached` (`bool`): Whether to reuse cached remote images if they already exist.
 * `**kwargs`: Parser-specific arguments. `split_ratios` may be supplied to resample split assignments.

Returns

 * `BaseDataset`: Dataset with parsed images and annotations.

Raises

 * `ValueError`: If the NDJSON file cannot be resolved or parsed as a valid Ultralytics dataset.

##### parse_split

```python
def parse_split(split: str | None = None, random_split: bool = True, split_ratios: dict[str, float | int] | None = None, reuse_cached: bool = True, **kwargs) -> BaseDataset:
```

Parse an NDJSON file that represents a single parser input.

Parameters

 * `split` (`str | None`): Optional split name to assign to all parsed images.
 * `random_split` (`bool`): Whether percentage `split_ratios` should resample all images.
 * `split_ratios` (`dict[str, float | int] | None`): Optional ratios or counts. Float values are treated as ratios; integer values
   are treated as counts.
 * `reuse_cached` (`bool`): Whether to reuse cached remote images if they already exist.
 * `**kwargs`: Parser-specific arguments. Must include `ndjson_path`.

Returns

 * `BaseDataset`: Dataset with parsed images and annotations.

Raises

 * `ValueError`: If `ndjson_path` is missing, the file has an invalid header, a remote image download directory already exists, or
   pose annotations cannot infer keypoint dimensionality.

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