4d — Preparation

Processing scripts · 4d User Manual

← Back to “Processing sections & scripts”

Preparation — scan-pattern design

Plan the acquisition by defining and managing the probe coordinate grids (scan patterns) used by 4D-STEM. These write project-wide STAR files that the import step later reads.

#TitleWhat it does
40Scan Pattern GeneratorCreates a scan pattern defining the probe coordinates for an acquisition and writes it to a STAR file.
42Scan Pattern InventoryLists the scan patterns already available in the project's STAR files.
45Scan Pattern TranslatorConverts between the TVIPS three-file scan-generator format and a STAR file, in either direction.
60Grab central positionsExtracts the 30 most central probe positions from a pattern for quick centered tests.
Scan patterns are stored as .star files in the project's STARFILES/ directory. Each script's ? help button opens its entry below. (These scripts show an interactive plot only when Show plot of scan positions is on — no plot image is saved to disk.)
40 — Scan Pattern Generator

Purpose

Generates a fresh probe scan pattern — the ordered list of X/Y probe coordinates a 4D-STEM acquisition will visit — purely computationally from a chosen geometry, and writes it to a STAR file in the system-wide star file directory (resources/starfiles of the 4d installation, the System-wide choice of Scan Pattern into HDF5 file, which is pointed at the new file), with a copy in the project's STARFILES/ for the inventory and centre-position steps. This is the primary "design a scan" tool: pick a pattern type and a number of positions, and it produces the coordinate list that later drives the scan generator and indexes the recorded diffraction stack.

Parameters

ParameterRole
ScanModeThe pattern geometry (drop-down) — see the algorithm for the full list.
ProbePositionsTotal number of probe positions to generate.
ProbePositionsPlotHow many positions to draw in the plot (0 = all).
ProbePositionsHorizontal, ProbePositionsDosefracHorizontal count and repetitions, used only by the hexagonal dose-fractionation modes.
snakeoffsetRow offset for the Snake-Offset pattern.
sfr_field_radius, sfr_pitch, sfr_offset, sfr_origin_angle, sfr_along, sfr_lanes, sfr_shear, sfr_ice_radius, sfr_rim_returns, sfr_rim_margin, sfr_alternateThe "Sunflower Rim scan" parameter family, used only by SunflowerRim12: field radius and position pitch in nm (these set the number of positions, not ProbePositions), where the spiral origin sits, the pass split (along × lanes = passes), and the return around the carbon rim between passes.
ht9_field_radius, ht9_pitch, ht9_twist_amp, ht9_twist_xi, ht9_seed, ht9_scramble, ht9_honeycomb, ht9_probe_d, ht9_ice_radius, ht9_rim_returns, ht9_rim_marginThe "Honeytomb9 scan" parameter family, used only by Honeytomb9: field radius and position pitch in nm (these set the number of positions, not ProbePositions), the amplitude, correlation length and seed of the twist, the pass scrambling and the honeycomb block order, the probe diameter for the coverage report, and the return around the carbon rim between passes.
lr_corner_dwell, lr_letter_dwell, lr_letter_heightThe "Letter R scan" parameter family, used only by Letter-R-Generator: the exposure of the four frame corners and of every position of the R, in multiples of the exposure of a position on the edges of the frame (5 and 3 by default), and the height of the R as a fraction of the frame side.
makeMultipleScanPositionsWrite the whole pattern this many times (dose-fractionated), each repeat given a tiny jitter.
scan_showplot, scan_y_downShow the interactive scatter plot; invert its Y axis.
ScanPatternSTARThe output STAR filename (written into STARFILES/).

Algorithm

  1. Writes the STAR header (_scan_mode, _probe_positions, the loop_ columns).
  2. Dispatches on ScanMode to a dedicated generator: Square, SquarePattern-DoseFrac, Snake, Snake-Offset, Spiral, HexPattern, HexDoseFracRound / HexDoseFracSquare, SunflowerDoseFrac, SunflowerRim12, Honeytomb9, Letter-R-Generator, Fermat, Fermat-Ysort, Random, and Develop_1…5.
  3. Rescales X and Y independently to the scan-generator integer range (roughly −6500…6500) as int16 — the STAR file stores hardware deflection coordinates, not Ångström distances.
  4. Repeats the pattern makeMultipleScanPositions times with a running position offset (and a tiny jitter on repeats), then optionally shows the scatter plot.

