# luxonis_dataset

Python API: `luxonis_ml.data.datasets.luxonis_dataset`

## 类

### LuxonisDataset

Luxonis 数据集格式 (LDF) 数据集句柄。

LDF 是一种灵活且功能丰富的数据集格式，专为 Luxonis MLOps 生态系统设计。

#### 方法

##### init

```python
def __init__(dataset_name: str, team_id: str | None = None, bucket_type: BucketType | Literal['internal', 'external'] = BucketType.INTERNAL, bucket_storage: BucketStorage | Literal['local', 'gcs', 's3', 'azure'] = BucketStorage.LOCAL, *, delete_local: bool = False, delete_remote: bool = False):
```

创建 Luxonis 数据集格式数据集句柄。

参数

 * `dataset_name` (`str`): 数据集名称。
 * `team_id` (`str | None`): 可选的云团队标识符。
 * `bucket_type` (`BucketType | Literal['internal', 'external']`): 数据集使用内部还是外部存储桶。
 * `bucket_storage` (`BucketStorage | Literal['local', 'gcs', 's3', 'azure']`): 底层存储后端。
 * `delete_local` (`bool`): 初始化前是否删除同名本地数据集。
 * `delete_remote` (`bool`): 是否同时删除远程数据集。

引发

 * `ValueError`: 如果数据集存在且未设置删除标志。
 * `ValueError`: 如果数据集是远程的但未配置存储桶。
 * `NotImplementedError`: 如果选择 Azure Blob Storage 作为存储桶存储。

##### add

```python
def add(generator: DatasetIterator, batch_size: int = 1000000) -> Self:
```

从记录生成器向数据集添加数据。

参数

 * `generator` (`DatasetIterator`): 生成器应生成可转换为 `DatasetRecord` 对象的字典或实际的 `DatasetRecord`
   实例。每条记录必须至少包含一个文件路径，并且可以选择包含一个注释和一个任务名称。对于附加到整个样本而不是单个注释的值，请使用 `sample_metadata`。 例如：```python
   def record_generator():
       yield {
           "file": "/path/to/image.jpg",
           "task_name": "animals",
           "sample_metadata": {
               "record_id": 123,
               "camera": "left",
               "tags": ["night", "warehouse"],
           },
           "annotation": {
               "instance_id": 1,
               "class": "cat",
               "boundingbox": {
                   "x": 0.10,
                   "y": 0.20,
                   "w": 0.30,
                   "h": 0.40,
               },
               "keypoints": {
                   "keypoints": [
                       (0.15, 0.25, 1),
                       (0.50, 0.60, 1),
                       (0.70, 0.80, 0),
                   ],
               },
               "instance_segmentation": {
                   "mask": "/path/to/mask.png",
               },
           },
       }
   ```
   [LuxonisLoader](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/loaders/luxonis_loader.md) 通过 [LoaderOutput.metadata](/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/typing.md) 返回 `sample_metadata`。`annotation["metadata"]` 下的注释元数据是不同的：它成为元数据标签任务。
 * `batch_size` (`int`): 在写入存储之前批量处理的记录数。较大的批量大小可能更高效，但会使用更多内存。

返回

 * `Self`

引发

 * `ValueError`: 如果生成器生成的记录格式不符合预期。
 * `ValueError`: 如果数据集包含类型冲突的元数据注释。

##### clone

```python
def clone(new_dataset_name: str, push_to_cloud: bool = True, splits_to_clone: list[str] | None = None, team_id: str | None = None)
-> LuxonisDataset:
```

创建当前数据集的本地副本。

> **警告**
> 克隆的数据集会覆盖任何同名现有数据集。

参数

 * `new_dataset_name` (`str`): 克隆数据集的名称。
 * `push_to_cloud` (`bool`): 当当前数据集是远程数据集时，是否将克隆的数据集推送到云端。
 * `splits_to_clone` (`list[str] | None`): 要克隆的可选拆分名称。如果省略，则克隆所有数据。
 * `team_id` (`str | None`): 克隆数据集的可选团队标识符。

返回

 * `LuxonisDataset`: 克隆的数据集句柄。

引发

 * `FileNotFoundError`: 如果当前数据集为空且指定了 `splits_to_clone`。

##### delete_dataset

