此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 类
  • LuxonisDataset
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

luxonis_dataset

最后更新
Python API: luxonis_ml.data.datasets.luxonis_dataset

类

LuxonisDataset

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

方法

init
Python
1def __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
1def add(generator: DatasetIterator, batch_size: int = 1000000) -> Self:
从记录生成器向数据集添加数据。参数
  • generator (DatasetIterator): 生成器应生成可转换为 DatasetRecord 对象的字典或实际的 DatasetRecord 实例。每条记录必须至少包含一个文件路径,并且可以选择包含一个注释和一个任务名称。对于附加到整个样本而不是单个注释的值,请使用 sample_metadata。 例如:
    Python
    1def record_generator():
    2    yield {
    3        "file": "/path/to/image.jpg",
    4        "task_name": "animals",
    5
    6        "sample_metadata": {
    7            "record_id": 123,
    8            "camera": "left",
    9            "tags": ["night", "warehouse"],
    10        },
    11
    12        "annotation": {
    13            "instance_id": 1,
    14            "class": "cat",
    15            "boundingbox": {
    16                "x": 0.10,
    17                "y": 0.20,
    18                "w": 0.30,
    19                "h": 0.40,
    20            },
    21            "keypoints": {
    22                "keypoints": [
    23                    (0.15, 0.25, 1),
    24                    (0.50, 0.60, 1),
    25                    (0.70, 0.80, 0),
    26                ],
    27            },
    28            "instance_segmentation": {
    29                "mask": "/path/to/mask.png",
    30            },
    31        },
    32    }
    LuxonisLoader 通过 LoaderOutput.metadata 返回 sample_metadata。annotation["metadata"] 下的注释元数据是不同的:它成为元数据标签任务。
  • batch_size (int): 在写入存储之前批量处理的记录数。较大的批量大小可能更高效,但会使用更多内存。
返回
  • Self
引发
  • ValueError: 如果生成器生成的记录格式不符合预期。
  • ValueError: 如果数据集包含类型冲突的元数据注释。
clone
Python
1def 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
1def delete_dataset(*, delete_remote: bool = False, delete_local: bool = False):
从本地存储中删除数据集,并可选择从云端删除。参数
  • delete_remote (bool): 是否删除远程数据集。
  • delete_local (bool): 是否删除本地数据集文件。
引发
  • ValueError: 如果 delete_remote 和 delete_local 都未设置为 True。
exists
Python
1def 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
1def 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
1def get_categorical_encodings(self) -> dict[str, dict[str, int]]:
获取按任务分组的数据集的分类编码。示例输出:
Python
1{
2    "vehicles": {
3        "color": {"red": 0, "green": 1, "blue": 2},
4        "brand": {"audi": 0, "bmw": 1, "mercedes": 2},
5    }
6}
get_classes
Python
1def get_classes(self) -> dict[str, dict[str, int]]:
获取每个任务的类名和 ID。返回
  • 从类名到按任务名分组的类 ID 的映射:
    Pycon
    1{
    2    "color": {"red": 0, "green": 1, "blue": 2},
    3    "brand": {"audi": 0, "bmw": 1, "mercedes": 2},
    4}
get_metadata_types
Python
1def get_metadata_types(self) -> dict[str, Literal['float', 'int', 'str', 'Category']]:
获取数据集中每个元数据注释的元数据类型。示例输出:
Python
1{
2    "id": "int",
3    "time_of_day": "Category",
4    "temperature": "float",
5}
get_skeletons
Python
1def 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
1def get_source_names(self) -> list[str]:
返回数据集的输入源名称。返回
  • list[str]: 用于识别输入数据的源名称。
get_splits
Python
1def get_splits(self) -> dict[str, list[str]] | None:
获取数据集拆分定义。返回
  • dict[str, list[str]] | None: 拆分名称到 UUID 列表的映射,如果未定义拆分,则为 None。
get_statistics
Python
1def 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
1def get_tasks(self) -> dict[str, list[str]]:
返回任务名称和任务类型。返回
  • dict[str, list[str]]: 按任务名称键入的任务类型。
list_datasets
Python
1def 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
1def make_splits(splits: Mapping[str, Sequence[PathType]] | Mapping[str, float] | tuple[float, float, float] | None = None, *, replace_old_splits: bool = False):
创建用于训练、验证和测试的数据集拆分。参数
  • 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
1def 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
1def 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
1def 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
1def remove_duplicates(self):
从数据集中删除重复的文件和注释。引发
  • FileNotFoundError: 如果数据集为空。
set_class_order_per_task
Python
1def 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
1def 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
1def 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
1def set_tasks(tasks: Mapping[str, Iterable[str]]):
设置数据集任务。参数
  • tasks (Mapping[str, Iterable[str]]): 从任务名称到任务类型的映射。
update_source
Python
1def update_source(source: LuxonisSource):
更新数据集源定义。参数
  • source (LuxonisSource): 要存储的源定义。

属性

bucket_storage
数据集的底层存储后端。
bucket_type
数据集使用内部还是外部存储桶。
dataset_name
数据集的名称。
identifier
数据集的唯一标识符。
is_remote
数据集是远程存储(在云存储桶中)还是本地存储。
metadata
获取数据集元数据。返回
  • 数据集元数据的深层副本。
source
获取数据集的源信息。返回
  • 数据集源元数据。
引发
  • ValueError: 如果源元数据缺失。
team_id
可选的云团队标识符。
version
数据集遵循的底层 LDF 版本。