# 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

```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/products/ory_box/basic_pipeline.py -v 0 -c ddjx01
```

ORY-MINI:

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

ORY-FINGER:

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

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