SunflowerRim12

The dose-fractionated aperiodic pattern for the WASP acquisitions. Positions lie on a Vogel (golden-angle) spiral whose origin sits outside the scanned field, far enough that the field falls inside a single Fibonacci band: the pattern is then locally lattice-like with a slowly rotating orientation, its parastichy arms cross the field without branching, and its residual spectral structure lies at the scan pitch itself, finer than the probe can transfer. Each position has two natural indices, its arm and its place along the arm, and a pass takes every sfr_along-th position along every sfr_lanes-th arm (3 × 4 = 12 passes by default), so a single pass has low internal overlap while still covering the field; the passes are ordered so that every cumulative subset covers the field as evenly as possible. Within a pass the arms are traversed end to end, the beam stepping onto the neighbouring arm at each turn, like a bent clock hand sweeping across the field. Between passes the beam returns around the carbon rim, on an arc sfr_rim_margin outside the field, so the transit dose lands outside the reconstructed area; those waypoints are real positions in the STAR file and are listed with pass 0 in the sidecar <ScanPatternSTAR>_passes.txt (index, pass) so the frames taken on the rim can be discarded. The log states whether the chosen origin offset keeps the field in one Fibonacci band and lists the offsets that do, the pass order, the traversal length and step statistics, and the covering radius and dose uniformity after 1, 3, 6 and 12 passes. The size of the pattern follows from the field radius and the pitch (about 245 000 positions for 750 nm at 2.8868 nm), not from ProbePositions.

Honeytomb9

The nine-pass twisted hexagonal pattern. Positions form a hexagonal lattice of pitch ht9_pitch, displaced by a divergence-free (area preserving) random twist of amplitude ht9_twist_amp and correlation length ht9_twist_xi: the local density and overlap are preserved exactly, while the long-range order that puts Bragg peaks of a perfect lattice into a reconstruction is broken. The lattice is identified with the Eisenstein integers and split into nine passes by the ideal (3 ζ6) of norm 9, whose divisor chain 1 | 3 | 9 makes the cumulative sets of 1, 3 and 9 passes each an exact hexagonal sublattice (pitch 3p, √3p and p): a uniform factor-of-three dose ladder, 1/9, 1/3 and the full dose. A hexagonal scan cannot step that ladder by two, since a sublattice of index 2 does not exist (2 is not a Loeschian number). With ht9_honeycomb on, passes 4–6 are one whole coset of the index-3 sublattice, so six passes form a honeycomb of hexagonal rings around holes that passes 7–9 then fill. Within these blocks the passes are ordered greedily for the widest nearest-neighbour spacing of the cumulative union, pass 1 being the coset with the smallest covering radius. ht9_scramble permutes the three passes of a block in a random fraction of cells, which leaves every level unchanged but removes the periodicity of the single passes. Each pass is swept along the rows of its own index-9 sublattice, alternately reversed, so every coil step stays near 3p; between passes the beam returns around the carbon rim exactly as for SunflowerRim12, on an arc ht9_rim_margin outside the field, with the waypoints listed as pass 0 in the same sidecar <ScanPatternSTAR>_passes.txt. The log reports the pass order, the traversal length and step statistics, and for every cumulative pass count the mean spacing, its ratio to the ideal hexagonal spacing at that density, the covering radius, the fraction of the field untouched by a probe of ht9_probe_d, and the dose uniformity. The size of the pattern follows from the field radius and the pitch (about 245 000 positions for 750 nm at 2.8868 nm), not from ProbePositions.

Letter-R-Generator

