RHEED Features and Masks

client.get() returns the standard RHEED feature set. When you need the full per-region feature space, a filtered subset of properties, a time window, or the segmentation masks behind the features, use get_rheed_timeseries() and get_frame_masks().

Method	Use case
`get_rheed_timeseries()`	Feature timeseries with low-level features, masks, and windowing
`get_frame_masks()`	Per-frame segmentation masks on their own, optionally decoded
`get_frame()`	A single extracted frame as a `RHEEDImageResult`
`decode_mask_rle()`	Turn an RLE string into an `(H, W)` binary array

Fetch the feature timeseries

get_rheed_timeseries() returns a DataFrame indexed by ["Angle", "Frame Number"] when both axes are available. For stationary videos there is a single angle; rotating videos carry one block per sampled azimuth.

from atomscale import Client

client = Client()
data_id = "44fa63b0-74da-4d25-a362-2276c80a670a"

df = client.get_rheed_timeseries(data_id)
print(df.index.names)   # ['Angle', 'Frame Number']
print(df.columns)

Standard columns use display names such as Specular Intensity, Strain, Cumulative Strain, Oscillation Period, Diffraction Spot Count, and Lattice Spacing.

Include low-level features

Set include_low_level_features=True to add the full set of per-point, per-region features (spot areas, eccentricities, FWHM values, and similar) as extra columns.

df = client.get_rheed_timeseries(data_id, include_low_level_features=True)
print(df.filter(like="area").columns)

Low-level columns keep their raw backend names, so they are not renamed to display labels the way standard metrics are. Nested values are flattened into dotted column paths. Where a low-level feature shares a name with an existing standard column, the standard column wins and the low-level value is dropped, so known metrics are never overwritten.

Low-level features are per-point: a frame that was not featurized contributes NA to those columns.

Restrict to specific properties

Pass property_names to fetch only the features you need. These are the underlying property names, which differ from the display column names in the returned DataFrame.

df = client.get_rheed_timeseries(
    data_id,
    property_names=["specular_intensity", "referenced_strain"],
)

Property name	Display column
`specular_intensity`	Specular Intensity
`referenced_strain`	Strain
`nearest_neighbor_strain`	Cumulative Strain
`spot_count`	Diffraction Spot Count
`oscillation_period`	Oscillation Period
`lattice_spacing`	Lattice Spacing
`cluster_id`	Cluster ID
`first_order_intensity`	First Order Intensity
`half_order_intensity`	Half Order Intensity
`specular_fwhm_1`	Specular FWHM

Limit the time window

Two parameters narrow which points come back, which matters for long growths and for live streams where you only want the tail:

# Last 500 points
recent = client.get_rheed_timeseries(data_id, last_n=500)

# Last 60 seconds of the recording
tail = client.get_rheed_timeseries(data_id, elapsed_seconds=60.0)

Attach segmentation masks

Every featurized frame of a processed RHEED video carries a binary segmentation mask of the diffraction pattern. Pass include_masks=True to join those masks onto the timeseries on the Frame Number axis:

from atomscale.results import decode_mask_rle

df = client.get_rheed_timeseries(
    data_id,
    include_low_level_features=True,
    include_masks=True,
)

row = df.dropna(subset=["mask_rle"]).iloc[0]
mask = decode_mask_rle(row["mask_rle"], row["mask_height"], row["mask_width"])
print(mask.shape)   # (H, W), uint8 with values 0 or 1

Three columns are added:

Column	Description
`mask_rle`	COCO run-length-encoded mask string
`mask_height`	Mask height in pixels
`mask_width`	Mask width in pixels

Mask coverage is sparse. Masks exist only for featurized frames, so rows whose frame has no mask contain NA in these columns, as do all rows when the video has no mask artifact at all. Drop the NA rows before decoding. The mask fetch is scoped to the frame range the returned series actually spans, so combining include_masks=True with last_n or elapsed_seconds pulls only the masks for that window rather than the whole video.

Fetch masks on their own

When you want masks without the feature columns, call get_frame_masks() directly. Frame numbers are absolute and keyed identically to the processed video frames and to the Frame Number axis of the timeseries, so a decoded mask overlays the matching frame of the video you get from download().

# Raw rows with the RLE string intact
rows = client.get_frame_masks(data_id)
print(rows[0].keys())
# dict_keys(['data_id', 'processed_data_id', 'frame_number',
#            'mask_rle', 'mask_height', 'mask_width'])

# Decoded arrays keyed by absolute frame number
masks = client.get_frame_masks(data_id, decode=True)
print(masks[0].shape)   # (H, W) uint8

Bound the request with from_frame and to_frame, both inclusive:

masks = client.get_frame_masks(
    data_id,
    from_frame=1000,
    to_frame=1200,
    decode=True,
)

For stationary videos every frame is featurized, so frame numbers are contiguous. For rotating and per-azimuth videos only a sampled subset is featurized, and frames without a mask are simply absent from the result.

An empty list (or empty dict with decode=True) 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.

Overlay a mask on a frame

Combine get_frame() with a decoded mask to inspect a specific frame:

import numpy as np

frame = client.get_frame(data_id, frame_index=0)
masks = client.get_frame_masks(data_id, from_frame=0, to_frame=0, decode=True)

image = np.array(frame.processed_image)
mask = masks[0]
highlighted = np.where(mask[..., None] == 1, image, image // 3)

get_frame() accepts negative indices, so frame_index=-1 returns the last extracted frame. It returns None when the video has no extracted frames, the index is out of range, or the selected frame has no image. For a single RHEED image item (rather than a video), the mask is already on the result object as result.mask, and get_plot(show_mask=True) renders it as an overlay. See Inspect Results.

Decode masks yourself

decode_mask_rle() handles the COCO RLE format used by every Atomscale mask endpoint. Use it when working with raw rows or with API responses fetched outside the SDK:

from atomscale.results import decode_mask_rle

rows = client.get_frame_masks(data_id, from_frame=0, to_frame=99)
decoded = {
    row["frame_number"]: decode_mask_rle(
        row["mask_rle"], row["mask_height"], row["mask_width"]
    )
    for row in rows
}

The counts string is column-major (Fortran order), matching pycocotools.

Next steps

Similarity and Embeddings

Compare growths with embedding vectors.

Client Reference

Full parameter reference for every method.

Introduction

Guides

References

Fetch the feature timeseries

Include low-level features

Restrict to specific properties

Limit the time window

Attach segmentation masks

Fetch masks on their own

Overlay a mask on a frame

Decode masks yourself

Next steps

Similarity and Embeddings

Client Reference

​Fetch the feature timeseries

​Include low-level features

​Restrict to specific properties

​Limit the time window

​Attach segmentation masks

​Fetch masks on their own

​Overlay a mask on a frame

​Decode masks yourself

​Next steps

Similarity and Embeddings

Client Reference

Fetch the feature timeseries

Include low-level features

Restrict to specific properties

Limit the time window

Attach segmentation masks

Fetch masks on their own

Overlay a mask on a frame

Decode masks yourself

Next steps