From 44bcc194269262385d27a15f304f0ab9004a8d77 Mon Sep 17 00:00:00 2001 From: ykcheungab Date: Tue, 18 Aug 2026 11:00:57 +0800 Subject: [PATCH] update docs and downstream sync --- docs/api.md | 316 ++++++++++++++++------------ docs/get_started.md | 167 +++++++++------ examples/basic_pipeline.py | 2 +- examples/finger_pipeline.py | 2 +- examples/mini_pipeline.py | 2 +- examples/plot_data.py | 2 +- scripts/calibration_script.py | 2 +- src/orisys/sensor.py | 2 +- tools/downstream_sync_manifest.json | 48 +++++ tools/sync_downstreams.py | 172 +++++++++++++++ 10 files changed, 501 insertions(+), 214 deletions(-) create mode 100644 tools/downstream_sync_manifest.json create mode 100644 tools/sync_downstreams.py diff --git a/docs/api.md b/docs/api.md index f3c15a4..5afc69b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,66 +1,19 @@ -# orisys API 文档 +--- +title: API Reference +description: Orisys SDK Python API 中文参考 +--- -本文件提供了 `orisys` 套件的中文文档 +# API Reference -## 准备 Python 开发环境 -推荐下载 Anaconda，并使用Python 3.10 -``` -# 创建并激活虚拟环境 -conda create -n orisys python=3.10 -conda activate orisys -``` -## 安装 CUDA Toolkit 和 cuDNN -在官方链接下载和安装：https://developer.nvidia.com/cuda/toolkit -或 -在Anaconda环境中安装（例子使用cuda12.9）： -https://anaconda.org/channels/nvidia/packages/cuda/overview -``` -conda install nvidia/label/cuda-12.9.0::cuda-toolkit nvidia::cudnn -``` -## SDK安装方法 -1. 根据系统（win / linux）,平台(amd64, aarch64), python(如p38、p39、p310) 版本下载对应的`.whl`文件 -2. 运行pip命令安装： -```bash -pip install orisys-{version}-{python-version}-{python-version}-{os}_{machine}.whl -``` -如 -```bash -pip install orisys-0.4.3-cp310-cp310-win_amd64.whl -``` +本文件提供 `orisys` 套件的 Python API 中文参考。安装、CUDA、CuPy 与运行示例的基础步骤请参考 [快速开始](./get_started.md)。 -3. **安装 CuPy（根据您的 CUDA 版本选择）：** - - **方法 1：使用 extras（推荐）** - ```bash - # 对于 CUDA 12.x - pip install orisys[cuda12] - - # 对于 CUDA 13.x - pip install orisys[cuda13] - ``` - - **方法 2：手动安装** - ```bash - # 对于 CUDA 12.x - pip install cupy-cuda12x>=12.3.0 - - # 对于 CUDA 13.x - pip install cupy-cuda13x>=13.0.0 - ``` +## Sensor API -4. 测试导入： -```python -import orisys -print(orisys.__version__) -``` - -*** - -## `Sensor` 类别 -### 描述 +### `Sensor` 类别 +#### 描述 `orisys`套件的核心类，用于从视频文件或实时摄像头中读取传感器图像，创建一个具体的传感器对象（实例）。并完成形变、光流及力信息的计算与管理。 -### 输入参数 +#### 输入参数 * **vid_src** (`int | str`, 必填): 传感器 ID、相机编号或视频路径。默认为 `0`。 * **config_name** (`str`，可选): 传感器配置文件名称或 `json` 文件路径，用于加载对应的参数配置；例如 `box` 或 `./config/box.json`。 @@ -69,9 +22,9 @@ print(orisys.__version__) * **verbose** (`bool`，可选): 是否输出初始化及运行过程中的详细日志信息，默认为 `False`。 -### 返回 +#### 返回 * `Sensor` 实例，用于后续图像采集、形变计算和数据读取操作。 -### 示例 +#### 示例 ```python # Example 1： 用相机编号创建 @@ -82,63 +35,62 @@ sensor = Sensor(0) sensor = Sensor("/data/data.mp4") ``` -*** +### `Sensor.get_img` 方法 -## 2. `Sensor.get_img` 方法 - -### 描述 +#### 描述 采集并预处理一帧图像并存到`Sensor` 类别中。 -### 返回 +#### 返回 * `bool`：是否成功读取图像。 -### 状态更新 +#### 状态更新 * 成功时更新`sensor`类里面的`sensor.img`。处理后的BGR格式图像(`uint8`，尺寸为json文件中`resolution_stitch`对应分辨率)。 -### 示例 +#### 示例 ```python sensor.get_img() ``` -*** +### `Sensor.compute_deformation` 方法 -## 3. `Sensor.compute_deformation` 方法 - -### 描述 +#### 描述 基于当前帧图像计算光流/形变向量场，并通过 HHD 分解将形变场分解为法向/切向分量，同时估计法向力、切向力与扭矩等标量输出。该方法会更新 `sensor`的形变场与力相关状态，并返回当前帧的光流场。 调用前置条件：需要先通过`get_img()`成功更新图像。 -### 输入参数 -* **check_motion**(`bool`，可选): 为 `True` 时先根据光流判断是否有运动，有运动才做 HHD 分解；为 `False` 时每帧都做 HHD。默认 `True`。 -* **threshold**(`float`，可选): **check_motion** 功能的阈值，默认为`6`。 -* **tail_frames** (`int`，可选): 光流变化低于阈值后继续解算多少帧，确保传感器回复，，默认为 `10`. +#### 输入参数 +* **decompose** (`bool`，可选): 是否在计算光流后继续执行 HHD 分解，默认 `True`。 +* **check_motion** (`bool`，可选): 是否启用运动检测门控。当前不推荐依赖该功能；新代码建议显式传入 `False`，让每帧都执行 HHD 分解。为兼容旧代码，函数默认值仍为 `True`。 -### 返回 +#### 兼容参数（暂不推荐） -* `bool`：是否接触到物体，如果**check_motion**为`False`时返回`None`。 +以下参数只在 `check_motion=True` 时生效。由于运动检测门控目前不稳定，建议在新代码中暂时不要使用： -### 示例 +* **threshold** (`float`，可选): 运动检测阈值，默认 `6`。 +* **tail_frames** (`int`，可选): 运动低于阈值后继续解算多少帧，默认 `10`。 + +#### 返回 + +* `None`: 当 `check_motion=False` 时返回。推荐用法下不要依赖该返回值判断接触状态。 +* `bool`: 仅当 `check_motion=True` 时返回运动检测结果；该模式目前暂不推荐。 + +#### 示例 ```python sensor.get_img() - -is_touched = sensor.compute_deformation(check_motion=True, threshold=6) -# 步骤 2.3: 计算触碰点 -if is_touched: - sensor.compute_contact() +sensor.compute_deformation(check_motion=False) +sensor.compute_contact() ``` -*** -## 4. `Sensor.compute_contact` 方法 +### `Sensor.compute_contact` 方法 -### 描述 +#### 描述 基于已计算的法向形变场进行接触区域分析，输出接触质心与轮廓等信息，并生成接触深度图，默认配置在`json`文件中，可按需调节。 调用前置条件：需先执行`compute_deformation()`。 -### 返回 +#### 返回 `dict`为接触分析结果字典，至少包含以下键： * **expansion_mask**: 扩张区域掩码（`np.ndarray`）。 @@ -148,12 +100,12 @@ if is_touched: * **centroid_found**: 是否检测到接触区域（`bool`）。 * **contour**: 最大轮廓或轮廓列表（可选字段，存在时返回）。 -### 状态更新 +#### 状态更新 * **sensor.centroid**: 接触质心（单点为 `(x, y)`，多点为列表）。 * **sensor.centroid_found**: 是否找到质心（`bool`）。 -### 示例 +#### 示例 ```python sensor.compute_contact() centroid, contour, depth = sensor.read_info( @@ -162,19 +114,18 @@ centroid, contour, depth = sensor.read_info( sensor.info.DEPTH, ) ``` -*** -## 4. `Sensor.read_info` 方法 +### `Sensor.read_info` 方法 -### 描述 +#### 描述 按指定的信息类型（`sensor.info`枚举值）批量读取传感器状态数据，并按传入顺序返回对应值的元组。 该方法通常用于在完成形变计算后，读取光流场、分量场、力、帧率等信息。 -### 输入参数 +#### 输入参数 * **args**: 任意数量的 `Sensor.info` 枚举，用于指定需要获取的数据类型。支持的枚举值及对应数据如下： -### 支持的枚 info keys： +#### 支持的 info keys 向量/图像类 @@ -188,6 +139,9 @@ centroid, contour, depth = sensor.read_info( * FNORMAL: 法向力，`float`。 * FSHEARX: X切向力，`float`。 * FSHEARY: Y切向力，`float`。 +* FNORMAL_RAW: 未经过低通滤波的原始法向力，`float`。 +* FSHEARX_RAW: 未经过低通滤波的原始 X 切向力，`float`。 +* FSHEARY_RAW: 未经过低通滤波的原始 Y 切向力，`float`。 * FPS: 输出帧率，`float`。 * CENTROID： 触碰点的坐标，(x, y)。 * CONTOUR： 触碰区域轮廓，`np.ndarray`, shape=(H, W), 未生成时返回`np.empty` @@ -198,7 +152,7 @@ centroid, contour, depth = sensor.read_info( 注：H/W 由当前`json`文件中的`resolution_stitch`配置分辨率决定。 -### 返回 +#### 返回 `Tuple` @@ -210,7 +164,7 @@ centroid, contour, depth = sensor.read_info( - 标量类数据：`float` - 时间戳：`str`（`TIMESTAMP`，格式为 `HH:MM:SS`） -### 示例 +#### 示例 ```python # Example 1：读取标量数据 fps, fn, fx, fy = sensor.read_info( @@ -223,20 +177,112 @@ fps, fn, fx, fy = sensor.read_info( # Example 2： 读取单个向量场（注意解包方式） flow = sensor.read_info(sensor.info.VRAW) ``` -*** +### `Sensor.disconnect` 方法 -## 5. `Sensor.disconnect` 方法 - -### 描述 +#### 描述 释放传感器相关资源并停止后台异步线程。 调用后将关闭视频/摄像头输入源，并销毁所有 OpenCV 窗口。 建议在程序退出前调用以确保资源被正确释放。 -*** -*** +### `Sensor.configure` 低通滤波设置 -## `orisys.finger` 手指 UV pipeline +#### 描述 + +运行时更新传感器设置，无需重新连接相机。常用于开启力信号低通滤波，降低 `FNORMAL`、`FSHEARX`、`FSHEARY` 的高频噪声。 + +默认采样率按 30 fps 计算，推荐低通截止频率为 5 Hz： + +```python +sensor.configure(lowpass_cutoff_hz=5.0, lowpass_sample_rate_hz=30.0) +``` + +注意：`lowpass_cutoff_hz` 必须小于 Nyquist 频率，即 `lowpass_sample_rate_hz / 2`。例如 30 fps 时，截止频率必须小于 15 Hz。 + +#### 输入参数 + +* **lowpass_cutoff_hz** (`float`，可选): 力信号低通截止频率，单位 Hz。`0` 表示关闭滤波；正数默认开启滤波。 +* **lowpass_sample_rate_hz** (`float`，可选): 力信号采样率，默认 `30.0`。 +* **lowpass_order** (`int`，可选): Butterworth 滤波器阶数，默认 `2`。 +* **lowpass_enabled** (`bool`，可选): 显式开启或关闭低通滤波。 +* **hhd_downsample** (`int`，可选): HHD 解算下采样倍数，需为 `>= 1` 的整数，配置默认 `3`。 + +#### 读取结果 + +开启低通滤波后，`read_info()` 读取的力输出会被滤波： + +```python +fn, fx, fy = sensor.read_info( + sensor.info.FNORMAL, + sensor.info.FSHEARX, + sensor.info.FSHEARY, +) +``` + +原始力输出仍可通过 `FNORMAL_RAW`、`FSHEARX_RAW`、`FSHEARY_RAW` 读取，便于调试或对比。 + +## Signal Processing API + +### `orisys.signal_processing.lowpass_filter` 函数 + +#### 描述 + +对一维、等间隔采样数据执行零相位 Butterworth 低通滤波，适合示例程序或图表中对历史数据做平滑处理。 + +默认参数为 `cutoff_hz=5.0`、`sample_rate_hz=30.0`、`order=2`。这表示在 30 fps 数据上使用 5 Hz 低通滤波。 + +#### 输入参数 + +* **data**: 一维数据序列。 +* **cutoff_hz** (`float`，可选): 截止频率，默认 `5.0`。传入 `0` 时不做滤波并返回数据副本。 +* **sample_rate_hz** (`float`，可选): 采样率，默认 `30.0`。 +* **order** (`int`，可选): Butterworth 滤波器阶数，默认 `2`。 + +#### 返回 + +* `np.ndarray`: 滤波后的 `float64` 数组。 + +#### 示例 + +```python +from orisys.signal_processing import lowpass_filter + +filtered_force = lowpass_filter(force_values, cutoff_hz=5.0, sample_rate_hz=30.0) +``` + +### `orisys.signal_processing.LowpassFilter` 类别 + +#### 描述 + +有状态的因果 Butterworth 低通滤波器，适合逐帧处理实时数据。它会保留上一帧的滤波状态，并通过 `process()` 一次处理一个多通道样本。 + +`Sensor.configure()` 内部使用该类来滤波力信号。构造时默认 `cutoff_hz=0.0`，表示关闭滤波；若要按 30 fps 使用推荐滤波，设置 `cutoff_hz=5.0`、`sample_rate_hz=30.0`。 + +#### 输入参数 + +* **cutoff_hz** (`float`，可选): 截止频率，默认 `0.0`，表示关闭滤波。 +* **sample_rate_hz** (`float`，可选): 采样率，默认 `30.0`。 +* **order** (`int`，可选): Butterworth 滤波器阶数，默认 `2`。 +* **n_channels** (`int`，可选): 每个样本的通道数，默认 `3`。 + +#### 常用方法 + +* **configure(...)**: 运行时更新 `cutoff_hz`、`sample_rate_hz` 或 `order`。 +* **reset(x0=None)**: 清除滤波器状态；传入 `x0` 时会用该样本初始化稳态。 +* **process(values)**: 滤波一个多通道样本，返回 shape 为 `(n_channels,)` 的 `np.ndarray`。 + +#### 示例 + +```python +from orisys.signal_processing import LowpassFilter + +filt = LowpassFilter(cutoff_hz=5.0, sample_rate_hz=30.0, n_channels=3) +filtered = filt.process([fnormal, fshearx, fsheary]) +``` + +## Finger Pipeline API + +### `orisys.finger` 手指 UV pipeline `examples/finger_pipeline.py` 展示了一个更适合手指/单相机场景的高层 API： @@ -247,7 +293,7 @@ flow = sensor.read_info(sensor.info.VRAW) 相比直接使用 `Sensor`，`FingerRuntime` 已封装了视频读取、相机尺寸设置、UV 展开和有效区域掩码传递，更适合作为手指 2D/3D 示例与上层应用的入口。 -### 1. `FingerRuntime.open` 方法 +### `FingerRuntime.open` 方法 #### 描述 @@ -288,7 +334,7 @@ runtime = FingerRuntime.open( ) ``` -### 2. `FingerRuntime` 常用属性 +### `FingerRuntime` 常用属性 * **runtime.geometry**: `FingerGeometry`，包含输入/输出分辨率、导出资产路径、相机内参、缓存路径等一次性初始化结果。 * **runtime.domain**: UV 展开域对象，内部包含 remap、valid mask 以及可选 surface 数据。 @@ -296,7 +342,7 @@ runtime = FingerRuntime.open( * **runtime.capture**: OpenCV `VideoCapture` 对象。 * **runtime.valid_mask**: 当前 UV 域有效像素掩码。 -### 3. `FingerRuntime.read_source` 方法 +### `FingerRuntime.read_source` 方法 #### 描述 @@ -308,7 +354,7 @@ runtime = FingerRuntime.open( * **ok** (`bool`): 是否成功读取。 * **frame** (`np.ndarray | None`): 原始 BGR 帧。 -### 4. `FingerRuntime.process_frame` 方法 +### `FingerRuntime.process_frame` 方法 #### 描述 @@ -323,7 +369,7 @@ runtime = FingerRuntime.open( * `np.ndarray`: 展开后的触觉图像。`color=False` 时通常为单通道灰度图；`color=True` 时为 BGR 图。 -### 5. `FingerRuntime.grab_and_process` 方法 +### `FingerRuntime.grab_and_process` 方法 #### 描述 @@ -339,7 +385,7 @@ runtime = FingerRuntime.open( * **ok** (`bool`): 是否成功读取并处理。 * **unrolled** (`np.ndarray | None`): 展开后的触觉图像。 -### 6. `FingerRuntime.get_img` 方法 +### `FingerRuntime.get_img` 方法 #### 描述 @@ -353,7 +399,7 @@ runtime = FingerRuntime.open( * `np.ndarray | None` -### 7. `FingerRuntime.warmup` 方法 +### `FingerRuntime.warmup` 方法 #### 描述 @@ -369,13 +415,13 @@ runtime = FingerRuntime.open( * **ok** (`bool`): 是否成功完成 warmup 前的采集。 * **unrolled** (`np.ndarray | None`): warmup 时得到的展开图。 -### 8. `FingerRuntime.close` 方法 +### `FingerRuntime.close` 方法 #### 描述 释放内部 `VideoCapture` 并调用 `runtime.tactile.disconnect()` 清理 `Sensor` 资源。程序退出前应调用。 -### 9. `TactileProcessor` 类别 +### `TactileProcessor` 类别 #### 描述 @@ -393,7 +439,7 @@ runtime = FingerRuntime.open( 除 `push_frame()` / `warmup()` 之外，`TactileProcessor` 的 `compute_deformation()`、`compute_contact()`、`read_info()`、`reset()` 调用方式与 `Sensor` 基本一致，因此可直接复用前文 `Sensor` 章节中的参数说明。 -### 10. 最小手指 pipeline 示例 +### 最小手指 pipeline 示例 下面的流程与 `examples/finger_pipeline.py` 一致： @@ -460,7 +506,7 @@ finally: cv2.destroyAllWindows() ``` -### 11. 关于 profile 模式 +### 关于 profile 模式 `examples/finger_pipeline.py` 中的 `--profile` / `--profile-every` 是示例脚本参数，不属于 `orisys` SDK 核心 API。本质上它只是把主循环拆成： @@ -472,11 +518,11 @@ finally: 并对各阶段做耗时统计。因此在业务代码中，也可以按同样方式自行插入计时逻辑。 -# 可视化相关 +## 可视化相关 -## 1. `util.draw_arrows` 方法 +### `util.draw_arrows` 方法 -### 输入参数 +#### 输入参数 * **frame**：背景图像 * **optical_flow**：光流场 @@ -488,12 +534,12 @@ finally: * **below_threshold_color**：RGB格式的`uint8`颜色，如(0, 0, 255) * **edge_margin**: 不显示箭头边距（pixel） -### 返回 +#### 返回 `np.ndarray` ：箭头光流可视化图像 -## 2. `util.draw_contact` 方法 +### `util.draw_contact` 方法 -### 输入参数 +#### 输入参数 * **image**：背景图像 * **contour**：轮廓 @@ -501,42 +547,36 @@ finally: * **point_color**：触碰点的颜色 (BGR) * **region_color**：轮廓的颜色 (BGR) -### 返回 +#### 返回 `np.ndarray` ：箭头光流可视化图像 -*** +## 配置标定相关 -# 配置标定相关 +### `list_config` 方法 -## 1. `list_config` 方法 - -### 描述 +#### 描述 列出内置传感器配置参数字典。 -### 返回 +#### 返回 * `list`: 内置传感器配置参数字典的名字列表。 -*** -## 2. `export_config` 方法 +### `export_config` 方法 -### 描述 +#### 描述 导出当前传感器实例使用的配置参数字典。 -### 输入参数 +#### 输入参数 * **config_name**: 需要导出的配置参数字典名字，`str` * **path**: 导出的路径，默认`"./config/exported_config.json"` -### 返回 +#### 返回 * `dict`: 导出的配置参数字典。 -### 保存 +#### 保存 * 导出内置的`config_name`配置参数字典至`path` -*** -*** - ## 常见问题解答 (FAQ) ### Q1:为什么必须先调用`get_img()`，再调用`compute_deformation()`？ A：`compute_deformation()`依赖最近一次获取并拼接的图像数据进行形变与力计算。 @@ -556,9 +596,5 @@ A：当需要接触相关信息（如接触质心、轮廓或深度/散度图） A：`read_info()`按传入的`sensor.info`参数顺序返回一个元组。 返回值顺序与参数顺序一一对应，与内部存储顺序无关。 -### Q5:如果没有标定文件，或拼接结果不正确，会发生什么？ -A：若未指定或未找到标定文件，系统会在需要时创建新的拼接标定数据并保存到默认路径。 -拼接结果异常通常与标定数据、拼接配置或输入图像质量有关，建议重新生成拼接标定并检查配置参数。 - -### Q6: 运行报错：“AttributeError: 'Stitcher' object has no attribute 'pos_default'” +### Q5: 运行报错：“AttributeError: 'Stitcher' object has no attribute 'pos_default'” A: 请检查视频源的编号是否正确，以及是否能正常打开视频源。在linux 使用`v4l2-ctl --list-devices` 或 Windows使用`Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match '^Camera' }` 列出摄像头设备。 \ No newline at end of file diff --git a/docs/get_started.md b/docs/get_started.md index 95c1829..b0838da 100644 --- a/docs/get_started.md +++ b/docs/get_started.md @@ -1,60 +1,87 @@ -叠动科技软件使用手册 -版本： 0.4.3 -更新日期： 2026年7月13日 +--- +title: 快速开始 +description: 安装并运行 Orisys SDK 的基础步骤 +--- -# 简介 +# 快速开始 + +版本：0.4.3 + +## 简介 本文件介绍如何上手和运行叠动视触觉传感器配套的开发套件。本套件是配合叠动视触觉传感器进行图像处理，计算形变、力以及接触信息。它可以从摄像头或视频文件中读取图像，处理后打印和展示处理后信息。 支持操作系统：Windows、Ubuntu 建议Python 版本: 3.10, 3.11, 3.12 -# 基础环境设置 -## 安装 Python 与 Anaconda -1. 访问 [Anaconda 官网](https://www.anaconda.com/download)下载适合您操作系统的安装包（Windows、Linux）。 -2. 按照提示完成安装。 -3. 安装完成后，打开命令行终端（Windows 用户可在”Anaconda Navigator”打开“Anaconda Prompt”），输入 `conda info` ，若能显示 conda 的信息，则说明安装成功。 +项目链接： -## 创建conda虚拟环境 +- PyPI 安装页：[https://pypi.org/project/orisys/](https://pypi.org/project/orisys/) +- 项目文档/代码：[https://github.com/Orisys-Tech/orisys-sdk](https://github.com/Orisys-Tech/orisys-sdk) + +## 基础环境设置 +### 安装 Python 与 Anaconda +1. 访问 [Anaconda 官网](https://www.anaconda.com/download) 下载适合您操作系统的安装包（Windows、Linux）。 +2. 按照提示完成安装。 +3. 安装完成后，打开命令行终端（Windows 用户可在 “Anaconda Navigator” 打开 “Anaconda Prompt”），输入 `conda info`，若能显示 conda 的信息，则说明安装成功。 + +### 创建 conda 虚拟环境 虚拟环境相当于一个独立的 Python 工作空间，可以避免不同项目所需的库版本冲突。 -打开命令行终端（或Anaconda Prompt），依次输入以下命令(以 python 3.10 为例)： -``` bash +打开命令行终端（或 Anaconda Prompt），依次输入以下命令（以 Python 3.10 为例）： +```bash conda create -n orisys python=3.10 conda activate orisys ``` 激活后，命令行提示符前会出现 `(orisys)` 字样，表示当前已进入虚拟环境。 -## 创建工作区文件夹 -“Anaconda Prompt”启动后的默认工作路径在用户根文件夹中，建议创建工作区文件夹方便管理，可以手动创建或者运行`mkdir `命令：, 例如 +### 创建工作区文件夹 +“Anaconda Prompt” 启动后的默认工作路径在用户根文件夹中，建议创建工作区文件夹方便管理。可以手动创建文件夹，也可以运行 `mkdir ` 命令。例如： -``` bash +```bash mkdir orisys_ws ``` -创建后如果要更换工作区，使用 `cd `命令，例如： +创建后如果要更换工作区，使用 `cd ` 命令，例如： -``` bash +```bash cd "C:\Users\orisys\orisys_ws" ``` -
- -## 安装 CUDA 和 cuDNN（可选） +### 安装 CUDA 和 cuDNN（可选） 如果您拥有 NVIDIA 显卡，并希望利用 GPU 加速计算，则需要安装 CUDA 工具包和 cuDNN。 1. 方法一（官网下载）： -访问 [NVIDIA CUDA Toolkit官网](https://developer.nvidia.com/cuda/toolkit)下载对应系统的 CUDA Toolkit 安装包，并按照提示安装, 注意12.X 和 13.X 的版本对应不同的 CuPy 库版本。 +访问 [NVIDIA CUDA Toolkit 官网](https://developer.nvidia.com/cuda/toolkit) 下载对应系统的 CUDA Toolkit 安装包，并按照提示安装。注意 12.x 和 13.x 的版本对应不同的 CuPy 库版本。 2. 方法二（使用 Anaconda 安装，推荐）： 在已激活的 orisys 环境中直接运行以下命令（以 CUDA 12.9 为例）： -`conda install nvidia/label/cuda-12.9.0::cuda-toolkit nvidia::cudnn` + +```bash +conda install nvidia/label/cuda-12.9.0::cuda-toolkit nvidia::cudnn +``` + 该方法会自动配置好 CUDA 和 cuDNN，无需手动下载。 注意：如果您的计算机没有 NVIDIA 显卡，或者不想使用 GPU 加速，可以跳过此步骤。套件也支持纯 CPU 运行（但速度可能较慢）。 -# 安装 orisys SDK +## 安装 orisys SDK -orisys SDK 以 .whl 文件形式提供，您需要根据操作系统、Python 版本和硬件平台选择正确的文件。 +推荐优先从 PyPI 安装。PyPI 会自动选择适合当前 Python 版本和操作系统的安装包，适合大多数用户。 -## 下载正确的 .whl 文件 +### 使用 PyPI 安装（推荐） +确认已经激活 `orisys` 虚拟环境后，运行： + +```bash +pip install orisys +``` + +如果需要升级到最新版本，运行： + +```bash +pip install --upgrade orisys +``` + +如果当前网络无法访问 PyPI，或需要安装客服提供的指定版本，可以使用下方 `.whl` 文件安装方式。 + +### 使用 .whl 文件安装（离线或指定版本） 从官方渠道获取 .whl 文件，文件名格式通常为： orisys-{版本}-{Python版本}-{Python版本}-{操作系统}_{硬件架构}.whl 例如：orisys-0.4.3-cp310-cp310-win_amd64.whl 表示： @@ -64,17 +91,16 @@ Python 版本：3.10（cp310） 操作系统：Windows（win） 硬件架构：64位（amd64） -请根据您的系统选择对应的文件，或者咨询客服索取： +请根据您的系统选择对应的文件，或者咨询客服索取。 -## 安装 .whl 文件 -将下载好的 .whl 文件放在一个文件夹中（如上述`orisys_ws`文件夹），打开命令行（确保已激活 orisys 环境或使用"Anaconda Prompt"），使用 `cd` 命令切换到该文件夹，然后运行： +将下载好的 `.whl` 文件放在一个文件夹中（如上述 `orisys_ws` 文件夹），打开命令行（确保已激活 `orisys` 环境或使用 “Anaconda Prompt”），使用 `cd` 命令切换到该文件夹，然后运行： -``` bash +```bash # 请将文件名替换为您实际下载的文件名 pip install orisys-0.4.3-cp310-cp310-win_amd64.whl ``` -## 安装 CuPy（可选） +### 安装 CuPy（可选） 注意：如果您没有安装 CUDA，或者使用 CPU 运行，可以跳过这一步。 CuPy 是一个与 NumPy 类似但支持 GPU 加速的库，您需要根据您安装的 CUDA 版本选择对应的 CuPy 版本。 @@ -84,83 +110,88 @@ CuPy 是一个与 NumPy 类似但支持 GPU 加速的库，您需要根据您安 ```bash # 如果您的 CUDA 版本是 12.x -pip install orisys[cuda12] +pip install "orisys[cuda12]" # 如果您的 CUDA 版本是 13.x -pip install orisys[cuda13] +pip install "orisys[cuda13]" ``` 如果之前已经安装了 orisys，可以单独安装 CuPy： 方法二（手动安装）： -``` bash +```bash # CUDA 12.x -pip install cupy-cuda12x>=12.3.0 +pip install "cupy-cuda12x>=12.3.0" # CUDA 13.x -pip install cupy-cuda13x>=13.0.0 +pip install "cupy-cuda13x>=13.0.0" ``` -## 测试安装 -安装完成后，在命令行输入” python“命令进入 Python 环境， 并导入 orisys 库并查看版本号，验证是否成功： -``` bash +### 测试安装 +安装完成后，在命令行输入 `python` 命令进入 Python 环境，并导入 `orisys` 库查看版本号，验证是否成功： +```bash python +``` + +进入 Python 后继续输入： + +```python import orisys print(orisys.__version__) ``` 如果输出版本号（例如 0.4.3），则说明安装成功。 -# 使用方法 -## 运行示例程序 -套件里面包含了多个例子，建议都在仓库根目录运行（即 `config/`、`examples/`、`assets/` 同级目录）。按产品入口如下： +## 使用方法 +### 运行示例程序 +套件里面包含了多个例子。运行示例前，请先进入 SDK 示例所在的文件夹，建议在仓库根目录运行（即 `config/`、`examples/`、`assets/` 同级目录）。如果您是通过 PyPI 安装并且本地没有示例文件，可以从上方项目链接下载示例。按产品入口如下： 1. `examples/basic_pipeline.py`：ORY-BOX 复眼/拼接传感器基础 OpenCV 示例（默认配置 `box`） 2. `examples/mini_pipeline.py`：ORY-MINI 基础 OpenCV 示例（默认配置 `mini`） -3. `examples/finger_pipeline.py`：ORY-FINGER 2D UV 最小流程（默认配置 `finger`） +3. `examples/finger_pipeline.py`：ORY-FINGER 2D 显示最小流程（默认配置 `finger`） 4. `examples/finger_pipeline_3dview.py`：ORY-FINGER Qt 3D 可视化界面（默认配置 `finger`） -`finger` 是当前 ORY-FINGER 的产品配置名。`dd02` 仍可作为兼容别名，实际会解析到 `dd02-ov`。 +`finger` 是当前 ORY-FINGER 的产品配置名。 下面先介绍最基础的 ORY-BOX 运行方式。 -### Windows: -1. 检查是否有其他正在连接的USB摄像头设备：打开powershell, 运行命令`Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match '^Camera' }`，如果没有的话不会有输出。 -2. 把传感器的USB头与电脑连接，再次运行步骤一的命令，会新增一行输出 -3. 如果第一步没有输出，传感器的ID就是“0”，如果第一步有一个设备，传感器的ID就是“1”，如此类推。 -4. 在确定了传感器的ID（下方例子假设为“0”）后，打开Anaconda Prompt, 切换到工作路径，然后在命令行中输入： - ``` bash +#### Windows +1. 检查是否有其他正在连接的 USB 摄像头设备：打开 PowerShell，运行命令 `Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match '^Camera' }`，如果没有的话不会有输出。 +2. 把传感器的 USB 头与电脑连接，再次运行步骤一的命令，会新增一行输出。 +3. 如果第一步没有输出，传感器的 ID 就是 `0`；如果第一步有一个设备，传感器的 ID 就是 `1`，如此类推。 +4. 在确定了传感器的 ID（下方例子假设为 `0`）后，打开 Anaconda Prompt，切换到工作路径，然后在命令行中输入： + ```bash python examples/basic_pipeline.py -v 0 -c box ``` -5. 程序会运行，并自动打开可视化窗口和打印资料，在窗口上按键盘”q”键可以停止运行，按”r”键可以重设数据 +5. 程序会运行，并自动打开可视化窗口和打印资料。在窗口上按键盘 `q` 键可以停止运行，按 `r` 键可以重设数据。 -### Ubuntu: -1. 检查是否有其他正在连接的USB摄像头设备：打开终端, 运行命令`v4l2 –list-devices`，如果没有的话不会有输出。 -2. 把传感器的USB头与电脑连接，再次运行步骤一的命令，会新增输出 -3. 根据新增的输出，例如”/dev/video0”，确定传感器的ID为“0”, 如果是”/dev/video3”的话ID为“3” ，如此类推。 -4. 在确定了传感器的ID（下方例子假设为“0”）后，打开终端, 激活相应的python环境，切换到工作路径，然后在命令行中输入： - ``` bash +#### Ubuntu +1. 检查是否有其他正在连接的 USB 摄像头设备：打开终端，运行命令 `v4l2 --list-devices`，如果没有的话不会有输出。 +2. 把传感器的 USB 头与电脑连接，再次运行步骤一的命令，会新增输出。 +3. 根据新增的输出，例如 `/dev/video0`，确定传感器的 ID 为 `0`；如果是 `/dev/video3`，ID 为 `3`，如此类推。 +4. 在确定了传感器的 ID（下方例子假设为 `0`）后，打开终端，激活相应的 Python 环境，切换到工作路径，然后在命令行中输入： + ```bash python examples/basic_pipeline.py -v 0 -c box ``` -5. 程序会运行，并自动打开可视化窗口和打印资料，在窗口上按键盘”q”键可以停止运行，按”r”键可以重设数据 +5. 程序会运行，并自动打开可视化窗口和打印资料。在窗口上按键盘 `q` 键可以停止运行，按 `r` 键可以重设数据。 -### ORY-FINGER UV 示例 +#### ORY-FINGER 示例 如果您使用的是 ORY-FINGER（配置名 `finger`），可运行： -``` bash +```bash python examples/finger_pipeline.py --camera_id 0 --config finger ``` 如果输入来自视频文件，也可以改用： -``` bash +```bash python examples/finger_pipeline.py --video ./data/sample.mp4 --config finger ``` 该示例会： - 读取相机或视频源 -- 将图像展开到 UV 平面 +- 将图像展开到平面 - 计算光流、法向/切向力和接触区域 - 在 OpenCV 窗口中显示展开后的光流箭头图 @@ -170,18 +201,18 @@ python examples/finger_pipeline.py --video ./data/sample.mp4 --config finger 例如： -``` bash +```bash python examples/finger_pipeline.py --camera_id 0 --config finger ``` -### ORY-FINGER 3D 可视化界面 +#### ORY-FINGER 3D 可视化界面 -如果要使用 GUI ,安装GUI依赖： -``` bash -pip install -e ".[gui]" +如果要使用 GUI，先安装 GUI 依赖： +```bash +pip install "orisys[gui]" ``` 然后运行： -``` bash +```bash python examples/finger_pipeline_3dview.py --video 0 --config finger ``` @@ -191,5 +222,5 @@ python examples/finger_pipeline_3dview.py --video 0 --config finger - 力曲线 - 3D 视图 -## 开发套件使用方法 +### 开发套件使用方法 参考开发套件附带的开发文档。 \ No newline at end of file diff --git a/examples/basic_pipeline.py b/examples/basic_pipeline.py index e6d1593..db2d2f5 100644 --- a/examples/basic_pipeline.py +++ b/examples/basic_pipeline.py @@ -43,7 +43,7 @@ def main(): # 步骤 2.1：获取并拼接图像（必需） sensor.get_img() # 步骤 2.2：计算形变场（必需）；返回值表示当前帧是否检测到接触/运动 - is_contact_now = sensor.compute_deformation(check_motion=True, threshold=0) + is_contact_now = sensor.compute_deformation() # 步骤 2.3：仅在当前帧检测到接触/运动时计算接触区域 # if is_contact_now: sensor.compute_contact() diff --git a/examples/finger_pipeline.py b/examples/finger_pipeline.py index 60c4947..10b17d3 100644 --- a/examples/finger_pipeline.py +++ b/examples/finger_pipeline.py @@ -62,7 +62,7 @@ def main(): if not ok: break - tactile.compute_deformation(check_motion=True, threshold=0) + tactile.compute_deformation() tactile.compute_contact() fps, flow, vnormal, img, contour, centroid, depth_map, fnormal, fshearx, fsheary = tactile.read_info( diff --git a/examples/mini_pipeline.py b/examples/mini_pipeline.py index ea44cfe..cb9e7c3 100644 --- a/examples/mini_pipeline.py +++ b/examples/mini_pipeline.py @@ -43,7 +43,7 @@ def main(): # 步骤 2.1：获取并拼接图像（必需） sensor.get_img() # 步骤 2.2：计算形变场（必需）；返回值表示当前帧是否检测到接触/运动 - is_contact_now = sensor.compute_deformation(check_motion=True, threshold=0) + is_contact_now = sensor.compute_deformation() # 步骤 2.3：仅在当前帧检测到接触/运动时计算接触区域 # if is_contact_now: sensor.compute_contact() diff --git a/examples/plot_data.py b/examples/plot_data.py index a158574..cdbb002 100644 --- a/examples/plot_data.py +++ b/examples/plot_data.py @@ -55,7 +55,7 @@ def main(): sensor.get_img() recorder.write_if_recording(sensor.frame) - sensor.compute_deformation(check_motion=True, threshold=0) + sensor.compute_deformation() sensor.compute_contact() fps, fn, fx, fy, flow, depth_map = sensor.read_info( sensor.info.FPS, diff --git a/scripts/calibration_script.py b/scripts/calibration_script.py index f8d85ac..87955b3 100644 --- a/scripts/calibration_script.py +++ b/scripts/calibration_script.py @@ -115,7 +115,7 @@ def main(): writer.write(save_img) - sensor1.compute_deformation(check_motion=False) # 计算形变和分解 + sensor1.compute_deformation() # 计算形变和分解 # 提取信息： # 向量场: VRAW, VNORMAL, VSHEAR: 原始，法向，切向 # 帧率，时间戳: FPS, TIMESTAMP diff --git a/src/orisys/sensor.py b/src/orisys/sensor.py index 878cb53..a8dc898 100644 --- a/src/orisys/sensor.py +++ b/src/orisys/sensor.py @@ -412,7 +412,7 @@ class Sensor: motion_value = mag.mean() return motion_value > threshold - def compute_deformation(self, decompose=True, check_motion=True, threshold=6, tail_frames=10): + def compute_deformation(self, decompose=True, check_motion=False, threshold=6, tail_frames=10): """ Compute optical flow and optionally decompose it into force components. diff --git a/tools/downstream_sync_manifest.json b/tools/downstream_sync_manifest.json new file mode 100644 index 0000000..3b50f09 --- /dev/null +++ b/tools/downstream_sync_manifest.json @@ -0,0 +1,48 @@ +{ + "version": 1, + "downstreams": [ + { + "name": "orisys-sdk-release", + "path": "../orisys-sdk-release", + "sync": [ + {"from": "docs", "to": "docs"}, + {"from": "examples", "to": "examples", "include": [ + "README.md", + "basic_pipeline.py", + "mini_pipeline.py", + "finger_pipeline.py", + "finger_pipeline_3dview.py", + "plot_data.py", + "two_sensor_pipeline.py" + ]}, + {"from": "config", "to": "config", "include": ["box.json", "finger.json", "mini.json"]} + ], + "checks": [ + "python -m py_compile examples/basic_pipeline.py examples/finger_pipeline.py examples/finger_pipeline_3dview.py examples/plot_data.py", + "python -c \"import pathlib; p=pathlib.Path('.'); hits=[f for f in p.rglob('*') if f.is_file() and 'examples/products' in f.read_text(encoding='utf-8', errors='ignore').replace('\\\\','/')]; print('stale products paths:' if hits else 'no stale products paths'); [print(x) for x in hits]\"" + ] + }, + { + "name": "sensor-bench", + "path": "../sensor-bench", + "sync": [ + {"from": "config", "to": "config", "include": ["box.json", "mini.json", "dd06-ov-0810.json"]} + ], + "checks": [ + "python tests/test_smoke.py" + ] + }, + { + "name": "finger-bench", + "path": "../finger-bench", + "sync": [ + {"from": "config", "to": "config", "include": ["finger.json", "dd02-ov.json"]}, + {"from": "assets/finger", "to": "assets/finger"} + ], + "checks": [ + "python tests/test_smoke.py", + "python -c \"import pathlib; t=pathlib.Path('README.md').read_text(encoding='utf-8'); print('README still mentions examples/products' if 'examples/products' in t else 'README products path ok')\"" + ] + } + ] +} diff --git a/tools/sync_downstreams.py b/tools/sync_downstreams.py new file mode 100644 index 0000000..c4f78aa --- /dev/null +++ b/tools/sync_downstreams.py @@ -0,0 +1,172 @@ +#!/usr/bin/env python3 +"""Plan and apply downstream file syncs from tools/downstream_sync_manifest.json. + +The ``apply`` command copies files/directories listed in the manifest. It does +not delete extra downstream files and does not run downstream tests. +""" + +from __future__ import annotations + +import argparse +import json +import shutil +import sys +from pathlib import Path + + +MANIFEST_NAME = "downstream_sync_manifest.json" + + +def sdk_root() -> Path: + return Path(__file__).resolve().parent.parent + + +def load_manifest(root: Path) -> dict: + path = Path(__file__).resolve().parent / MANIFEST_NAME + with path.open(encoding="utf-8") as handle: + data = json.load(handle) + if data.get("version") != 1: + raise SystemExit(f"unsupported manifest version: {data.get('version')}") + if not isinstance(data.get("downstreams"), list): + raise SystemExit("manifest is missing a downstreams list") + return data + + +def selected_downstreams(manifest: dict, target: str | None) -> list[dict]: + items = manifest["downstreams"] + if target is None: + return items + matches = [item for item in items if item.get("name") == target] + if not matches: + names = ", ".join(item.get("name", "") for item in items) + raise SystemExit(f"unknown target {target!r}; known: {names}") + return matches + + +def expand_jobs(root: Path, item: dict) -> list[tuple[Path, Path]]: + dest_root = (root / item["path"]).resolve() + jobs: list[tuple[Path, Path]] = [] + for entry in item.get("sync", []): + src_base = root / entry["from"] + dest_base = dest_root / entry["to"] + includes = entry.get("include") + if includes: + for name in includes: + jobs.append((src_base / name, dest_base / name)) + else: + jobs.append((src_base, dest_base)) + return jobs + + +def print_plan(root: Path, items: list[dict]) -> None: + print(f"SDK root: {root}") + print() + for item in items: + dest_root = (root / item["path"]).resolve() + print(f"== {item['name']} ==") + print(f"path: {dest_root}") + jobs = expand_jobs(root, item) + if jobs: + print("sync:") + for src, dest in jobs: + print(f" {src} -> {dest}") + else: + print("sync: (none)") + checks = item.get("checks") or [] + if checks: + print("checks:") + for command in checks: + print(f" {command}") + else: + print("checks: (none)") + print() + + +def check_paths(root: Path, items: list[dict]) -> int: + missing: list[str] = [] + print(f"SDK root: {root}") + print() + for item in items: + dest_root = (root / item["path"]).resolve() + print(f"== {item['name']} ==") + if dest_root.is_dir(): + print(f"ok downstream root: {dest_root}") + else: + print(f"MISS downstream root: {dest_root}") + missing.append(str(dest_root)) + for src, dest in expand_jobs(root, item): + src_ok = src.exists() + dest_note = "exists" if dest.exists() else "missing (ok until apply)" + status = "ok " if src_ok else "MISS" + print(f"{status} source: {src}") + print(f" dest: {dest} [{dest_note}]") + if not src_ok: + missing.append(str(src)) + print() + if missing: + print(f"{len(missing)} missing path(s).") + return 1 + print("all required source and downstream roots exist.") + return 0 + + +def copy_job(src: Path, dest: Path) -> None: + if not src.exists(): + raise FileNotFoundError(src) + if src.is_dir(): + shutil.copytree(src, dest, dirs_exist_ok=True) + return + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(src, dest) + + +def apply_sync(root: Path, items: list[dict]) -> int: + if check_paths(root, items) != 0: + print("apply aborted because required paths are missing.") + return 1 + + copied = 0 + for item in items: + print(f"== {item['name']} ==") + for src, dest in expand_jobs(root, item): + copy_job(src, dest) + copied += 1 + print(f"copied {src} -> {dest}") + print() + print(f"copied {copied} sync job(s).") + print("checks were not run; execute the listed check commands manually.") + return 0 + + +def parse_args(argv: list[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser(description=__doc__) + sub = parser.add_subparsers(dest="command", required=True) + + plan = sub.add_parser("plan", help="print intended sync jobs and checks") + plan.add_argument("--target", help="limit to one downstream name") + + check = sub.add_parser("check-paths", help="verify source and dest roots exist") + check.add_argument("--target", help="limit to one downstream name") + + apply_cmd = sub.add_parser("apply", help="copy manifest sources to downstreams") + apply_cmd.add_argument("--target", help="limit to one downstream name") + + return parser.parse_args(argv) + + +def main(argv: list[str] | None = None) -> int: + args = parse_args(argv if argv is not None else sys.argv[1:]) + root = sdk_root() + items = selected_downstreams(load_manifest(root), getattr(args, "target", None)) + if args.command == "plan": + print_plan(root, items) + return 0 + if args.command == "check-paths": + return check_paths(root, items) + if args.command == "apply": + return apply_sync(root, items) + raise SystemExit(f"unknown command: {args.command}") + + +if __name__ == "__main__": + raise SystemExit(main())