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

本页目录

  • 类
  • Counter
  • 函数
  • clean_url
  • decode_text_metadata_labels
  • get_attribute_check_none
  • get_batch_instances
  • get_signature
  • get_with_default
  • infer_upscale_factor
  • instances_from_batch
  • make_divisible
  • safe_download
  • to_shape_packet
  • url2file
  • 属性
  • T
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Python API: luxonis_train.utils.general包中使用的少量辅助函数。这些辅助函数用于舍入通道计数、推断放大因子、检查签名、拆分批处理实例、将文件下载到缓存以及解码文本元数据标签。

类

Counter

一个计数器,每次调用时返回下一个整数。保存推理渲染的预测写入器为所有批次保留一个计数器。它使用计数器对保存的渲染文件进行编号,或选择每个图像的图像路径。

方法

init
Python
1def __init__(start: int = 0):
初始化计数器。参数
  • start (int): 计数器返回的第一个值。

函数

clean_url

Python
1def clean_url(url: str) -> str:
从 URL 中去除查询字符串并解码百分比转义。该函数首先使用 pathlib.PurePosixPath 规范化 URL。此步骤将重复的斜杠折叠为一个,删除 . 路径组件,并删除尾部斜杠。该函数在第一个 ? 处截断 URL 之前解码转义,因此转义的 %3F 也会截断 URL。参数
  • url (str): URL,例如 "https://url.com/file%20a.txt?auth"。
返回
  • str: 没有第一个 ? 及其后面文本的 URL,其中 %XX 转义已解码,例如 "https://url.com/file a.txt"。

decode_text_metadata_labels

Python
1def decode_text_metadata_labels(labels: dict[str, np.ndarray], metadata_types: dict[str, type]) -> dict[str, np.ndarray]:
从字符代码解码 str 元数据标签。BaseLoaderTorch 将字符串标签转换为其字符代码的 float32 张量。当它整理一批 metadata/text 标签时,它用 0 填充较短的行。此函数为 metadata_types 中类型为 str 的每个标签反转此操作:
  • 每行都成为其代码的字符串,直到第一个 0。
  • 一维数组算作一行。
  • 代码可以是整数或整数值浮点数。
该函数将所有其他标签转换为 np.asarray 数组。在以下情况下,str 标签保持不变:
  • 其数组为空或具有字符串或对象 dtype。
  • 一行在其第一个 0 之前具有负值。
  • 一行在其第一个 0 之前具有小数。
  • 一行在其第一个 0 之前具有非整数或非浮点值。
参数
  • labels (dict[str, np.ndarray]): 标签名称映射到其标签数组。
  • metadata_types (dict[str, type]): 标签名称映射到其元数据值的类型。此处缺失的标签不会被函数解码。
返回
  • dict[str, np.ndarray]: 相同的标签名称。解码后的 str 标签是一个字符串数组,每行一个。

get_attribute_check_none

Python
1def get_attribute_check_none(obj: object, attribute: str) -> Any:
获取私有属性 _<attribute> 并拒绝 None。属性使用它来公开构造函数可以未设置的值。参数
  • obj (object): 包含属性的对象。
  • attribute (str): 不带前导下划线的属性名称。
返回
  • Any: obj._<attribute> 的值。
引发
  • AttributeError: 当 obj 没有属性 _<attribute> 时。
  • ValueError: 当值为 None 时。

get_batch_instances

Python
1def get_batch_instances(batch_index: int, bboxes: Tensor, payload: Tensor | None = None) -> Tensor:
从批处理实例数据中选择一个图像的行。参数
  • batch_index (int): 图像在批次中的索引。
  • bboxes (Tensor): 整个批次的边界框,形状为 [N, C],批次索引在第一列。
  • payload (Tensor | None): 形状为 [N, ...] 的张量,每行对应 bboxes 的一行,顺序相同。None 从 bboxes 本身选择。
返回
  • Tensor: 批次索引等于 batch_index 的行。从 bboxes 中,它们不带第一列,形状为 [n, C - 1]。从 payload 中,它们带所有列,因此 payload 中的批次索引列保留。

get_signature

Python
1def get_signature(func: Callable, exclude: Collection[str] | None = None) -> dict[str, Parameter]:
获取函数参数,不包括排除的参数。该函数始终省略参数 self 和 kwargs。它还省略 exclude 中的名称。参数
  • func (Callable): 要检查的函数或方法。
  • exclude (Collection[str] | None): 更多要省略的参数名称。None 仅排除 "self" 和 "kwargs"。
返回
  • dict[str, Parameter]: 剩余的参数名称,按签名顺序排列,映射到其 inspect.Parameter 对象。

get_with_default

Python
1def get_with_default(value: T | None, action_name: str, caller_name: str | None = None, *, default: T) -> T:
返回 value,当 value 为 None 时返回 default。当函数返回 default 时,它会记录一条信息消息,其中包含 action_name。参数
  • value (T | None): 当不为 None 时返回的值。
  • action_name (str): 值的作用,在日志消息中命名。
  • caller_name (str | None): 调用者的名称,用作日志消息的前缀。None 不添加前缀。
  • default (T): 当 value 为 None 时返回的值。
返回
  • T: 当 value 不为 None 时为 value,否则为 default。

