# Node manifest: the typed contract a consumer wires against.
#
# No source package is shared between node repositories, so this file and its
# type URNs are the only contract a consumer has. `dora validate` checks a
# dataflow against it without running the node, so CI needs neither a camera nor
# OpenCV.
apiVersion: 1
name: dora-webcam
namespace: liria
description: Captures frames from a webcam and publishes them as std/media/v1/Image
categories: [sensor]
keywords: [opencv, camera, webcam, video, capture, image, v4l2]

runtime: python
entrypoint: dora-webcam
# Run the dataflow with --uv, which gives the node its own managed venv under
# `.dora/python-envs/`, so what it imports at runtime is what was installed
# here. Without --uv this needs a virtualenv to install into.
build: uv pip install .
dora: ">=1.0"

inputs:
  tick:
    required: true
    description: >-
      Reads and publishes one frame. Wire to dora/timer/millis/N. The node stops
      when this input closes.

outputs:
  image:
    type: std/media/v1/Image
    description: >-
      Captured frame as an Arrow struct {width, height, encoding, data}. For a
      compressed encoding, width and height are the image's dimensions rather
      than the length of data, so a receiver can size a buffer without decoding
      first.

env:
  CAMERA_ID:
    description: >-
      Substring of an entry in /dev/v4l/by-id/. Stable across reboots and across
      which USB port the camera is in, unlike an index, so it takes precedence
      over CAPTURE_PATH. Linux only.
  CAPTURE_PATH:
    default: "0"
    description: Device path such as /dev/video1, or an index. A numeric string is read as an index.
  IMAGE_WIDTH:
    type: int
    description: Requested capture width; frames are also resized to it. Defaults to the camera's native width.
  IMAGE_HEIGHT:
    type: int
    description: Requested capture height; frames are also resized to it. Defaults to the camera's native height.
  ENCODING:
    default: bgr8
    description: One of bgr8, rgb8, yuv420, jpeg/jpg/jpe, png, bmp, webp.
  JPEG_QUALITY:
    type: int
    default: 95
    description: Quality 0-100, used only by the JPEG encodings.
  FLIP:
    description: Flip the frame. One of VERTICAL, HORIZONTAL or BOTH. Unset means no flip.
  PREVIEW:
    type: bool
    description: >-
      Open a local window showing the frames as they are published, so a camera
      can be checked without wiring a viewer. Press q to stop the node. Ignored
      under CI, where there is no display.
  CAPTURE_FRAMES:
    type: int
    default: 0
    description: >-
      Stop after this many frames. 0, the default, runs until the tick input
      closes. A positive count is what lets a test run the dataflow to
      completion rather than killing it on a timeout.
  CI:
    type: bool
    description: >-
      When true, a failed read publishes a labelled black frame instead of
      raising, which is what lets the dataflow run on a machine with no camera.

example: |
  - id: camera
    git: ssh://git@gitea.liria.cl:5001/liria/dora-webcam.git
    tag: v0.1.0
    build: uv pip install .
    path: dora-webcam
    inputs:
      tick: dora/timer/millis/33
    outputs:
      - image