orisys-sdk/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.

Repository Layout

• src/orisys/: installable SDK package
• config/: default and lab/runtime JSON configurations
• examples/: product demos (products/ory_box, ory_mini, ory_finger) 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/products/ory_box/basic_pipeline.py -v 0 -c ddjx01

ORY-MINI:

python examples/products/ory_mini/basic_pipeline.py -v 0 -c mini

ORY-FINGER:

python examples/products/ory_finger/finger_pipeline.py --camera_id 0 --config dd02

Compatibility wrappers remain at examples/basic_pipeline.py and examples/finger_pipeline*.py.

Configuration

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

1. an explicit JSON file path
2. a config file stem under config/ (for example ddjx01, mini, dd02)
3. a product alias such as dd02 -> dd02-ov
4. a backward-compatible JSON "name" match, such as "prototype"

Examples:

import orisys

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

Examples and Tools

• Example entry points: examples/README.md
• User documentation: docs/get_started.md
• Packaging helper: build/build_nuitka.py (compiled SDK wheel)
• GUI standalone folder: build/build_gui_win.bat → dist/OrisysDashboard/
• Specialized utilities: tools/

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.