A test mark rather than a scan: a square frame with a long dwell in its four corners, and the letter R in its centre with a dwell of its own, to be written into the sample so that an image of the mark shows how the scan generator maps onto the specimen. The frame is the outline of the Square raster of ProbePositions positions (√ProbePositions per side) and is the bounding box of the pattern, so it is scaled onto the same range in X and Y and stays exactly square in scan-generator units: a rectangle or a parallelogram in the image is the aspect ratio or the shear of the scan, read off most precisely at the corner marks. The R is not mirror symmetric, so its orientation in the image gives the rotation of the scan and whether one axis is flipped. With scan_y_down on, the R is mirrored in Y so that it reads upright in the image. The scan generator spends the same time on every position, so a longer exposure is written as the same position repeated in a row: each corner lr_corner_dwell times (5 by default) and each position of the R lr_letter_dwell times (3 by default), the edges of the frame once. The beam draws the frame anticlockwise from the lower left corner, then the stem, top bar, bowl and middle bar of the R, then its leg; the positions are spaced by one step of the Square raster, and the beam never comes back to a position it has left. The letter is lr_letter_height of the frame side high and 0.7 of that wide. The STAR header records the number of positions drawn as _probe_positions (2239 for 65 536 positions and the default dwells), but ProbePositions is not set to it, since here it sets the size of the frame and a second run would draw a smaller one.

Results

Images: an interactive scatter plot only if Show plot is on (no PNG is saved).

Data written: the STAR file STARFILES/<ScanPatternSTAR> (one row per probe position); the results file registers the STAR file and records the final ProbePositions count.

42 — Scan Pattern Inventory

Purpose

A read-only bookkeeping tool. It scans the STARFILES/ directory and lists every existing scan-pattern STAR file with its scan mode and number of probe positions, so you can see at a glance which patterns are already available.

Parameters

This script inherits the standard scan-parameter list in its GUI, but its logic uses none of them to select or filter — it always lists all .star files. There are no effective inputs.

Algorithm

  1. Ensures STARFILES/ exists.
  2. For each .star file, reads until it finds _scan_mode and _probe_positions, then records that file's mode and position count (malformed files are skipped).

Results

Images: none.

Data written: nothing on disk is changed. It prints one line per pattern to the log and registers each STAR file as an "important" result (labelled with its mode and position count), so the inventory appears prominently in the Results panel.

45 — Scan Pattern Translator

Purpose

Converts scan patterns between the microscope's TVIPS scan-generator format (plain-text _x/_y/prescan integer lists) and 4d's STAR format, in either direction. This bridges externally acquired or scan-generator-native patterns with 4d's STAR-based pipeline, including handling of "prescan" (dummy lead-in) positions.

Parameters

ParameterRole
ScanPatternTranslateDirection: 0 = do nothing, 1 = TVIPS → STAR, 2 = STAR → TVIPS.
ScanPatternSTARThe STAR file read (dir 2) or written (dir 1).
ScanPatternTVIPSBase name of the TVIPS triple (<name>_x.txt, _y.txt, _prescan.txt).
ScanPattern_prescanWhether prescan (dummy lead-in) positions are expected/created.
ProbePositionsZeroStartNumber of dummy positions inserted before the real scan.
StepSize, ScanModeStep size (Å) and scan mode carried through the STAR header.
ProbePositionsPlot, scan_showplot, scan_y_downPlot controls.

Algorithm

  1. TVIPS → STAR: loads the X/Y integer arrays (the _prescan variants when flagged), drops the blank lead-in dummies (keeping only flagged real positions), and writes the STAR file.
  2. STAR → TVIPS: parses the STAR header and rows and writes <base>_x.txt/_y.txt; when prescan is on it prepends synthetic lead-in positions (linear extrapolation), uses the _prescan filenames, and writes a companion flag file (0 for each dummy, 1 for each real position).
  3. Optionally shows the resulting scatter plot.

Results

Images: an interactive plot only if Show plot is on.

Data written: the STAR file (dir 1) or the TVIPS text files <base>_x[_prescan].txt, _y[_prescan].txt and _prescan.txt (dir 2); all written files are registered to the Results panel.

