# general

Python API: `luxonis_train.utils.general`

包中使用的少量辅助函数。

这些辅助函数用于舍入通道计数、推断放大因子、检查签名、拆分批处理实例、将文件下载到缓存以及解码文本元数据标签。

## 类

### Counter

一个计数器，每次调用时返回下一个整数。

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

> **示例**
> ```pycon
>>> counter = Counter(start=5)
>>> counter(), counter(), counter()
(5, 6, 7)
```

#### 方法

##### init

```python
def __init__(start: int = 0):
```

初始化计数器。

参数

 * `start` (`int`): 计数器返回的第一个值。

## 函数

### clean_url

```python
def clean_url(url: str) -> str:
```

从 URL 中去除查询字符串并解码百分比转义。

该函数首先使用 `pathlib.PurePosixPath` 规范化 URL。此步骤将重复的斜杠折叠为一个，删除 `.` 路径组件，并删除尾部斜杠。该函数在第一个 `?` 处截断 URL 之前解码转义，因此转义的 `%3F` 也会截断 URL。

> **示例**
> ```pycon
>>> clean_url("https://url.com/dir/file%20name.txt?token=abc")
'https://url.com/dir/file name.txt'
>>> clean_url("https://url.com//dir/")
'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
def decode_text_metadata_labels(labels: dict[str, np.ndarray], metadata_types: dict[str, type]) -> dict[str, np.ndarray]:
```

从字符代码解码 `str` 元数据标签。

[BaseLoaderTorch](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/loaders/base_loader.md)
将字符串标签转换为其字符代码的 `float32` 张量。当它整理一批 `metadata/text` 标签时，它用 `0` 填充较短的行。此函数为 `metadata_types` 中类型为 `str` 的每个标签反转此操作：

 * 每行都成为其代码的字符串，直到第一个 `0`。
 * 一维数组算作一行。
 * 代码可以是整数或整数值浮点数。

该函数将所有其他标签转换为 `np.asarray` 数组。

在以下情况下，`str` 标签保持不变：

 * 其数组为空或具有字符串或对象 dtype。
 * 一行在其第一个 `0` 之前具有负值。
 * 一行在其第一个 `0` 之前具有小数。
 * 一行在其第一个 `0` 之前具有非整数或非浮点值。

> **示例**
> ```pycon
>>> import numpy as np
>>> labels = {
...     "text": np.array([[72.0, 105.0, 0.0], [79.0, 75.0, 33.0]]),
...     "count": np.array([1, 2]),
... }
>>> decoded = decode_text_metadata_labels(
...     labels, {"text": str, "count": int}
... )
>>> decoded["text"].tolist()
['Hi', 'OK!']
>>> decoded["count"].tolist()
[1, 2]
```

参数

 * `labels` (`dict[str, np.ndarray]`): 标签名称映射到其标签数组。
 * `metadata_types` (`dict[str, type]`): 标签名称映射到其元数据值的类型。此处缺失的标签不会被函数解码。

返回

 * `dict[str, np.ndarray]`: 相同的标签名称。解码后的 `str` 标签是一个字符串数组，每行一个。

### get_attribute_check_none

```python
def get_attribute_check_none(obj: object, attribute: str) -> Any:
```

获取私有属性 `_<attribute>` 并拒绝 `None`。

属性使用它来公开构造函数可以未设置的值。

> **示例**
> ```pycon
>>> class Person:
...     def __init__(self, age: int | None = None):
...         self._age = age
...
...     @property
...     def age(self):
...         return get_attribute_check_none(self, "age")
```

```pycon
>>> mike = Person(20)
>>> print(mike.age)
20
```

```pycon
>>> amanda = Person()
>>> print(amanda.age)
Traceback (most recent call last):
ValueError: attribute 'age' was not set
```

参数

 * `obj` (`object`): 包含属性的对象。
 * `attribute` (`str`): 不带前导下划线的属性名称。

返回

 * `Any`: `obj._<attribute>` 的值。

引发

 * `AttributeError`: 当 `obj` 没有属性 `_<attribute>` 时。
 * `ValueError`: 当值为 `None` 时。

### get_batch_instances

```python
def get_batch_instances(batch_index: int, bboxes: Tensor, payload: Tensor | None = None) -> Tensor:
```

从批处理实例数据中选择一个图像的行。

> **示例**
> ```pycon
>>> import torch
>>> bboxes = torch.tensor([[0, 1], [0, 2], [1, 3]])
>>> get_batch_instances(1, bboxes).tolist()
[[3]]
>>> payload = torch.tensor([10, 20, 30])
>>> get_batch_instances(0, bboxes, payload).tolist()
[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
def get_signature(func: Callable, exclude: Collection[str] | None = None) -> dict[str, Parameter]:
```

