4d — Parameter Editor

Preferences ▸ Parameters · 4d User Manual

← Back to Preferences

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.

The Parameter Editor with numbered regions 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
#Region / columnWhat it is and does
1Preferences tabsThe eight Preferences pages; Parameters is selected here.
2Parameter Editor titleThe panel title.
3Mode-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.
4Section tabsOne 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.
5Row # & "4D" show-in-table boxThe row number, and a check-box that makes the parameter appear as a column in the Library table for the current program mode.
6ParameterThe parameter's internal name, exactly as scripts reference it in their # DISPLAY: lines. Must be unique (see below).
7LabelThe human-readable text shown for this parameter in the Manual Processing parameter form.
8ValueThe parameter's default value. The Manual Processing tab shows it next to each parameter, under Default Values.
9TypeThe parameter's data type — see Parameter types.
10DescriptionThe explanatory text (legend), shown to the user as the parameter's tooltip/help.
11ExampleAn example value, to show the expected format.
12Lock / Wrong / SyncThree YES/NO flags controlling initial lock state, the "still needs editing" mark, and folder-wide syncing — see Lock, Wrong & Sync.
13User & 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.
14HelpAn optional link to a help page for the parameter.
15Action buttonsAdd 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.
Double-click any row to open the full Edit Parameter dialog, where you can change the name, label, value, type, min/max, description, example, the lock/wrong/sync flags, user level, program mode and the visibility rule. Add a new one with Add New Parameter.

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:

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:

TypeMeaning
Text_EditFree text — any string.
Bool (y;n)A yes/no switch, stored as y or n.
IntegerA whole number.
FloatA decimal number. A range can be attached, written as Float "MIN=…;MAX=…".
Two_FloatA pair of decimal numbers (e.g. 16,100).
Three_FloatThree decimal numbers.
Four_FloatFour decimal numbers.
Drop_Down_MenuA choice from a fixed list, written as Drop_Down_Menu "a;b;c" — the GUI shows a drop-down of those options.
File_PathA path to a file (with a file browser).
Dir_PathA path to a directory.
Dir_Path_No_SubdirA directory path, restricted to a directory without browsing into sub-directories.
File_Path_System_WideA file path resolved against system-wide locations.
File_Path_Project_WideA file path resolved against the project.
File_Path_Local_ImageA file path local to the current image/dataset.

Lock, Wrong & Sync

These three YES/NO columns (12) are per-parameter flags:

FlagYES means…
LockThe 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.
WrongThe 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:

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:

StateIn the processing GUI
NormalThe default: the parameter is shown and editable as usual.
FrozenThe 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.
HiddenThe 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:

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