# Atlas Viewer

The Atlas Viewer reconstructs a scan map from the dense stage trajectory and per-frame intensity summaries stored in the dataset HDF5 file. It can be useful for checking dataset coverage or navigating to specific diffraction frames.

Open the viewer from the **Atlas** panel in the main window. If all required data are present and no saved atlas exists yet, COSEDA reconstructs the default atlas automatically.

## Requirements

The dataset must contain:

- stage positions: `entry/data/stagepos_x_refined` or `entry/data/stagepos_x`, plus `entry/data/stagepos_y_refined` or `entry/data/stagepos_y`
- `entry/data/index`
- streak labels generated by COSEDA (`streak_id`; generated automatically when the atlas opens if possible)
- at least one supported intensity source

Supported contrast sources are:

| UI label | HDF5 dataset |
|---|---|
| **Mean intensity** | `entry/data/frame_mean_intensities` |
| **Total intensity** | `entry/data/frame_total_intensities` |
| **Virtual dark field** | derived from `entry/data/frame_radial_intensities` |

Mean intensity is the default contrast when available.

## Virtual dark field

When **Virtual dark field** is selected, the atlas intensity is derived from the radial intensity profile of each frame. The virtual detector is controlled by:

| Control | Description |
|---|---|
| **Center radius** | Radial position of the virtual annulus, in detector pixels. |
| **Annulus width** | Width of the virtual annulus, in detector pixels. |
| **Show detector overlay** | Draws the selected annulus on the main diffraction preview. |

Changing the sliders updates the atlas interactively. Virtual dark-field atlases are not saved as separate HDF5 atlas datasets for every slider position.

## Backlash correction

The **Backlash correction** control applies a horizontal offset to left-going scan streaks during atlas reconstruction. This is intended to correct small offsets between alternating scan directions caused by mechanical backlash of the specimen stage. This is only used for atlas reconstruction and does not modify the raw stage positions in the HDF5 file. Adjust the value to reduce visible interlacing of scan lines if necessary.

The value is saved in the dataset INI file:

```ini
[Parameters]
atlas_backlash_offset_um = 0.0
```

The value is in micrometres. `0.0` disables the correction. Positive values shift left-going streaks to higher stage-x positions; negative values shift them lower.

Saved atlases store the offset used as atlas metadata, but the stage-position datasets remain unchanged.

## Stripped files

The Atlas Viewer is designed to work after file stripping. COSEDA preserves the dense stage-position streams, frame intensity summaries, radial intensity profiles, streak labels, and detector mask during stripping. The full atlas can therefore be regenerated even when the image stack has been shortened.

While frame mean intensities are generated by default by the importers, radial intensity profiles must be triggered manually from the `Process` menu. If you want a full virtual dark-field atlas after stripping, calculate the radial profiles before stripping.

Clicking on the atlas still navigates to the nearest available frame. If the clicked position corresponds to a frame that was stripped, COSEDA jumps to the nearest retained frame.