ykcheungab
147 lines
4.6 KiB
Markdown
147 lines
4.6 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
|
|
- `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,
|
|
`data/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:
|
|
|
|
The source checkout provides `data/calibrations/{box,mini,finger}/` folders; device
|
|
files placed there are ignored by Git. This location is optional: pass
|
|
`--calibration-dir data/calibrations`
|
|
and `--device-id BOX-001` to `examples/basic_pipeline.py` to select a file there.
|
|
Installed wheels do not create or search this directory automatically.
|
|
|
|
```python
|
|
sensor = orisys.Sensor(0, config_name="box", calibration_dir="data/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.
|