infer_upscale_factor

Python
1def infer_upscale_factor(in_size: tuple[int, int] | int, orig_size: tuple[int, int] | int) -> int:
推断从一个大小到另一个大小的倍增次数。该函数返回指数 n,其中 o = i⋅2n,i 是输入大小,o 是原始大小。结果不是因子 2n 本身。当原始大小较小时,n 为负数。分割头使用 n 作为上采样步数,或从中计算比例因子 2n。参数
  • in_size (tuple[int, int] | int): 输入大小为 (height, width),或一个整数表示两者。
  • orig_size (tuple[int, int] | int): 原始大小为 (height, width),或一个整数表示两者。
返回
  • int: 指数 n。
引发
  • ValueError: 当宽度比或高度比不是 2 的幂时,当两个指数不同时,或当大小不为正时。

instances_from_batch

Python
1def instances_from_batch(bboxes: Tensor, *args: Tensor, batch_size: int | None = None) -> Iterator[Tensor | tuple[Tensor, ...]]:
从批处理实例数据中生成每个图像的实例。批次索引在 bboxes 的第一列。args 中的额外张量每行对应 bboxes 的一行,顺序相同。该函数使用 bboxes 的批次索引选择它们的行并保留所有列。对象关键点相似度度量将目标关键点作为额外张量传递。该函数为从 0 到 batch_size - 1 的每个图像索引生成一个项。当 batch_size 为 None 或 0 时,项数是最大批次索引加一。在这种情况下,该函数不会为批次末尾没有实例的图像生成项。当 bboxes 为空时,该函数从 torch.empty_like 生成新的空张量,具有输入的形状。边界框保留批次索引列。当 batch_size 为 None 或 0 时,空输入不生成任何项。参数
  • bboxes (Tensor): 整个批次的边界框,形状为 [N, C],批次索引在第一列。
  • *args (Tensor): 形状为 [N, ...] 的额外张量,与 bboxes 顺序相同。
  • batch_size (int | None): 要生成的图像数量。None 或 0 从最大批次索引推断。
返回
  • Iterator[Tensor | tuple[Tensor, ...]]
生成
  • 没有额外张量时,一个图像的边界框,删除了批次索引列,形状为 [n, C - 1]。有额外张量时,一个元组,包含这些边界框,后跟 args 中每个张量的匹配行。
引发
  • ValueError: 当 args 中的张量长度与 bboxes 不同时。错误在迭代开始时发生,而不是在代码调用函数时发生。

make_divisible

Python
1def make_divisible(x: float, divisor: int) -> int:
将 x 向上舍入到 divisor 的最近倍数。该函数计算 ⌈x ⁄ d⌉⋅d,其中 d 是 divisor。骨干网络和颈部网络使用它来舍入通道计数。参数
  • x (float): 要舍入的值。
  • divisor (int): 结果的倍数。
返回
  • int: 不小于 x 的 divisor 的最小倍数。

safe_download

Python
1def safe_download(url: PathType | None, file: str | None = None, cache_dir: PathType = '.cache/luxonis_train', retry: int = 3, force: bool = False) -> Path | None:
将远程文件下载到缓存并返回其本地路径。该函数返回未更改的 pathlib.Path。它将没有远程协议的 str 转换为 pathlib.Path。它不检查本地文件是否存在。该函数将远程文件保存为 cache_dir/<version>/<file>,其中 <version> 是 luxonis_train 版本。如果该目录不存在,它会创建该目录。它会重用已存在的文件并记录警告,除非 force 为 True。下载之前,它会记录一条信息消息,其中包含本地路径和 URL。记录的 URL 来自 clean_url 且没有查询字符串。该函数使用 LuxonisFileSystem.download 下载 s3、gcs 和 gs URL,并使用 torch.hub.download_url_to_file 下载所有其他 URL。尝试失败后,它会记录回溯并再次尝试,最多再尝试 retry 次。当所有尝试都失败时,它会记录警告并返回 None。参数
  • url (PathType | None): 文件的 URL 或路径。None 返回 None。
  • file (str | None): 保存的文件名。None 从 url 获取文件名。
  • cache_dir (PathType): 缓存目录的根目录。
  • retry (int): 下载失败后重复尝试的次数。
  • force (bool): 当 True 时,即使文件在缓存中也再次下载。
返回
  • Path | None: 文件的本地路径,或当所有尝试都失败时为 None。对于 s3、gcs 和 gs URL,LuxonisFileSystem.download 返回的路径。

to_shape_packet

Python
1def to_shape_packet(packet: Packet[Tensor]) -> Packet[Size]:
将张量包转换为其形状包。LuxonisOutput 在其字符串形式中使用它来显示节点的输出形状。模型在构建节点时使用它,为每个节点提供其输入的形状。参数
  • packet (Packet[Tensor]): 值是张量或张量列表的包。
返回
  • Packet[Size]: 具有相同键的包。张量变为其 torch.Size,张量列表变为 torch.Size 对象的列表。

url2file

Python
1def url2file(url: str) -> str:
从 URL 获取文件名。参数
  • url (str): URL,例如 "https://url.com/file.txt?auth"。
返回
  • str: clean_url 后 URL 的最后一个路径组件,例如 "file.txt"。

属性

T