```python
def delete_dataset(*, delete_remote: bool = False, delete_local: bool = False):
```

从本地存储中删除数据集，并可选择从云端删除。

参数

 * `delete_remote` (`bool`): 是否删除远程数据集。
 * `delete_local` (`bool`): 是否删除本地数据集文件。

引发

 * `ValueError`: 如果 `delete_remote` 和 `delete_local` 都未设置为 `True`。

##### exists

```python
def exists(dataset_name: str, team_id: str | None = None, bucket_storage: BucketStorage = BucketStorage.LOCAL, bucket: str | None
= None) -> bool:
```

检查数据集是否存在。

参数

 * `dataset_name` (`str`): 要检查的数据集名称。
 * `team_id` (`str | None`): 可选的团队标识符。
 * `bucket_storage` (`BucketStorage`): 要检查的存储后端。
 * `bucket` (`str | None`): 远程存储的可选存储桶名称。

返回

 * `bool`: 如果数据集存在，则为 `True`，否则为 `False`。

引发

 * `ValueError`: 如果存储桶存储是远程的但未提供存储桶名称。

##### export

```python
def export(output_path: PathType, dataset_type: DatasetType = DatasetType.NATIVE, max_partition_size_gb: float | None = None,
zip_output: bool = False, ldf_version: str | None = None) -> Path | list[Path]:
```

将数据集导出为支持的格式之一。

参数

 * `output_path` (`PathType`): 应导出数据集的目录。
 * `dataset_type` (`DatasetType`): 导出格式。
 * `max_partition_size_gb` (`float | None`): 可选的最大分区大小。如果数据集超过此大小，它将被拆分为名为 `{dataset_name}_part{partition_number}` 的分区。
 * `zip_output` (`bool`): 导出后是否压缩导出的数据集或每个分区。
 * `ldf_version` (`str | None`): 要写入的 LDF 版本，例如 `"2.0"`，以便旧版 luxonis-ml 可以读取导出。仅限原生格式。默认为此安装写入的版本。降级会丢失数据并警告其丢弃的内容。

返回

 * `Path | list[Path]`: 导出目录，或启用 `zip_output` 时的 ZIP 存档路径。

引发

 * `NotImplementedError`: 如果指定的导出格式不受支持。
 * `ValueError`: 如果输出路径已存在，或者 `ldf_version` 设置为非原生格式或命名了此安装无法写入的版本。

##### get_categorical_encodings

```python
def get_categorical_encodings(self) -> dict[str, dict[str, int]]:
```

获取按任务分组的数据集的分类编码。

示例输出：

```python
{
    "vehicles": {
        "color": {"red": 0, "green": 1, "blue": 2},
        "brand": {"audi": 0, "bmw": 1, "mercedes": 2},
    }
}
```

##### get_classes

```python
def get_classes(self) -> dict[str, dict[str, int]]:
```

获取每个任务的类名和 ID。

返回

 * `从类名到按任务名分组的类 ID 的映射`:```pycon
   {
       "color": {"red": 0, "green": 1, "blue": 2},
       "brand": {"audi": 0, "bmw": 1, "mercedes": 2},
   }
   ```

##### get_metadata_types

```python
def get_metadata_types(self) -> dict[str, Literal['float', 'int', 'str', 'Category']]:
```

获取数据集中每个元数据注释的元数据类型。

示例输出：

```python
{
    "id": "int",
    "time_of_day": "Category",
    "temperature": "float",
}
```

##### get_skeletons

```python
def get_skeletons(self) -> dict[str, tuple[list[str], list[tuple[int, int]]]]:
```

返回每个任务的关键点骨架。

返回

 * `dict[str, tuple[list[str], list[tuple[int, int]]]]`: 按任务名称键入的关键点标签和边。

##### get_source_names

```python
def get_source_names(self) -> list[str]:
```

返回数据集的输入源名称。

返回

 * `list[str]`: 用于识别输入数据的源名称。

##### get_splits

```python
def get_splits(self) -> dict[str, list[str]] | None:
```

获取数据集拆分定义。

返回

 * `dict[str, list[str]] | None`: 拆分名称到 UUID 列表的映射，如果未定义拆分，则为 `None`。

##### get_statistics

```python
def get_statistics(sample_size: int | None = None, view: str | None = None) -> dict[str, Any]:
```

