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
sensors/: product bundles containing the current sensor.json configurations and assets
config/: legacy JSON configurations retained for compatibility
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]

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

Product configurations live in sensors/<name>/sensor.json. The repo-level config/ folder remains available for older configurations and aliases. The package loader orisys.configs resolves configs from:

an explicit JSON file path
sensors/<name>/sensor.json (for example box, mini, finger)
a file stem under the legacy config/ folder, including aliases 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")

For multiple physical sensors, keep calibration files in a user-selected directory: <calibration_dir>/<product>/<device_id>.json (for example, data/calibrations/box/BOX-001.json). Each file uses the existing calibration JSON format and must contain matching identity.sensor_type and identity.sn, Newton curves for FN/FX/FY, and a compatible measurement pipeline. Enter the device ID manually until hardware identification is available:

The source checkout provides data/calibrations/{box,mini,finger}/ folders; device files placed there are ignored by Git. This location is optional: pass --calibration-dir data/calibrations and --device-id BOX-001 to examples/basic_pipeline.py to select a file there. Installed wheels do not create or search this directory automatically.

sensor = orisys.Sensor(0, config_name="box", calibration_dir="data/calibrations", device_id="BOX-001")

If that ID has no file, the sensor reports raw force; it never falls back to the product's default. An invalid or mismatched file raises CalibrationError. FingerRuntime.open accepts the same calibration_dir and device_id arguments. Existing calls without a device ID still use the product bundle default, and explicit cal_path remains available for one-off use. cal_path and calibration_dir cannot be combined. Pass device_id with cal_path to validate that explicit file against the selected device.

Examples and Tools

Example entry points: examples/README.md
Contributor start: docs/get_started.en.md
Chinese installation guide: docs/get_started.md
Build launcher: python build/run.py (see build/README.md)
Build and publish guide: docs/publishing.en.md
Chinese release runbook: 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.