# 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/](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

```bash
conda create -n orisys python=3.10
conda activate orisys
```

### 2. Install the SDK in editable mode

```bash
pip install -e .
```

Optional GPU extras:

```bash
pip install -e .[cuda12]
```

or

```bash
pip install -e .[cuda13]
```

### 3. Run tests

```bash
pytest
```

### 4. Run an example

ORY-BOX:

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

ORY-MINI:

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

ORY-FINGER:

```bash
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:

1. an explicit JSON file path
2. `sensors/<name>/sensor.json` (for example `box`, `mini`, `finger`)
3. a file stem under the legacy `config/` folder, including aliases such as `dd02` -> `dd02-ov`
4. a backward-compatible JSON `"name"` match, such as `"prototype"`

Examples:

```python
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,
`./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:

```python
sensor = orisys.Sensor(0, config_name="box", calibration_dir="./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](docs/get_started.en.md)
- Chinese installation guide: [docs/get_started.md](docs/get_started.md)
- Build launcher: `python build/run.py` (see `build/README.md`)
- Build and publish guide: [docs/publishing.en.md](docs/publishing.en.md)
- Chinese release runbook: [docs/publishing.md](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:

```powershell
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.