# 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` |

```python
# 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

```bash
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:

```python
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, using `StreamPipeline` with `StreamRecorder`
- `two_sensor_pipeline.py` - two-sensor multiprocessing demo, manual staging
- `plot_data.py` - single-sensor OpenCV views plus PyQtGraph force charts
- `finger_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 packaged `orisys/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.