orisys-tech/orisys-sdk

T

ykcheungab 35190562e5 标定指纹改读生效值并按测量/读数分组 - What: calibration.py 新增 FILTER_MEASUREMENT_KEYS（flow_ema_alpha）与 FILTER_READOUT_KEYS（中值窗口、低通截止/阶数/采样率/rate_auto）、filters_fingerprint()（把 Sensor.filters_state() 归一化成 {measurement, readout, preset, source}：非法值丢弃、来源没写的键不出现而不是补默认、空映射返回 {} 表示"无记录"）、filter_mismatches()（按组判读差异）与 _filters_from_config / _flat_filters_from（扁平旧格式与 preset 展开的兼容解析，显式键优先）；pipeline_from_sensor_json() 新增 filters_state= 关键字——传了生效值就用生效值，否则读文件的 filters 段并标注 source="sensor.json.filters"，返回结构化 filters 键，删除原先会凭空补出 0.5/3/10 的扁平键与 enabled 覆盖逻辑；Calibration.to_dict() 写 meta.filters（同时保留扁平键供旧读者按名取用）；parse() 把 filters 读回 pipeline（此前 to_dict 写进 meta 的滤波键在读回时被整段丢弃，指纹实际是"只写不读"）；check() 改用 filter_mismatches 分开报告——measurement 组差异进 warnings 且措辞含 not comparable，readout 组差异进新增字段 CheckResult.notes（只记录、不拦截）；build(extra_meta=…) 把 filters 与扁平滤波键折进结构化组。tests/test_calibration.py 新增 11 项测试（分组、preset 展开与显式键优先、enabled:false 全关、非法值为空而非默认、写入-读回往返、旧扁平文档读回、生效值压过文件、四个预设逐档核对）。docs/filters.md 新增第 7 节。 - Why: 用户决策 B 要求"Sensor.filters_state() 作为唯一生效值出口，calibration.py 指纹与 session.json 都读它、不读配置文件，指纹分 measurement/readout 两组"；动手时确认旧实现三个问题叠加：来源错（读文件、被 filters.enabled 覆盖、文件没写就补默认 0.5/3/10），写进 meta 的指纹在读回时被丢弃，check() 因此永远比不出滤波差异——审计链是断的，不是不精确。 - Verification: SDK 全量 pytest 335 passed / 15 skipped，唯一失败 test_vnormal_longrun_no_outlier_jumps 需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧（环境/数据，与本改动无关）；external-frame 模式逐预设构造真实 Sensor，filters_fingerprint(filters_state()) 得 off(1.0,1,0.0) / low_latency(1.0,3,0.0) / balanced(0.5,3,0.0) / low_noise(0.3,3,10.0)；写入→读回往返后 measurement/readout/preset 完整保留且 to_dict 幂等；旧扁平 meta 文档仍读回同一指纹；.repro/verify_cal_filters.py 50 项全绿。 - Not in this change: 未动 app（app 的 meta_from_sensor_json 只取 4 个键，不受影响）；未升级 venv 内 SDK；examples/filters 的四个机器可读预设片段与 app 侧 wrapper/齿轮/CSV 17 列未动。

2026-09-14 10:43:58 +08:00

update plot example

2026-01-30 20:04:23 +08:00

refractor capture to a module

2026-08-23 15:53:02 +08:00

fix pypi cannot check after upload

2026-09-12 17:43:40 +08:00

organize settings to dedicated sensors folder, json + assets

2026-08-23 12:21:24 +08:00

fix/update dd02 asset to 0703 version

2026-07-09 13:55:27 +08:00

