# Examples

This folder contains user-facing example scripts for the Orisys SDK.

## Files

- `basic_pipeline.py`: single-sensor basic processing and visualization flow
- `two_sensor_pipeline.py`: dual-sensor multiprocessing example
- `two_sensor_force_reader.py`: dual-sensor force-only reader for gripper control
- `gripper_force_control.py`: closed-loop gripper force control from left/right tactile feedback
- `gripper_timed_cycle_control.py`: timed open/close gripper loop with two-sided tactile force adjustment
- `plot_data.py`: real-time plotting example with PyQtGraph
- `manual_annotator.py`: manual Qt annotation tool for corners, lines, rectangles, and ROI boxes

## Typical usage

Run examples from the repository root so relative paths such as `./config/ddjx01.json`
resolve correctly.

### Basic pipeline

```bash
python examples/basic_pipeline.py -v 0 -c ./config/ddjx01.json
```

### Two-sensor pipeline

```bash
python examples/two_sensor_pipeline.py
```

### Two-sensor force reader

```bash
python examples/two_sensor_force_reader.py -v1 0 -v2 1
```

### Gripper force control

```bash
python examples/gripper_force_control.py --port COM3 -v1 0 -v2 1
```

Use `--dry-run` to verify tactile feedback and control decisions without
opening the gripper serial port.

### Timed gripper open/close control

```bash
python examples/gripper_timed_cycle_control.py --port COM3 -v1 0 -v2 1 --open-seconds 3 --close-seconds 5
```

By default, control parameters are loaded from
`./gripper_control/config/gripper_timed_cycle_control.py`; CLI options override config values.

The open/close cycle is time-driven. During the close phase, object detection
uses calibrated N thresholds. After detection, the timed open/close loop stops.
The gripper holds its current position, resets to a low force, and slowly ramps
force. When tangential force is high enough and stable, it enters hold-check.
Human handoff release is enabled by default; pass `--disable-human-release` to
keep holding even after later tangential-force changes.

### Real-time plotting

```bash
python examples/plot_data.py -v 0 -c ./config/ddjx01.json
```

### Manual annotation

```bash
python examples/manual_annotator.py -s 0
```

Use `-s` with a camera index, video path, or image path. Coordinates saved in the
JSON file are original image pixel coordinates.

## Requirements

- Python environment with the SDK dependencies installed
- a supported camera or test video
- valid JSON config in `./config/`

Some examples also require:

- `pyqtgraph`
- `PyQt5`
- multiple cameras for multi-sensor demos

## Notes

- Most examples assume a tactile sensor camera is connected.
- Press `q` in the display window to quit where applicable.
- If your camera index is not `0`, change `-v` accordingly.