ykcheungab
4c1ab5c27e
Adds tools/api_audit.py, a read-only static audit of the public API surface, and docs/api-audit.md, its first run against this revision. The audit answers three questions the reference cannot answer about itself: 1. Does every declared export exist, have a docstring, and appear in docs/api.md? It reads the root __all__ plus each submodule's __all__. 2. How complete is each public definition? Docstring presence, detected docstring convention, parameter and return annotations. 3. Which public names do examples and tests actually use but the reference never explains? That set is the real documentation gap. It parses with ast and never imports the package, so it costs no numpy/cv2 import and cannot be affected by the environment. Findings on this revision (full detail in docs/api-audit.md): - 393 public classes/methods/functions; 65% have a docstring, 32% have a fully annotated signature, 38 document their return value. - 243 docstrings are unstructured prose, 137 are absent, 13 use Google or NumPy sections. There is effectively one convention: none. - 9 of the 18 root exports are absent from docs/api.md, including StreamPipeline, StreamRecorder, mosaic_videos and FFCFrameProcessor - the pipelined multi-stream and offline-recording paths. - Six sub-surfaces have zero coverage in the reference: unroll (18 exports), capture (17), hhd + solvers (7), pipeline (3), export (2). - 74 names are used by examples or tests but absent from the reference. - 21 public classes are exported nowhere; LowpassFilter is documented in docs/api.md and importable, but declared in no __all__. No behaviour change: a new tool and a new document, no source file touched.
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.