> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atomscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get RHEED Frame Masks

> Retrieve per-frame RLE-encoded masks for a processed RHEED video

Returns the binary segmentation mask for each featurized frame of a processed RHEED video, encoded using run-length encoding (RLE) in the same COCO format as the [single-image mask](/api-reference/rheed/mask).

`frame_number` is the absolute frame index, keyed identically to the processed video frames and to the `Frame Number` axis of the RHEED timeseries, so a decoded mask overlays the matching frame of the processed video.

<Note>
  Coverage is sparse. Masks exist only for featurized frames: every frame for stationary videos, but
  only the sampled subset for rotating and per-azimuth videos. Frames without a mask are absent from
  the response rather than returned as null.
</Note>

<ParamField path="data_id" type="string" required>
  The data entry UUID of the RHEED video, the same ID used for the video and timeseries
</ParamField>

<ParamField query="from" type="integer" default="0">
  First absolute frame number to return, inclusive
</ParamField>

<ParamField query="to" type="integer">
  Last absolute frame number to return, inclusive. Omit to return every featurized frame from
  `from` onward
</ParamField>

## Response

Returns an array of mask records.

<ResponseField name="data_id" type="string">
  Data entry UUID
</ResponseField>

<ResponseField name="processed_data_id" type="string">
  Processed data entry UUID
</ResponseField>

<ResponseField name="frame_number" type="integer">
  Absolute frame index within the video
</ResponseField>

<ResponseField name="mask_rle" type="string">
  Run-length encoded mask data, column-major (Fortran order)
</ResponseField>

<ResponseField name="mask_height" type="integer">
  Height of the mask in pixels
</ResponseField>

<ResponseField name="mask_width" type="integer">
  Width of the mask in pixels
</ResponseField>

A `404` means the video has no per-frame mask artifact, either because the item is not RHEED or because it was processed before per-frame masks were persisted.

<RequestExample>
  ```python SDK theme={null}
  from atomscale import Client

  client = Client(api_key="YOUR_API_KEY")

  # Decoded arrays keyed by absolute frame number
  masks = client.get_frame_masks(
      "d290f1ee-6c54-4b01-90e6-d701748f0851",
      from_frame=0,
      to_frame=200,
      decode=True,
  )
  print(masks[0].shape)  # (H, W) uint8, values 0/1
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.atomscale.ai/rheed/images/d290f1ee-6c54-4b01-90e6-d701748f0851/frame_masks",
      params={"from": 0, "to": 200},
      headers={"X-API-KEY": "YOUR_API_KEY"},
  )
  rows = response.json()
  ```

  ```bash cURL theme={null}
  curl "https://api.atomscale.ai/rheed/images/d290f1ee-6c54-4b01-90e6-d701748f0851/frame_masks?from=0&to=200" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "data_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "processed_data_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "frame_number": 0,
      "mask_rle": "PZ`0c0X<f0^C...",
      "mask_height": 512,
      "mask_width": 512
    },
    {
      "data_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "processed_data_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "frame_number": 1,
      "mask_rle": "Ub`0d0W<g0]C...",
      "mask_height": 512,
      "mask_width": 512
    }
  ]
  ```
</ResponseExample>