The Parameter Editor
The Parameters tab of the Preferences dialog opens the
Parameter Editor — the master list of every parameter 4d knows
about. Each parameter has a name used in the processing scripts (via their
# DISPLAY: lines) and a set of properties (label, default value,
type, help, and where it is shown). The scripts and the per-dataset/project
configuration all draw their labels, types and defaults from here. Parameters are
grouped into tabs, one per parameter file (Sample, 4D STEM, Parallax, …).
The numbered markers on the screenshot point to each region; the legend and the sections below explain them. The ? button at the top-right of the Parameter Editor (just to the right of the mode-filter toggle) opens this page.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| # | Region / column | What it is and does |
|---|---|---|
| 1 | Preferences tabs | The eight Preferences pages; Parameters is selected here. |
| 2 | Parameter Editor title | The panel title. |
| 3 | Mode-filter toggle | "Showing only parameters valid for program mode …" — toggles between showing only the parameters used in the current program mode and showing all parameters. The ? help button sits just to its right. |
| 4 | Section tabs | One tab per parameter file / group (Sample, 4D STEM, Parallax, Ptychography, Motion correction, …). Use the ‹ › arrows to reach tabs that don't fit. Editing a tab writes back to its own .cfg file. A file that declares several # SECTION: blocks shows one table per section in its tab, each under its own title line, and all of them are saved back into that one file — see Files with several sections. |
| 5 | Row # & "4D" show-in-table box | The row number, and a check-box that makes the parameter appear as a column in the Library table for the current program mode. |
| 6 | Parameter | The parameter's internal name, exactly as scripts reference it in their # DISPLAY: lines. Must be unique (see below). |
| 7 | Label | The human-readable text shown for this parameter in the Manual Processing parameter form. |
| 8 | Value | The parameter's default value. The Manual Processing tab shows it next to each parameter, under Default Values. |
| 9 | Type | The parameter's data type — see Parameter types. |
| 10 | Description | The explanatory text (legend), shown to the user as the parameter's tooltip/help. |
| 11 | Example | An example value, to show the expected format. |
| 12 | Lock / Wrong / Sync | Three YES/NO flags controlling initial lock state, the "still needs editing" mark, and folder-wide syncing — see Lock, Wrong & Sync. |
| 13 | User & program mode (4D / Fibr.) | The User level (Normal vs. Advanced — advanced parameters are hidden until the "Advanced parameters" switch of the processing window is on), and the 4D / Fibr. check-boxes that say which program mode(s) the parameter belongs to. |
| 14 | Help | An optional link to a help page for the parameter. |
| 15 | Action buttons | Add New Parameter Section (see Parameter sections), Add New Parameter, Copy / Cut / Paste (⌘C/⌘X/⌘V), and Search (⌘F) at the bottom-left; Save All Parameters and Close without saving at the bottom-right. |
Parameter sections
Every parameter file starts with a # SECTION: line that names the
group of parameters below it. A file may declare more than one
# SECTION:; its tab then shows one table per section, each under its
own title line, in the order in which the sections appear in the file. The tab is
named after whichever section comes first.
Each title line carries two controls:
- ≡ — press it and drag up or down to move that section to another place within its file. Moving a section to the top renames the tab after it.
- pen — click it to give the section a new name.
Add New Parameter Section (bottom left, next to Add New
Parameter) appends a further section, called Parameter Section, to
the end of the tab you are in; rename it with the pen and fill it with
Add New Parameter. The new section starts with one placeholder
parameter, dummy of type Text_Edit — rename it through
the Edit Parameter dialog (double-click its row) or delete it once the
section holds the parameters you want.
A section lives through its parameters: deleting or cutting the last parameter of a section removes the section as well, and it is no longer written to the file. The last remaining section of a file is kept even when it runs empty, so that the file itself is not lost.
Editing works the same in every table, and Save All Parameters
writes all sections of a tab back into that one file, keeping its
# SECTION: blocks in the order shown. When the mode filter is on, a
section without a single parameter for the current program mode is left out of the
tab, and a tab without any is dropped from the tab bar.
Parameter types
The Type column (9) fixes how a parameter is entered and validated. The available types are:
| Type | Meaning |
|---|---|
Text_Edit | Free text — any string. |
Bool (y;n) | A yes/no switch, stored as y or n. |
Integer | A whole number. |
Float | A decimal number. A range can be attached, written as Float "MIN=…;MAX=…". |
Two_Float | A pair of decimal numbers (e.g. 16,100). |
Three_Float | Three decimal numbers. |
Four_Float | Four decimal numbers. |
Drop_Down_Menu | A choice from a fixed list, written as Drop_Down_Menu "a;b;c" — the GUI shows a drop-down of those options. |
File_Path | A path to a file (with a file browser). |
Dir_Path | A path to a directory. |
Dir_Path_No_Subdir | A directory path, restricted to a directory without browsing into sub-directories. |
File_Path_System_Wide | A file path resolved against system-wide locations. |
File_Path_Project_Wide | A file path resolved against the project. |
File_Path_Local_Image | A file path local to the current image/dataset. |
Lock, Wrong & Sync
These three YES/NO columns (12) are per-parameter flags:
| Flag | YES means… |
|---|---|
| Lock | The parameter starts locked in the processing GUI — a small lock icon is shown, and the user must unlock it before editing. Use it to protect values that should rarely change. |
| Wrong | The parameter is flagged as still requiring editing — it is marked as "wrong / not yet set" so the user's attention is drawn to it before a script is run. |
| Sync (sync with upper level) | The parameter is global to its folder: its value is shared by all datasets of the same folder (group) instead of being stored separately per dataset, and is kept in that folder's 4d_group.cfg. Changing it in one dataset changes it for every dataset of that folder, and for no other folder. A new folder starts from the project-level values; to use the same value in another folder, set it there as well. |
Visibility rules: hide or freeze depending on other parameters
A parameter, or a whole section, can be hidden or frozen in the processing GUI depending on the current value of other parameters. For example, the settings of one scan pattern are only shown while that pattern is the selected scan mode. The rule is entered in the Parameter Editor:
- for one parameter, in the Visibility field of its Edit Parameter dialog (double-click the row);
- for a whole section, in the Visibility field next to the section title.
A rule the editor cannot read is flagged in red as you type, with the reason. The table has no column for the rule, but the tooltip of a row's Type cell shows it. Leave the field empty for a parameter that is always shown.
The three states a rule can put a parameter in:
| State | In the processing GUI |
|---|---|
| Normal | The default: the parameter is shown and editable as usual. |
| Frozen | The row stays in the panel, but the field and its label are greyed out and the field cannot be edited; its tooltip names the parameter and value that froze it. The stored value is kept and is used by scripts as before. |
| Hidden | The row is taken out of the panel (a section left without rows disappears with it). The stored value is kept; it comes back unchanged when the condition lifts. |
A rule is one or more clauses separated by ;. Each clause is a state, Normal,
Frozen or Hidden, optionally followed by if and a condition. The
clauses are tried in the order written; the first one whose condition holds (or which has no
condition) wins, and if none holds the parameter is Normal.
A condition compares another parameter with a value: ScanMode = Fermat,
ProbePositionsDosefrac <= 1. The comparisons are =, !=
(or <>), <, <=, > and
>=. Several comparisons are joined with and and or, where
and binds tighter. Values that both read as numbers are compared as numbers; anything
else is compared as text without regard to case, with y, yes,
true, 1 and n, no, false, 0
treated as the same two answers, so a yes/no parameter matches either spelling.
Examples of what to enter in the Visibility field:
| Entry | Effect |
|---|---|
Hidden if ScanMode <> Honeytomb9 |
Shown only while the scan mode is Honeytomb9, hidden for every other mode. Typical for a section holding one pattern's settings. |
Frozen if scan_single_frame = y |
Greyed out and not editable while the data has a single scan frame, as set by the scan calibration step. Shown and editable again for a multi-frame stack. |
Hidden if ProbePositionsDosefrac <= 1 |
Hidden while there is at most one dose-fractionation layer, so a per-layer setting only appears when there are layers to apply it to. |
Frozen if Thread_Number > 1 |
Editable only in a single-thread run; greyed out as soon as more than one thread is set. |
Frozen if ScanMode = HexDoseFracSquare or ScanMode = SunflowerDoseFrac |
Greyed out for the two dose-fractionated patterns, removed from the panel for Fermat, normal for every other mode. |
Hidden if ScanMode = SunflowerRim12 and sfr_offset <= 0 |
Hidden only when both hold: the rim pattern is selected and its origin offset is zero or negative. With or instead of and, either one would hide it. |
Normal if ScanMode = Honeytomb9; Hidden |
The same as the first example, written with the clause order: the first clause keeps it normal for Honeytomb9, the second, which has no condition, hides it otherwise. |
Hidden |
Never shown in the panel; the value is still stored and used by scripts. |
The rule is re-evaluated the moment one of the parameters it reads changes, whether you edit that parameter in the panel or a script sets it, so rows and sections appear, grey out and come back without a reload. A Frozen section is greyed out as a whole, title included, and the title's tooltip says why; a Hidden section disappears from the panel. A parameter's own rule still applies on top of its section's, so the more restrictive of the two states wins for that row. The "Advanced parameters" switch, the User level column and a script's own parameter list still apply as well: a parameter is shown only when all of them allow it.
Parameter names must be unique
A parameter name (column 6) may appear only once across the whole Parameter Editor — the name is the key that scripts use, so two definitions would be ambiguous. If the same name is entered twice (in the same tab or in different tabs), every row with that name is highlighted in orange to flag the clash. An orange row means you must rename or remove one of the duplicates before saving. The Edit Parameter dialog also turns the name field orange and warns "Parameter exists already in tab '…'" as you type a name that is already in use.