> ## 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.

# Recording Sessions

> How RHEED frames are split into data items, including following kSA 400's acquisition state

The integration groups frames into **data items**, one per acquisition. The **Data Item Boundary Mode** setting, in the **Sessions & Image** section of the configuration, decides when a data item starts and ends.

| Mode | A data item opens and closes | Use it when |
| - | - | - |
| **Frame Activity** (default) | Opens when active frames start arriving. Closes after **Session Gap** (120 seconds) without an active frame. | Your RHEED software stops acquiring between growths. |
| **kSA Acquisition Status** | Opens when kSA 400 starts acquiring and closes when it stops. Pausing keeps the same item open. | You run kSA 400 and want one data item per kSA 400 acquisition. |

In either mode, a change in image size closes the current data item and opens a new one.

## Frame Activity

A frame counts as active when its average brightness is at least **Minimum Mean Intensity**. Dark frames neither open a data item nor keep it open, but dark frames inside an open data item are still kept. This keeps a camera that streams between growths, for example with the beam off, from recording empty data items.

Leave **Minimum Mean Intensity** blank and the integration learns it. Each time capture starts, the threshold begins at 0, so every frame counts. Once the last half hour has shown the beam both off and on, the integration sets the threshold just above the darkest frames. It lowers the threshold if darker frames arrive, but never raises it while capturing, so dim patterns are kept. It starts over after the camera sends nothing for half an hour.

To set it yourself, enter a value from 0 to 255; 0 counts every frame as active. Use Auto Manage to hand it back to the integration.

Set **Session Gap** longer than normal pauses within a run and shorter than the gap between runs.

## Following kSA 400

**1. Enable kSAComm in kSA 400**

In kSA 400, open **Options > General > Chamber Interface** and select **kSAComm** (default port
1800\). Make sure **Save settings at program exit** is enabled, then restart kSA 400. It accepts
connections only after the restart.

**2. Switch the boundary mode**

Stop the integration, open Configure, and set **Data Item Boundary Mode** to **kSA
Acquisition Status**. If kSA 400 runs on a different computer, set **kSA Communication Host** to
its address.

**3. Apply and start**

Apply the configuration and start the integration. A data item opens when kSA 400 starts
acquiring and closes when acquisition stops.

The integration only reads kSA 400's status; it never controls kSA 400. Until it gets its first status reply, it excludes frames and creates no data item. If kSA 400 stops answering, the activity log warns kSA status polling failed and the integration keeps the last status it confirmed, so a stop and restart while kSA 400 is unreachable can end up in one data item.

## What Gets Uploaded

* **8-bit grayscale.** Frames are converted before upload. Color (Bayer) frames are averaged to grayscale at half width and height. For high bit-depth cameras whose images look too dark, set **White Point** (advanced) to the pixel value that should map to white.
* **Frame rate.** Up to 120 frames per second. The rate is measured once at the start of each data item. **Upload Frame Rate Limit** caps how many frames per second upload; extra frames are skipped, and the camera's own rate doesn't change.
* **Spatial Downsampling.** Halves width and height before upload, either by dropping pixels or averaging each 2 × 2 block (**Downsampling Method**). Brightness checks still use the full image.
* **Stage rotation.** With **Stage Rotation** set, every data item is analyzed as rotating RHEED at that speed. Left blank, Atomscale detects whether the stage rotates.
* **Camera settings.** Each data item records the camera's exposure, gain, pixel format, image size, frame rate, model, and serial when it opens.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| The integration is Running but no data item appears | Confirm the RHEED software is acquiring, with live frames updating in its viewport. With Frame Activity, check that **Minimum Mean Intensity** isn't above the image brightness. With network capture, the health summary in **Health** then says Not recording because the camera image is too dark. With kSA Acquisition Status, check that the activity log shows no kSA status polling failed warning. |
| One growth is split into several data items | **Session Gap** is shorter than pauses in the run, or the image size changed. The activity log's Data item closed entry gives the reason. |
| Several growths end up in one data item | With Frame Activity, the camera keeps streaming bright frames between growths. Shorten **Session Gap**, set **Minimum Mean Intensity** above the between-growth brightness, or follow kSA 400. |
| Observed frame rate differs from the fixed item rate | The camera's rate changed by more than 10% after the data item opened. The data item keeps the rate measured when it opened; the next data item uses the new rate. Avoid changing the camera's frame rate during a growth. |
| Delivery overloaded | The computer can't keep up with the frame rate. Set **Upload Frame Rate Limit** or turn on Spatial Downsampling. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.