ykcheungab
b5d7533e24
The two canonical examples taught the advanced path: they sequenced get_img() -> compute_deformation() -> compute_contact() -> read_info() by hand and unpacked a 13-element tuple positionally, which is what led developers to reach for the compute backend, the capture queue and the stitch mode. The managed alternative already existed and was documented nowhere. Library (add-only, nothing removed): - FrameSnapshot.image_size_raw carries the capture resolution, so a caller can compare it with the processed frame instead of reaching into Sensor. - StreamPipeline.reset() resets the tracker and force filters *safely*. It is queued and applied by the flow stage before its next frame, never inline: Sensor.reset rebases initial_img on the current Sensor.img, which the flow stage is reading concurrently, so a caller-thread reset would capture a half-written reference frame. Idempotent. - TactileProcessor.pipeline(produce) and FingerRuntime.pipeline() build a pipeline without the caller naming a backend concept; the latter is `with runtime.pipeline(contact=True) as pipe`. Examples: - examples/basic_pipeline.py and examples/finger_pipeline.py rewritten onto StreamPipeline + FrameSnapshot: one object, one call per frame, no tuple, and no compute backend, queue or stitch setting in sight. - examples/archive/basic_pipeline_manual.py and _finger_pipeline_manual.py keep the previous versions byte-for-byte apart from a supersede header, so code copied from them keeps working. The finger header also records the archived --show defect (store_true with default=True, so it could never be disabled). - examples/_display.py holds the shared display helpers, so an example no longer hand-rolls depth normalisation and colormap application. - examples/README.md leads with the recommended pair and documents the manual form as still-supported, and states that examples/gui/ is moving to orisys-studio. Tests: three added to tests/test_pipeline.py, covering the reset queue (it must not run on the caller's thread and must land before the first compute_flow), image_size_raw, and the None case when a producer reports no size. Verified the reset test fails when reset() is made inline, so it discriminates. Verified end-to-end against real media: basic_pipeline on data/sample/s1_480p.mp4 (box) reaches ~113 FPS and exits 0; finger_pipeline on data/dd02-0703/1.mp4 (finger) reaches ~140 FPS with mask coverage 0.41 and exits 0. Both archived manual versions still run. tests/test_pipeline.py: 20 passed. Full suite: 342 passed, 3 failed - all three failures reproduce on the pristine tree (import precedence, longrun timing, and a stale ruff version literal in docs/code-review.md) and are unrelated to this change.
3.6 KiB
Examples
Runnable demos live at the examples/ root. Shared helpers stay in pipeline/, viz/, and
gui/. Run commands from the repository root.
Start here
Both recommended examples create one object, then read a frame at a time. Everything else -
camera reading, stitching, preprocessing, the optical-flow and force stages - happens inside
StreamPipeline, and each frame arrives as one FrameSnapshot. There is no stage sequence to
remember and no tuple to unpack, and no backend setting to tune.
| Product | Entry | Default config |
|---|---|---|
| ORY-BOX | basic_pipeline.py |
box |
| ORY-MINI | basic_pipeline.py -c mini |
mini |
| ORY-FINGER | finger_pipeline.py |
finger |
# ORY-BOX / ORY-MINI
sensor = orisys.Sensor(0, config_name="box")
with orisys.StreamPipeline(sensor, sensor.get_img, contact=True) as pipe:
while (snap := pipe.wait()) is not None:
print(snap.normal_force, snap.shear_x, snap.shear_y)
# ORY-FINGER - the runtime owns camera, Blender export, unroll map and valid mask
runtime = FingerRuntime.open(config="finger", video=0)
with runtime.pipeline(contact=True) as pipe:
while (snap := pipe.wait()) is not None:
print(snap.normal_force, snap.shear_x, snap.shear_y)
contact=True runs contact analysis; include=(...) chooses which arrays each snapshot carries
(image, flow, vnormal, vshear, depth, centroid, contour). Arrays you do not include
are None, so you pay only for what you use. pipe.reset() resets the tracker safely from your
loop; snap.image_size_raw reports the capture resolution before UV unroll or resize.
Typical usage
python examples/basic_pipeline.py -v 0 -c box # first camera, ORY-BOX
python examples/basic_pipeline.py -v 0 -c mini # ORY-MINI
python examples/basic_pipeline.py -v recording.mp4 -c box
python examples/basic_pipeline.py --no-show # headless: print only
python examples/finger_pipeline.py --camera_id 0 --config finger
python examples/finger_pipeline.py --video data/dd02-0703/1.mp4
Keys in both: q quits, r resets the tracker.
The manual form, for when you need the stages
examples/archive/ holds the previous versions of these two examples. They call the stages by
hand:
sensor.get_img()
sensor.compute_deformation()
sensor.compute_contact()
fps, flow, vnormal, img, ... = sensor.read_info( ... ) # positional, 13 elements
That path is still supported and still correct - it is the right choice if you are implementing your own scheduling. It is no longer the recommended starting point, and the archived files carry a header explaining the difference. They are kept so that code copied from them keeps working.
Other root examples
multi_stream.py- several sensors at once, usingStreamPipelinewithStreamRecordertwo_sensor_pipeline.py- two-sensor multiprocessing demo, manual stagingplot_data.py- single-sensor OpenCV views plus PyQtGraph force chartsfinger_pipeline_3dview.py- the Qt/open3d dashboard; see the note below
Requirements
- SDK installed from the repository root:
pip install -e . - a camera index or a test video path
- matching config names under
./config/or the packagedorisys/configs/
Qt / PyQtGraph examples additionally need pip install -e ".[gui]".
The GUI is moving out
examples/gui/ - the 2D viewer, the 3D dashboard and their widgets - is a full Qt + open3d
application, not an example. It is being moved to the orisys-studio application, which is
where the GUI belongs. Until that lands, finger_pipeline_3dview.py and examples/gui/ still
work as before; new work should not build on them.