Merge branch 'stable'

docs/api.md

@@ -0,0 +1,336 @@
+# orisys API 文档
+
+本文件提供了 `orisys` 套件的中文文档
+
+## 准备 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.3.2-cp310-cp310-win_amd64.whl
+```
+
+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
+   ```
+
+4. 测试导入：
+```python
+import orisys
+print(orisys.__version__)
+```
+
+5 安装opencl（实验）:
+
+在不带nvidia显卡的设备，可选择通过opencl进行gpu 计算加速，需要确保opencl的库或驱动已经安装，然后在conda环境中安装依赖：
+
+``` bash
+pip install pyopencl
+conda install conda-forge::pyvkfft 
+```
+
+***
+
+## `Sensor` 类别
+### 描述
+`orisys`套件的核心类，用于从视频文件或实时摄像头中读取传感器图像，创建一个具体的传感器对象（实例）。并完成形变、光流及力信息的计算与管理。
+
+### 输入参数
+
+* **vid_src** (`int | str`, 必填): 传感器 ID、相机编号或视频路径。默认为 `0`。  
+* **config_name** (`str`，可选): 传感器配置文件名称或 `json` 文件路径，用于加载对应的参数配置；例如 `ddjx01` 或 `./config/ddjx01.json`。  
+* **cal_path** (`str`，可选，已弃用): 该参数仅为兼容旧代码保留，当前版本中不再使用，传入后也会被忽略。  
+* **backend** (`str`，可选): 光流场解耦计算后端，默认为 `auto`，可选`cupy`,`opencl`,`cpu`。  
+* **verbose** (`bool`，可选): 是否输出初始化及运行过程中的详细日志信息，默认为 `False`。  
+
+  
+### 返回
+* `Sensor` 实例，用于后续图像采集、形变计算和数据读取操作。
+### 示例
+
+```python
+# Example 1：  用相机编号创建
+from orisys import Sensor
+sensor = Sensor(0)
+
+# Example 2： 用视频文件创建
+sensor = Sensor("/data/data.mp4")
+```
+
+***
+
+## 2. `Sensor.get_img` 方法
+
+### 描述
+
+采集并预处理一帧图像并存到`Sensor` 类别中。
+
+
+### 返回
+* `bool`：是否成功读取图像。
+
+### 状态更新
+* 成功时更新`sensor`类里面的`sensor.img`。处理后的BGR格式图像(`uint8`，尺寸为json文件中`resolution_stitch`对应分辨率)。
+### 示例
+
+```python
+sensor.get_img() 
+```
+***
+
+## 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`.
+
+### 返回
+
+* `bool`：是否接触到物体，如果**check_motion**为`False`时返回`None`。
+
+### 示例
+
+```python
+sensor.get_img()
+
+is_touched = sensor.compute_deformation(check_motion=True, threshold=6)
+# 步骤 2.3: 计算触碰点 
+if is_touched:
+    sensor.compute_contact()
+```
+***
+## 4. `Sensor.compute_contact` 方法
+
+### 描述
+基于已计算的法向形变场进行接触区域分析，输出接触质心与轮廓等信息，并生成接触深度图，默认配置在`json`文件中，可按需调节。
+
+调用前置条件：需先执行`compute_deformation()`。
+
+### 返回
+`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. `Sensor.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`。
+* CENTROID： 触碰点的坐标，(x, y)。
+* CONTOUR： 触碰区域轮廓，`np.ndarray`, shape=(H, W), 未生成时返回`np.empty`
+
+时间戳
+
+* TIMESTAMP: 时间戳字符串（HH:MM:SS），`str`。
+
+注：H/W 由当前`json`文件中的`resolution_stitch`配置分辨率决定。
+
+### 返回
+
+`Tuple`
+
+按传入的 `sensor.info` 参数顺序返回一个元组，  
+返回值数量与有效参数数量一致。
+
+- 向量/图像类数据：`np.ndarray`  
+  - 若当前流程中尚未生成该数据，返回空数组
+- 标量类数据：`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. `Sensor.disconnect` 方法
+
+### 描述
+
+释放传感器相关资源并停止后台异步线程。 调用后将关闭视频/摄像头输入源，并销毁所有 OpenCV 窗口。
+
+建议在程序退出前调用以确保资源被正确释放。
+
+***
+***
+# 可视化相关
+
+## 1. `util.draw_arrows` 方法
+
+### 输入参数
+
+* **frame**：背景图像
+* **optical_flow**：光流场
+* **threshold**：光流箭头显示阈值
+* **grid_spacing**：光流箭头间距（pixel）
+* **arrow_scale**：箭头大小
+* **margin**：箭头最大长度/间距的比例
+* **colormap**：色图，如`cv2.COLORMAP_JET`
+* **below_threshold_color**：RGB格式的`uint8`颜色，如(0, 0, 255)
+* **edge_margin**: 不显示箭头边距（pixel）
+
+### 返回
+`np.ndarray`  ：箭头光流可视化图像
+
+## 2. `util.draw_contact` 方法
+
+### 输入参数
+
+* **image**：背景图像
+* **contour**：轮廓
+* **centroid**：触碰点
+* **point_color**：触碰点的颜色 (BGR)
+* **region_color**：轮廓的颜色 (BGR)
+
+### 返回
+`np.ndarray`  ：箭头光流可视化图像
+
+***
+
+# 配置标定相关
+
+## 1. `list_config` 方法
+
+### 描述
+列出内置传感器配置参数字典。
+
+### 返回
+
+* `list`: 内置传感器配置参数字典的名字列表。
+***
+## 2. `export_config` 方法
+
+### 描述
+导出当前传感器实例使用的配置参数字典。
+
+### 输入参数
+* **config_name**: 需要导出的配置参数字典名字，`str`
+* **path**: 导出的路径，默认`"./config/exported_config.json"`
+
+### 返回
+
+* `dict`: 导出的配置参数字典。
+
+### 保存
+
+* 导出内置的`config_name`配置参数字典至`path`
+
+***
+***
+
+## 常见问题解答 (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：若未指定或未找到标定文件，系统会在需要时创建新的拼接标定数据并保存到默认路径。
+拼接结果异常通常与标定数据、拼接配置或输入图像质量有关，建议重新生成拼接标定并检查配置参数。
+
+### Q6: 运行报错：“AttributeError: 'Stitcher' object has no attribute 'pos_default'”
+A: 请检查视频源的编号是否正确，以及是否能正常打开视频源。在linux 使用`v4l2-ctl --list-devices` 或 Windows使用`Get-PnpDevice -PresentOnly | Where-Object { $_.Class -match '^Camera' }` 列出摄像头设备。

