bluepulsar
238 lines
7.8 KiB
Markdown
238 lines
7.8 KiB
Markdown
# orisys API 文档
|
||
|
||
本文件提供了 `orisys` 套件的中文文档
|
||
## 使用方法
|
||
1. 根据平台和python 版本下载对应的`.whl`文件
|
||
2. 运行pip命令安装：
|
||
```bash
|
||
pip install orisys-{version}-{python}-none-{os}_amd64.whl
|
||
```
|
||
3. 并测试导入：
|
||
```python
|
||
import orisys
|
||
orisys.__version__
|
||
```
|
||
---
|
||
## `Sensor` 类别
|
||
### 描述
|
||
`orisys`套件的核心类，用于从视频文件或实时摄像头中读取传感器图像，创建一个具体的传感器对象（实例）。并完成形变、光流及力信息的计算与管理。
|
||
### 输入参数
|
||
* **vid_src** (`int | str`, 必填): 传感器 ID、相机编号或视频路径。默认为 `0`。
|
||
* **isstitch** (`bool`，可选): 是否启用图像拼接，默认为 `True`。
|
||
* **cuda** (`bool`，可选): 是否使用 GPU cuda 加速，默认为 `False`。
|
||
* **verbose** (`bool`，可选): 是否输出初始化及运行过程中的详细日志信息，默认为 `False`。
|
||
* **config_name** (`str`，可选): 内部算法或传感器配置名称，用于加载对应的参数配置，默认为 `prototype`。
|
||
|
||
|
||
### 返回
|
||
* `Sensor` 实例，用于后续图像采集、形变计算和数据读取操作。
|
||
### 示例
|
||
|
||
```python
|
||
# Example 1： 用相机编号创建
|
||
from orisys import Sensor
|
||
sensor = Sensor(0)
|
||
|
||
# Example 2： 用视频文件创建
|
||
sensor = Sensor("/data/data.mp4")
|
||
```
|
||
|
||
---
|
||
|
||
## 2. `get_img` 方法
|
||
|
||
### 描述
|
||
|
||
采集并预处理一帧图像。
|
||
|
||
### 返回
|
||
* `np.ndarray`：处理后的灰度图(`uint8`，尺寸为`config_resolution_stitch`对应分辨率)。
|
||
* `None`：当输入源读取失败（例如视频结束、摄像头断开）时返回。
|
||
### 状态更新
|
||
* 成功时更新`sensor`类里面的灰度图。
|
||
### 示例
|
||
|
||
```python
|
||
img = sensor.get_img()
|
||
if img is None:
|
||
break
|
||
```
|
||
---
|
||
|
||
## 3. `compute_deformation` 方法
|
||
|
||
### 描述
|
||
|
||
基于当前帧图像计算光流/形变向量场，并通过 HHD 分解将形变场分解为法向/切向分量，同时估计法向力、切向力与扭矩等标量输出。该方法会更新
|
||
`sensor`的形变场与力相关状态，并返回当前帧的光流场。
|
||
调用前置条件：需要先通过`get_img()`成功更新图像。
|
||
|
||
### 返回
|
||
|
||
无
|
||
|
||
### 示例
|
||
|
||
```python
|
||
img = sensor.get_img()
|
||
if img is None:
|
||
break
|
||
|
||
sensor.compute_deformation()
|
||
```
|
||
---
|
||
## 4. `compute_contact` 方法
|
||
|
||
### 描述
|
||
基于已计算的法向形变场进行接触区域分析，输出接触质心与轮廓等信息，并生成接触强度图。
|
||
|
||
调用前置条件：需先执行`compute_deformation()`。
|
||
|
||
### 输入参数
|
||
* **min_contour_area** (`int`，可选): 多接触点模式下的最小轮廓面积阈值，默认为 `3000`。
|
||
* **min_magnitude** (`float`，可选): 最小光流幅度阈值，低于该阈值的区域不参与接触分析，默认为 `1.0`。
|
||
* **expansion_threshold** (`float`，可选): 扩张/收缩判定阈值，用于接触区域分割，默认为 `0.01`。
|
||
* **downsample_factor** (`int`，可选): 下采样因子，用于平滑与加速计算，默认为 `1`。
|
||
* **kernel_size** (`tuple`，可选): 形态学操作核大小，默认为 `(5, 5)`。
|
||
* **denoise_sigma** (`float`，可选): 高斯降噪强度；设为` 0 `可禁用降噪，默认为 `15`。
|
||
|
||
### 返回
|
||
`dict`为接触分析结果字典，至少包含以下键：
|
||
* **expansion_mask**: 扩张区域掩码（`np.ndarray`）。
|
||
* **contraction_mask**: 收缩区域掩码（`np.ndarray`）。
|
||
* **divergence_map**: 散度图（`np.ndarray`）。
|
||
* **centroid**: 质心坐标（单点模式为 `(x, y)`；多点模式为列表）。
|
||
* **centroid_found**: 是否检测到接触区域（`bool`）。
|
||
* **contour**: 最大轮廓或轮廓列表（可选字段，存在时返回）。
|
||
|
||
### 状态更新
|
||
|
||
* **sensor.centroid**: 接触质心（单点为 `(x, y)`，多点为列表）。
|
||
* **sensor.centroid_found**: 是否找到质心（`bool`）。
|
||
|
||
### 示例
|
||
```python
|
||
sensor.compute_contact()
|
||
centroid, contour, depth = sensor.read_info(
|
||
sensor.info.CENTROID,
|
||
sensor.info.CONTOUR,
|
||
sensor.info.DEPTH,
|
||
)
|
||
```
|
||
---
|
||
## 4. `read_info` 方法
|
||
|
||
### 描述
|
||
|
||
按指定的信息类型（`sensor.info`枚举值）批量读取传感器状态数据，并按传入顺序返回对应值的元组。
|
||
该方法通常用于在完成形变计算后，读取光流场、分量场、力、帧率等信息。
|
||
|
||
### 输入参数
|
||
|
||
* **args**: 任意数量的 `Sensor.info` 枚举，用于指定需要获取的数据类型。支持的枚举值及对应数据如下：
|
||
|
||
### 支持的枚 info keys：
|
||
向量/图像类
|
||
* VRAW: 原始光流场, `np.ndarray`，shape=(H, W, 2)
|
||
* VNORMAL: 法向光流场, `np.ndarray`，shape=(H, W, 2)
|
||
* VSHEAR: 切向光流场, `np.ndarray`，shape=(H, W,2)
|
||
* DEPTH: 深度场（可选）, 未启用/未生成时返回空数组`np.array([])`。
|
||
|
||
标量类
|
||
* FNORMAL: 法向力，`float`。
|
||
* FSHEARX: X切向力，`float`。
|
||
* FSHEARY: Y切向力，`float`。
|
||
* FPS: 输出帧率，`float`。
|
||
|
||
时间戳
|
||
* TIMESTAMP: 时间戳字符串（HH:MM:SS），`str`。
|
||
|
||
注：H/W 由当前配置分辨率决定。
|
||
|
||
### 返回
|
||
|
||
`Tuple`
|
||
|
||
按传入的 `sensor.info` 参数顺序返回一个元组，
|
||
返回值数量与有效参数数量一致。
|
||
|
||
- 向量/图像类数据：`np.ndarray`
|
||
- 若当前流程中尚未生成该数据，返回空数组 `np.array([])`
|
||
- 标量类数据：`float`
|
||
- 时间戳：`str`（`TIMESTAMP`，格式为 `HH:MM:SS`）
|
||
|
||
### 示例
|
||
```python
|
||
# Example 1：读取标量数据
|
||
fps, fn, fx, fy = sensor.read_info(
|
||
sensor.info.FPS,
|
||
sensor.info.FNORMAL,
|
||
sensor.info.FSHEARX,
|
||
sensor.info.FSHEARY,
|
||
)
|
||
|
||
# Example 2： 读取单个向量场（注意解包方式）
|
||
flow = sensor.read_info(sensor.info.VRAW)
|
||
```
|
||
---
|
||
|
||
## 5. `disconnect` 方法
|
||
|
||
### 描述
|
||
|
||
释放传感器相关资源并停止后台异步线程。 调用后将关闭视频/摄像头输入源，并销毁所有 OpenCV 窗口。
|
||
|
||
建议在程序退出前调用以确保资源被正确释放。
|
||
|
||
---
|
||
---
|
||
# 配置标定相关
|
||
|
||
## 1. `export_config` 方法
|
||
|
||
### 描述
|
||
导出当前传感器实例使用的配置参数字典。
|
||
|
||
### 输入参数
|
||
* **config_name**: 需要导出的配置参数字典名字`str`
|
||
* **path**: 导出的路径，默认`"./config/exported_config.json"`
|
||
|
||
### 返回
|
||
|
||
* `dict`: 导出的配置参数字典。
|
||
|
||
---
|
||
## 2. `list_config` 方法
|
||
|
||
### 描述
|
||
列出内置传感器配置参数字典。
|
||
|
||
### 返回
|
||
|
||
* `list`: 内置传感器配置参数字典的名字列表。
|
||
|
||
---
|
||
---
|
||
|
||
## 常见问题解答 (FAQ)
|
||
### Q1:为什么必须先调用`get_img()`，再调用`compute_deformation()`？
|
||
A：`compute_deformation()`依赖最近一次获取并拼接的图像数据进行形变与力计算。
|
||
在调用该方法前，必须先通过`get_img()`更新当前帧图像，否则无法进行有效计算。
|
||
|
||
### Q2:为什么调用了`read_info()`，但读到的数据是空的？
|
||
A：`read_info()`仅用于读取当前已计算的数据状态，不会触发任何计算。
|
||
部分字段依赖特定计算步骤生成，例如：
|
||
* `VRAW / VNORMAL / VSHEAR`依赖`compute_deformation()`；
|
||
* `DEPTH / CENTROID / CONTOUR`依赖`compute_contact()`。
|
||
|
||
### Q3:`compute_contact()`为一定要调用吗？什么时候需要？
|
||
A：当需要接触相关信息（如接触质心、轮廓或深度/散度图）时，必须调用`compute_contact()`。
|
||
若仅关注形变场或力信息（如光流、法向力、切向力），则无需调用该方法。
|
||
|
||
### Q4:`read_info()`的返回值顺序是如何确定的？
|
||
A：`read_info()`按传入的`sensor.info`参数顺序返回一个元组。
|
||
返回值顺序与参数顺序一一对应，与内部存储顺序无关。
|
||
|
||
### Q5:如果没有标定文件，或拼接结果不正确，会发生什么？
|
||
A：若未指定或未找到标定文件，系统会在需要时创建新的拼接标定数据并保存到默认路径。
|
||
拼接结果异常通常与标定数据、拼接配置或输入图像质量有关，建议重新生成拼接标定并检查配置参数。 |