# ultralytics_ndjson_parser

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

## 类

### UltralyticsNDJSONParser

将 Ultralytics NDJSON 数据集解析为 LDF。

NDJSON 记录可以携带自己的拆分名称。当图像记录中不存在拆分时，图像被分配给 `"train"`。`"valid"` 和 `"validation"` 被规范化为 `"val"`。

图像记录通过两个字段定位其图像：

 * `file` 命名本地图像。相对路径根据包含 `.ndjson` 清单的目录进行解析。绝对路径按原样使用。
 * `url` 命名远程图像。解析器下载它，然后 `file` 只提供缓存的文件名。解析器将 URL 的哈希附加到该名称，并将图像写入每个拆分的缓存目录。

因此，包含 `url` 的记录从不读取本地 `file` 路径。一个清单可以描述一个完全远程的数据集。

#### 方法

##### from_dir

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

将 Ultralytics NDJSON 文件解析为数据集记录。

参数

 * `dataset_dir` (`Path`): 包含一个 `.ndjson` 文件的目录，或 `.ndjson` 文件的直接路径。
 * `reuse_cached` (`bool`): 是否重用已缓存的远程图像（如果它们已存在）。
 * `**kwargs`: 解析器特定参数。

返回

 * `tuple[list[Path], list[Path], list[Path]]`: 训练、验证和测试拆分中添加的图像。

抛出

 * `ValueError`: 如果无法解析 NDJSON 数据集文件，解析的文件具有无效的标头，远程图像下载目录已存在，或者姿势注释无法推断关键点维度。

##### from_split

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

解析单个 Ultralytics NDJSON 文件。

参数

 * `ndjson_path` (`Path`): Ultralytics NDJSON 文件的路径。
 * `reuse_cached` (`bool`): 是否重用已缓存的远程图像（如果它们已存在）。

返回

 * `ParserOutput`: 包含注释记录、空骨架元数据和添加图像的解析器输出。

抛出

 * `ValueError`: 如果文件具有无效的标头，远程图像下载目录已存在，或者姿势注释无法推断关键点维度。

##### parse_dir

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

解析完整的 NDJSON 数据集并保留记录级拆分。

参数

 * `dataset_dir` (`Path`): 包含一个 `.ndjson` 文件的目录，或 `.ndjson` 文件的直接路径。
 * `reuse_cached` (`bool`): 是否重用已缓存的远程图像（如果它们已存在）。
 * `**kwargs`: 解析器特定参数。可以提供 `split_ratios` 以重新采样拆分分配。

返回

 * `BaseDataset`: 包含已解析图像和注释的数据集。

抛出

 * `ValueError`: 如果 NDJSON 文件无法解析或无法解析为有效的 Ultralytics 数据集。

##### 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:
```

解析表示单个解析器输入的 NDJSON 文件。

参数

 * `split` (`str | None`): 可选的拆分名称，用于分配给所有已解析的图像。
 * `random_split` (`bool`): 百分比 `split_ratios` 是否应重新采样所有图像。
 * `split_ratios` (`dict[str, float | int] | None`): 可选的比率或计数。浮点值被视为比率；整数值被视为计数。
 * `reuse_cached` (`bool`): 是否重用已缓存的远程图像（如果它们已存在）。
 * `**kwargs`: 解析器特定参数。必须包含 `ndjson_path`。

返回

 * `BaseDataset`: 包含已解析图像和注释的数据集。

抛出

 * `ValueError`: 如果缺少 `ndjson_path`，文件具有无效的标头，远程图像下载目录已存在，或者姿势注释无法推断关键点维度。

##### validate

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

验证数据集目录是否具有预期格式。

参数

 * `dataset_dir` (`Path`): 源数据集目录。

返回

 * `bool`: 数据集是否为预期格式。

##### validate_split

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

验证拆分目录是否具有预期格式。

参数

 * `split_path` (`Path`): 拆分目录的路径。

返回

 * `dict[str, Any] | None`: `from_split` 的关键字参数，如果拆分不是预期格式，则为 `None`。