docs/get_started.md

@@ -0,0 +1,138 @@
+叠动科技软件使用手册  
+版本： 0.3.2  
+更新日期： 2026年4月16日
+
+# 简介
+本文件介绍如何上手和运行叠动视触觉传感器配套的开发套件。本套件是配合叠动视触觉传感器进行图像处理，计算形变、力以及接触信息。它可以从摄像头或视频文件中读取图像，处理后打印和展示处理后信息。  
+支持操作系统：Windows、Ubuntu  
+建议Python 版本: 3.10
+
+# 基础环境设置 
+## 安装 Python 与 Anaconda
+1.	访问 [Anaconda 官网](https://www.anaconda.com/download)下载适合您操作系统的安装包（Windows、Linux）。
+2.	按照提示完成安装。（Widnows：建议在安装过程中勾选“将 Anaconda 添加到系统环境变量”选项，方便后续使用）。
+3.	安装完成后，打开命令行终端（Windows 用户可在”Anaconda Navigator”打开“Anaconda Prompt”），输入 `conda info` ，若能显示 conda 的信息，则说明安装成功。
+
+## 创建conda虚拟环境
+虚拟环境相当于一个独立的 Python 工作空间，可以避免不同项目所需的库版本冲突。
+打开命令行终端（或Anaconda Prompt），依次输入以下命令(以 python 3.10 为例)：
+``` bash
+conda create -n orisys python=3.10
+conda activate orisys
+```
+
+激活后，命令行提示符前会出现 `(orisys)` 字样，表示当前已进入虚拟环境。
+
+## 创建工作区文件夹
+“Anaconda Prompt”启动后的默认工作路径在用户根文件夹中，建议创建工作区文件夹方便管理，可以手动创建或者运行`mkdir <path>`命令：, 例如
+
+``` bash
+mkdir orisys_ws
+```
+
+创建后如果要更换工作区，使用 `cd <path>`命令，例如：
+
+``` bash
+cd "C:\Users\orisys\orisys_ws"
+```
+<div style="page-break-after: always;"></div>
+
+## 安装 CUDA 和 cuDNN（可选）
+如果您拥有 NVIDIA 显卡，并希望利用 GPU 加速计算，则需要安装 CUDA 工具包和 cuDNN。
+
+1. 方法一（官网下载）：
+访问 [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`
+该方法会自动配置好 CUDA 和 cuDNN，无需手动下载。
+
+注意：如果您的计算机没有 NVIDIA 显卡，或者不想使用 GPU 加速，可以跳过此步骤。套件也支持纯 CPU 运行（但速度可能较慢）。
+
+# 安装 orisys SDK
+
+orisys SDK 以 .whl 文件形式提供，您需要根据操作系统、Python 版本和硬件平台选择正确的文件。
+
+## 下载正确的 .whl 文件
+从官方渠道获取 .whl 文件，文件名格式通常为：
+orisys-{版本}-{Python版本}-{Python版本}-{操作系统}_{硬件架构}.whl
+例如：orisys-0.3.2-cp310-cp310-win_amd64.whl 表示：
+
+版本：0.3.2
+Python 版本：3.10（cp310）
+操作系统：Windows（win）
+硬件架构：64位（amd64）
+
+请根据您的系统选择对应的文件，或者咨询客服索取：
+
+## 安装 .whl 文件
+将下载好的 .whl 文件放在一个文件夹中（如上述`orisys_ws`文件夹），打开命令行（确保已激活 orisys 环境或使用"Anaconda Prompt"），使用 `cd` 命令切换到该文件夹，然后运行：
+
+``` bash
+# 请将文件名替换为您实际下载的文件名
+pip install orisys-0.3.2-cp310-cp310-win_amd64.whl
+```
+
+## 安装 CuPy（可选）
+注意：如果您没有安装 CUDA，或者使用 CPU 运行，可以跳过这一步。
+
+CuPy 是一个与 NumPy 类似但支持 GPU 加速的库，您需要根据您安装的 CUDA 版本选择对应的 CuPy 版本。
+
+方法一（使用 extras 参数，推荐）：
+在安装 orisys 时，可以直接指定 CUDA 版本，pip 会自动安装配套的 CuPy：
+
+```bash
+# 如果您的 CUDA 版本是 12.x
+pip install orisys[cuda12]
+
+# 如果您的 CUDA 版本是 13.x
+pip install orisys[cuda13]
+```
+如果之前已经安装了 orisys，可以单独安装 CuPy：
+
+方法二（手动安装）：
+
+``` bash
+# CUDA 12.x
+pip install cupy-cuda12x>=12.3.0
+
+# CUDA 13.x
+pip install cupy-cuda13x>=13.0.0
+```
+
+## 测试安装
+安装完成后，在命令行输入” python“命令进入 Python 环境， 并导入 orisys 库并查看版本号，验证是否成功：
+``` bash
+python
+import orisys
+print(orisys.__version__)
+```
+如果输出版本号（例如 0.3.2），则说明安装成功。
+
+# 使用方法
+## 运行示例程序
+套件里面包含了例子展示用法，运行步骤如下：
+
+### 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
+    ```
+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
+    python examples/basic_pipeline.py -v 0
+    ```
+5.	程序会运行，并自动打开可视化窗口和打印资料，在窗口上按键盘”q”键可以停止运行，按”r”键可以重设数据
+
+## 开发套件使用方法
+参考开发套件附带的开发文档。

docs/render_command.txt

@@ -0,0 +1 @@
+quarto render get_started.md --to docx