(usage)=
# Usage

## `nauscopia detect`
Run a video oder a sequence of bitmap images through object detection,
and produce an annotated output video or sequence.

Run object detection on video file.
```shell
nauscopia detect \
  --input="/path/to/sarcam_2024-03-02_12-35-50.mp4" \
  --output="/path/to/sarcam_2024-03-02_12-35-50_annotated.mp4" \
  --live
```
Run object detection on a single bitmap image frame.
```shell
nauscopia detect \
  --input="/path/to/image.png" \
  --output="/path/to/image_annotated_%03d.png" \
  --live
```
Run object detection on a sequence of bitmap image frames, using a sequence
pattern on the `--input` option.
```shell
nauscopia detect \
  --input="/path/to/image_%03d.png" \
  --output="/path/to/images_annotated.mp4" \
  --live
```

:::{rubric} Options
:::
- The `--live` option displays the recording on a UI window while the pipeline
  is processing.
- Please note on the `--output` option, you always must use either a video format,
  or, for single images, the sequence pattern.
- Using the `--debug` option like `nauscopia --debug detect ...` will display
  additional information like `Inference time: 255.51 ms`.
- Based on OpenCV, the program understands a number of media file formats.
  Just address resources by using corresponding file name extensions like
  `.avi`, `.mkv`, `.mp4`, or any others supported by OpenCV.

:::{note}
Currently, the software uses YOLOv10 for object detection.
:::