ykcheungab
118 lines
2.8 KiB
Markdown
118 lines
2.8 KiB
Markdown
# 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
|
|
- `config/`: default and lab/runtime JSON configurations
|
|
- `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
|
|
|
|
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 `box`, `mini`, `finger`)
|
|
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="box")
|
|
cfg = orisys.export_config("box", "./config/exported_config.json")
|
|
```
|
|
|
|
## Examples and Tools
|
|
|
|
- Example entry points: `examples/README.md`
|
|
- User documentation: `docs/get_started.md`
|
|
- Build launcher: `python build/run.py` (see `build/README.md`)
|
|
- Manylinux / PyPI binary wheel: `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.
|