included low pass filter in package and add to plot_data example

2026-08-17 22:11:17 +08:00
parent 9a69f01278
commit 2e09c9360e
50 changed files with 1055 additions and 1873 deletions
@@ -25,7 +25,7 @@ pip install orisys-{version}-{python-version}-{python-version}-{os}_{machine}.wh
 ```
 如
 ```bash
-pip install orisys-0.4.2-cp310-cp310-win_amd64.whl
+pip install orisys-0.4.3-cp310-cp310-win_amd64.whl
 ```

 3. **安装 CuPy（根据您的 CUDA 版本选择）：**
@@ -63,7 +63,7 @@ print(orisys.__version__)
 ### 输入参数

 * **vid_src** (`int | str`, 必填): 传感器 ID、相机编号或视频路径。默认为 `0`。  
-* **config_name** (`str`，可选): 传感器配置文件名称或 `json` 文件路径，用于加载对应的参数配置；例如 `ddjx01` 或 `./config/ddjx01.json`。  
+* **config_name** (`str`，可选): 传感器配置文件名称或 `json` 文件路径，用于加载对应的参数配置；例如 `box` 或 `./config/box.json`。  
 * **cal_path** (`str`，可选，已弃用): 该参数仅为兼容旧代码保留，当前版本中不再使用，传入后也会被忽略。  
 * **backend** (`str`，可选): 光流场解耦计算后端，默认为 `auto`，可选`cupy`,`opencl`,`cpu`。  
 * **verbose** (`bool`，可选): 是否输出初始化及运行过程中的详细日志信息，默认为 `False`。  
@@ -238,7 +238,7 @@ flow = sensor.read_info(sensor.info.VRAW)

 ## `orisys.finger` 手指 UV pipeline

-`examples/products/ory_finger/finger_pipeline.py` 展示了一个更适合手指/单相机场景的高层 API：
+`examples/finger_pipeline.py` 展示了一个更适合手指/单相机场景的高层 API：

 1. 使用 `FingerRuntime.open()` 打开视频源、加载 Blender 导出的资产，并构建 UV 展开映射。
 2. 用 `grab_and_process()` 或 `read_source() + process_frame()` 获取一帧展开后的触觉图像。
@@ -262,7 +262,7 @@ flow = sensor.read_info(sensor.info.VRAW)
 #### 输入参数

 * **export_dir** (`str`，可选): 手指导出资产目录，默认值来自 `orisys.finger.DEFAULT_FINGER_EXPORT_DIR`。目录下通常需要包含 `mesh.npz`、`camera_intrinsics.npz`、`world_to_cam.npy`。
-* **config** (`str`，可选): Orisys 配置文件名称或路径，默认 `dd02`（兼容解析到 `dd02-ov`）。
+* **config** (`str`，可选): Orisys 配置文件名称或路径，默认 `finger`。
 * **map_cache** (`str`，可选): UV 展开缓存文件路径，默认值来自 `orisys.finger.DEFAULT_FINGER_MAP_CACHE`。
 * **source_scale** (`float`，可选): 输入相机分辨率缩放比例；未提供时根据配置自动推断。
 * **calib** (`str | None`，可选): 外部相机标定文件路径；未提供时优先使用导出资产中的内参。
@@ -282,7 +282,7 @@ flow = sensor.read_info(sensor.info.VRAW)
 from orisys.finger import FingerRuntime

 runtime = FingerRuntime.open(
-    config="dd02",
+    config="finger",
    video=0,
    verbose=True,
 )
@@ -312,7 +312,7 @@ runtime = FingerRuntime.open(

 #### 描述

-对一帧原始输入执行源图预处理、UV 展开，并把展开后的结果送入内部 `TactileProcessor`。这是 `examples/products/ory_finger/finger_pipeline.py` 中 profile 模式使用的方法。
+对一帧原始输入执行源图预处理、UV 展开，并把展开后的结果送入内部 `TactileProcessor`。这是 `examples/finger_pipeline.py` 中 profile 模式使用的方法。

 #### 输入参数

@@ -327,7 +327,7 @@ runtime = FingerRuntime.open(

 #### 描述

-先读取一帧视频源，再调用 `process_frame()` 完成 UV 展开并推入内部触觉处理器。非 profile 模式下，`examples/products/ory_finger/finger_pipeline.py` 使用该方法作为主循环入口。
+先读取一帧视频源，再调用 `process_frame()` 完成 UV 展开并推入内部触觉处理器。非 profile 模式下，`examples/finger_pipeline.py` 使用该方法作为主循环入口。

 #### 输入参数

@@ -357,7 +357,7 @@ runtime = FingerRuntime.open(

 #### 描述

-先执行一次采集与 UV 展开，然后调用 `runtime.tactile.warmup()` 预热内部光流/HHD 相关缓存。`examples/products/ory_finger/finger_pipeline.py` 在进入主循环前会先执行一次 warmup。
+先执行一次采集与 UV 展开，然后调用 `runtime.tactile.warmup()` 预热内部光流/HHD 相关缓存。`examples/finger_pipeline.py` 在进入主循环前会先执行一次 warmup。

 #### 输入参数

@@ -386,7 +386,7 @@ runtime = FingerRuntime.open(
 * **raw_sensor**: 底层 `Sensor` 对象。
 * **info**: 与 `Sensor.info` 相同的枚举入口。
 * **img / flow / vnormal / vshear / depth_map**: 当前帧处理结果。
-* **mask_stats**: 有效 UV 区域统计信息；`examples/products/ory_finger/finger_pipeline.py` 会读取 `mask_stats["coverage"]` 输出当前掩码覆盖率。
+* **mask_stats**: 有效 UV 区域统计信息；`examples/finger_pipeline.py` 会读取 `mask_stats["coverage"]` 输出当前掩码覆盖率。
 * **valid_mask**: 当前有效区域掩码。

 #### 说明
@@ -395,7 +395,7 @@ runtime = FingerRuntime.open(

 ### 10. 最小手指 pipeline 示例

-下面的流程与 `examples/products/ory_finger/finger_pipeline.py` 一致：
+下面的流程与 `examples/finger_pipeline.py` 一致：

 ```python
 import time
