ykcheungab
f700102067
examples/gui/ is a full Qt + open3d application (30 modules, 4,815 lines) rather than an example, and its proper home is the orisys-studio application. The move is planned but not started, so this records the plan rather than performing any of it. What the plan establishes, so the work does not have to be re-derived: - src/orisys/ imports no gui/viz/examples module, verified by AST rather than grep. The dependency is one-way, so the GUI can leave without a library change. The single apparent hit is `from .pipeline import ...` in src/orisys/__init__.py, which is the SDK's own module. - examples/viz/ is shared and cannot follow the GUI wholesale: it mixes open3d renderers with toolkit-independent helpers that examples/pipeline/service.py and tests/test_contact_arrow_scale.py depend on. It has to be split. - The real coupling is inverted and lives in the tests: tests/test_qt_viewer_backend.py imports examples/gui, and tests/conftest.py deliberately puts examples/ ahead of build/ because both define a package named `gui`. Removing the GUI means re-deriving that guard, not deleting it blindly. - UVMeshViewer and friends are in src/orisys/finger/__init__.__all__, so removing them is a breaking change to a released API and needs a deprecation release first. It must not be folded into a code move. - The `examples/` directory must keep existing in the packaged layout even after gui/ leaves it: src/orisys/configs.py anchors its run-root detection on a sibling examples/ folder. Also updates examples/README.md to say "lives here for now" instead of "is moving out", so nothing reads as work in progress. The GUI itself is untouched, and the only guidance offered is that new SDK work should not build on it.
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/
Repository Layout
src/orisys/: installable SDK packageconfig/: default and lab/runtime JSON configurationsexamples/: runnable demos (basic_pipeline.py,mini_pipeline.py,finger_pipeline*.py) plus sharedgui/,pipeline/,viz/scripts/: maintenance, calibration, packaging, and demo scriptstools/: non-package tooling such as patch-generation utilitiestests/: automated pytest suitedocs/: usage and API documentation
Quick Start
1. Create an environment
conda create -n orisys python=3.10
conda activate orisys
2. Install the SDK in editable mode
pip install -e .
Optional GPU extras:
pip install -e .[cuda12]
or
pip install -e .[cuda13]
3. Run tests
pytest
4. Run an example
ORY-BOX:
python examples/basic_pipeline.py -v 0 -c box
ORY-MINI:
python examples/mini_pipeline.py -v 0 -c mini
ORY-FINGER:
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:
- an explicit JSON file path
- a config file stem under
config/(for examplebox,mini,finger) - a product alias such as
dd02->dd02-ov - a backward-compatible JSON
"name"match, such as"prototype"
Examples:
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(seebuild/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:
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/, andSDK/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
.gitignorefirst. - Never commit PyPI / TestPyPI API tokens.