Interfaces

Interfaces refers to generalized specifications for how a profile can implement a certain feature. This allows for all profiles to share a consistent way to communicate, and allow generalizable frontend component to be built to interact with any profile.

Snapshots

Snapshots interface allows a profile to take a snapshot, on interval, or triggered by the user. If a profile implements this interface, the frontend will display a Take Snapshot button while managing a pipeline.

To manually take a snapshot, a cloud event is sent to the API /api/pipeline/<mx_id>/input with a cloudevent of type madrona.snapshot.trigger. An example is seen below:

{
  "specversion": "1.0",
  "id": "9c4ee2d7-0650-40fd-84f5-ebaeb5ede23b",
  "source": "/madrona/application",
  "type": "madrona.snapshot.trigger",
  "time": "2025-01-02T23:39:48.615Z"
}

The pipeline should respond with a cloudevent of type madrona.snapshot.taken with the data payload being the path to the saved image. An example is seen below:

{
    "specversion": "1.0",
    "id": "e1276c24-a31d-45b6-98dd-cb52f580b369",
    "source": "/madrona/profile/RGBCenterBasic",
    "type": "madrona.snapshot.taken",
    "time": "2025-01-02T23:39:53.526417+00:00",
    "data": "/tmp/madrona/snapshot-2025-01_02-15-39-53.484580.jpg"
}

Through the Snapshot interface, the user can also control whether or not to save additional EXIF data to the image files such as time and date, camera model, software version, and more in the future. Note that only JPEG snapshots are supported at this time.

Snapshots that are taken on an interval first need to be enabled after the pipeline is running. This is used to prevent collecting data unnecessarily. A cloudevent of type madrona.snapshot.start or madrona.snapshot.stop, respectively, should be sent to start and stop interval capture. The pipeline should respond with cloudevents of madrona.snapshot.started and madrona.snapshot.stopped, respectively, if acknowledged.

Camera Controls

Camera Controls interface allows a profile to manually control settings on each indiviudal camera on a stereographic camera, like exposure, white balance, and focus. If a profile implements this interface, the frontend will display a Camera Controls form while managing a pipeline.

To manually control anyone of the cameras (left, right, or center), a cloud event is sent to the API /api/pipeline/<mx_id>/input with a cloudevent of type madrona.camera.control. An example is seen below:

{
  "specversion": "1.0",
  "id": "407d765c-3c31-434f-9340-daf8c441fa4e",
  "source": "/madrona/application",
  "type": "madrona.camera.control",
  "time": "2025-01-03T00:07:02.064Z",
  "data": {
    "left": {
      "focus_manual": 30,
      "exposure": 100,
      "sensitivity": 1600,
    },
    "center": {
      "exposure_auto": true,
      "exposure_auto_limit": 130,
      "exposure": 100,
      "sensitivity": 1600,
      "saturation": 50,
      "focus_auto": false,
      "focus_manual": 30,
      "white_balance_auto": true,
      "white_balance": 4600,
      "white_balance_lock": false
    },
    "right": {
      "focus_manual": 30,
      "exposure": 100,
      "sensitivity": 1600,
    }
  }
}

The pipeline will respond with a cloudevent for each camera of type madrona.camera.controlled with the data payload being the camera settings that were applied. The subject indicates what camera was controlled. An example is seen below:

{
    "specversion": "1.0",
    "id": "e1276c24-a31d-45b6-98dd-cb52f580b369",
    "source": "/madrona/profile/RGBCenterBasic",
    "subject": "center",
    "type": "madrona.camera.controlled",
    "time": "2025-01-03T00:07:02.064Z",
    "data": {
        "exposure_auto": true,
        "exposure_auto_limit": 130,
        "exposure": 100,
        "sensitivity": 1600,
        "saturation": 50,
        "focus_auto": false,
        "focus_manual": 30,
        "white_balance_auto": true,
        "white_balance": 4600,
        "white_balance_lock": false
    }
}