ykcheungab
b5d7533e24
The two canonical examples taught the advanced path: they sequenced get_img() -> compute_deformation() -> compute_contact() -> read_info() by hand and unpacked a 13-element tuple positionally, which is what led developers to reach for the compute backend, the capture queue and the stitch mode. The managed alternative already existed and was documented nowhere. Library (add-only, nothing removed): - FrameSnapshot.image_size_raw carries the capture resolution, so a caller can compare it with the processed frame instead of reaching into Sensor. - StreamPipeline.reset() resets the tracker and force filters *safely*. It is queued and applied by the flow stage before its next frame, never inline: Sensor.reset rebases initial_img on the current Sensor.img, which the flow stage is reading concurrently, so a caller-thread reset would capture a half-written reference frame. Idempotent. - TactileProcessor.pipeline(produce) and FingerRuntime.pipeline() build a pipeline without the caller naming a backend concept; the latter is `with runtime.pipeline(contact=True) as pipe`. Examples: - examples/basic_pipeline.py and examples/finger_pipeline.py rewritten onto StreamPipeline + FrameSnapshot: one object, one call per frame, no tuple, and no compute backend, queue or stitch setting in sight. - examples/archive/basic_pipeline_manual.py and _finger_pipeline_manual.py keep the previous versions byte-for-byte apart from a supersede header, so code copied from them keeps working. The finger header also records the archived --show defect (store_true with default=True, so it could never be disabled). - examples/_display.py holds the shared display helpers, so an example no longer hand-rolls depth normalisation and colormap application. - examples/README.md leads with the recommended pair and documents the manual form as still-supported, and states that examples/gui/ is moving to orisys-studio. Tests: three added to tests/test_pipeline.py, covering the reset queue (it must not run on the caller's thread and must land before the first compute_flow), image_size_raw, and the None case when a producer reports no size. Verified the reset test fails when reset() is made inline, so it discriminates. Verified end-to-end against real media: basic_pipeline on data/sample/s1_480p.mp4 (box) reaches ~113 FPS and exits 0; finger_pipeline on data/dd02-0703/1.mp4 (finger) reaches ~140 FPS with mask coverage 0.41 and exits 0. Both archived manual versions still run. tests/test_pipeline.py: 20 passed. Full suite: 342 passed, 3 failed - all three failures reproduce on the pristine tree (import precedence, longrun timing, and a stale ruff version literal in docs/code-review.md) and are unrelated to this change.
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 packageconfig/: default and lab/runtime JSON configurationsexamples/: runnable demos (basic_pipeline.py,mini_pipeline.py,finger_pipeline*.py) plus sharedgui/,pipeline/,viz/scripts/: maintenance, calibration, packaging, and demo scriptstools/: non-package tooling such as patch-generation utilitiestests/: automated pytest suitedocs/: 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 examplebox,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(seebuild/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/, andSDK/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
.gitignorefirst. - Never commit PyPI / TestPyPI API tokens.