标定指纹改读生效值并按测量/读数分组 - What: calibration.py 新增 FILTER_MEASUREMENT_KEYS（flow_ema_alpha）与 FILTER_READOUT_KEYS（中值窗口、低通截止/阶数/采样率/rate_auto）、filters_fingerprint()（把 Sensor.filters_state() 归一化成 {measurement, readout, preset, source}：非法值丢弃、来源没写的键不出现而不是补默认、空映射返回 {} 表示"无记录"）、filter_mismatches()（按组判读差异）与 _filters_from_config / _flat_filters_from（扁平旧格式与 preset 展开的兼容解析，显式键优先）；pipeline_from_sensor_json() 新增 filters_state= 关键字——传了生效值就用生效值，否则读文件的 filters 段并标注 source="sensor.json.filters"，返回结构化 filters 键，删除原先会凭空补出 0.5/3/10 的扁平键与 enabled 覆盖逻辑；Calibration.to_dict() 写 meta.filters（同时保留扁平键供旧读者按名取用）；parse() 把 filters 读回 pipeline（此前 to_dict 写进 meta 的滤波键在读回时被整段丢弃，指纹实际是"只写不读"）；check() 改用 filter_mismatches 分开报告——measurement 组差异进 warnings 且措辞含 not comparable，readout 组差异进新增字段 CheckResult.notes（只记录、不拦截）；build(extra_meta=…) 把 filters 与扁平滤波键折进结构化组。tests/test_calibration.py 新增 11 项测试（分组、preset 展开与显式键优先、enabled:false 全关、非法值为空而非默认、写入-读回往返、旧扁平文档读回、生效值压过文件、四个预设逐档核对）。docs/filters.md 新增第 7 节。 - Why: 用户决策 B 要求"Sensor.filters_state() 作为唯一生效值出口，calibration.py 指纹与 session.json 都读它、不读配置文件，指纹分 measurement/readout 两组"；动手时确认旧实现三个问题叠加：来源错（读文件、被 filters.enabled 覆盖、文件没写就补默认 0.5/3/10），写进 meta 的指纹在读回时被丢弃，check() 因此永远比不出滤波差异——审计链是断的，不是不精确。 - Verification: SDK 全量 pytest 335 passed / 15 skipped，唯一失败 test_vnormal_longrun_no_outlier_jumps 需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧（环境/数据，与本改动无关）；external-frame 模式逐预设构造真实 Sensor，filters_fingerprint(filters_state()) 得 off(1.0,1,0.0) / low_latency(1.0,3,0.0) / balanced(0.5,3,0.0) / low_noise(0.3,3,10.0)；写入→读回往返后 measurement/readout/preset 完整保留且 to_dict 幂等；旧扁平 meta 文档仍读回同一指纹；.repro/verify_cal_filters.py 50 项全绿。 - Not in this change: 未动 app（app 的 meta_from_sensor_json 只取 4 个键，不受影响）；未升级 venv 内 SDK；examples/filters 的四个机器可读预设片段与 app 侧 wrapper/齿轮/CSV 17 列未动。

2026-09-14 10:43:58 +08:00