@@ -404,7 +404,7 @@ import orisys
 from orisys.finger import FingerRuntime

 runtime = FingerRuntime.open(
-    config="dd02",
+    config="finger",
    video=0,
    verbose=True,
 )
@@ -462,7 +462,7 @@ finally:

 ### 11. 关于 profile 模式

-`examples/products/ory_finger/finger_pipeline.py` 中的 `--profile` / `--profile-every` 是示例脚本参数，不属于 `orisys` SDK 核心 API。本质上它只是把主循环拆成：
+`examples/finger_pipeline.py` 中的 `--profile` / `--profile-every` 是示例脚本参数，不属于 `orisys` SDK 核心 API。本质上它只是把主循环拆成：

 1. `runtime.read_source()`
 2. `runtime.process_frame(...)`
@@ -1,5 +1,5 @@
 叠动科技软件使用手册  
-版本： 0.4.2  
+版本： 0.4.3  
 更新日期： 2026年7月13日

 # 简介
@@ -57,9 +57,9 @@ orisys SDK 以 .whl 文件形式提供，您需要根据操作系统、Python
 ## 下载正确的 .whl 文件
 从官方渠道获取 .whl 文件，文件名格式通常为：
 orisys-{版本}-{Python版本}-{Python版本}-{操作系统}_{硬件架构}.whl
-例如：orisys-0.4.2-cp310-cp310-win_amd64.whl 表示：
+例如：orisys-0.4.3-cp310-cp310-win_amd64.whl 表示：

-版本：0.4.2
+版本：0.4.3
 Python 版本：3.10（cp310）
 操作系统：Windows（win）
 硬件架构：64位（amd64）
