general
最后更新
luxonis_train.utils.general包中使用的少量辅助函数。这些辅助函数用于舍入通道计数、推断放大因子、检查签名、拆分批处理实例、将文件下载到缓存以及解码文本元数据标签。类
Counter
示例
Pycon
1>>> counter = Counter(start=5)
2>>> counter(), counter(), counter()
3(5, 6, 7)方法
init
Python
1def __init__(start: int = 0):start(int): 计数器返回的第一个值。
函数
clean_url
Python
1def clean_url(url: str) -> str:pathlib.PurePosixPath 规范化 URL。此步骤将重复的斜杠折叠为一个,删除 . 路径组件,并删除尾部斜杠。该函数在第一个 ? 处截断 URL 之前解码转义,因此转义的 %3F 也会截断 URL。示例
Pycon
1>>> clean_url("https://url.com/dir/file%20name.txt?token=abc")
2'https://url.com/dir/file name.txt'
3>>> clean_url("https://url.com//dir/")
4'https://url.com/dir'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之前具有非整数或非浮点值。
示例
Pycon
1>>> import numpy as np
2>>> labels = {
3... "text": np.array([[72.0, 105.0, 0.0], [79.0, 75.0, 33.0]]),
4... "count": np.array([1, 2]),
5... }
6>>> decoded = decode_text_metadata_labels(
7... labels, {"text": str, "count": int}
8... )
9>>> decoded["text"].tolist()
10['Hi', 'OK!']
11>>> decoded["count"].tolist()
12[1, 2]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。属性使用它来公开构造函数可以未设置的值。示例
Pycon
1>>> class Person:
2... def __init__(self, age: int | None = None):
3... self._age = age
4...
5... @property
6... def age(self):
7... return get_attribute_check_none(self, "age")Pycon
1>>> mike = Person(20)
2>>> print(mike.age)
320Pycon
1>>> amanda = Person()
2>>> print(amanda.age)
3Traceback (most recent call last):
4ValueError: attribute 'age' was not setobj(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:示例
Pycon
1>>> import torch
2>>> bboxes = torch.tensor([[0, 1], [0, 2], [1, 3]])
3>>> get_batch_instances(1, bboxes).tolist()
4[[3]]
5>>> payload = torch.tensor([10, 20, 30])
6>>> get_batch_instances(0, bboxes, payload).tolist()
7[10, 20]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 中的名称。示例
Pycon
1>>> def forward(self, x, y=1, **kwargs): ...
2>>> list(get_signature(forward))
3['x', 'y']
4>>> list(get_signature(forward, exclude=["y"]))
5['x']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。示例
Pycon
1>>> get_with_default(0.4, "area factor", default=0.53)
20.4value(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:示例
Pycon
1>>> infer_upscale_factor((32, 32), (128, 128))
22
3>>> infer_upscale_factor(16, 64)
42
5>>> infer_upscale_factor(64, 16)
6-2Pycon
1>>> infer_upscale_factor((32, 64), (128, 128))
2Traceback (most recent call last):
3ValueError: Width and height upscale factors are different. ...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 时,空输入不生成任何项。示例
Pycon
1>>> import torch
2>>> bboxes = torch.tensor([[0, 1], [0, 2], [1, 3]])
3>>> keypoints = torch.tensor([[10], [20], [30]])
4>>> for bbox, kpt in instances_from_batch(bboxes, keypoints):
5... print(bbox.tolist(), kpt.tolist())
6[[1], [2]] [[10], [20]]
7[[3]] [[30]]Pycon
1>>> [b.tolist() for b in instances_from_batch(bboxes, batch_size=3)]
2[[[1], [2]], [[3]], []]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。骨干网络和颈部网络使用它来舍入通道计数。示例
Pycon
1>>> make_divisible(37, 8)
240
3>>> make_divisible(40, 8)
440x(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。示例
Pycon
1>>> from pathlib import Path
2>>> safe_download("weights/model.ckpt") == Path("weights/model.ckpt")
3True
4>>> safe_download(None) is None
5Trueurl(PathType | None): 文件的 URL 或路径。None返回None。file(str | None): 保存的文件名。None从url获取文件名。cache_dir(PathType): 缓存目录的根目录。retry(int): 下载失败后重复尝试的次数。force(bool): 当True时,即使文件在缓存中也再次下载。
Path | None: 文件的本地路径,或当所有尝试都失败时为None。对于s3、gcs和gsURL,LuxonisFileSystem.download返回的路径。
to_shape_packet
Python
1def to_shape_packet(packet: Packet[Tensor]) -> Packet[Size]:示例
Pycon
1>>> import torch
2>>> features = [torch.zeros(1, 3), torch.zeros(2, 4)]
3>>> to_shape_packet({"features": features, "boxes": torch.zeros(5, 4)})
4{'features': [torch.Size([1, 3]), torch.Size([2, 4])],
5 'boxes': torch.Size([5, 4])}packet(Packet[Tensor]): 值是张量或张量列表的包。
Packet[Size]: 具有相同键的包。张量变为其torch.Size,张量列表变为torch.Size对象的列表。
url2file
Python
1def url2file(url: str) -> str:示例
Pycon
1>>> url2file("https://url.com/dir/file.txt?token=abc")
2'file.txt'url(str): URL,例如"https://url.com/file.txt?auth"。
str: clean_url 后 URL 的最后一个路径组件,例如"file.txt"。