获取函数参数，不包括排除的参数。

该函数始终省略参数 `self` 和 `kwargs`。它还省略 `exclude` 中的名称。

> **示例**
> ```pycon
>>> def forward(self, x, y=1, **kwargs): ...
>>> list(get_signature(forward))
['x', 'y']
>>> list(get_signature(forward, exclude=["y"]))
['x']
```

参数

 * `func` (`Callable`): 要检查的函数或方法。
 * `exclude` (`Collection[str] | None`): 更多要省略的参数名称。`None` 仅排除 `"self"` 和 `"kwargs"`。

返回

 * `dict[str, Parameter]`: 剩余的参数名称，按签名顺序排列，映射到其 `inspect.Parameter` 对象。

### get_with_default

```python
def 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
>>> get_with_default(0.4, "area factor", default=0.53)
0.4
```

参数

 * `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
def 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。

> **示例**
> ```pycon
>>> infer_upscale_factor((32, 32), (128, 128))
2
>>> infer_upscale_factor(16, 64)
2
>>> infer_upscale_factor(64, 16)
-2
```

```pycon
>>> infer_upscale_factor((32, 64), (128, 128))
Traceback (most recent call last):
ValueError: 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
def 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
>>> import torch
>>> bboxes = torch.tensor([[0, 1], [0, 2], [1, 3]])
>>> keypoints = torch.tensor([[10], [20], [30]])
>>> for bbox, kpt in instances_from_batch(bboxes, keypoints):
...     print(bbox.tolist(), kpt.tolist())
[[1], [2]] [[10], [20]]
[[3]] [[30]]
```

```pycon
>>> [b.tolist() for b in instances_from_batch(bboxes, batch_size=3)]
[[[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
def make_divisible(x: float, divisor: int) -> int:
```

将 `x` 向上舍入到 `divisor` 的最近倍数。

该函数计算 ⌈x ⁄ d⌉⋅d，其中 d 是 `divisor`。骨干网络和颈部网络使用它来舍入通道计数。

> **示例**
> ```pycon
>>> make_divisible(37, 8)
40
>>> make_divisible(40, 8)
40
```

参数

 * `x` (`float`): 要舍入的值。
 * `divisor` (`int`): 结果的倍数。

返回

 * `int`: 不小于 `x` 的 `divisor` 的最小倍数。

### safe_download

```python
def 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](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/general.md)
且没有查询字符串。

该函数使用 `LuxonisFileSystem.download` 下载 `s3`、`gcs` 和 `gs` URL，并使用 `torch.hub.download_url_to_file` 下载所有其他
URL。尝试失败后，它会记录回溯并再次尝试，最多再尝试 `retry` 次。当所有尝试都失败时，它会记录警告并返回 `None`。

> **示例**
> ```pycon
>>> from pathlib import Path
>>> safe_download("weights/model.ckpt") == Path("weights/model.ckpt")
True
>>> safe_download(None) is None
True
```

参数

 * `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
def to_shape_packet(packet: Packet[Tensor]) -> Packet[Size]:
```

将张量包转换为其形状包。

[LuxonisOutput](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/lightning/luxonis_output.md) 在其字符串形式中使用它来显示节点的输出形状。模型在构建节点时使用它，为每个节点提供其输入的形状。

> **示例**
> ```pycon
>>> import torch
>>> features = [torch.zeros(1, 3), torch.zeros(2, 4)]
>>> to_shape_packet({"features": features, "boxes": torch.zeros(5, 4)})
{'features': [torch.Size([1, 3]), torch.Size([2, 4])],
 'boxes': torch.Size([5, 4])}
```

参数

 * `packet` (`Packet[Tensor]`): 值是张量或张量列表的包。

返回

 * `Packet[Size]`: 具有相同键的包。张量变为其 `torch.Size`，张量列表变为 `torch.Size` 对象的列表。

### url2file

```python
def url2file(url: str) -> str:
```

从 URL 获取文件名。

> **示例**
> ```pycon
>>> url2file("https://url.com/dir/file.txt?token=abc")
'file.txt'
```

参数

 * `url` (`str`): URL，例如 `"https://url.com/file.txt?auth"`。

返回

 * `str`: [clean_url](/software-v3/ai-inference/model-source/training/luxonis-train/luxonis-train-api-reference/utils/general.md) 后 URL 的最后一个路径组件，例如 `"file.txt"`。

## 属性

### T