@@ -71,7 +71,7 @@ Python 版本：3.10（cp310）

 ``` bash
 # 请将文件名替换为您实际下载的文件名
-pip install orisys-0.4.2-cp310-cp310-win_amd64.whl
+pip install orisys-0.4.3-cp310-cp310-win_amd64.whl
 ```

 ## 安装 CuPy（可选）
@@ -108,18 +108,18 @@ python
 import orisys
 print(orisys.__version__)
 ```
-如果输出版本号（例如 0.4.2），则说明安装成功。
+如果输出版本号（例如 0.4.3），则说明安装成功。

 # 使用方法
 ## 运行示例程序
 套件里面包含了多个例子，建议都在仓库根目录运行（即 `config/`、`examples/`、`assets/` 同级目录）。按产品入口如下：

-1. `examples/products/ory_box/basic_pipeline.py`：ORY-BOX 复眼/拼接传感器基础 OpenCV 示例（默认配置 `ddjx01`）
-2. `examples/products/ory_mini/basic_pipeline.py`：ORY-MINI 基础 OpenCV 示例（默认配置 `mini`）
-3. `examples/products/ory_finger/finger_pipeline.py`：ORY-FINGER 2D UV 最小流程（默认配置 `dd02`）
-4. `examples/products/ory_finger/finger_pipeline_3dview.py`：ORY-FINGER Qt 3D 可视化界面（默认配置 `dd02`）
+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`）
+4. `examples/finger_pipeline_3dview.py`：ORY-FINGER Qt 3D 可视化界面（默认配置 `finger`）

-`dd02` 是当前 ORY-FINGER 的稳定别名，实际会解析到 `dd02-ov`。旧路径 `examples/basic_pipeline.py` / `examples/finger_pipeline*.py` 仍可作为兼容入口。
+`finger` 是当前 ORY-FINGER 的产品配置名。`dd02` 仍可作为兼容别名，实际会解析到 `dd02-ov`。

 下面先介绍最基础的 ORY-BOX 运行方式。

@@ -129,7 +129,7 @@ print(orisys.__version__)
 3.	如果第一步没有输出，传感器的ID就是“0”，如果第一步有一个设备，传感器的ID就是“1”，如此类推。
 4.	在确定了传感器的ID（下方例子假设为“0”）后，打开Anaconda Prompt, 切换到工作路径，然后在命令行中输入：
    ``` bash
-    python examples/products/ory_box/basic_pipeline.py -v 0 -c ddjx01
+    python examples/basic_pipeline.py -v 0 -c box
    ```
 5.	程序会运行，并自动打开可视化窗口和打印资料，在窗口上按键盘”q”键可以停止运行，按”r”键可以重设数据

@@ -139,22 +139,22 @@ print(orisys.__version__)
 3.	根据新增的输出，例如”/dev/video0”，确定传感器的ID为“0”, 如果是”/dev/video3”的话ID为“3” ，如此类推。
 4.	在确定了传感器的ID（下方例子假设为“0”）后，打开终端, 激活相应的python环境，切换到工作路径，然后在命令行中输入：
    ``` bash
-    python examples/products/ory_box/basic_pipeline.py -v 0 -c ddjx01
+    python examples/basic_pipeline.py -v 0 -c box
    ```
 5.	程序会运行，并自动打开可视化窗口和打印资料，在窗口上按键盘”q”键可以停止运行，按”r”键可以重设数据

 ### ORY-FINGER UV 示例

-如果您使用的是 ORY-FINGER（当前配置别名 `dd02`），可运行：
+如果您使用的是 ORY-FINGER（配置名 `finger`），可运行：

 ``` bash
-python examples/products/ory_finger/finger_pipeline.py --camera_id 0 --config dd02
+python examples/finger_pipeline.py --camera_id 0 --config finger
 ```

 如果输入来自视频文件，也可以改用：

 ``` bash
-python examples/products/ory_finger/finger_pipeline.py --video ./data/sample.mp4 --config dd02
+python examples/finger_pipeline.py --video ./data/sample.mp4 --config finger
 ```

 该示例会：