滤波说明落到文档与 examples：三级位置/性质、四个预设、可追溯性清单 - What: 新增 docs/filters.md（json.load 不支持注释，故建议以"代码预设 + 文档 + 可复制配置"承载：三级滤波的作用位置与性质对照——flow_ema_alpha 在 compute_flow/HHD 之前、改变测量故两次录制不可比，中值与低通是读数滤波；取值规则：每级按值开关、非法值一律关、filters.enabled 仅作废弃别名、显式键优先于预设；FILTER_PRESETS 四个档位的延迟与用途表；configure()/filters_state() 用法；force_triplets() 两个 buffer 的语义与尖峰实测 10/999；可追溯性五条清单）与 examples/filters/README.md（off/low_latency/balanced/low_noise 四段可直接整块替换的 filters 配置、preset 等价写法、"从预设出发只改一个键"的写法、复制后用 filters_state() 核对生效值的片段）。 - Why: 用户提出"在 json 里加 comment 说明建议的滤波，或在 examples 里写"，查证 configs.py 使用 json.load 且环境无 json5/commentjson，加注释会导致加载失败；因此把建议做成可执行预设并在文档与 examples 中给出可复制版本。 - Verification: 文档中的四个预设与 FILTER_PRESETS 逐值一致；示例片段与 sensors/*/sensor.json 的 filters 段结构一致；filters_state()/force_triplets() 的行为已用 external-frame 模式实测（预设解析结果与尖峰 10/999 对照）。 - Not in this change: 未生成四个独立的 sensor_<preset>.json 整机配置文件（README 里给的是整块 filters 段）；calibration.py 指纹尚未改读 filters_state()；venv 内 SDK 未升级；app 侧 wrapper/齿轮与 CSV 17 列未动。

2026-09-14 10:36:00 +08:00

test if optical flow integration error: not significant for Mems

2026-09-01 21:27:10 +08:00

滤波配置自描述：去掉覆盖式总开关，每级按自己的值生效 - What: sensor.py 删除 filters.enabled 这个覆盖层——flow_ema_alpha / force_median_window / force_lowpass_cutoff_hz 现在各自按值生效（0<α<1 才滤、≤1 关中值、≤0 关低通），非法值一律回落到"关"而不再回落到"默认开"（原实现里非法取值的 except 分支会把 cutoff 变回 10 Hz）；enabled 仅作废弃别名保留（显式 false = 三级全关）并在 verbose 时提示弃用，true 不再有覆盖作用；_filters_enabled 改为派生量（任一级在滤才为真）供旧调用方查询。三份 sensors/{box,mini,finger}/sensor.json 的 filters 段改为自描述且默认全关（flow_ema_alpha 1.0 / force_median_window 1 / force_lowpass_cutoff_hz 0.0 / order 2 / sample_rate "auto"）。 - Why: 用户问"flow_ema_alpha 是不是受 filter_enabled 控制、这样合适吗"，查证后确认三级都被同一总开关覆盖，且出厂配置写 enabled:false 却仍列着 0.5/3，导致文件说的与设备实际跑的不一致（审计/指纹会误报）；同时 flow_ema_alpha 位于 HHD 之前、改变的是测量本身，与中值/低通这类读数滤波性质不同，不应被一个开关捆绑。 - Verification: 用 SDK 的 external-frame 模式逐个 bundle 构造真实 Sensor 并读取解析结果：box/mini/finger 均为 ema=1.0、median=1、cutoff=0.0、lowpass_on=False、any_stage=False；三份 JSON 解析通过；compileall 通过；SDK 内 _filters_enabled 仅剩派生定义一处引用。 - Not in this change: 未动采集路径与 read_info/force_triplets（第 2 步），未动 calibration.py 指纹（第 2 步），未升级 venv 里的 SDK（第 5 步）——因此 app 当前行为不变（它仍在运行时硬编码 lowpass_cutoff_hz=10，压过本配置），"默认关"要到 app 改用 FilterSettings.apply_to(sensor) 后才在界面体现。

2026-09-14 10:26:39 +08:00

标定指纹改读生效值并按测量/读数分组 - What: calibration.py 新增 FILTER_MEASUREMENT_KEYS（flow_ema_alpha）与 FILTER_READOUT_KEYS（中值窗口、低通截止/阶数/采样率/rate_auto）、filters_fingerprint()（把 Sensor.filters_state() 归一化成 {measurement, readout, preset, source}：非法值丢弃、来源没写的键不出现而不是补默认、空映射返回 {} 表示"无记录"）、filter_mismatches()（按组判读差异）与 _filters_from_config / _flat_filters_from（扁平旧格式与 preset 展开的兼容解析，显式键优先）；pipeline_from_sensor_json() 新增 filters_state= 关键字——传了生效值就用生效值，否则读文件的 filters 段并标注 source="sensor.json.filters"，返回结构化 filters 键，删除原先会凭空补出 0.5/3/10 的扁平键与 enabled 覆盖逻辑；Calibration.to_dict() 写 meta.filters（同时保留扁平键供旧读者按名取用）；parse() 把 filters 读回 pipeline（此前 to_dict 写进 meta 的滤波键在读回时被整段丢弃，指纹实际是"只写不读"）；check() 改用 filter_mismatches 分开报告——measurement 组差异进 warnings 且措辞含 not comparable，readout 组差异进新增字段 CheckResult.notes（只记录、不拦截）；build(extra_meta=…) 把 filters 与扁平滤波键折进结构化组。tests/test_calibration.py 新增 11 项测试（分组、preset 展开与显式键优先、enabled:false 全关、非法值为空而非默认、写入-读回往返、旧扁平文档读回、生效值压过文件、四个预设逐档核对）。docs/filters.md 新增第 7 节。 - Why: 用户决策 B 要求"Sensor.filters_state() 作为唯一生效值出口，calibration.py 指纹与 session.json 都读它、不读配置文件，指纹分 measurement/readout 两组"；动手时确认旧实现三个问题叠加：来源错（读文件、被 filters.enabled 覆盖、文件没写就补默认 0.5/3/10），写进 meta 的指纹在读回时被丢弃，check() 因此永远比不出滤波差异——审计链是断的，不是不精确。 - Verification: SDK 全量 pytest 335 passed / 15 skipped，唯一失败 test_vnormal_longrun_no_outlier_jumps 需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧（环境/数据，与本改动无关）；external-frame 模式逐预设构造真实 Sensor，filters_fingerprint(filters_state()) 得 off(1.0,1,0.0) / low_latency(1.0,3,0.0) / balanced(0.5,3,0.0) / low_noise(0.3,3,10.0)；写入→读回往返后 measurement/readout/preset 完整保留且 to_dict 幂等；旧扁平 meta 文档仍读回同一指纹；.repro/verify_cal_filters.py 50 项全绿。 - Not in this change: 未动 app（app 的 meta_from_sensor_json 只取 4 个键，不受影响）；未升级 venv 内 SDK；examples/filters 的四个机器可读预设片段与 app 侧 wrapper/齿轮/CSV 17 列未动。

2026-09-14 10:43:58 +08:00

标定指纹改读生效值并按测量/读数分组 - What: calibration.py 新增 FILTER_MEASUREMENT_KEYS（flow_ema_alpha）与 FILTER_READOUT_KEYS（中值窗口、低通截止/阶数/采样率/rate_auto）、filters_fingerprint()（把 Sensor.filters_state() 归一化成 {measurement, readout, preset, source}：非法值丢弃、来源没写的键不出现而不是补默认、空映射返回 {} 表示"无记录"）、filter_mismatches()（按组判读差异）与 _filters_from_config / _flat_filters_from（扁平旧格式与 preset 展开的兼容解析，显式键优先）；pipeline_from_sensor_json() 新增 filters_state= 关键字——传了生效值就用生效值，否则读文件的 filters 段并标注 source="sensor.json.filters"，返回结构化 filters 键，删除原先会凭空补出 0.5/3/10 的扁平键与 enabled 覆盖逻辑；Calibration.to_dict() 写 meta.filters（同时保留扁平键供旧读者按名取用）；parse() 把 filters 读回 pipeline（此前 to_dict 写进 meta 的滤波键在读回时被整段丢弃，指纹实际是"只写不读"）；check() 改用 filter_mismatches 分开报告——measurement 组差异进 warnings 且措辞含 not comparable，readout 组差异进新增字段 CheckResult.notes（只记录、不拦截）；build(extra_meta=…) 把 filters 与扁平滤波键折进结构化组。tests/test_calibration.py 新增 11 项测试（分组、preset 展开与显式键优先、enabled:false 全关、非法值为空而非默认、写入-读回往返、旧扁平文档读回、生效值压过文件、四个预设逐档核对）。docs/filters.md 新增第 7 节。 - Why: 用户决策 B 要求"Sensor.filters_state() 作为唯一生效值出口，calibration.py 指纹与 session.json 都读它、不读配置文件，指纹分 measurement/readout 两组"；动手时确认旧实现三个问题叠加：来源错（读文件、被 filters.enabled 覆盖、文件没写就补默认 0.5/3/10），写进 meta 的指纹在读回时被丢弃，check() 因此永远比不出滤波差异——审计链是断的，不是不精确。 - Verification: SDK 全量 pytest 335 passed / 15 skipped，唯一失败 test_vnormal_longrun_no_outlier_jumps 需要 1200 帧而 data/sample/s1_480p.mp4 只有 577 帧（环境/数据，与本改动无关）；external-frame 模式逐预设构造真实 Sensor，filters_fingerprint(filters_state()) 得 off(1.0,1,0.0) / low_latency(1.0,3,0.0) / balanced(0.5,3,0.0) / low_noise(0.3,3,10.0)；写入→读回往返后 measurement/readout/preset 完整保留且 to_dict 幂等；旧扁平 meta 文档仍读回同一指纹；.repro/verify_cal_filters.py 50 项全绿。 - Not in this change: 未动 app（app 的 meta_from_sensor_json 只取 4 个键，不受影响）；未升级 venv 内 SDK；examples/filters 的四个机器可读预设片段与 app 侧 wrapper/齿轮/CSV 17 列未动。

2026-09-14 10:43:58 +08:00

automate publishing: release github + release pypi

2026-09-12 16:50:55 +08:00

.gitignore

added 5 sensors multi-stream support, 5 finger reach > 100 fps stable using .mp4 video

2026-09-13 12:18:27 +08:00

MANIFEST.in

exclude docs from wheel; harden bundle item handling; single-source version

2026-09-12 16:19:34 +08:00

nuitka-crash-report.xml

update sorting tolerance

2026-01-25 09:50:10 +08:00

pyproject.toml

exclude docs from wheel; harden bundle item handling; single-source version

2026-09-12 16:19:34 +08:00

pytest.ini

added preflight check

2026-09-12 15:49:28 +08:00

README.md

included low pass filter in package and add to plot_data example

2026-08-17 22:11:17 +08:00

requirements-dev.txt

prepare for dd03 shipping

2026-08-03 14:20:30 +08:00

requirements.txt

included low pass filter in package and add to plot_data example

2026-08-17 22:11:17 +08:00

setup.py

update pip install .copy manifest for developments

2026-08-26 20:04:40 +08:00

README.md

Orisys SDK

Orisys SDK is a Python toolkit for optical tactile sensing. It provides image capture, stitching, dense optical flow, Helmholtz-Hodge decomposition, contact/depth estimation, and several runnable examples for camera and video-based workflows.

PyPI: https://pypi.org/project/orisys/

Repository Layout

src/orisys/: installable SDK package
config/: default and lab/runtime JSON configurations
examples/: runnable demos (basic_pipeline.py, mini_pipeline.py, finger_pipeline*.py) plus shared gui/, pipeline/, viz/
scripts/: maintenance, calibration, packaging, and demo scripts
tools/: non-package tooling such as patch-generation utilities
tests/: automated pytest suite
docs/: usage and API documentation

Quick Start

1. Create an environment

conda create -n orisys python=3.10
conda activate orisys

2. Install the SDK in editable mode

pip install -e .

Optional GPU extras:

pip install -e .[cuda12]

or

pip install -e .[cuda13]

3. Run tests

pytest

4. Run an example

ORY-BOX:

python examples/basic_pipeline.py -v 0 -c box

ORY-MINI:

python examples/mini_pipeline.py -v 0 -c mini

ORY-FINGER:

python examples/finger_pipeline.py --camera_id 0 --config finger

Run commands from the repository root.

Configuration

The canonical configuration files now live in the repo-level config/ folder. The package loader orisys.configs resolves configs from:

an explicit JSON file path
a config file stem under config/ (for example box, mini, finger)
a product alias such as dd02 -> dd02-ov
a backward-compatible JSON "name" match, such as "prototype"

Examples:

import orisys

sensor = orisys.Sensor(0, config_name="box")
cfg = orisys.export_config("box", "./config/exported_config.json")

Examples and Tools

Example entry points: examples/README.md
User documentation: docs/get_started.md
Build launcher: python build/run.py (see build/README.md)
Manylinux / PyPI binary wheel: docs/publishing.md
Specialized utilities: tools/

Publishing (Linux manylinux)

To build PyPI-compliant CPython 3.10/3.11/3.12 Linux wheels from Windows Docker Desktop:

python build/run.py manylinux

Upload candidates land in dist/repaired/. Full TestPyPI → PyPI steps: docs/publishing.md.

Notes for Collaborators

Generated build outputs such as build/, dist/, and SDK/ are intentionally ignored.
Large or generated tooling outputs should stay under ignored output folders rather than be committed.
If you add new images or arrays that should be versioned, review .gitignore first.
Never commit PyPI / TestPyPI API tokens.