# Measurement Triggers

> [!note] Ta strona nie została jeszcze przetłumaczona i jest wyświetlana w języku angielskim.


Measurement triggers are the primary way to obtain data from a connected instrument. A trigger executes a device-class–specific measurement procedure and returns a measurement container — by default a binary RAE file (see [RAE File Format](rhopoint-elements-hub-rae-file-format.md)) — containing all metric values, metadata and any attached device images.

### Endpoints Overview

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/v1/devices/{deviceId}/measurement-triggers` | List the measurement triggers available on the device |
| POST | `/v1/devices/{deviceId}/measurement-triggers` | Execute a measurement |

### Listing Available Triggers

```http
GET /v1/devices/{deviceId}/measurement-triggers
```

```bash
curl http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/measurement-triggers
```

The response describes which triggers the connected device supports and which parameters they accept. Example shape:

```json
[
  {
    "identifier": "measure",
    "title": "Measure",
    "category": "measure",
    "parameters": [
      {
        "key": "metricGroupKeys",
        "type": "EnumArray",
        "description": "Specify the metric group keys measured."
      },
      {
        "key": "imageFormat",
        "type": "String",
        "description": "Image encoding for images in the RAE container. Allowed values: 'image/png' (default), 'image/jpeg', 'image/x-raw'."
      }
    ]
  }
]
```

Use the listing endpoint to discover the parameter keys that are valid for the specific device class and firmware combination — they may evolve between releases.

### Executing a Measurement

```http
POST /v1/devices/{deviceId}/measurement-triggers
Content-Type: application/json

{
  "measurementKey": "measure",
  "containerFormat": "raeBinary",
  "parameters": [
    { "key": "metricGroupKeys", "value": ["sparkle", "scratchLinear"] },
    { "key": "imageFormat",     "value": "image/png" }
  ]
}
```

```bash
curl -X POST http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/measurement-triggers \
  -H "Content-Type: application/json" \
  -d '{
    "measurementKey": "measure",
    "containerFormat": "raeBinary",
    "parameters": [
      { "key": "metricGroupKeys", "value": ["sparkle", "scratchLinear"] }
    ]
  }' \
  --output measurement.rae
```

#### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `measurementKey` | string | Yes | Identifier of the trigger to execute, as returned by `GET /v1/devices/{deviceId}/measurement-triggers`. |
| `containerFormat` | string | Yes | Output container format. One of `raeBinary` or `raeJson`. |
| `parameters` | array | No | Operation parameters, as `{ "key": "...", "value": ... }` entries. Parameter keys and value types depend on the device. |

#### Container Formats

| `containerFormat` | Response `Content-Type` | When to use |
| --- | --- | --- |
| `raeBinary` | `application/vnd.rhopoint.rae+binary` | Default. Compact, CBOR-encoded, GZip-compressed binary file. Recommended for storage and transfer. See [RAE File Format](rhopoint-elements-hub-rae-file-format.md). |
| `raeJson` | `application/json` | Human-readable JSON representation of the same data. Easier to inspect from a browser or `curl`, but considerably larger. |

> [!note]
> The container always contains the full measurement tree: scalar metrics, hierarchical groups, attached images, and metadata. The choice between `raeBinary` and `raeJson` affects encoding only, not content.

### Image Encoding

Device images embedded in the container are PNG-encoded by default. The optional `imageFormat` operation parameter on Aesthetix devices selects an alternative encoding:

| `imageFormat` value | Encoding in the container | Container MIME type |
| --- | --- | --- |
| *(omitted)* or `image/png` | PNG | `image/png` |
| `image/jpeg` | JPEG, quality 90 | `image/jpeg` |
| `image/x-raw` | Original kernel bytes (16-byte header + pixel data) | `image/x-raw` |

See [Measurement Image Formats](rhopoint-elements-hub-measurement-image-formats.md) for the binary layout of `image/x-raw`, parsing examples, and per-image notes (some images are cropped server-side before PNG/JPEG encoding; the raw payload is uncropped).

### Aesthetix Metric Groups

For Aesthetix-family devices the `metricGroupKeys` parameter selects which metric groups participate in the measurement. Typical values include `sparkle`, `scratchLinear`, `scratchRadial`, `gloss`, `haze`, `cell`, `waviness`, `crossCut`, `shadeImages`. See [Aesthetix — Available Measurements](rhopoint-elements-hub-instruments-aesthetix.md#available-measurements) for the full list. Pass an empty array or omit the parameter to use the device's default selection.

### Decoding the Container Client-Side

If you receive a binary RAE container and want to decode it without parsing the format yourself, the hub also exposes:

```http
POST /v1/measurements/decode
Content-Type: multipart/form-data
```

Upload a `.rae` file as form data and receive the parsed measurement components as JSON. Useful for testing and one-off decoding from environments where embedding a RAE parser is impractical.

### Best Practices

- Call the `GET` endpoint once after connecting and cache the trigger metadata for the lifetime of the connection — the parameter list does not change while the device is connected.
- Validate `parameters` against the metadata returned by `GET` to avoid runtime parameter errors.
- For Aesthetix devices, restrict `metricGroupKeys` to the metrics you actually need. Each group adds processing time on the device side; an unrestricted measurement is several seconds slower than a single-group measurement.
- Prefer `raeBinary` for any data that is going to be stored — the size difference compared to `raeJson` is significant for measurements that contain images.

### Error Cases

| Condition | HTTP | Error Code |
| --- | --- | --- |
| Connected device not found | 404 | `E5` |
| Unknown `measurementKey` | 404 | `E15` |
| Unrecognised `containerFormat` | 400 | `E16` |
| Invalid `imageFormat` value (Aesthetix) | 400 | `E42` |
| Hardware error during measurement | 502 | device-class–specific (e.g. `E38`, `E39`, `E40`) |

See [Error Handling](rhopoint-elements-hub-error-handling.md) for the response format.