@@ -171,19 +171,18 @@ python examples/products/ory_finger/finger_pipeline.py --video ./data/sample.mp4
 例如：

 ``` bash
-python examples/products/ory_finger/finger_pipeline.py --camera_id 0 --config dd02
+python examples/finger_pipeline.py --camera_id 0 --config finger
 ```

 ### ORY-FINGER 3D 可视化界面

 如果要使用 GUI ,安装GUI依赖：
 ``` bash
-pip install open3d
-pip install pyqt5 pyqtgraph
+pip install -e ".[gui]"
 ```
 然后运行：
 ``` bash
-python examples/products/ory_finger/finger_pipeline_3dview.py --video 0 --config dd02
+python examples/finger_pipeline_3dview.py --video 0 --config finger
 ```

 该界面会提供：
@@ -1,171 +0,0 @@
-# Publishing Orisys to PyPI
-
-This document covers the **Linux manylinux binary wheel** path (Nuitka-compiled
-`orisys` for CPython 3.10 / 3.11 / 3.12). Windows wheels are still built on
-Windows hosts; they cannot be produced inside the manylinux container.
-
-## Why Docker?
-
-PyPI rejects wheels tagged `manylinux_x86_64` (missing glibc ABI version). A
-compliant tag looks like:
-
-```text
-orisys-0.4.2-cp310-cp310-manylinux_2_28_x86_64.whl
-orisys-0.4.2-cp311-cp311-manylinux_2_28_x86_64.whl
-orisys-0.4.2-cp312-cp312-manylinux_2_28_x86_64.whl
-```
-
-Those tags are produced by building inside the official manylinux image and
-running `auditwheel repair`. On Windows, use **Docker Desktop in Linux container
-mode**.
-
-> Note: we use `manylinux_2_28_x86_64` (not 2014). Recent NumPy/SciPy no longer
-> provide manylinux2014 wheels and fail to build from source on that older GCC.
-
-## Prerequisites
-
-1. Docker Desktop installed and running (**Linux containers**, not Windows containers).
-2. Repository checked out locally (this tree is bind-mounted into the container).
-3. Version bumped in `src/orisys/__init__.py` (`__version__`) before every upload.
-   PyPI never allows re-uploading the same filename/version.
-4. PyPI / TestPyPI project-scoped API tokens (never commit tokens or `.pypirc` with secrets).
-
-Quick Docker check:
-
-```powershell
-docker version --format "{{.Server.Os}}"
-# expect: linux
-docker run --rm hello-world
-```
-
-## Build manylinux wheels (3.10 / 3.11 / 3.12)
-
-From the repository root:
-
-```bash
-python build/run.py manylinux
-```
-
-Or call the Docker helper directly:
-
-```powershell
-.\build\wheel\docker\run.ps1
-```
-
-Default builds **all three** ABIs. To build a subset:
-
-```powershell
-python build/run.py manylinux -PythonVersions 3.10,3.12
-python build/run.py manylinux -PythonVersions 3.11
-```
-
-What this does:
-
-1. Builds `orisys-manylinux` from [`build/wheel/docker/Dockerfile.manylinux`](../build/wheel/docker/Dockerfile.manylinux)
-   (`quay.io/pypa/manylinux_2_28_x86_64` with Nuitka/auditwheel in cp310/cp311/cp312).
-2. Runs [`build/wheel/docker/entrypoint.sh`](../build/wheel/docker/entrypoint.sh), which loops:
-
-   ```bash
-   /opt/python/cp310-cp310/bin/python build/wheel/build.py --target pypi-linux
-   /opt/python/cp311-cp311/bin/python build/wheel/build.py --target pypi-linux
-   /opt/python/cp312-cp312/bin/python build/wheel/build.py --target pypi-linux
-   ```
-
-3. For each ABI: Nuitka compile → wheel → `auditwheel repair` → isolated smoke test.
-4. Artifacts land in:
-
-   - `dist/repaired/orisys-*-manylinux_2_28_x86_64.whl` (upload candidates)
-   - `SDK/<version>/` (same compliant wheels)
-
-Expect roughly **3×** the wall time of a single-ABI build.
-
-Rebuild without refreshing the image:
-
-```powershell
-python build/run.py manylinux -SkipImageBuild
-```
-
-Equivalent manual `docker` invocation:
-
-```powershell
-docker build -f build/wheel/docker/Dockerfile.manylinux -t orisys-manylinux .
-docker run --rm `
-  -e ORISYS_BUILD_TARGET=pypi-linux `
-  -e ORISYS_PYTHON_TAGS=cp310-cp310,cp311-cp311,cp312-cp312 `
-  -v "${PWD}:/src" `
-  orisys-manylinux
-```
-
-### Acceptance checks before upload
-
- Each filename contains `cp310` / `cp311` / `cp312` and `manylinux_2_28_x86_64`
-  (or another accepted manylinux tag such as `manylinux_2_17_x86_64`).
- Isolated smoke test printed `public API imports OK` for every ABI.
- Do **not** upload any wheel still tagged `linux_x86_64` or bare `manylinux_x86_64`.
-
-Optional re-verify on a Linux machine:
-
-```bash
-python build/run.py verify dist/repaired/orisys-*-cp310-cp310-manylinux_*.whl
-```
-
-## Promote: TestPyPI then PyPI
-
-Install upload tooling in a clean environment:
-
-```powershell
-python -m pip install --upgrade twine
-```
-
-### 1. Upload to TestPyPI
-
-```powershell
-$env:TWINE_USERNAME = "__token__"
-$env:TWINE_PASSWORD = "<TestPyPI API token>"
-
-python -m twine check dist/repaired/*.whl
-python -m twine upload --repository testpypi dist/repaired/*.whl
-```
-
-Install from TestPyPI in a fresh venv (pull runtime deps from real PyPI), testing
-each Python you care about:
-
-```powershell
-py -3.10 -m venv .venv-testpypi310
-.\.venv-testpypi310\Scripts\Activate.ps1
-python -m pip install --index-url https://test.pypi.org/simple/ `
-  --extra-index-url https://pypi.org/simple `
-  "orisys==<version>"
-python -c "import orisys; print(orisys.__version__)"
-```
-
-### 2. Upload the same artifacts to PyPI
-
-Only after TestPyPI install/import succeeds:
-
-```powershell
-$env:TWINE_USERNAME = "__token__"
-$env:TWINE_PASSWORD = "<PyPI API token>"
-
-python -m twine upload dist/repaired/*.whl
-```
-
-Prefer CI **Trusted Publishing** (OIDC) for production uploads so long-lived tokens
-are not stored on developer machines.
-
-## Related local targets
-
-| Command | Purpose |
-|---------|---------|
-| `python build/run.py wheel` | Preferred wheel builder launcher |
-| `python build/wheel/build.py` | Direct wheel builder (current host) |
-| `python build/run.py wheel --target pypi-linux` | Linux-only; requires manylinux + CPython 3.10–3.12 |
-| `python build/run.py wheel-win` | Windows wheels for py310/py311/py312 conda envs |
-| `python build/run.py manylinux` | manylinux Docker runner |
-| `python build/run.py gui finger` | ORY-FINGER standalone GUI |
-| `python -m build` | Pure-Python / sdist path from `pyproject.toml` (no Nuitka) |
-
-See also [`build/README.md`](../build/README.md) for the target-oriented layout.
-
-Windows binary wheels and Linux manylinux wheels must be built on their respective
-platforms. Never rename a platform tag to bypass PyPI validation.