Scan region, axes and scan direction¶

Every SPM vendor writes the geometry of a scan differently: some store a centre, some a corner, some no range at all and some no scan direction. This section states the single convention pynxtools-spm writes into NeXus, which raw element of each format it comes from, and how strong the evidence for each reading is.

Where a vendor documents the meaning, the vendor is cited. Where no document was found, the meaning was measured on published data and the measurement is shown, so that anyone can repeat it or overturn it — see Challenge these findings.

What you will find here¶

Fields the reader writes¶

The convention¶

Offset is the centre of the scan area¶

scan_start_n = offset_n - range_n / 2
scan_end_n   = offset_n + range_n / 2

scan_start = offset with scan_end = offset + range is never used. When a format stores a corner instead of a centre, the corner is shifted first, offset = corner + range/2, and the relations above are applied to it. Start and end are always derived, even where a format has a start-like key of its own.

flowchart LR
    A["offset
(centre)"] --- B["range"]
    B --> C["scan_start = offset - range/2"]
    B --> D["scan_end = offset + range/2"]
    C --> E["axis[0] = scan_start + step/2"]
    D --> F["axis[-1] = scan_end - step/2"]

Axis values are pixel centres¶

An axis value is the centre of its pixel, not its edge, so pixel i of N sits at offset - range/2 + (i + 0.5) × step with step = range / N. The first and last axis values are therefore half a pixel inside the scan region, and the midpoint of any axis is exactly the scan offset. Placing the coordinate at the pixel centre is this reader's choice; no vendor prescribes it.

Frames of reference¶

A non-zero scan_angle_* rotates the scan frame against the sample, so X and Y are the fast and the slow axis of the scan frame, not the x and y of the sample. The angle is recorded but never applied to the data.

Image orientation¶

Images follow the bottom-left convention: row 0 is the bottom row, column 0 the left column, and both axes ascend. An up scan and a down scan of the same area give the same image; only the order in which the lines were recorded differs.

Two kinds of axes¶

@axes and independent_scan_axes answer different questions and are written independently of each other.

Scan direction as a sign¶

An axis is signed when the entry holds exactly one pass along it and the format records which way that pass ran.

A bare axis covers two different situations, which the file itself tells apart:

• Both passes are stored. The entry has a forward and a backward NXdata group, so no single direction applies to the fast axis.
• The format never records it. Bruker .FLT stores one channel and no slow scan direction, so its Y means unknown, not upward.

Raw-file elements per flavour¶

Each flavour has its own section with the full key table, how its scan direction is decided and what it leaves unrecorded. Click a flavour to open it.

No raster: Nanonis .dat STS and Bruker .spm.txt¶

Neither flavour rasters an area, so neither writes a 2D scan region or independent_scan_axes.

Evidence and confidence¶

Grades¶

What each claim rests on¶

How the empirical test works¶

A small scan taken inside a larger scan of the same area shows up as a patch of the large image. Where the patch is found is a measurement; where each reading of the offset predicts it differs by (range_big - range_small) / 2 per axis. The small image is resampled to the pixel size of the large one, both are line- and plane-levelled, and the patch is located by normalized cross-correlation.

Pairs whose two scans share the same offset are the clearest: a centre reading puts the small scan in the middle of the large one, a corner reading in a corner, and that holds whatever the axis directions are.

In the results below, Measured is where the small scan was found, while Centre predicts and Corner predicts are the positions computed from the raw offsets under each reading. Whichever prediction the measurement matches is the reading the file follows.

The measured results are shown with the flavour they concern: Bruker SPMLab .FLT and Omicron / RHK .sm4.

Data used¶

Challenge these findings¶

Four of the claims above rest on measurement or on third-party readers rather than on a vendor document. If you can show one of them is wrong, the reader should change.

Please open an issue with the Challenge a scan-region convention template. A vendor document is the strongest evidence; an openly licensed raw file that the current reading gets wrong is just as welcome, because it can be added to the test set.

References¶