返回视图或完整数据集的数据集统计信息。

返回的统计信息包括：

 * `"duplicates"`: 重复内容的分析。
 * `"class_distributions"`: 按任务名称和任务类型组织的类频率。分类任务被排除。
 * `"missing_annotations"`: 缺少注释的文件路径。
 * `"heatmaps"`: 空间注释分布。

参数

 * `sample_size` (`int | None`): 用于生成热图的可选样本数。
 * `view` (`str | None`): 要分析的可选拆分名称。如果省略，则分析整个数据集。

返回

 * `dict[str, Any]`: 数据集统计信息。

##### get_tasks

```python
def get_tasks(self) -> dict[str, list[str]]:
```

返回任务名称和任务类型。

返回

 * `dict[str, list[str]]`: 按任务名称键入的任务类型。

##### list_datasets

```python
def list_datasets(team_id: str | None = None, bucket_storage: BucketStorage = BucketStorage.LOCAL, bucket: str | None = None) -> list[str]:
```

列出可用数据集。

参数

 * `team_id` (`str | None`): 可选的团队标识符。
 * `bucket_storage` (`BucketStorage`): 要检查的存储后端。
 * `bucket` (`str | None`): 远程存储的可选存储桶名称。

返回

 * `list[str]`: 数据集名称列表。

引发

 * `ValueError`: 如果存储桶存储是远程的但未提供存储桶名称。
 * `ValueError`: 如果数据集存储在远程但未提供 `bucket` 参数或未设置 `LUXONISML_BUCKET` 环境变量。

##### make_splits

```python
def make_splits(splits: Mapping[str, Sequence[PathType]] | Mapping[str, float] | tuple[float, float, float] | None = None, *, replace_old_splits: bool = False):
```

创建用于训练、验证和测试的数据集拆分。

> **注意**
> 尽管 `"train"`、`"val"` 和 `"test"` 是传统的拆分名称，但您可以通过向 `splits` 参数提供映射来使用任何您想要的拆分名称。这对于组合来自多个源的记录（`"train_real"`、`"train_synth"`）或创建完全自定义的拆分非常有用。

参数

 * `splits` (`Mapping[str, Sequence[PathType]] | Mapping[str, float] | tuple[float, float, float] | None`): 定义拆分的映射。可以是以下之一： *
   拆分名称到文件路径列表的映射。
    * 拆分名称到比率的映射。
    * 训练、验证和测试拆分的三个比率的元组。 比率是 0 到 1 之间的数字，比率之和为 1。`1` 和 `1.0` 都有效。
 * `replace_old_splits` (`bool`): 是否用新拆分替换旧拆分。如果为 `False`（默认），则将新拆分添加到现有拆分中。如果为 `True`，则首先丢弃现有拆分。

引发

 * `TypeError`: 如果映射值既不是比率也不是文件路径列表。该方法会警告并跳过文件路径列表中不是文件路径的每个元素。
 * `ValueError`: 如果提供了 `splits` 但为空。
 * `ValueError`: 如果比率超出 0 到 1 的范围或总和不为 1。
 * `ValueError`: 如果使用了拆分比率但所有数据都已属于某个拆分，而 `replace_old_splits` 为 `False`。
 * `FileNotFoundError`: 如果数据集为空。

##### merge_with

```python
def merge_with(other: LuxonisDataset, inplace: bool = True, new_dataset_name: str | None = None, splits_to_merge: list[str] | None = None, team_id: str | None = None) -> LuxonisDataset:
```

将另一个数据集合并到此数据集或新数据集中。

参数

 * `other` (`LuxonisDataset`): 要合并到此数据集的数据集。
 * `inplace` (`bool`): 是否合并到此数据集。如果为 `False`，则创建新数据集。
 * `new_dataset_name` (`str | None`): 当 `inplace` 为 `False` 时新数据集的名称。
 * `splits_to_merge` (`list[str] | None`): 要合并的可选拆分名称。
 * `team_id` (`str | None`): 新创建数据集的可选团队标识符。

返回

 * `LuxonisDataset`: 包含合并数据的数据集。

引发

 * `ValueError`: 如果数据集具有不同的存储桶存储类型。
 * `ValueError`: 如果 `inplace` 为 `False` 但未提供新数据集的名称。