60 — Grab central positions

Purpose

Reads an existing scan-pattern STAR file, computes the pattern's centroid, and extracts the 30 probe positions closest to that centre into a new, smaller STAR file. This gives a compact "central subset" pattern — handy for quick tests, alignment, or focusing on the centre of the field without running the full scan.

Parameters

ParameterRole
ScanPatternSTARThe input STAR file (in STARFILES/).
imagenumber, imagename, comment, tempkeepStandard image/utility fields (not used by the logic).

The count — 30 positions — is fixed.

Algorithm

  1. Parses the STAR file's header and position rows.
  2. Computes the centroid (mean X, mean Y).
  3. Sorts all positions by squared distance to the centroid and keeps the closest 30 (or all, if fewer).
  4. Writes the subset, re-indexed, to a new STAR file.

Results

Images: none.

Data written: a new STAR file STARFILES/<name>_centerpositions.star with the up-to-30 most central positions; both the original and the new file are registered to the Results panel.

ScanInspect — visualise a scan pattern

ScanInspect is an interactive viewer for scan patterns, reached from the Planning tab (4D-STEM project mode). A scan pattern is the list of probe positions a 4D-STEM acquisition visits, stored as a .star file by the Scan Pattern Generator. ScanInspect lets you load such a file and see the pattern before you use it — to confirm its geometry, spacing, coverage, scan order, and the coordinate convention are what you intend.

It loads a scan-position .star file and draws every probe position as a dot on a canvas. The numbered markers on the screenshot below point to each control; the legend that follows explains them, and the small ? button at the far top-right of the window opens this page.

The ScanInspect window with numbered regions 1 2 3 4 5 6 7 8 9 10 11
#ControlWhat it is and does
1Select .star file / Load STAR fileChoose a scan-position .star file (the drop-down lists the patterns in the project's STARFILES/) and press Load STAR file to display it.
2Scangenerator coordinate systemWhether the file's Y axis points down (X=right, Y=down) or up (X=right, Y=up), matching your scan generator so the preview is oriented correctly.
3File previewA text panel showing the loaded file's first lines — the header (_scan_mode, _probe_positions) and the numbered X Y position list.
4Scan Preview canvasEvery probe position drawn as a dot, with a nanometre scale on both axes. Drag to pan; scroll or pinch to zoom.
5Display modeStatic shows the whole pattern at once; Animated draws the positions in acquisition order to reveal the scan path.
6TransparencyDot opacity — lower it to see overlapping dots in dense patterns.
7DiameterDot size, in nm (with a pixel read-out). Set it near the intended probe size to judge overlap.
8SpeedAnimation rate (up to Max) when Display mode is Animated.
9StepHow many positions are added per animation step.
10ZoomMagnify the preview (1–100×); also available with scroll/pinch on the canvas.
11Index–nm scaleNanometres per digital scan-generator unit — calibrates the axes so the pattern is shown at true physical scale.

Step-by-step

  1. Open ScanInspect from the Planning tab.
  2. Pick a pattern (1): choose a .star file from the drop-down and press Load STAR file. The file preview (3) and the canvas (4) fill in.
  3. Set the coordinate convention (2) to match your scan generator, so up/down is correct.
  4. Set the physical scale (11): enter the nm-per-scan-unit value so the axes read in true nanometres.
  5. Inspect the geometry (4): pan and zoom (10) the canvas to check spacing, coverage and shape; adjust Diameter (7) and Transparency (6) to judge how much neighbouring probes overlap.
  6. Check the scan order: switch Display mode to Animated (5) and use Speed (8) and Step (9) to watch the positions appear in acquisition order — useful to confirm the fly-back/serpentine path is what you expect.
  7. Accept or revise: if the pattern is right, use it for acquisition; if not, edit it with the Scan Pattern Generator and reload.
ScanInspect only visualises an existing pattern — it does not modify the .star file. Use the Scan Pattern Generator to create or change patterns.