# 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/`: user-facing example scripts
- `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

```bash
python examples/basic_pipeline.py -v 0 -c ./config/ddjx01.json
```

## 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/`
3. 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: `scripts/build_nuitka.py`
- 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.