##### pull_from_cloud

```python
def pull_from_cloud(update_mode: UpdateMode = UpdateMode.MISSING):
```

将数据集从远程存储桶同步到本地存储。

注释和元数据始终被拉取。媒体文件根据 `update_mode` 在本地缺失时或始终被拉取。

每次调用时，拉取都会用远程副本覆盖本地 `annotations/` 和 `metadata/` 文件夹，因此对这些文件夹的本地编辑将丢失。

使用 `UpdateMode.MISSING` 时，仅当两个位置都缺失时，媒体文件才算作缺失：

 * Parquet 分片中 `file` 列的路径；
 * `media/<uuid><suffix>`，其中 UUID 来自同一分片的 `uuid` 列。

使用 `UpdateMode.ALL` 时，每个媒体文件都会再次下载并覆盖本地副本。

参数

 * `update_mode` (`UpdateMode`): 媒体同步模式。

##### push_to_cloud

```python
def push_to_cloud(bucket_storage: BucketStorage | None, update_mode: UpdateMode = UpdateMode.MISSING):
```

将本地数据集推送到远程存储桶。

注释和元数据始终被推送。媒体文件根据 `update_mode` 在远程缺失时或始终被推送。

参数

 * `bucket_storage` (`BucketStorage | None`): 要推送到的远程存储后端。如果未设置，则使用数据集当前的存储桶存储类型。
 * `update_mode` (`UpdateMode`): 媒体同步模式。

引发

 * `ValueError`: 如果数据集为空或未初始化。
 * `FileNotFoundError`: 如果尝试推送时任何媒体文件在本地缺失。

##### remove_duplicates

```python
def remove_duplicates(self):
```

从数据集中删除重复的文件和注释。

引发

 * `FileNotFoundError`: 如果数据集为空。

##### set_class_order_per_task

```python
def set_class_order_per_task(class_order_per_task: dict[str, list[str]]):
```

设置特定任务的类顺序。

参数

 * `class_order_per_task` (`dict[str, list[str]]`): 从任务名称到所需顺序的类名称的映射。

引发

 * `ValueError`: 如果任务缺失或提供的类名与该任务的数据集类不匹配。

##### set_classes

```python
def set_classes(classes: list[str] | dict[str, int], task: str | None = None, rewrite_metadata: bool = True):
```

为一个或多个任务设置类。

参数

 * `classes` (`list[str] | dict[str, int]`): 类名，或按类名键入的类 ID。如果提供了类名，则从 0 开始按字母顺序分配 ID。名为 `"background"` 的类始终分配 ID 0。
 * `task` (`str | None`): 要更新的可选任务。如果省略，则更新所有任务。
 * `rewrite_metadata` (`bool`)

##### set_skeletons

```python
def set_skeletons(labels: list[str] | None = None, edges: list[tuple[int, int]] | None = None, task: str | None = None):
```

设置关键点骨架元数据。

参数

 * `labels` (`list[str] | None`): 可选的关键点名称。
 * `edges` (`list[tuple[int, int]] | None`): 可选的关键点边，作为基于 0 的索引对。
 * `task` (`str | None`): 要更新的可选任务。如果省略，则更新所有任务。

引发

 * `ValueError`: 如果 `labels` 和 `edges` 都未提供。

##### set_tasks

```python
def set_tasks(tasks: Mapping[str, Iterable[str]]):
```

设置数据集任务。

参数

 * `tasks` (`Mapping[str, Iterable[str]]`): 从任务名称到任务类型的映射。

##### update_source

```python
def update_source(source: LuxonisSource):
```

更新数据集源定义。

参数

 * `source` (`LuxonisSource`): 要存储的源定义。

#### 属性

##### bucket_storage

数据集的底层存储后端。

##### bucket_type

数据集使用内部还是外部存储桶。

##### dataset_name

数据集的名称。

##### identifier

数据集的唯一标识符。

##### is_remote

数据集是远程存储（在云存储桶中）还是本地存储。

##### metadata

获取数据集元数据。

返回

 * 数据集元数据的深层副本。

##### source

获取数据集的源信息。

返回

 * 数据集源元数据。

引发

 * `ValueError`: 如果源元数据缺失。

##### team_id

可选的云团队标识符。

##### version

数据集遵循的底层 LDF 版本。
