The script processor is case-insensitive; you can enter commands as ALLCAPS or alllowercase, but for readability it is helpful to use MixedCase as in the table. Completing a command by typing tab or ` will convert it to MixedCase. Parameters to the individual commands are abbreviated as follows:
When there are multiple optional entries, there needs to be an entry for every one up to the last one that you want to enter. If there are several entries within one set of brackets, they must all be entered if any of them are desired. For example, 'RealignToNavItem #R [#C] [#S #N #Z]' must have at least one entry, and can have 2 or 5, such as 'RealignToNavItem 0', ' RealignToNavItem 0 1', or 'RealignToNavItem 0 0 0.3 2 0'.
Frequently used non-numeric parameters used in SerialEM scripting are referred to by these names:
Any place where an integer entry is expect, an entry starting with '0x' can be used to specify a hexadecimal value.
Commands assign the primary values that they report to the variables reportedVariable1, etc. When the command description lists the various values that it reports, with no other details, it can be assumed that these variables are each assigned to one of the reportedVariables, in the order in which they are listed.
Commands starting with 'Report...' will assign output to one or more variable names listed after the command (omitting the '$'), except where the table notes otherwise. For other commands, the table explicitly states when they accept variable names. Arithmetic expressions can be used after virtually all commands starting with 'Set' and with the commands listed in Commands Allowing Arithmetic Expressions for Arguments.
Some commands will call functions that may not be supported by the Thermo/FEI scripting adapter or JEOL scripting interface on your scope. In either case, the program will crash if it calls a function that does not exist in the scripting interface. (Neither of these interfaces has a version number that could be used to prevent this.) For a JEOL, the version of TemExt.dll that provides the interface may be new enough to have the function, but the call will fail with an error if it is not supported by the microscope software/hardware.
All commands not available from Python are marked as 'Not from Python'.
| Flow Control Commands | |
| Repeat | Place at end of script to repeat it. Not from Python. |
| Loop # [var] | Loops the given # of times until EndLoop; optionally set var with index.
A loop count less than or equal to 0 is allowed and
will cause the loop to be skipped. If a script relying on this is liable
to run on earlier versions, it should include the line 'Require zeroloop'.
Not from Python. |
| DoLoop var #S #E [#I] | Loops from #S to #E, inclusive, assigning the loop index to var.
The optional #I can be entered to set the increment, which is 1 by default.
If the starting index is already past the ending one, the loop will be skipped.
Integer values should be entered; non-integer values will be truncated to
integers. Not from Python. |
| EndLoop | Marks the end of a loop. Not from Python. |
| DoScript # DoMacro # |
Switches to given script #. Not from Python. |
| CallScript # [arg1 arg2 ...] CallMacro # [arg1 arg2 ...] |
Calls other script by # and returns. The # can be -1 to use the script
number found by a previous 'FindScriptByName'. A regular SerialEM script
may call a Python script provided that the top-level script was not Python.
When doing so, optional arguments can be added and will be placed into a list of
strings named 'SEMargStrings' in the Python script.
Callable from Python with the number of a regular SerialEM script, but with no optional arguments. |
| FindScriptByName text | Finds the number of the script whose name is text and stores its number internally
so that it can be used in a following 'CallScript -1'. Names are case-sensitive
and must match exactly, including spaces. Not from Python. |
| Call text | Calls other script by name. Names are case-sensitive and must match exactly,
including spaces. A regular SerialEM script may call a Python script provided
that the top-level script was not Python. Callable from Python with the name of a regular SerialEM script. |
| CallStringArray var [#E] |
Places the array of strings in var into an 'extra' script and runs
it. Extra scripts are temporary and available only until a script ends. Up to
5 extra scripts can be defined; they are added sequentially to positions
numbered 1 to 5. The optional #E can be entered to place a script into a
previously used position or the next unused position. If the script
depends on other temporary scripts, they can be loaded first with
'StringArrayToScript'. Callable from Python if the string array contains a regular SerialEM script and the Python script was not called from a regular script. |
| Function name [#N] [#S] [args] | Defines a function with the given name (without embedded spaces). The
optional #N indicates the number of numeric arguments and #S is non-zero to
indicate that a string argument occurs after the numeric ones. Optional
variable names can be provided for the arguments. Functions
must be placed at the ends of scripts. Not from Python. |
| EndFunction | Required ending to a function definition. Not from Python. |
| CallFunction name [args] | Calls the function with the given name and supplies arguments for the function
to receive. If the name could occur in more than one script, it must be
qualified with a script number or name, i.e. '5::GoodFunc' or 'Func
Script::GoodFunc'. The variable functionName is defined with the
name. Callable from Python with the name of a regular script function as its first, string argument. The order of arguments is changed from what is used in a regular script: the first optional argument is the string argument that the function may allow, and then up to 17 numeric arguments can be passed. If a function takes no string argument, you can just use an empty string. For example: retVals = CallFunction('My Functions::Cycle Defocus', '', 1., 10) |
| PythonScript [arg1 arg2 ...] | Allows a Python script to be embedded in a regular script and run at that point.
Optional arguments can be added and will be placed into a list of strings named
'SEMargStrings' in the Python script. This is equivalent to having the Python
text by itself in a different script and calling it with 'CallScript'. Not from Python. |
| EndPythonScript | This line must occur at the end of an embedded Python script started with 'PythonScript'. Not from Python. |
| If expression | Starts a block that is executed conditionally on the value of 'expression'.
Not from Python. |
| Endif | Ends a block started with 'If'. Not from Python. |
| ElseIf expression | Inside of an If/Endif block, starts a block that is executed conditionally on
the value of 'expression' if the expressions in the starting 'If' statement and
any preceding 'ElseIf' statements were not true. Not from Python. |
| Else | Inside of an If/Endif block, starts a block that is executed if the expression
after the 'If' and any preceding 'ElseIf' commands is false. Not from Python. |
| Break | Stops execution of the innermost Loop containing this statement. Not from Python. |
| KeyBreak [key] | If the user presses 'B', or the key given by the optional key entry, the
script breaks out of the innermost Loop containing this statement. key
should be a letter or number; the test for the key is case-insensitive. Callable from Python. |
| Continue | Skips the rest of the current iteration of the innermost Loop containing this
statement. Not from Python. |
| SkipTo label | Skips forward to the line starting with the given label, where the label has a
colon (:) at the end of it and is the only item on the line. The colon is
not included in the label in the 'SkipTo' statement. Not from Python. |
| Try [#] | Starts a block within which an error will result in the script jumping to the
line after the following 'Catch' statement instead of a message box appearing.
See Error Handling and TRY - CATCH - ENDTRY Blocks.
As of SerialEM 4.1, 13-Oct-23, set the optional # non-zero to suppress
the log output. Not from Python. |
| Catch | Starts the block of commands that are run only when an error occurs or 'Throw'
statement is used inside the 'Try' portion of the block. Not from Python. |
| EndTry | Ends the block of commands run upon error. Not from Python. |
| Throw [text] | Jumps to the 'Catch' section of the 'Try' block containing this statement,
adding the optional text to the message given in the log about the jump.
Not from Python. |
| OnStopCallFunc name | Calls the function with the given name when the script is stopped by the user
pressing STOP or by an error in a script operation or in an external routine.
The function must not take any arguments, and it should not call other functions
or scripts (such calls will be skipped). The function will be called only
once, even if there is an error or STOP while it is running. The script
will be aborted (not left in a resumable state) when the end of the function is
reached. Not from Python. |
| Return [r1] [r2] [r3] [r4] r[5] [r6] | Without executing to the end of the current script, returns to calling script or
ends execution if this is the top-level script. Up to 6
return values can be placed in reportedValue1 to reportValue6 with optional
arguments r1 to r6 If any such arguments are included, existing reported
values will be cleared; otherwise they will be preserved. If there is any chance that a script relying on this
feature will be run on an earlier version, include the line 'require 203' in the script.
Callable from Python with the same functionality, except that existing reported values are always cleared. The returned arguments must all be strings. |
| Exit [text] or Exit [#exc] [text] (from Python) | Ends execution unconditionally and prints the optional text to the log.
Callable from Python: From a Python script, there are two optional arguments, an integer then a string; i.e., it is called as Exit([exc], [text]). In a script run from SerialEM, exc should be 0 when exiting from normal code or positive when exiting from a Python exception; the default is 0. In a script run from an externally started Python, the default is 1 to keep the script from raising a SEMexited exception. You can call with a 0 if you want to catch this exception. |
| Variable and Array Commands | |
| CompareStrings var text | Compares the strings in the given variable var (without a $) and in the text on the rest of the line. Sets reportedValue1 to 0 if the strings are equal, a negative number if the variable is alphabetically before the text, and a positive number if it is after. |
| CompareNoCase var text | Like CompareStrings except that upper/lower case differences are ignored in the comparison. |
| StripEndingDigits var1 var2 | Removes any digits from the end of the variable var1 and assigns it to the variable var2 (both named without a $). The digits are converted to a number and assigned to reportedValue1. |
| FindSubstring var #D text | Finds the substring in text in the given variable var and sets reportedValue1 with the index, numbered from 0, or -1 if it is not found; also sets reportedValue2 to 0. It finds the first occurrence if #D is 0 or 1, or the last occurrence if #D is -1 or -2 The search is case-insensitive if #D is 1 or -2. Command added in 4.1, 14-Nov-23. |
| TrimString var #F token/#I | Trims a string in variable varfrom either the back or the front, and either from a specified index in token (numbered from 0) or from the location of a substring in token within the string. If #F is 0 or 1, token is taken to be a substring (one character or word without spaces). Trimming from the back (#F 0), it starts at and includes the last occurrence of token. From the front (#F 1), it trims through the first occurrence of token. With #F -1, it trims off the end starting at the index in token; with #F -2, it trims everything before that index, which cannot be 0 in either case. The result can be assigned to a variable at the end of the command. Command added in 4.1, 14-Jul-22; expanded to take indexes, 14-Nov-23. |
| ListVars | Lists all variables and their values in the log window, including reported values, persistent variables, and loop indices. |
| ListPersistentVars | Lists all variables defined as persistent and their values in the log window. |
| ClearPersistentVars | Removes all persistent variables defined with ':=' |
| ClearNonPersistentVars | Removes all non-persistent variables that have been defined, except loop index variables. This command is important to use when controlling the program remotely (e.g., from an external Python script) because variables are cleared only when such a script relinquishes control. Command added in 4.2, 1-Nov-24. |
| MakeVarPersistent var [#] | Changes a regular variable to persistent, or if a 0 is entered for #, makes a persistent variable non-persistent. |
| IsVariableDefined var | Reports whether a variable is defined, placing a 1 in reportedValue1 if it is and a 0 if it is not. Follow with the variable name without a $. Value can be assigned to a variable at end of command. |
| LocalVar var [var] ... | Creates the listed variables as variables local to the current script or function. They will not be accessible outside this script or function and will become undefined when returning from the script or function. Not from Python. |
| LocalLoopIndexes | Makes loop indexes local; this means that a called function or script cannot
access the index value in the caller and is free to reuse the variable name
as a loop index or other variable. If this feature is used, this
command should
be near the start of any script that may be started independently. Once
the feature is invoked, it cannot be turned off. Not from Python. |
| NewArray var #T #E | Creates a new variable with the name var, making it persistent or local if
#T is 1 or -1, respectively, or a regular variable if #T is 0. The
array is initialized with #E zeros. Not from Python. |
| New2DArray var [#T] [#R #E] | Creates a 2D array variable with the name var, making it persistent or
local if #T is 1 or -1, respectively, or a regular variable if #T is 0. If
the optional #R and #E are
given, the array is initialized with #R rows of #E zeros each, where both
must be positive. Not from Python. |
| AppendToArray var item | Appends one item or an array or items either to a 1D variable, which may
already be an array or not, or to a row of a 2D array, specified with var[row], or as a new row of a 2D array, specified without a subscript.
As with setting a variable, if there are multiple items on the line not
specified as an array, only the first item will be added, whereas if there
the multiple items are enclosed in '{ }', all items will be added to the
array. Not from Python. |
| TruncateArray var # | Truncates the given array variable var to # elements; # must be positive. For a
1D array, the values is truncated to # elements; for a row of a 2D
array, specified by var[row], the row of values is truncated; for a
2D array given without a subscript, the number of rows is truncated to #.
Not from Python. |
| ArrayStatistics var | For the set of values in the given array variable, computes and reports the total number of values, the minimum, the maximum, the mean, the standard deviation and the median. For a 2D array, the statistics can be of the whole array, or of one row if the variable is given with a row subscript. Values can be assigned to variables at end of command. |
| LinearFitToVars var1 var2 [var3] | Computes a linear least-squares fit between values in 2 or 3 array variables. With two variables, fits to the equation v2 = slope * v1 + intercept and reports the number of values, slope, intercept, and correlation coefficient 'ro'. With three variables, fits to the equation v3 = a1 * v1 + a2 * v2 + c and reports the number of values, a1, a2, and c. All variables must have the same number of values. |
| StringArrayToScript var [#E] | Loads the array of strings in var into an 'extra' or regular script. Use
this command to make functions in an extra script available, such as to another
extra script. Extra scripts are added sequentially to positions numbered 1
to 5. A positive value #E can be entered to place a script into a
previously used position or the next unused position. A negative value (-1
to -60) can be used to replace the script in one of the regular script positions
that are editable and saved to settings. As of 21-Jul-23, This command can be called from Python, but only with a regular script position (#E must be entered and must be negative), and with either a SerialEM script that can be called with 'CallScript', or a Python script to be run later. |
| Other Script Operation Control Commands | |
| ScriptName text MacroName text |
Names the script to the given text, which can include spaces. The variable scriptName is defined with either this name, or "Script #n" if no name has been defined, when the script is started running. Not called as a function from Python, but can be present as a comment. |
| LongName text | A longer name to appear in the Run submenu of the Script menu; if this name is not defined, the regular name defined by ScriptName or MacroName appears there. The variable longName is defined with this name when a script is started running. Not called as a function from Python, but can be present as a comment. |
| ReadOnlyUnlessAdmin | Prevents changing the script in the script editor from this command to the end of the script, unless Administrator mode is turned on in the Calibration menu. Place the command at the beginning of script to make the whole script read-only. Not called as a function from Python, but can be present as a comment. |
| Delay # units | Waits for given amount of time, where units can be 'msec', 'ms', 'sec', 's', or 'min'. The units are actually optional but it is bad practice to leave them out and a message will be printed if you do. If no units are given, a # <= 60 is taken to be seconds, and a # > 60 is taken to be milliseconds |
| WaitForMidnight [#B] [#A] [#H #M] | If the current time is between #B (default 5) minutes before and #A (default 5) minutes after midnight, or an alternative time specified by the optional entries #H (the hour from 0 to 23) and #M (the minute from 0 to 59), the script will wait until #A minutes after midnight or the given time. |
| WaitForNewMarkerPoint | Waits until a new marker point is placed in the currently active image buffer; and makes 'SET NEW MARKER' flash in the status bar. The marker must be added to the image that is active when the wait is started, although the program may not be able to enforce this in some cases. Command added in 4.1, 18-Aug-23. |
| ParseQuotedStrings [#] | Allows strings that may have spaces to be enclosed in single quotes (e.g.,
'text string') and treated as a single entity in cases where it would be broken
up at the spaces. Follow with a 0 to turn off such parsing. The best
use of this feature would be for making an array of strings in a single
statement that encloses the entries with braces. It also allows a string
to be assigned to a variable without using '@='. Not from Python. |
| Verbose # | Turns echoing of each script line on or off for # 1 or 0 |
| SuppressReports [#] | Disables printing of reports and some other script output, and just assigns the values to report variables. Including 0 for the optional # reenables printing. |
| SuppressInfoOutput [#] | Disables printing of most other script outputs that provide information and that are still printed with 'SuppressReports'. Including 0 for the optional # reenables printing. There is no consistent distinction between which such output is suppressed by this command instead of 'SuppressReports'; if you think an item should be moved between categories, let us know. Command added in 4.1, 31-Oct-23. |
| SuspendNavRedraw [#] | Disables updating of the table list box in the Navigator window and redrawing of the image window when Navigator items are changed, to speed up scripting changes of multiple items. Updating is reenabled and done when this command is given again with 0 for the optional # or when the script ends. |
| DeferLogUpdates [#] | Makes output to the log window be held in a buffer and added to the window periodically, to speed up repetitive printing to log. The buffering ends when this command is given again with 0 for the optional # or when the script ends. |
| DeferSettingsUpdate | Prevents control panels from being updated for new settings when 'SetUserSetting' is run; the update will occur before the next command that is not 'SetUserSetting'. Use this before doing a consecutive series of settings changes. Command added in 4.2, 19-Feb-24. |
| ErrorsToLog [#] | Makes most script error messages be duplicated in the log window. Follow with a 0 to turn off the feature again. |
| NoMessageBoxOnError [#] | Outputs an error message to the log instead of opening a message box. The script stops, but if it is being run from Navigator Acquire at Items, the Navigator is able to go to the next item. Follow with 0 to turn the feature off again. |
| GetFileInWatchedDir pattern | Looks for a file matching the given pattern, where pattern can be a directory followed by a filename including '*' to match multiple names. If just a directory is entered, the program appends a '*'. If a file is found, it returns 1 in reportedValue1 and the filename in reportedValue2; otherwise it returns 0 and 'none'. A file is ignored if a file with the same name plus '.lock' is found as well. Thus, if there is a risk that a file might not all be present when SerialEM first sees it, the program creating the file should create the '.lock' file (which can be empty), then create and finish writing to the file to be found, then remove the '.lock' file. The file will need to be removed to avoid finding it again on the next call. |
| IsFFTWindowOpen | Reports whether the FFT window is open; the value can be assigned to a variable after the command. |
| RunScriptInWatchedDir pattern | Looks for a file matching the given pattern, like 'GetFileInWatchedDir',
and reads the file, places its contents in an extra script position, removes the file,
and runs that script. It sets reportedValue1 and 2 just as
for 'GetFileInWatchedDir'. As for 'GetFileInWatchedDir', a '.lock'
file can be used to avoid the risk that the file is not complete when SerialEM
sees it. Not from Python, although the script may be Python. |
| RunScriptInFile file | Runs a script in file by reading it into an extra script position and
calling it from the current script. Not from Python, although the script may be Python. |
| Require feature [feature] ... Require script_version_number |
This command tests whether scripting features used in the script are available in this
version of SerialEM. Earlier versions will not generate an error when some
newer features are used, so including this command is the only way to test
whether the script will run correctly. Initially these features were
specified by name, but this was silly and the command now takes a scripting
version number, which is unrelated to the program version number. You can
enter either the latest feature name or the version number that your script
needs. The available features, in order of addition, were: 1) 'variable1',
which includes two capabilities: assigning reported values
directly to variables listed after a command, and assigning function arguments
directly to variables listed on the 'Function' line. 2) 'arrays',
which is the ability to define a variable with an indexable array of values.
3) 'keepcase', which means that case will be preserved when assigning text to a
variable. 4) 'zeroloop', which means that a non-positive loop count is
allowed. 5) 'evalargs', which means that arithmetic expressions will be
evaluated in arguments to some commands. 6) Scripting version 201, which
means commands can be continued onto multiple lines with backslash.
7) Version 202, which means that limited arithmetic can be done in
array subscripts (without spaces) and that arithmetic clauses can start with a minus sign.
8) Version 203, in which the 'Return' command can
return values from a function or script. 9) Version 204, in which string assignments
can have embedded newlines, and string assignments and defining an array of quoted strings can
have more than ~55 words.
Not from Python. |
| IsVersionAtLeast #V [#D] | Tests whether the program version is at least the version specified with #V, and also if its build date is at least that specified by the optional #D. The version should be 5 digits: the initial version number (currently 3) times 10000, plus the major release version times 100, plus the minor version (.e.g, 3.6.3 is 30603). The build date should have the format yyyymmdd, e.g., 'Sep 12 2017'; is specified as 20170912. Sets reportedValue1 to 1 if the version is high enough, 0 if not. |
| SkipIfVersionLessThan #V [#D] | Skips the command on the next line if the program version is earlier than the version specified with #V, or if the build date is earlier than the optional entry #D. The format of these entries is as just described. The next line will be skipped unconditionally when checking the script before execution. Thus, loop and conditional control statements cannot be on that line. This command is intended to provide a way to place a newer command into a script and allow it to be runnable on older versions. |
| Test expression | Evaluates a conditional expression (just as would be used for an IF statement)
or a single number or variable value and stores whether the test passed (i.e.,
if the expression is true or if the number is non-zero) internally, as well as
storing a 1 for success or 0 for failure in reportedValue1 and a variable
TestResult. Not from Python. |
| PauseIfFailed [text] | If the last 'Test' command failed, this command opens a message box with the
optional text plus the question of whether to proceed with the script, even if
NoMessageBoxOnError is set. Not from Python. |
| AbortIfFailed [text] | If the last 'Test' command failed, this command opens a message box with the optional text (unless NoMessageBoxOnError; is set) and aborts the script. Not from Python. |
| Log Output, User Input, and Other Communication Commands | |
| Echo [text] | Prints the text to the log window, or a blank line if there is no text. Variables are substituted but arithmetic expressions are not evaluated. Multiple spaces between words are preserved, as well as extra spaces before the text. The two characters '\n' will print unchanged, so file paths will print correctly. |
| EchoBreakLines [text] | Prints the text to the log window, or a blank line if none, after substituting variables and breaking the line at either escaped newlines (the two characters '\n') in text or at embedded newline characters, which are the separators between array elements. I.e., an array of strings will be printed on separate lines. |
| EchoEval [text] | Prints the text to the log window after substituting variables and evaluating arithmetic expressions. Multiple spaces between words will be lost. Not from Python. |
| EchoNoLineEnd text | Prints the text to the log window after substituting variables and evaluating arithmetic expressions, without adding a line ending, so more text can be written to the line. Multiple spaces between words will be lost. |
| EchoReplaceLine [text] | Removes existing text from the log back to the last line ending, if there is any such text, then prints the optional text to the log after substituting variables and evaluating arithmetic expressions, without adding a line ending. This command can be used repeatedly to update the text on a line, such as with a status output. |
| EchoNoVarSub [text] | Prints the text verbatim to the log window including initial extra spaces,
or a blank line if there is
no text, without substituting variables. Not from Python. Command added in 4.9, 1/8/21. |
| SetNextLogOutputStyle #S [#I] [#G #B] | Sets the type style and color of the next output printed to the log. The style is set with #S, which can be the sum of 1 for bold, 2 for italics, and 4 for underlined. The color is set with either the stock color given by index #I or a custom color specified by red, green, and blue values in #I, #G, and #B. Stock colors with indexes 0 to 6 are black, gray, red, green, blue, purple, and brown, and indexes 7 to 11 are for whatever color is defined for errors, warnings, manually inserted text, debug output, and verbose output. Red, green, and brown will be largely indistinguishable for people with the most common forms of color blindness, so green and brown should be avoided except for local use. The color and style will apply to one of the echo statements or to the first line put out by some other operation. If the next output to the log contains multiple lines, they will all be modified. Command added in 4.2, 5-Feb-24. |
| Pause [text] | Opens message box with optional text plus question of whether to proceed with script. Is not suppressed by NoMessageBoxOnError. |
| YesNoBox text | Opens a Yes-No message box with the given text, which should be a question that can be answered with yes or no. Sets reportedValue1 to 1 or 0 for a yes or no answer. If NoMessageBoxOnError is set, no box appears, the text is printed to the log, and reportedValue1 is 0. If you do not like the way lines are broken in the standard message box or want to use a monospaced font, use the command 'NoLineWrapInMessageBox' and a 'three-choice box' with Yes and No buttons will be used instead. |
| OKBox text | Opens a message box with the given text and just an OK button. The box is not suppressed by NoMessageBoxOnError. If you do not like the way lines are broken in the standard message box or want to use a monospaced font, use the command 'NoLineWrapInMessageBox' and a 'three-choice box' with one OK button will be used instead. |
| EnterOneNumber text | Opens a dialog box for the user to enter one floating point number, with the given text as the prompt. Sets reportedValue1 to the entered value. |
| EnterDefaultedNumber #V #D text | Opens a dialog box for the user to enter one floating point or integer value. Follow with the default value #V to show in the box, the number of decimal places #D to show for a float entry or -1 for an integer entry, and the prompt text on the rest of the line. Sets reportedValue1 to the entered value. |
| EnterString var text | Opens a dialog box for the user to enter a string of text, with the given text as the prompt, and assigns it to the given variable var (without a $). |
| ThreeChoiceBox header choice1 [choice2] [choice3] buttons | Opens a dialog box to allow the user to choose between two or three options, although just one response is also allowed. Follow with 3 to 5 variable names. Put initial text to appear at the top of the box in variable header, descriptions of the choices in variables choice1, the optional choice2, and the optional choice3, and button labels as an array of strings in buttons. These names are arbitrary. Use an array of strings to have multiple lines of text for the header or descriptions. Use a line with just 'header @=' to make a variable for omitting the header text. The number of the choice (1, 2, or 3) is placed in reportedValue1. See Three Choice Box in Advanced Examples. |
| NoLineWrapInMessageBox [#W] [#M] | Sets parameters for the message boxes opened with 'ThreeChoiceBox', 'YesNoBox', and OKBox'. Enter no arguments or a non-zero value for #W to disable line wrapping; enter a non-zero value for #M to use a monospaced font. |
| EnterNameOpenFile [prompt] | Gets a filename through a dialog with a simple text box and open it as a new file. If the optional prompt string is not supplied, the prompt is 'Enter name for new file:'. |
| ChooserForNewFile # var | Opens a file chooser for the user to specify a new file; # should be 0 for an MRC file or non-zero for an .idoc file, and var must be the name of a variable to which the full filename will be assigned. Since the user will confirm the replacement of a file, the command also allows 'OpenNewFile' and 'OpenNewMontage' to overwrite an existing file. |
| UserOpenOldFile | Opens a file chooser for a user to open an existing MRC, HDF or .idoc file and opens the file, just like the Open Old item in the File menu. The script is suspended if the user cancels or picks a file that cannot be opened. |
| ChooserForTextFile # | Opens a file chooser for a user to select an existing text file if # is 0, or a new text file if # is 1. The filename is returned in reportedValue1 and assigned to an optional variable after #; 'NONE' is returned if the user cancels. If a new file already exists, the user has confirmed replacing it, so you should use 'AllowFileOverwrite' before opening the file. Command added in 4.2, 15-Feb-24. |
| SetStatusLine #L text | Places the given text in status line #L at the bottom of the Camera & Script control panel and makes sure that enough lines are displayed there to show this line (see Set # of Status Lines in the Script menu). There are currently up to 6 lines allowed so #L can be between 1 and 6. Command added in 4.1, 9-Mar-23. |
| HighlightStatusLine #L #O | Sets the background color of status line #L to magenta if #O is nonzero or restores it to yellow if it is 0, or does so to all lines if #L is 0. Command added in 4.1, 9-Mar-23. |
| ClearStatusLine #L | Clears the text out of status line #L and restores it from using the highlight color, or does so with all lines if #L is 0. Command added in 4.1, 9-Mar-23. |
| FlashDisplay [#T] [#D] [rgb] | Flashes between a uniformly colored screen and normal image display several times. The first optional entry, #T, sets the number of times to flash (default 4) and the second optional entry, #D, sets the duration of each state in seconds (default 0.3). Total duration may not exceed 6 seconds. The third optional entry, rgb, sets the color of the flashing screen in hexadecimal (RRGGBB) notation, e.g. FF5500 is orange. | Functions Available Only from Python |
| SetVariable(var, value) | Sets variable var within SerialEM scripting with value, which must be a string. Here and in the next 3 commands, var must be a string. A one-dimensional array variable can be passed by separating each value with newlines ('\n', written as '|\n' within SerialEM). The Python wrapper function 'listToSEMarray' can be used to convert a list with numeric and/or string values to a newline-separated string. Variable names are stored as upper case within SerialEM, so all variable specifications are case-insensitive. |
| SetPersistentVar(var, value) | Like SetVariable, but sets it as a persistent variable. |
| SetFloatVariable(var, value [, #P]) | Sets variable var within SerialEM scripting with value, which must be numeric, and sets it as a persistent variable if the optional #P is non-zero. |
| GetVariable(var) | Returns the value of a variable var as string or floating point value, depending on whether the variable was designated as numeric when it was stored The Python wrapper function 'SEMarrayToFloats' can be used to create a list of float values from the return value if the variable contains either a single numeric value or an array of numeric values |
| ReturnAllValuesAsTuples [#] | Make all reportedValues be returned as a tuple, even when there is a single reported value. Otherwise, a single value will be returned as a float, which can be problematic for commands that return a single value sometimes and multiple values other times, or if a second reportedValue is added to a command that previously had one. Set the optional # to 0 to turn off this feature. Command added in 4.1, 1-Oct-23. |
| bufferImage(buf) | Returns an image from a buffer by constructing an instance of the 'bufferImage' type that has an image pointer and other essential information about the image in buffer buf, which is a non-numeric string and can specify an FFT buffer. This type instance can provide the image to other classes via the Python 'Buffer Protocol'. To convert to a numpy array, use 'numpy.asarray()'; numpy.frombuffer() requires extra steps to set the shape and data size. The image may have padding (i.e., not be strictly contiguous) and a request that does not permit striding between lines could generate an exception. Not available below Python 3.4. |
| PutImageInBuffer(image, buf [,#X, #Y, base, #B, #C]) | Places an image that provides the 'Buffer Protocol' for array access into buffer buf. If buf is 'A' then buffers are rolled as when making a new processed image. Optional arguments are: #X and #Y with the X and Y size of the image (this seems to be required for an image from numpy); base with the letter of a buffer to use as the basis for various buffer parameters (the default is the buffer where the image is being placed); #B with a value of additional binning (default 1); #C with a 'capture flag' to define how the image is labeled in the buffer status window (the default is -1 for 'Processed'). |
| PluginAllDoubles(name, func, [,#D, #D, #D, #D, #D, #D, #D] | Calls the function func in the plugin named name with up to 7 optional floating point values. func and name are string arguments and name can be ':' to use the last plugin called. Command added in 4.2, 19-Apr-24. |
| PluginString(name, func, text) | Calls the function func in the plugin named name with the string in text. Command added in 4.2, 19-Apr-24. |
| PluginDoubleString(name, func, #D, text) | Calls the function func in the plugin named name with the floating point value in #D and the string in text. Command added in 4.2, 19-Apr-24. |
| ConnectToSEM([#P, IP]) | When running Python externally to control SerialEM, this function can be used optionally as the first call to SerialEM to define an alternative port in #P (the default is 48888) or an alternative IP address in IP (the default is '127.0.0.1'). If you use a different port, it must be specified in a property entry 'SocketServerPort 8'. |
| ReportNumModuleFuncs | Returns the number of functions defined in the serialem module through MacroMasterList.h (the count does not include some of the functions listed in this section). An integer is returned regardless of whether ReturnAllvaluesAsTuples was set. Use the command 'ReportNumExeFuncs' to find the corresponding number in the SerialEM executable and thus determine whether the module needs to be updated to have the newest commands. Command added in 4.1, 3-Oct-23. |
| Camera Control | |
| SelectCamera # | Makes the given camera be the active camera, where the # is the position of the camera in the ActiveCameraList property or Camera setup dialog, numbered from 1. Will switch in and out of EFTEM mode or STEM mode if appropriate. |
| RetractCameras | Retracts all retractable cameras; for backwards compatibility, 'RetractCamera' is still accepted. |
| ReportCameraInserted # | Reports whether the given camera is inserted, where # is either 0 for the current camera or the position of the camera in the ActiveCameraList property or Camera setup dialog, numbered from 1. The reported value is 0 if retracted, 1 if inserted, -2 if no information is available for the camera, or -1 for failure to create an interface for a Gatan camera. Command added in 4.1, 6-Aug-23. |
| CameraProperties [#C] [#M] | Reports unbinned size in X and Y, RotationAndFlip property, size of detector pixel in microns, and unbinned pixel size, and active camera number of the current camera, or of the active camera whose number is given by the optional #C Active camera values are numbered from 1. Also sets a variable numberOfCameras with the number of active cameras/ The unbinned pixel size is for the current magnification, or for the magnification index given by the optional #M. |
| ReportCameraName # | Reports the name of the active camera # (numbered from 1), or of the current camera if # is not positive. reportedValue1 is set to NOCAM if # is out of range. Command added in 4.1, 17-Jul-22. |
| SetDivideBy2 # | Turns division by 2 for the current camera on or off if # is 1 or 0, respectively. |
| ArePostActionsEnabled | Reports whether post-exposure actions are allowed for the current camera for all shots, and for Record shots specifically, and sets reportedValue1 and reportedValue2 to 1 if so, 0 if not. For Falcon and DE cameras, post-actions are allowed only when frames are being aligned in SerialEM. The values can be assigned to a variable after the command. |
| ReportCountScaling | Reports two values of current camera: either the scaling being applied to counting/super-resolution mode images returned from a K2 camera, or the 'CountsPerElectron' property; and whether division by 2 is on. |
| Acquisition Commands | |
| V or View | Acquires image with 'View' parameters |
| F or Focus | Acquires image with 'Focus' parameters |
| T or Trial | Acquires image with 'Trial' parameters |
| R or Record | Acquire image with 'Record' parameters |
| L or Preview | Acquires image with 'Preview' parameters |
| M or Montage [#] | Acquires montage, or acquires Prescan if optional # is non-zero. |
| Search | Acquires image with 'Search' parameters, or with 'View' parameters if the option is set to use those for Search. |
| PrescanWithPreview | In Low Dose mode, acquires a 3x3 Prescan montage with Preview parameters, automatically opening a temporary montage file and closing it at the end. Command added in 4.2, 29-Oct-24. |
| PreCookMontage #D [#P] [#C] [#S] | If montaging is enabled with stage movement, lowers the screen to expose the specimen, then moves the stage to each piece position and waits there for the number of seconds indicated by #D, if the number is positive. If #D is negative or #P is entered, it skips pieces within each column, with an interval given by the #P or the negative of #D: 2 will stop at every second piece, 3 at every third, etc. For convenience, 1 is equivalent to a large interval and will make it stop only at the bottom and top of each column. Set #C non-zero to skip columns partially or 0 not to: in every other column, the stage will be moved only to the first and last piece and to any piece that does not have an adjacent piece in the columns on both sides. This entry will make no difference if you use 1 or a very large number for the skip interval. Set #S with a stage movement speed factor or 0 for normal speed. If setting a speed factor crashes SerialEM or FEI-SEMserver, see notes under TiltDuringRecord. |
| Parameter Commands | |
| The commands in this section report or change values in one of the camera parameter sets for the current camera. The set entries can be specified as either V, F, T, R, P, S, M or 0, 1, 2, 3, 4, 5, 6 for View, Focus, Trial, Record, Preview, Search, and Mont-Map, respectively. Changed parameters will be restored whenever the script ends or stops or when a different camera is selected. However, if the script is suspended, any changed parameters will be set again when the script resumes. | |
| ReportExposure set | Reports the exposure time and drift settling for set. |
| SetExposure set #E [#D] | Sets exposure and, optionally, drift settling for set to the given values #E and #D. If #D is omitted, the existing drift settling will be unchanged. |
| ReportBinning set | Reports the binning for set. |
| SetBinning set #B | Sets binning for set to #B. |
| ReportCameraSetArea set | Reports the (binned) image size in X and Y that would be acquired by set, plus the unbinned left, right, top and bottom coordinates as they are shown in the Camera Setup dialog. |
| SetCameraArea set #L #R #T #B SetCameraArea set area |
Sets the acquisition area for set. Follow the set with either 4 numbers #L #R #T #B for the unbinned left, right, top, and bottom coordinates (the same kind of numbers as in the camera setup dialog) or with area set to 'F', 'H', 'Q', 'WH' or 'WQ' for full, half, quarter, wide half, or wide quarter. Values will be adjusted for a legal area. Python: The second argument, #L, is defined as a string argument, so a number must be quoted, or a numeric variable must be converted to string. |
| SetCenteredSize set #B #X #Y | Sets set for acquisition from a centered area. Follow set with 3 numbers: the binning #B, the binned size in X, and the binned size in Y. |
| SetContinuous set # | Sets the acquisition mode for set for continuous if # is non-zero, or single-frame if # is 0. |
| SetSTEMDetectors set #D [#D] [#D] ... | Sets the STEM detectors for each available channel of set. Follow set with a detector number #D for each channel, numbered from 0, or -1 to select no detector for that channel. At least one actual detector must be specified. |
| SetProcessing set #P | Sets processing for set to the given value #P, which should be 0 for unprocessed, 1 for dark-subtracted, or 2 for gain-normalized. |
| ReportReadMode set | Reports the read mode for set: 0 for linear, 1 for counting, 2 for super-resolution. |
| SetK2ReadMode set #M | Sets the processing mode for set to the given value. For a K2 or DE camera, #M should be 0 for linear, 1 for counting, or 2 for super-resolution mode. For a Falcon or K3 camera, #M would be 0 for linear or 1 for counting mode. |
| SetFrameTime set #F | Sets the frame time in set for a K2/K3, Falcon 4 where the parameter set will result in saving as EER (even just for aligning), DE, or generic frame-saving camera to the given number #F. reportedValue1 is set to the actual frame time after constraints are applied; for DE, reportedValue2 is set to the new exposure time. For a Falcon 4 where the parameter set would not result in saving as EER, or a Falcon 3, or a Falcon 2 that can save more than 7 frames, the fractions for saving in MRC files are adjusted to give a mean fraction time close to #F, and reportedValue1-3 are set with the number of fractions, mean fraction time, and exposure time. For Falcon 4, the frame time for aligning EER frames is also modified as when parameters are set for saving as EER, but not set in reportedValue1. |
| ChangeFrameAndExposure set #F | Changes the frame time and exposure time in set for a K2/K3, Falcon 4 where the parameter set will result in saving as EER (even just for aligning), DE, or generic frame-saving camera by the given factor #F, maintaining the same number of frames. reportedValue1 and reportedValue2 are set to the actual frame time and exposure time after constraints are applied. For a Falcon 4 where the parameter set would not result in saving as EER, or a Falcon 3, or a Falcon 2 that can save more than 7 frames, the exposure time is adjusted by the given amount, as closely as possible, and fractions for saving in MRC files are adjusted to change the mean fraction time by #F; reportedValue1-3 are set with the number of fractions, mean fraction time, and exposure time. For Falcon 4, the frame time for aligning EER frames is also modified as when parameters are set for saving as EER, but not set in reportedValue1. |
| ReportCurrentPixelSize set | Reports the pixel size for images that would be acquired by set (i.e., with its binning) under the current conditions, namely at the current magnification if outside Low Dose mode, or at the magnification of the corresponding area in Low Dose mode. |
| SetDoseFracParams set #D [#S] [#A] [#M] [#C] | Sets dose fractionation parameters for set; follow with up to 5 numbers: #D non-zero for dose-fractionation mode on K2/K3; #S non-zero to save frames (not just for K2/K3); #A non-zero to align frames; #M 0 to align in DM, 1 to align in plugin, or 2 to save a command file for alignframes; #C non-zero to combine frames into sums. |
| RestoreCameraSet [set] | Restores one or all camera parameter set(s) modified with the 'Set' commands above. If set is omitted, all modified sets will be restored. |
| KeepCameraSetChanges [set] | Retains changes in one or all modified camera parameter sets when script ends. Use this after making all the changes with the 'Set' commands that you wish to retain. If set is omitted, all modified sets will be retained. 'RestoreCameraSet' cannot be used on a set that has been retained. Subsequent changes by the 'Set' commands will be restored on script end or by 'RestoreCameraSet', unless this command is given again. |
| Continuous Mode Control | |
| StopContinuous | Stops continuous acquisition if it is running. |
| ReportContinuous | Returns -1 if continuous acquisition is not running, or the camera parameter set number being used if it is running, numbered from 0. |
| UseContinuousFrames # | If # is non-zero, the script keeps executing commands (such as stage movement and alignment) even when the camera is acquiring in continuous mode. Use 0 to return to normal operation, in which the script will wait for continuous acquisition to be ended by the user. |
| WaitForNextFrame [#S] [#A] | After starting a continuous acquisition, this command waits until the next image becomes available in buffer A. The program will wait until the exposure time has elapsed so that the image is likely to be taken after completion of previous operations, unless the command 'StartFrameWaitTime -1' is used first. For the next script command, the image will be available in buffers A and B, but for commands after that, buffer B should be accessed instead because the copy in A may be overwritten with a new continuous frame by then. The 'UseContinuousFrames 1' command must be used before the acquisition is started. If the optional #S is given, that number of frames will be aligned with the Framealign module and summed, or averaged if the optional #A is non-zero. Use averaging if the sum may exceed 32767 (for signed images) or 65535. Essential frame alignment parameters are controlled by several properties; the default is for alignment to a cumulative sum, which is somewhat faster than pairwise alignments and should be adequate for high-contrast frames. |
| StartFrameWaitTimer [#] | With no optional value #, sets the time from which the next 'WaitForNextFrame' will require an exposure time to elapse. Without this command, the program will wait the full exposure time after the 'WaitNextFrameCommand'. If this command is given with no value just after getting a frame, and operations are done before waiting for the next frame, the next frame may be obtained sooner. However, if the command is followed by a negative value, then the program will not wait for the exposure time to elapse but just return the next distinct frame. Use this command with # set to -1 before WaitForNextFrame to get every successive frame if possible, such as after starting a continuous tilt. |
| SetLiveSettleFraction # | Sets the fraction of the usual settling time to apply in continuous mode after image shift or stage movement. By default, no settling is applied in continuous mode (i.e., the fraction is 0), but some settling may be needed when a script or other operation is using continuous frames. The fraction is reset to zero when continuous mode ends. |
| Frame Saving and Alignment | |
| ReportNumFramesSaved | Reports the number of frames saved, or being saved, in the last acquisition that saved frames. |
| ReportFrameAliParams | Reports six values for the frame alignment parameter set selected to be used for Record images: the binning or target size for alignment, whether to keep precision for gain-normalized images when doing early returns or GPU frame alignment, the strategy (0 to 3, corresponding to the radio buttons in the Frame Alignment dialog), the number of frames to align all pairs among, the number of iterations to refine (negative if refinement off), and the group size (negative if using groups is off). |
| SetFrameAliParams #B [#K] [#S] [#A] [#R] [#G] | In the frame alignment parameter set selected to be used for Record images, sets the binning to #B if #B is 1-16 or the target size to #B otherwise, and optionally sets whether to keep precision during early returns or GPU frame alignment if #K is 1, the strategy from #S (0, 1, or 2 for pairwise alignment using specified, half, or all frames; 3 for cumulative alignment), the number of frames for all pairs from #A, the number of refinement iterations from the absolute value of #R and to do refinement if #R is positive, and the group size from absolute value of #G and the whether to use groups if #G is positive. |
| ReportFrameAli2 | Reports more values for frame alignment: whether GPU use is selected, and for the Record parameter set: truncation limit (negative if truncation is off), whether to use hybrid shifts, and the three filter radii. |
| SetFrameAli2 #G [#T] [#H] [#R1] [#R2] [#R3] | Sets whether to use GPU for frame alignment (#G 0 or 1) and, in the frame alignment parameters for Record, optionally sets truncation limit from the absolute value of #T and to truncate if #T is positive, whether to use hybrid shifts if #H is 1, primary filter radius from #R1, and second and third filter radii from #R2 and #R3 or 0 for either if #R1 is present and #R2 or #R3 is not. |
| SkipFrameAliParamCheck [#] | Disables the checking of whether the selected frame alignment parameter set fits the constraints for use selected in the Frame Alignment dialog. This can be used when modifying frame alignment parameters or Record parameters to avoid an annoying message before every shot. The optional value of 0 can be supplied to re-enable the checking. |
| EarlyReturnNextShot #N [#D] [#S] | Returns as early as possible from the next acquisition, which must involve either aligning or saving dose-fractionation frames from a K2/K3 camera. Follow with the number of frames #N to be summed in the returned image, 0 to return without any summed image, -1 to return with the full sum, or -9 to return immediately after starting the acquisition, without waiting for the exposure to end. The optional #D should be 1 to make a deferred full sum when not aligning in the plugin; this sum is always made when aligning in the plugin for an ordinary acquisition. If the optional #S is non-zero, the plugin will not stack frames, which is done by default in order to allow another single-shot image to be taken as soon as possible; this stacking takes extra time and delays the ability to take another dose-fractionation image. However, stacking is always done, and #S thus has no effect, if the property 'EarlyReturnUseSaveThread' is set. Single-shot and dose-fractionation images can be requested without delay in the script. The single-shot images will be taken as soon as possible (after the frame stack has been accessed), do not enter #S if the next image will be a single-shot. Another dose-fractionation shot will be delayed until saving is finished for the current shot, so do use #S when doing a series of frame-saving shots. When a frame tilt series is to be taken, a non-zero value of #D triggers the making of separate deferred sums for each tilt angle. In this case, the Record parameters can specify just saving, just aligning, or both operations. |
| GetDeferredSum | Acquires the deferred full sum that was saved as a result of 'EarlyReturnNextShot', or the next deferred tilt sum available from a frame tilt series. |
| SetFolderForFrames dir | Sets the folder for saving frames from the current camera to dir. A simple directory name without path separators is required for DE cameras and Thermo/FEI cameras run with Advanced Scripting. For other cameras, an absolute path is required, either a network path starting with two slashes or one starting with a drive letter. |
| FrameThresholdNextShot #T [#S] [#E] [#D] | Skips saving frames whose mean value is below the given threshold #T in the next shot from a K2/K3 camera. The mean value used for comparison with the threshold will be the value that the frame would have after saving, thus a scaled electron count value when taking normalized frames or actual electron counts otherwise (even if aligning also). The first and last frame will be saved regardless. The plugin will write a list of frames actually saved, numbered from 0, named as the root of the frame stack name and '_saved.txt'. The SEMCCD plugin must be dated 12/18/19 or later. If a command file is being saved for aligning in IMOD, and this command includes the optional #S and #E, these values will be used for the entry to the PartialFrameThreshold option to Alignframes, which takes thresholds for skipping the frames at the start and end of a tilt. These relative thresholds are between 0 and 1, where 0 sets no threshold. If #E is omitted, #S will be used for both values. If the optional #D is added, the frame threshold will be adjusted dynamically on each tilt angle after the first to this fraction of the mean or median value of the frames above threshold on the nearest previous tilt angle. |
| QueueFrameTiltSeries #S #I #N [#D] [#O] [#W] [#F] [#X #Y] | Sets up a tilt series with discrete tilts and other uniform changes to occur during the next shot, provided frames are saved. Follow with starting angle (#S), increment (#I) and number of tilt steps (#N), plus optional entries #D for the initial delay before starting the starts, #O for the time the beam should be unblanked, #W for time to wait between tilting and unblanking, #F for a change in focus per step, #X and #Y for a change in image shift values for each step. Image shift values are in microns in 'specimen' coordinates, i.e. with the X axis along the tilt axis, and they will be converted to image shift units at the Record magnification if in Low Dose mode, or at the current magnification if not. All times are in seconds. A frame stack mdoc file with tilt angle and dose information is written by the SEMCCD plugin regardless of whether the option for one is turned on. |
| FrameSeriesFromVar var #F [#D] [#P] | Sets up a tilt series with all steps specified in the given array variable var, which should contain 1 to 6 values per step of the series, with the values for one step followed by those for the next step, etc. #F is the sum of 1 if there are tilt angles, 2 if there are shutter open times, 4 if there are wait times or intervals between steps, 8 if there are changes in defocus from the current value, 16 if there are image shift changes from the current value, and 32 if there are beam shift changes from the current value. For image shift, there should be values for X and Y in microns in 'specimen' coordinates, i.e. with the X axis along the tilt axis. The shifts will be converted to image shift units at the Record magnification if in Low Dose mode, or at the current magnification if not. For beam shift, the values would be the changes in raw X and Y beam shift units. The values must be present in the order just listed. If there are tilt angles, then the third possible value in the array, wait times or intervals, is a delay between the end of the tilt and the opening of the shutter, if any. If there are no tilt angles because continuous tilt is being used, then this item sets the total interval between steps of the series. In this continuous tilt case, and when there are shutter times, the optional #P sets a post-image shift delay before opening the shutter. #D is an optional initial delay before the first step. All times are in seconds. If there are discrete tilts, a frame stack mdoc file with tilt angle and dose information is written. |
| SetFrameSeriesParams #B [#S] [#X #Y] [#G] [#D] | Sets optional parameters for frame tilt series. Set #B non-zero to use backlash for all tilt steps not in the same direction as the first one, 0 otherwise. Set optional entries: #S with a tilting speed factor or 0 for normal speed; #X and #Y for X and Y stage coordinates to restore after the tilt, or values greater than 9000 for no stage restoration if further entries follow; #G for the minimum gap between frames above threshold for recognizing a new tilt angle when specifying a dynamic threshold with 'FrameThresholdNextShot' or getting back deferred tilt sums with 'EarlyReturnNextShot'; and #D for the number of initial frames to drop when getting simple deferred tilt sums. The default gap size is 2 frames below threshold and this value should be entered when dropping frames unless a different gap is desired. The default is not to drop any frames from simple sums; frames are never dropped when getting aligned sums. For CryoARM, speed factors of 100 - 105 will select pre-set speeds of 10, 2, 1, 0.5, 0.25, and 0.1 degrees/sec. If setting a speed factor crashes SerialEM or FEI-SEMserver, see notes under TiltDuringRecord. |
| WriteFrameSeriesAngles file | Writes the actual tilt angles from the last frame tilt series to the given file, one per line. |
| ReportFrameTiltSum | Reports: 0 if there is a tilt sum or 1 of there is not, the tilt angle or 0 if there is no tilt sum, the tilt index (numbered from 0), the number of frames in the sum, and the starting and ending frame number after getting a deferred tilt sum from a frame tilt series. |
| ModifyFrameTSShifts #I #X #Y | Changes the image shift values to be imposed for each future step in the same tilt direction after aligning a deferred sum from a frame tilt series to the one at the adjacent previous tilt angle. #I specifies the tilt index obtained from 'ReportTiltSumProperties', and #X and #Y are relative image shift values needed to align this tilt sum with the previous one with a command such as 'AlignTo B 1' that aligns without imposing an image shift. There are two ways to get these values: 1) Use 'ReportISforBufferShift' then 'ClearAlignment 1' to remove the alignment shifts from the image each time, and use the values from 'ReportISforBufferShift' directly; or 2) Keep track of the last IS values from 'ReportISforBufferShift', subtract them each time from the new IS values, and use those differences for #X and #Y. |
| ReplaceFrameTSShifts varX varY | Changes the entire array of image shift values to be imposed in a frame tilt series with a new set of values (i.e., refined predictions) in the two array variables given by varX and varY. As of SerialEM 3.8.8, these shifts should be in 'specimen' coordinates just like the original shifts. Both arrays must have the same size as the original number of tilt angles. Untested |
| ReplaceFrameTSFocus var | Changes the entire array of focus values to be imposed in a frame tilt series with a new set of values (i.e., refined predictions) in the array variable var,which must have the same size as the original number of tilt angles. Untested. |
| AlignWholeTSOnly [#] | Allows a whole tilt series taken from a K2/K3, Falcon, or DE camera through the script to be aligned with one command file in IMOD, just as when using the tilt series controller. Specifically, no command files will be written for individual Record images taken after the command is given, and a single command file to align all frame stacks in the series is written at the end with the 'WriteComForTSAlign' command. The command has no effect unless frame alignment in IMOD is selected in the Record parameter set and 'Align only whole tilt series' is selected in the Frame Alignment Parameters dialog. If these conditions are satisfied, there must already be a current image file with an associated .mdoc file. The optional # can be 0 to turn this mode of operation off. Sets reportedValue1 to 1 or 0 depending on whether this operating mode was switched to or not. |
| Hardware Specific Camera Commands | |
| ReportK2FileParams | Reports values selected in the Frame File Options dialog: 0 for MRC, 1 for TIFF LZW, or 2 for TIFF ZIP; sum of 1 to pack unnormalized data at all, plus 2 to pack counting mode to bytes; 1 to save MRC files in 4-bit mode 101; 1 to save normalized data times 100; 1 to skip rotation and flip of frames; 1 for one file per frame. |
| SetK2FileParams #T [#P] [#M] [#N] [#R] [#O] | Sets values to control K2/K3 frame file saving. Follow with up to 6 values: #T 0 for MRC, 1 for TIFF LZW, or 2 for TIFF ZIP; #P as the sum of 1 to pack unnormalized data at all, plus 2 to pack counting mode to bytes; #M non-zero to save MRC files in 4-bit mode 101; #N non-zero to save normalized data times 100; #R non-zero to skip rotation and flip of frames; #O non-zero for one file per frame. |
| ReportK3CDSmode | Reports 1 if CDS mode is on for a K3 camera acquisitions, 0 if not. |
| SetK3CDSmode #O [#P] | Sets the CDS mode option for K3 camera acquisitions on if #O is non-zero, off otherwise. The existing value is restored at the end of the script unless #P as entered with a non-zero value to make it permanent. |
| DeferStackingNextShot | Disables stacking Falcon intermediate frames after the next exposure. To stack frames from multiple exposures into one stack, use this command before each exposure except the last one. |
| OpenDECameraCover | Opens the protection cover of the Direct Electron camera for the remainder of the script, if it is the current camera. Without this command, the cover will be opened and closed for each exposure except during tasks. |
| SetDECamFrameRate # | Sets the frame rate of the current camera if it is a DE camera; follow with the new rate in frames per second, which must be positive and less than the maximum frame rate. The user's original frame rate is placed into reportedValue1 and is restored when the script ends. |
| NewDEserverDarkRef #P #H | Acquires a dark reference in the DE server if the known interval since the last reference for processing mode #P is longer than #H in hours. #P must be 0 for linear mode, 1 for counting mode, or -1 for the mode selected in the current Record parameters. Parameters for the reference are those specified in the Direct Electron Server Reference Maker Dialog for the given mode, except that with -1, the hardware binning and ROI will be those in the Current Record parameters. If #H is 0, the reference is done unconditionally; if #H is negative (-1), the command simply records the current time as the time of the last reference. |
| UpdateHWDarkRef # | Updates the K2 hardware dark reference if the known interval since the last update is longer than # in hours. If # is 0, the update is done unconditionally; if # is negative (-1), it simply records the current time as the time of the last update. In order for the time interval to be kept track of between runs of the program, the property IgnoreShortTermCals must not be set. This command is available on a K3 with GMS 3.31 or higher. |
| Other Camera Commands | |
| OppositeFocus | In low dose mode, acquires Focus image from area on opposite side of Record from the defined Focus area. Opposite areas are not available if Balance Shifts is turned on. |
| OppositeTrial | In low dose mode, acquires Trial image from area on opposite side of Record from the defined Trial area. |
| AcquireToMatchBuffer buf | Acquires an image whose size matches that of the image in the given buffer, with camera parameters matching those used to acquire that image. The image will be cropped after acquisition if necessary. The camera parameters will be based on the parameter set used for buffer's image, with the exposure time and binning taken from values stored in the buffer. In Low Dose mode, the image will be acquire from the corresponding Low Dose area. |
| StepFocusNextShot # # [# #] | Does one or two focus changes during the next exposure. Follow with 2 or 4 numbers: the time in seconds from start of the exposure to the first focus change, the first focus change in microns, the time from start of the exposure to the second focus change if any, and the second focus change relative to the starting focus, not relative to the focus after the first change. The command will have no effect if the exposure time is less than the time to the first change, and the second change will not be done if the time for it is greater than the exposure time. This command is enabled for Gatan, Falcon, and Tietz cameras. |
| SmoothFocusNextShot # # | Changes focus linearly through next exposure. Follow with 2 numbers, the starting and ending defocus relative to the current focus. This command is enabled for Gatan, Falcon, and Tietz cameras. |
| RecordAndTiltUp [#R] [#X #Y] | Starts a Record acquisition and tilts the stage up by the current increment after the exposure is expected to be done. Post-exposure actions must be allowed for the current camera, at least for current Record parameters, but need not be not enabled by the user in the Camera menu. If optional #R is non-zero, then the program will restore the stage X and Y positions after tilting, either to the position before starting or to #X, #Y if they are entered. |
| RecordAndTiltDown [#R] [#X #Y] | Like 'RecordAndTiltUp', but tilts the stage down by the current increment. |
| RecordAndTiltTo #T [#B] [#R] [#X #Y] | Like 'RecordAndTiltUp', but tilts the stage to the given angle #T. If an optional non-zero backlash is entered in #B, the stage will tilt first to #T +/- #B, then back to #T. Prior to 5/23/19, #T + #B was used and the sign of #B had to be set to correct the backlash for the desired direction; after then, the program sets the sign properly and a positive value can always be entered. |
| TiltDuringRecord #A #D [#S] | Starts a Record acquisition and starts the stage tilting to angle #A after the delay #D in milliseconds. On Thermo/FEI scopes with recent enough versions of Thermo/FEI scripting, or JEOL scopes with recent versions of TemExt.dll, #S can be added with a speed multiplier (< 1 for slower, > 1 for faster). For CryoARM, speed factors of 100 - 105 will select pre-set speeds of 10, 2, 1, 0.5, 0.25, and 0.1 degrees/sec. On Hitachi scopes, the speed factor is relative to the tilt speed that can be set with the property HitachiTiltSpeed. With the default of speed of 100, the factor can range from 0.4 to 1.27, and the tilt speed in degrees per second is approximately 1.65 times the factor to the 1.85 power. On Thermo/FEI scopes this command will freeze the user interface and prevent scope updates while the stage is tilting. If the command crashes SerialEM or FEI-SEMserver with a speed multiplier but runs OK without one, it means that the Thermo/FEI scripting version is too old to support the speed command. In that case, define an environment variable SEM_USE_TOMMONIKER with the value of 1 on the microscope computer to use an alternate interface. |
| SetDoseAdjustmentFactor # | Sets a factor for adjusting the exposure dose and frame doses stored in an .mdoc file for an image. Set to 0 to eliminate the adjustment; the factor will be reset to 0 when the script ends. |
| RunGatanScript var [#T] | Run a script in DigitalMicrograph contained in an array of strings in variable var, with an optional timeout in seconds specified in #T. The Exit value from the script is placed in reportedValue1. This operation is run on a separate thread like other camera operations. If there is no timeout, the STOP button will stop the script by killing its thread; if there is a timeout, STOP will not kill the script, similar to image acquisitions. The array can be created with the 'ReadStringsFromFile' command, or array of up to ~55 quoted strings can be defined in one statement, or a longer script can be stored in an array one line at time with 'AppendToArray'. In the latter two cases, you will need to use the 'ParseQuotedStrings' command and enclose each line of the DM script in single quotes. |
| GetSTEMBrightContrast name | Reports the brightness and contrast for the STEM detector with the given name, where this is the name in the user interface (the 'ChannelName', not the 'DetectorName', in SerialEMproperties.txt.) This command only works for Thermo/FEI STEM, and STEM must be the currently selected camera. Command added in 4.1, 10-Jan-23. |
| SetSTEMBrightContrast #B #C name | Sets the brightness to #B and the contrast to #C for the STEM detector with the given name; use '-1.e9' for a value to leave it unchanged and just set the other value. This command only works for Thermo/FEI STEM, and STEM must be the currently selected camera. Command added in 4.1, 10-Jan-23. |
| SetupDynamicFocus #E #X #Y #B | Sets up dynamic focus to be run through FocusRamper on a Thermo/FEI scope during an externally run STEM acquisition, with exposure time #E, size of resulting image #X by #Y pixels, and binning #B. Sets reportedValue1-4 with the parameters to be sent to FocusRamper: initial delay, total time of ramp in msec, interval between focus steps in msec (based on property 'DynamicFocusInterval'), and index in the focus ramp table per msec. If no ramp can be set up, sets only reportedValue1 to -1. Values can be assigned to variables at end of command. Command added in 4.2, 24-May-24. |
| StartFocusRamper [#D] [#T] [#S] [#I] | Starts the FocusRamper with the parameters determined by 'SetupDynamicFocus', optionally modifiable with entries of #D for initial delay, #T for total time, #S for step interval (all in msec), and #I for index in the focus ramp table per msec. Before returning, this command also sets the starting defocus of the ramp with backlash and a delay set by property 'InitialDynamicFocusDelay'. The FocusRamper object must already have been created by taking at least one STEM image through SerialEM with dynamic focus. Command added in 4.2, 24-May-24. |
| FinishFocusRamp | Makes sure the FocusRamper has finished and kills the thread if necesssary after a 3 second timeout, collects statistics that can be output with Debug Output set to 1, and restores focus to the initial value. Command added in 4.2, 24-May-24. |
| SetRedoMontageXCorrs # | Turns the option in the Camera - Correlation Filter submenu to redo montage cross-correlations instead of using previous ones from the .mdoc file on or off if # is non-zero or zero, respectively. Command added in 4.1, 02-Mar-23 |
In all commands including a buffer to operate on, the buffer can be specified with either the buffer letter or the corresponding number, where A corresponds to 1.
| Buffer and Image Commands | |
| Copy buf1 buf2 | Copies from buf1 to buf2 (e.g., Copy C A), where buf1 can be in the FFT window. |
| Show buf | Displays the given buffer (e.g., Show C) |
| ReportCurrentBuffer | Returns the letter of the buffer currently open in the main window in reportedValue1 and 0 or 1 in reportedValue2 indicating if the buffer contains an image or not. FFT windows or image windows other than the main window are ignored. |
| ReportActiveViewTitle | Reports the title of the currently active window (view), which is "Main Window" for the main window. |
| SetActiveViewByTitle name | Makes the window whose title matches name the active window, which is useful for making sure that a snapshot is of the intended window. Sets reportedValue1 to 0 if a window is found with that title, 1 if not. |
| SetBufZoomAndCenter buf #Z [#X #Y] | Displays the buffer buf, sets its zoom to #Z, and optionally centers the display on image coordinate #X, #Y, or as close as possible to that point. Enter -1 for #X or #Y to center the image in that dimension. Command added in 4.2, 18-Sep-24. |
| AddBufToStackWindow buf #M #S [#B] [#O] [title] | Adds the image in buffer buf to the secondary stack window, opening it if needed. Set #M the the maximum size of the reduced image, or 0 to not reduce the image. Set #S to an arbitrary "section number" that is greater than equal to 0 to have a unique image in the stack with that number (i.e, an existing image with the same number will be replaced), -1 to simply add the image, or -2 or less to add the image and replace an existing image at index (-#B - 2) in the stack, numbered from 0 (e.g., -3 will replace the image at index 1). Set optional #B non-zero to convert the image to bytes, and #O to 1 or -1 to maintain the stack in order or reverse order by tilt angle. The rest of the text on the line is an optional window title, replacing the default title 'Script Stack'. Command added in 4.2, 18-Sep-24. |
| CloseStackWindow | Closes the stack window if it is open. Command added in 4.2, 18-Sep-24. |
| ImageProperties [buf] | Reports size in X and Y, binning, exposure, pixel size, and parameter set used for the image in buffer A or in the buffer indicated by buf, which can be in the FFT window. It also sets the variable imageTickTime with the time that the image finished being acquired, in seconds since the program started. Values can be assigned to variables after the buffer letter. Command added in 4.1, 1-Apr-22. |
| ImageMarkerPosition buf | Reports the coordinates of the green marker point in the image in buffer buf, where buf can be 0 or -1 to select the active image buffer. Reports -1, -1 if there is no marker point set. Values can be assigned to variables after the buffer letter. Command added in 4.1, 31-Oct-22. |
| ImageConditions buf | Reports the electron dose and the magnification for the image in buffer buf; other items will be added upon request. |
| ImageMetadataToVar buf var | For the image in buffer buf, saves the metadata text that would be output to an '.mdoc' file into the variable var, which will contain an array of strings. buf may be in the FFT window. The section header in the first line will be '[ImageMetadata = #]', where '#' is the buffer number (positive for a regular buffer and negative for an FFT buffer). |
| ReportMetadataValues buf key | Reports the values that would occur for the given key in an .mdoc file if the image in buf were saved to file. The value string will be broken into individual strings at the spaces and assigned to up to reportedValues as well as to variables at the end of the command. Command added in 4.1, 13-Apr-23. |
| ReportMetadataString buf key | Like 'ReportMetadataValues', but simply assigns to the value string to reportedValue1 and, optionally, to an optional variable an the end of the command. If the string is a set of numbers, it can then be assigned to an array variable. Command added in 4.1, 13-Apr-23. |
| ImageLowDoseSet [buf] | Reports the parameter set that an image was taken with and whether it was taken in Low Dose mode, for the image in buffer A or in the buffer indicated by buf. For one of the 5 standard parameter sets, it will report the set name. For a montage image, it will report Record. For a tracking image, it will report View if the mag matches that of View in Low Dose; if the mag matches Record in Low Dose, it will report Record or Preview depending on which has an closest exposure time closest to that of the image. Values can be assigned to variables after a buffer letter/number. |
| ReportMeanCounts [buf] [#] | Reports the mean counts of the A buffer, or of the buffer indicated by buf; add a 1 as # to get unbinned counts per second instead, or add a 2 as # to get a report of mean, standard deviation, minimum and maximum. No optional assignment to variables. |
| ElectronStats [buf] | Reports the min, max, mean, and SD of the A buffer, or of the buffer indicated by buf, scaled to electrons, and also reports the electrons per unbinned pixel per second. The camera must have a defined counts per electron. Values recorded in electron counting mode will be linearized if possible (corrected for decreasing counting efficiency at higher dose rates). Values can be assigned to variables after a buffer letter/number. |
| RawElectronStats [buf] | Reports the same items as 'ElectronStats' without linearizing them for loss in counting mode. Values can be assigned to variables after a buffer letter/number. |
| CalibrateElectronDose | Calibrates electron dose with the image in buffer A without popping up any message boxes, but generates an error if any of the preconditions for calibrating dose are not met. |
| SubareaMean #X0 #X1 #Y0 #Y1 | Reports the mean counts in a subarea of the A buffer from #X0 to #X1 in X and from #Y0 to #Y1 in Y. Coordinates are numbered from 0 to size - 1 in each dimension and 0 in Y is at the top. Value can be assigned to variable at end of command. |
| CircularSubareaMean #X #Y #R | Reports the mean counts in a circular subarea of the A buffer defined by center point #X,#Y and radius #R. Value can be assigned to variable at end of command. |
| QuadrantMeans [#N] [#F1] [#F2] | Reports means of strips along quadrant boundaries. Optional entries are #N for the number of pixels between strip and boundary (default 2), #F1 for the strip width as a fraction of quadrant extent (default 0.1), and #F2 for the fraction of quadrant extent to trim off the length of the strip (default 0.1). Output is labeled by quadrant number (1 to 4) and 'h' for horizontal strips or 'v' for vertical strips. |
| ReportPercentileStats buf #P #M #R #S | Computes the intensity values in square patches of size #S pixels in buffer buf at low and high percentile levels given by #P and 100. - #P. Reports the mean values of the low and high percentile intensities, the fraction of midpoints between those intensities exceeding #M, and the fraction of intensity ranges exceeding #R. For 1% limits and patches of ~50-100 pixels, and values of #M and #R around 0.33 and 0.45 of the maximum intensity, these fractions will reflect what fraction of the image is unusably dark. Command added in 4.2, 24-May-24. |
| StageToBufImageMatrix buf #I | For the image in buffer buf>, reports the transformation from stage to image
coordinates: the 6 elements XperX, XperY. YperX, YperY delX, delY, where the transformation is Ximage = Xstage * XperX + Ystage * XperY + delX Yimage = Xstage * YperX + Ystage * YperY + delY Set #I 0 for delX and delY values that work with Navigator stage coordinates, which are potentially adjusted to be magnification-independent, or non-zero for values that wrork with an actual stage coordinate that applies at the current magnification and image shift. Image Y is inverted: the origin for the image coordinates is at the top of the image. Values can be assigned to variables at end of command. This and the following 3 commands were fixed on 24-Oct-24 to work with Navigator coordinates when #I is 0 and modified for #I non-zero to treat raw coordinates in a way that is probably correct but may not be useful. Command added in 4.1, 16-Jun-23. |
| BufImageToStageMatrix buf #I | Like 'StageToBufImageMatrix', but reports the 6-element transformation from image to stage coordinates. Values can be assigned to variables at end of command. Command added in 4.1, 16-Jun-23, modified 24-Oct-24. |
| BufImagePosToStagePos buf #I #X #Y | Reports the stage position (X and Y) corresponding to the position #X, #Y in the image in buffer buf. Image coordinates are inverted in Y. If the image is a montage, it also reports the piece the point is in and the coordinates within the piece, defined the same as the PieceOn and XYinPc entries in a Navigator file; otherwise -1 is reported for each. Set #I 0 for potentially magnification-independent Navigator stage coordinates, or non-zero for a stage coordinate valid at the current microscope magnification and image shift. In either case, if the image is a stage montage overview, the offsets of pieces are taken into account in computing the position, making this result different from what could be computed with the matrix from 'StageToBufImageMatrix'. Values can be assigned to variables at end of command. Command added in 4.1, 16-Jun-23, modified 24-Oct-24. |
| StagePosToBufImagePos buf #I #X #Y | Like 'BufImagePosToStagePos', but reports the image position (X and Y) in the image in buffer buf of the stage position #X, #Y. These image coordinates are left-handed; i.e., Y is inverted. Set #I for Navigator stage coordinates, or non-zero for actual stage coordinates that apply at the current magnification and image shift. The resulting coordinates account for montage piece alignments as in 'BufImagePosToStagePos' and just as occurs when drawing Navigator points on an image. If the image is a montage overview, it also reports the index of the montage position and the position within that piece (X and Y) in right-handed coordinates, with 0 in Y at the bottom of each piece (see PieceOn and XYinPC in Navigator Files). Values can be assigned to variables at end of command. Command added in 4.1, 16-Jun-23, modified 24-Oct-24. |
| Image Processing Commands | |
| CropImage buf #X0 #X1 #Y0 #Y1 | Crops out a subarea of the given buffer, which can be in the FFT window, from #X0 to #X1 in X and from #Y0 to #Y1 in Y (inclusive). The size in X is rounded down to be even if necessary. Coordinates are numbered from 0 to size - 1 in each dimension and 0 in Y is at the top. |
| CropCenterToSize buf #X #Y | Crops out a centered subarea of size #X by #Y from the given buffer, which can be in the FFT window. |
| ReduceImage buf # | Reduces the image in the given buffer by the factor #, which must be greater than 1 but need not be an integer. buf may be in the FFT window. Antialiased reduction (with a Lanczos 2 filter) is used instead of binning. |
| Rotate90CW buf | Rotates the image in the given buffer by 90 degrees clockwise. The result is placed into buffer A. |
| Rotate90CCW buf | Rotates the image in the given buffer by 90 degrees counterclockwise. The result is placed into buffer A. |
| FFT buf [#B] | Takes the FFT of the image in the given buffer, optionally applying the binning given in #B. The FFT will appear in buffer A, or in the side-by-side FFT window if that option is on. |
| FilterImage buf sig1 rad1 rad2 sig2 [obuf] | Applies a filter in Fourier space to the image in the given buffer, which can be in the FFT window. The filter is the product of two separate filters, one controlled by sig1 (sigma1) and the other by rad2 (radius2) and sig2 (sigma2). Sigma1 provides low-frequency filtering with an inverted Gaussian rising from 0 to 1 with that sigma, and starting at either 0 frequency or the frequency specified by |rad1| (radius1) if it is negative. Radius2 and sigma2 provide high-frequency filtering with a Gaussian that falls past radius2 with that sigma. If radius1 is positive, a Gaussian with the same sigma falls off to the left of radius1. If sigma1 is negative, it provides a band-pass filter peaking at 1.414 * |sigma1|. See Filterplot in IMOD for a complete description and ability to graph any filter. The units are reciprocal pixels (0 to 0.5 along an axis). The floating point output is placed into buffer A, and top buffers are rolled, unless the optional obuf is added specifying a different buffer, which can be buf. |
| AddImages buf1 buf2 [obuf] | Adds the two images in buffers buf1 and buf2 The floating point output is placed into buffer A, and top buffers are rolled, unless the optional obuf is added specifying a different buffer, which can be buf1 or buf2. |
| SubtractImages buf1 buf2 [obuf] | Like 'AddImages', except that buf2 is subtracted from buf1. |
| MultiplyImages buf1 buf2 [obuf] | Like 'AddImages', except that buf2 is multiplied by buf1 |
| DivideImages buf1 buf2 [obuf] | Like 'AddImages', except that buf1 is divided by buf2, with 0 in the output at pixels where buf2 is zero. |
| ScaleImage buf #S #A [obuf] [#K] | Scales the image in buffer buf by multiplying by #S then adding #A. buf may be in the FFT window. The output is placed into buffer A, and top buffers are rolled, unless the optional obuf is added specifying a different buffer, which can be buf unless that is in the FFT window. The resulting image is floating point unless the optional #K is non-zero to keep the existing image type. |
| TransformToMatchBuffer buf1 buf2 [obuf] [#CX] [#CY] [#XS] [#YS] | Scales and rotates the image in buffer buf1 to match the pixel size of the image in buf2 Enter an optional buffer obuf to place the result in, or -1 for the default (A). Enter optional #CX and #CY to set the center of the operation, or -1 and -1 for the default, the center of the image. Enter #XS and #YS to set the size of the transformed image, or -1 to use the default size in a dimension, which is the full scaled down size when scaling down, or the size of a camera frame for the other buffer. Command added in 4.2, 19-Jan-24. |
| TransformToOtherMag buf #M [obuf] [#CX] {#CY] [#XS] [#YS] [#B] [#C] | Scales and rotates the image in buffer buf to match the pixel size at magnification index #M. This command is similar to 'TransformtoMatchBuffer' except that the binning and camera to match are optionally specified with #B and #C (-1 for the same as the image in buf. Command added in 4.2, 19-Jan-24. |
| ComputeIceThickness buf1 buf2 [obuf] [#C] | Computes an ice thickness image from an unfiltered image (U) in buf1 and an energy-filtered image (F) in buf2, using the equation C * ln( U / F ). The coefficient is taken from the property 'ThicknessCoefficient', or from the optional entry [#C], but it must be available one way or the other. The floating point output is placed into buffer A, and top buffers are rolled, unless the optional obuf is added specifying a different buffer, which can be buf1 or buf2. A shift between the images is taken into account, with non-overlapping areas filled with 0; thus, images can be aligned with each other. Command added in 4.1, 26-Oct-22. |
| ConvertToBytes buf [#L #H] | Converts the image in buffer buf from float or integer to bytes, applying the scaling in the current display by default, with values between the 'Black' and 'White' levels scaled from 0 to 255, values less than 'Black' truncated at 0, and values above 'White' truncated at 255. The optional #L and #H can be used to specify the scaling, with #L mapped to 0 and #H mapped to 255. buf may be in the FFT window. |
| PasteImagesTogether buf1 buf2 buf3 [#V] | Creates a byte image in buffer buf3 with the image in buf1 on the left and the image in buffer buf2 on the right, or with buf1 on the top and buf2 on the bottom if the optional #V is nonzero. buf1 and buf2 may be in the FFT window but buf3 may not. Scaling to bytes is based on the Black and White limits in the current display; if you want a different scaling, use 'ConvertToBytes' first. |
| ScaledSpectrum buf #S | Takes the FFT of the image in buffer buf after padding it to be square, reduces it with antialiasing to the size given by #S, and scales it to bytes using the standard FFT scaling specifications set with Set Truncation in the Image Display control panel. #S must be no larger than the biggest dimension of the image, but can be 0 to specify no reduction. The result is placed into buffer A. |
| SpectrumBesideImage buf #Y | Produces a byte image in buffer A with the image in buf on the left, reduced to #Y in height, and the scaled spectrum of the image on the right.#Y must be no larger the biggest dimension of the image, but can be 0 to specify no reduction. The reduced image ends up in buffer B and the original image in A ends up in C. |
| CheckForBadStripe [buf] [#H] | Checks for sharp transitions between columns or rows in an image and for whether they occur at expected positions for a bad channel of data from a K2 or K3 camera. Analyzes the image in buffer A, or the buffer indicated by buf. It uses the RotationAndFlip property of the camera, if it can be identified, to determine if vertical or horizontal stripes should be sought, unless the option #H is entered with 1 for horizontal or 0 for vertical stripes. Reports the number of significant transitions found and the number of those that are within a few pixels of the expected boundaries between channels for a K2 or K3 camera. Multiple significant transitions near the same boundary are counted as a single transition. If there is just one transition and it occurs at the first or last expected boundary, the second value is returned as -1. The second value would be a more reliable number to use if there are uncorrected line defects or a risk of very straight grid bars in the field. The appropriate test would be for a value either greater than 1 or less than 0. |
| CtfFind buf #M #N [#F] [#B] [#P0] [#P9] [#S] [#A] | Determines defocus and astigmatism by fitting to Thon rings in an FFT of the
image in the given buffer. Follow the buffer letter/number with the minimum (#M) and
maximum (#N) defocus for the search (in microns, underfocus negative), and with these
optional entries:
#F non-zero to do a 1-D initial search instead of a slower 2D one #B between 128 and 640 to set the box size for the amplitude spectrum to analyze, or zero to use the default (256) #P0 alone to set the additional phase shift, in degrees, or 0 (or 0 0) to use the phase shift set in the Set Phase Plate Shift menu item #P0 and #P9 to set the minimum and maximum phase shift for a search that includes phase shift; the range must be less than 90 degrees. Such a search may be slow. #S nonzero to set the phase shift search step, or 0 to use the default (5.7 degrees) #A non-zero to fix astigmatism at zero. See Do Ctffind On Click and Set Ctffind Options for more details on these options. After successful fitting, the command will set reportedValue1-6 with mean defocus and astigmatism (difference between maximum and minimum defocus) in microns (underfocus negative), astigmatism angle in degrees, additional phase shift in degrees, fitting score, and resolution in Angstroms to which Thon rings fit. |
| Ctfplotter buf #M #N [#AP] [#P] [#O] [#T] [#C] [#S] [#E] | Runs the IMOD program Ctfplotter to determine defocus and astigmatism of he
image in the given buffer. Follow the buffer letter/number with the
minimum (#M) and
maximum (#N) values for the initial defocus scan (in microns, underfocus negative), and with these
optional entries:
#AP sum of 1 to find astigmatism and 2 to find phase; the default is 1 #P expected phase shift in degrees; if it is 0, it will use the phase shift set in the Set Phase Plate Shift menu item #O tilt angle offset used in adjusting spectra for tilt-dependent defocus changes, such as a lamellar pretilt #T tuning or power spectra resolution value: 0 for the default resolution (101), a value greater than 100 to set the resolution, 1 for autotuning, or -1 to use the last values from autotuning for PS resolution, spectrum cropping, and fitting limits. When setting the resolution with or a value, the following three values must be entered; when autotuning or using autotune values, no more entries after this are allowed. #C Pixel size to crop spectra to, or 0 for no cropping #S Start of the fitting range in either reciprocal pixels (< 0.5) or Angstroms (> 0.5), or -1 to use the default start of the range determined from the defocus #E End of the fitting range in either reciprocal pixels or Angstroms Automatic truncation of the fitting range, and weighting by local correlation coefficient, will be used in the fit. After successful fitting, the command will set reportedValue1-6 with mean defocus and astigmatism (difference between maximum and minimum defocus) in microns (underfocus negative), astigmatism angle in degrees, phase shift in degrees, overall cross-correlation coefficient (CCC) between the power spectrum and fitted CTF curve, and resolution in Angstroms of the last point with a correlation coefficient high enough to be included in the fit. The CCC is not at all comparable to the score from Ctffind. If the program exits with an error, reportedValue1 will be set to 1, and reportedValue2 will contain the exit status. Failure to start the program or to read results after successful completion generates a script error, but a non-zero exit status will not. Three files will be created in the current directory: 'single.defocus' with the basic results, 'ctfplotter.log' with program output, and 'ctfplotter.info' with stored settings plus the CCC and fit-to-resolution values. Ctfplotter is about as fast as Ctffind and will give significantly more accurate results for images with weaker signals or ones taken at higher tilt. To save some time, use autotuning (the default) on an initial image and use last parameters (-1 for #T) on a similar image. Command added in 4.1, 24-Aug-22. |
| ReportCtplotterTuning | Reports the values set from the last autotuning in Ctfplotter: power spectrum resolution, pixel size to which spectra are cropped or 0 if no cropping, and start and end of the fitting range in reciprocal pixels then in Angstroms. If there was cropping, the range in reciprocal pixels applies to the pixel size after cropping; otherwise the range applies to the pixel size of the original image (not of the possibly reduced image sent to Ctfplotter). These reciprocal pixel values are appropriate entries for the 'Ctfplotter' command with and without cropping specified, respectively. Command added in 4.1, 24-Aug-22. |
| SaveNextCtfplotterGraph buf [file] | Saves the graph from the next run of Ctfplotter and reads it into the buffer given by buf if that is a positive number or letter, or into the standard read buffer if buf is 0. A specific filename file is optional if the the graph is to be displayed, but the file will always be a TIFF file in this case. If buf is -1 or -2, the graph will just be saved into a PNG or TIFF file, respectively, and file must be entered in this case. In either case, the program will attach the extension '.tif' or '.png', depending on the file type, if the name does not already end in the right extension. Graph-saving requires either a full installation or 3dmod package from IMOD 4.12.51 or higher; see Additional Packages for GPU and Python Support, and for Displaying General and Ctfplotter Graphs for details on how to achieve this. The Ctfplotter packed with SerialEM will be used instead unless a graph is being saved. Command added in 4.1, 18-Jul-23. |
| Directory and Miscellaneous Commands | |
| SetDirectory dir | Changes the working directory to dir, which can contain spaces. The working directory is the location where script commands will access files when the names given to commands do not include a path. It is also the directory where file choosers will open, except for files like settings and scripts (as of SerialEM 4.2.0beta, 12-Feb-24). |
| ReportDirectory | Reports the current working directory, which is where a file will be created if it is opened from a script command without a full path. |
| IsDirectoryWritable dir | Tests whether directory dir is writable by trying to create a file with read/write access using the Windows CreateFile function. Sets reportedValue1 to 1 if writable, 0 if not, and reportedValue2 with the error code from GetLastError. Command added in 4.1, 13-Oct-23. |
| UserSetDirectory [prompt] | Opens a directory chooser dialog to allow user to select or make a directory, and change the working directory to it. If the optional prompt string is not supplied, the dialog title is 'Choose a new current working directory'. The chosen directory is stored in reportedValue1. If the user cancels the chooser, that value is set to 'Cancel' and can be tested with 'CompareStrings'. This is the directory where script commands will access files when given a name with a path, and where file choosers will open, except for files like settings and scripts. |
| OpenChooserInCurrentDir | This command is unnecessary as of SerialEM 4.2.0beta, 12-Feb-24. |
| MakeDirectory dir | Creates the directory dir if it does not already exist. dir can contain spaces. As of 5/18/22, the parent directory need not already exist, and multiple parent directories can be created. |
| MakeDateTimeDir | Creates a directory named by the date and time (e.g., Aug15_12.23.15) under the current directory and change to this as the new working directory. |
| ReportFreeDiskSpace dir | Reports the amount of free disk space in megabytes available on the filesystem containing directory dir. Command added in 4.1, 21-Jul-23. |
| DoesFileExist file | Reports if file exists in the current working directory if the name includes no path, or at the indicated path if it includes a path. file can be a directory. |
| AllowFileOverwrite # | Allows 'OpenNewFile', 'OpenNewMontage', and 'OpenTextFile ID W...' to overwrite an existing file if # is 1, or disallow it again if # is 0. |
| RemoveFile file | Removes the given file unconditionally, prints a warning if it cannot be removed. |
| WriteComForTSAlign | Writes the command file for aliging a whole tilt series if this mode of operation was selected with the AlignWholeTSOnly command; otherwise it has no effect. The tilt series file with associated .mdoc must still be the current open file. |
| SaveLogOpenNew [newFile] | Closes the log window and opens a new one. If a log file has been saved, the log is automatically saved to it before closing. If there is no log file and the log has new contents since program startup, the program will ask the user whether to save to log first; if the user cancels, the script is aborted. If a filename (newFile) is added, the new log will be saved with that name. Variables will be substituted before using the name. An extension in this name will be stripped off before adding '.log', so if you want to preserve extensions or other text after a period, add '.log' to the end of the name. If the file already exists, a number will be added to get a unique new name. |
| CloseLogOpenNew [#] | Closes the log window and opens a new one. If a log file has been saved, the log is automatically saved to it before closing. If there is no log file and the log has new contents since program startup, the program will ask the user whether to save to log first unless a non-zero value is entered for the optional #, in which case the contents of the log are discarded. If the user cancels the query, the script is aborted. |
| SaveLog [#O newFile] | Saves the log to a file. If no optional entries are made, it will be saved to the current file if there is one; otherwise the user will be asked for a filename in which to save. If a filename newFile is entered on this command, the log will be saved to a new file with that name. Variables will be substituted before using the name. An extension in this name will be stripped off before adding '.log', so if you want to preserve extensions or other text after a period, add '.log' to the end of the name. Enter a non-zero value for #O to overwrite the file if it already exists, or zero to have a number added to get a unique new name. |
| LoadSettingsFile file | Loads the given settings file after saving to the current one. Command added in 4.1, 31-Oct-22. |
| SaveSettings | Saves settings to file; if there is no current setting file, the user will be asked to provide a filename. If the user cancels, the command gives an error. Command added in 4.1., 28-Nov-22. |
| SaveCalibrations | Saves the calibrations to a file. The name of the calibrations file is printed in the log window; execution of this command requires Administrator mode to be enabled in the Calibrations menu. |
| ListAllCalibrations | Print tables with image shift, stage shift, focus, astigmatism via CTF, beam shift, beam intensity, spot intensity, and high focus mag calibrations to the log window for diagnostic purposes. It also reports rotation problems and inconsistencies between stage calibrations. |
| ListISVectorsToGraph #P #C #W | List image shift vectors for one camera whose active camera number is given in #C (numbered from 1), using calibrated pixel sizes and relative rotations if #P is non-zero, and save values in arrays for plotting with 'GraphPreStoredValues'. The magnification is stored in column 1. Set #W to 1 to store just lengths in columns 2 and 3, 2 to store just angles there, or 3 to store lengths in 2 and 3 and angles in 4 and 5. Command added in 4.1, 27-Oct-22. |
| ReportRotationProblems | Prints warnings about both the lack of calibrated absolute rotations (as is printed on program startup by default) and the lack of relative rotation information (printed on program startup in Administrator Mode). |
| CheckStageToCamera [#R] [#S] [#D] | Checks for inconsistencies between stage calibrations that are directly measured, derived for a mag from another mag using image shift calibrations, and derived using rotation and pixel size information. If there is no stage calibration at a mag, it compares one derived by IS calibrations (if any) with one derived from rotation and pixel values. If there is a stage calibration, it compares it with one derived by IS calibrations (if any) and separately compares it with one derived from rotation and pixel values. The rotation, average scaling in X and Y, and maximum stretch along an axis are reported if the rotation is larger than 8 degrees (or the value entered with the optional #R), or the scaling or stretch differ from 1 by more than 0.08 (or the value entered with #S). If #D is nonzero, it prints details about how each troublesome matrix is derived. Only mags where there is either a calibrated pixel size or calibrated relative or absolute rotation angle will be tested. Not all of the discrepancies will cause a problem in practice. |
| RunSerialEMSnapshot | Captures diagnostic information about the SerialEM configuration and calibrations in the log by running the script SerialEM_Snapshot.txt. It looks for this script in the directory with SerialEM.exe, then in C:\Program Files\SerialEM. If it is not present, the current version can be downloaded from the Nexperion script repository and renamed to this name. |
| ReorderMontageByTilt | Changes the piece coordinates in the current open file, which must be a montage, to reorder them by tilt, just as is done for bidirectional and dose-symmetric tilt series. An MRC file must have an associated metadata audoc ('.mdoc'), and both the piece coordinates in the image file header and the ones in the .mdoc will be reordered. An HDF file can also have its piece coordinates reordered. Command added in 4.1, 23-Apr-22. |
| Image File Commands | |
| S or Save [buf] [#F] | Saves image in A or in buf to current open file, or to the given file number #F |
| SetNewFileType #T [#S] | Enter #T as 0 to open files as MRC, or 1 to open files as a TIFF series described in an image autodoc file. The optional second value #S sets whether to open montaged files as MRC or as a TIFF series, but only if the property MontageAutodocOptions is set. |
| ReportFileOptions # | Reports the main file options if # is zero and the options used in Save To Other/Save Single otherwise; the main ones are initialized from properties and the other ones are saved in settings between sessions. The 10 values printed out are listed next in 'SetFileOptions'; reportedValues are set from the first 6. Command added in 4.2, 17-Oct-24. |
| SetFileOptions #O #K [#T] [#D] [#U] [#M] [#L] [#H] [TC] [HC] [MT] [MM] | Sets the main file options if #O is 0 and the file options used for
Save To Other/Save Single otherwise. Options are restored at script end if #K is 0,
kept if it is 1, or restored immediately if it is -1, provided that it was 0 on a previous use of the
command. Other entries are ignored if #K is -1. Enter -1 for any optional
value to leave it unchanged. These entries, which correspond to the options displayed in
the File Properties dialog, are: #T for file type: 0 for MRC, 2 for TIFF, 3 for numbered TIFFs listed in a '.idoc' file, 4 for JPEG, 5 for HDF. #D for data mode: 0 for bytes, 1 for signed 16-bit integers, 6 for unsigned 16-bit. #U for treatment of unsigned values when saving as signed: 0 to truncate, 1 to divide by 2, 2 to subtract 32768. #M set to 1 to write an '.mdoc' file for an MRC file, 0 not to. #L for percentage of intensity values to truncate to 0 at the low end of the distribution when scaling to bytes. #H for percentage of high intensity values to truncate at 255 when scaling to bytes. #TC for compression type in TIFF files: 1 for none, 5 for LZW, 7 for JPEG, or 8 for ZIP. #HD for compression type in HDF files: 1 for none or 8 for ZIP. #MT for file type for montage files: 0 for MRC, 3 for numbered TIFFs listed in a '.idoc' file, or 5 for HDF. #MM set to 1 to write an '.mdoc' file for a montaged MRC file, 0 not to. There are error checks or limits applied on individual entries, but no check for conflicting or irrelevant options, which generally would correspond to grayed out items in the dialog. Command added in 4.2, 17-Oct-24. |
| OpenNewFile file | Opens a file with the given name, which can contain spaces. The file properties dialog will be bypassed. Since the current working directory can be unpredictable, depending on whether the user has opened a file with the file chooser, it is advisable either to specify an absolute path for the filename, use a 'SetDirectory' with an absolute path, or use a filename in a variable set by 'ChooserForNewFile'. The same advice applies for the following commands that open files as well. |
| SaveToOtherFile buf typ cmp file | Saves one image in the given buffer buf, which can be in the FFT window, to the file with the given name and closes the file. typ specifies the type of file and can be MRC, HDF, TIF, TIFF, JPG, JPEG, CUR, or -1 (case insensitive), where CUR or -1 means use the current file type for the File menu entry Save Single/Save to Other. If that type is a series of TIFF files, a single TIFF will be written with the given name instead. cmp specifies the compression for a TIFF file and can be NONE, LZW, ZIP, JPG, JPEG, CUR, or -1 (case insensitive), where CUR or -1 means use the current compression for Save Single/Save to Other. If JPG or JPEG is entered for 'typ', a true JPEG file will be written, not a JPEG-compressed TIFF, and the compression entry does not matter (but must be present before the filename file). |
| SnapshotToFile #S #T feat typ cmp file | Takes a snapshot of the image display in the current active buffer of the active window, saves it to the file with the given name, and closes the file. #S sets the amount of image scaling relative to the display with a value of 1 or greater, or 0 or less to take the whole image at 1:1 zoom. #T sets the scaling of text labels and line thicknesses with a value of 1 or more, or 0 or less to use the same scaling as for the image. Set feat non-zero to skip feature drawing, with the sum of 1 to skip some features, 2 to skip Navigator items, and 4 to skip the scale bar. typ specifies the type of file and can be TIF, TIFF, JPG, JPEG, CUR, or -1 (case insensitive), where CUR or -1 means use the current file type selected in the Image Snapshots dialog. cmp specifies the compression for a TIFF file and can be NONE, LZW, ZIP, JPG, JPEG, CUR, or -1 (case insensitive), where CUR or -1 means use the current compression in the Image Snapshots dialog. If JPG or JPEG is entered for 'typ', a true JPEG file will be written, not a JPEG-compressed TIFF, and the compression entry does not matter (but must be present before the filename file). Use the 'ReportActiveViewTitle' and 'SetActiveViewByTitle' commands to ensure that the snapshot is of the desired window. |
| OpenFrameSumFile suffix | Opens a file whose name starts with the last name used for saving frames from a K2/K3, DE, or Falcon camera, and ends with the suffix string given in the command. The string can contain spaces and variables. |
| OpenOldFile file | Opens an existing MRC, HDF, or .idoc file with the given name, which can contain spaces. |
| ReadFile # [buf] | Reads the given section # (numbered from 0) from the current open file into the standard Read buffer, or into the buffer indicated by the optional buf |
| ReadOtherFile # buf file | Reads the given section # (numbered from 0) from a file into the given buffer buf and leaves the file closed; buf can be a buffer letter/number or -1 to use the standard Read buffer; end with filename. This command can read from a TIFF file, which cannot be opened otherwise. |
| RetryReadOtherFile # | Sets the number of times to retry if there is an error in ReadOtherFile, with a 2-second wait between trials. |
| ReadMontagePiece #X #Y #Z [buf] | Reads a piece from the current montage file at piece index #X and #Y (numbered from 1) in section #Z (numbered from 0), placing it in the current read buffer or the the buffer indicated by the optional buf Command added in 4.1, 07-Apr-23. |
| CloseFile [#] | Closes the current file. Enter optional # to stop script if no file is open. |
| ReportFileNumber | Reports the number of the currently selected file, numbered from 1, or -1 if there is no file open. |
| SwitchToFile # | Makes the given file number, numbered from 1, be the current open file. |
| ReportNumOpenFiles | Reports the number of open image files. Command added in 4.2, 30-Jan-24. |
| IsImageFileOpen name | Reports whether the file given by name is open; a full or relative path must be used if the file is not in the current directory. Command added in 4.2, 30-Jan-24. |
| ReportFileZsize | Reports the number of frames in currently open file, and if the file is a montage, also reports the number of sections of montage. |
| ReportCurrentFilename [#] | Reports the full path and filename of the current open file and sets it into reportedValue1; or if the optional # is entered with a 1, sets the root of the filename including the path in reportedValue1, the extension (including the dot) in reportedValue2, the path only in reportedValue3, and the rest of the rootname in reportedValue4. No optional assignment to variable. |
| ReportOpenImageFile #F [#P] | Like 'ReportCurrentFilename', but reports the name of the file whose index is #F (numbered from 1) and reporting parts of the name if #P is non-zero. Command added in 4.2, 30-Jan-24. |
| AddTitleToFile #F title | Adds the text in title to the header of the file whose number is given by #F, or to the current open file if #F is 0. The file must already have at least one image saved to it before running this command. The title will also be added to the ".mdoc" file for an MRC file, or to an ".idoc" file, but it will appear after the section for the last image written. |
| ReportLastFrameFile | Reports the full path and filename of the last frame file saved from a K2/K3, DE, or Falcon camera and sets it into reportedValue1, sets the directory only into reportedValue2, and sets the filename only into reportedValue3. |
| ReportFrameBaseName | Reports the base name if one is defined and whether it is used in frame or folder names; sets reportedValue1 to 1 if it is included in frame names and 0 if not, sets reportedValue2 to the base name if it is defined or 'none' if it is not, and sets reportedValue3 to 1 if it is included in folder names and 0 if not. |
| SetFrameBaseName #K #F #D name | Sets the base name with name and sets whether to use it in frame or directory names. Set #K to 1 to keep these settings after the script ends; otherwise they will be restored. Set #F to 1 to use the name in frame file names, 0 not to, or -1 to leave the current settings unchanged. Set #D to 1 to use it in directory names, 0 not to, or -1 to leave the setting as is. |
| ReportFrameNameFormat | Reports the variable governing the frame file name format, which is a sum of
flags: 0x1: Use the base name in the folder name 0x2: Use the root of the current open file name in the folder name 0x4: Use the Navigator item label in the folder name 0x8: Use the base name in the file name 0x10: Use the root of the current open file name in the file name 0x20: Use the Navigator item label in the file name 0x40: Use a sequential number 0x80: Use month and day 0x100: Use the hour, minute, and second 0x200: Use the Navigator label only if running from Acquire at Items 0x400: Use the tilt angle 0x800: Use a full date-time prefix 0x1000: Use hole and position in hole when doing Multiple Records Command added in 4.2, 18-Apr-24./TD> |
| SetFrameNameFormat #K #S #B | Sets or clears bits in the variable governing the frame file name format, as listed in 'ReportFrameNameFormat'. Set #K to 1 to keep the change after the script ends, otherwise the original format will be restored. Set #S to 1 to set the bits listed in #B, 0 to clear them, or -1 to set the format variable to just what is given in #B (such as if restoring a value saved from 'ReportFrameNameFormat'). #B can be entered as a single hex number starting with 0x as above, or as a sum of hex numbers (as can any integer entry). Command added in 4.2, 18-Apr-24. |
| ReportFrameSavingPath | Reports the path defined with the Set Folder button in the Camera Setup dialog for the current camera, which must be either a Gatan or a generic frame-saving camera. Sets reportedValue1 to the path, or to NONE if it is not defined. Command added in 4.1, 26-Apr-23. |
| Montage File Commands | |
| OpenNewMontage #X #Y file | Opens a file with the given name for montaging, with the number of frames in X and Y given by #X and #Y. If either #X or #Y is 0, the number of frames will be taken from the last montage that was open. The file properties and montage setup dialogs will be bypassed, and some properties like overlap and whether to do a stage montage will be taken from the last montage that was open. If no montage has been open before, or if the binning in the montage parameters does not match the binning in the camera parameter set to be used for the montage, the montage will use full-sized frames with the default overlap and will use stage movement if it is obvious enough that it is appropriate. |
| SetMontageParams #S [#OX #OY #FX #FY #N #B] | Sets up to 7 montage parameters after a montage file has been opened; enter a value or -1 to leave the parameter unchanged. The entries are: #S 1 to use stage movement or 0 not to; #OX overlap in X in pixels; #OY overlap in Y in pixels #FX frame size in X; #FY frame size in Y, #N 1 to skip correlations or 0 not to; #B a binning. The frame sizes, overlaps, and binnings cannot validly be changed after acquiring into the file. As of 12-Jul-23, if the binning is changed before acquiring, then whichever frame sizes and overlaps are specified as -1 will be changed by the change in binning to maintain the same acquisition area. If binning is changed after acquiring, it will attempt to take frames with the same number of pixels and the new binning, which may or may not work. |
| ParamSetToUseForMontage #P [#N] | Specifies what parameters to use for a montage with #P:
1 and -1 will turn on or off the option to use Mont-Map parameters; 2 or -2 will turn on or off the option to use View in Low Dose mode; 3 or -3 will turn on or off the option to use Search in Low Dose mode; When one of these is turned on, the other is turned off. Set the optional #N non-zero to defer changing the parameter until the next montage opened through the current script. In general, it is best to use this command before opening a montage; and if Low Dose is on and the current file is a montage, using +/-2 or +/-3 will generate an error unless #N is used. Command added in 4.1, 6-Mar-23; #N added 27-Apr-24. |
| SetMontPanelParams #V [#A #B #M] | Sets parameters in the montage control panel; enter: 1 for #V to treat as very sloppy or 0 not to; 1 for optional #A to align pieces in overview or 0 not to, optional #B with an overview binning; and 1 for optional #M to assess multiple peaks or 0 not to. Enter -1 for any of these to leave it unchanged. Setting overview binning has no real effect unless montaging is on, in which case it is limited by the allowed maximum binning. Command added in 4.1, 10-Dec-23. |
| SetupWaffleMontage #B file | Opens a montage file or adjust the current file's properties so that it will hold an image of the cross-line (waffle) replica grating with at least #B blocks in X and Y at the current magnification. Follow with the minimum # of blocks and the name of the file to be opened if necessary. If montaging is not needed, no changes are made. If there is an existing montage that is adequate, its properties will be adjusted to work at the current mag. If a new montage is needed, it will close the current file if it is a montage and open a new one with the given name. Variables will be substituted, so the name can contain the mag index, for example. It sets reportedValue1 to 1 or 0 depending on whether montaging is needed or not. |
| SetupFullMontage #O file | Opens a full grid montage with the given name at the current magnification, without opening any dialogs. The current acquisition parameters of the camera parameter set indicated in the Montage Setup dialog will be used. If #O is nonzero, it sets the minimum overlap factor for fitting the montage, overriding the corresponding entry in the setup dialog. If nonzero, this factor must be between 0 and 0.5. Command added in 4.1, 31-Oct-22, changed to have an overlap factor 6-Mar-23. |
| SetGridMapLimits #P #LX #UX #LY #UY | Sets the limiting stage positions to be covered by a full grid montage, overriding the limits set with Set Grid Limits in the Navigator - Montaging & Grids submenu until the script ends (if #P is 0) or replacing those limits if #P is nonzero. LX and UX are the lower and upper X coordinates in microns and they must be negative and positive, respectively; enter a 0 to use the existing limit. LY and UY are similar for Y. Command added in 4.1, 6-Mar-23. |
| SetupPolygonMontage #I #O file | Opens a polygon montage with the given name at the current magnification, without opening any dialogs. For #I, enter 0 for the current Navigator item or the item being acquired; an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. The indicated item must be a polygon. The current acquisition parameters of the camera parameter set indicated in the Montage Setup dialog will be used. If O is nonzero, it sets the minimum overlap factor for fitting the montage, overriding the corresponding entry in the setup dialog. If nonzero, this factor must be between 0 and 0.5 Command added in 4.1, 31-Oct-22, changed to have an overlap factor 6-Mar-23. |
| ReportNumMontagePieces | Reports the number of pieces that will be acquired for a montage if one is currently open, or 1 if not. |
| Text File Commands | |
| ReadTextFile var file | Reads the entire contents of the given text file, breaks it up by spaces or tabs, and stores the words or numbers as an array in the variable var. All lines will be read and combined into the one variable. The file will be closed after reading. |
| ReadStringsFromFile var file | Reads the entire contents of the given text file as a whole string per line, and stores the lines as an array in the variable var. |
| Read2DTextFile var file | Reads the entire contents of the given text file, breaks it up by spaces or tabs, and stores the words or numbers of each line as a separate row of a 2D array in the variable var. The file will be closed after reading. |
| The following commands allow multiple files to be opened for either reading or writing (not both) and accessed one line at a time. Each file is referred to by an arbitrary one-word identifier (ID) that immediately follows the command; the ID is case-insensitive. | |
| OpenTextFile ID mode #K file | Opens a file with the given ID in the given mode, closing it when the
script ends if #K is 0 or keeping it open if #K is non-zero. The mode can
be: R or r to open for reading, giving an error if the file does not exist; T or t to try to open for reading, setting reportedValue1 to 1 if the file exists or 0 if it does not; W or w to open for writing, giving an error if the file exists unless 'AllowFileOverwrite 1' has been used; O or o to open for writing, overwriting an existing file if any; A or a to open for appending (writing at the end), giving an error if the file does not exist. The same file cannot be opened under two different ID's. The 'T' mode can be used to avoid a script error and also can be used in a loop to wait for a file to appear from an external source. |
| WriteLineToFile ID [line] | Writes the remainder of the text on the script line (after variable substitution) to the file with the given ID. The comment character '#' can be included and text after it will be written. Omit text to write a blank line. |
| ReadLineToArray ID var | Reads the next line of the file with the given ID, breaks it into words, and sets up an array variable var with each word as an element. '#' is treated as the start of comment and the rest of the line is discarded. Blank lines and lines starting with '#' will be skipped. Parts of the line enclosed in single quotes will be treated as single strings if the 'ParseQuotedStrings' command has been given. Reaching the end of the file does not give a script error; instead, reportedValue1 is set to 1 when a line is read or 0 if nothing was read. This command could be used in a loop to wait for a file to be added to by external source. |
| ReadLineToString ID var | Works like 'ReadLineToArray ', but the line is stored in the variable exactly as it is in the file, including a line starting with '#'. Blank lines will still be skipped. |
| FlushTextFile ID | Flushes the output added to the file with the given ID to disk. |
| CloseTextFile ID | Closes the file with the given ID. |
| IsTextFileOpen ID [file] | Sets reportedValue1 to 1 if there is an open file with the given ID, or with the given optional name, and to 0 otherwise. The ID can be nonsense when testing with a filename (file). |
| Autodoc/.mdoc File Commands | |
| AddToAutodoc key value | Adds a key-value pair to the last section of the autodoc associated with the current open image file, if any. The next word after the command is the key, and the remainder of the text on the line is taken as the value. Variables are substituted before using the text. After one or more additions to a section of the autodoc, a WriteAutodoc command must be used to save the values before closing the file or saving another image to it. If no images have been written yet, the entry will be added to the global section. |
| WriteAutodoc | Writes the autodoc associated with the current open image file. Use this command once after adding one or more values to a section of the autodoc. |
| OpenFrameMdoc filename | Opens an '.mdoc' file with the given filename for information about image acquisitions that save frames, the same as using the Open .mdoc for Frames command. An error is generated if such a file is already open. |
| CloseFrameMdoc [#] | Closes the '.mdoc' file for acquisitions that save frames, if one is open. If the optional # is non-zero, an error is generated if no file is open. |
| AddToFrameMdoc key value | Adds a key-value pair to the last section of the autodoc opened with the Open .mdoc for Frames or 'OpenFrameMdoc' command. This works just like AddToAutodoc, but the WriteFrameMdoc command must be used instead after adding values. |
| WriteFrameMdoc | Writes the frame autodoc file; use this command after adding one or more values to a section. |
| ReportFrameMdocOpen | Reports whether a frame .mdoc file is open; sets reportedValue1 to 1 if so. |
| DeferWritingFrameMdoc | Prevents the program from appending a new section to the frame .mdoc file after frames are acquired. If you use this command before starting the acquisition, add values after acquisition with 'AddToFrameMdoc ', and finish with 'WriteFrameMdoc', the new section with your additions can be appended to the file rather than rewriting the whole file. |
| StartNextFrameStackMdoc key value | Adds a key-value pair to the global section of the .mdoc file written with each frame stack when the option for such a file is selected in the Frame File Options dialog, after clearing out any previous entries in the global section. This command and the next must be given before acquiring. |
| AddToNextFrameStackMdoc key value | Adds a key-value pair to the global section of the frame stack .mdoc file while retaining previous entries there. |
Microscope and Filter Control Commands
| Stage-Related Commands | |
| U or TiltUp [#R] [#X #Y] | Tilts up by preset increment. If optional #R is non-zero, then the program will restore the stage X and Y positions after tilting, either to the position before starting or to #X, #Y if they are entered. |
| D or TiltDown [#R] [#X #Y] | Like TiltUp, but tilts down by preset increment |
| SetTiltIncrement #I [#C] | Sets the tilt increment to the #I. If the option #C is entered, it sets cosine tilting if non-zero or turns it off if 0. Command added in 4.1, 20-Jan-23. |
| TiltTo #A [#R] [#X #Y] | Like TiltUp, but tilts to given angle #A |
| TiltBy #A [#R] [#X #Y] | Like TiltUp, but changes tilt by the given amount #A |
| BackgroundTilt #A [#S] | Starts tilting stage in the background; images can be taken and scripts can run during the tilt. Follow with #A, the angle to tilt to, and optionally with #S, a speed factor for Thermo/FEI or JEOL scopes that support this (< 1 for slower than normal tilting). For CryoARM, speed factors of 100 - 105 will select pre-set speeds of 10, 2, 1, 0.5, 0.25, and 0.1 degrees/sec. On Hitachi scopes, the factor is relative to the tilt speed that can be set with the property HitachiTiltSpeed. With the default of speed of 100, the factor can range from 0.4 to 1.27, and the tilt speed in degrees per second is approximately 1.65 times the factor to the 1.85 power. On Thermo/FEI scopes, background stage movement requires the property 'BackgroundSocketToFEI' set to 1 so that the fourth socket for background stage operations is opened when the program starts. If the command crashes SerialEM or FEI-SEMserver, see notes under TiltDuringRecord. |
| StopBackgroundTilt [#] | Stops tilting started by BackgroundTilt by issuing a new call to tilt at normal speed, at the current angle or the current angle plus the optional #. This command works on JEOL scopes and has been seen to work on Thermo/FEI scopes with 7.x servers, but not with 6.x servers or earlier. Command added in 4.1, 10-Apr-23. |
| ReportTiltAngle | Reports current tilt angle |
| MoveStage #X #Y [#Z] | Moves stage by micron increments in X, Y, Z (#Z optional) |
| MoveStageTo #X #Y [#Z] | Moves stage to given position in microns. #Z is optional and Z will not be changed if it is omitted. |
| StageShiftByPixels #X #Y | Moves the stage by the given number of unbinned pixels in X and Y on the current camera. |
| MoveStageWithSpeed #X #Y #S | Moves the stage by micron increments in X and/or Y with a speed factor #S. On Thermo/FEI scopes, this may work only with one axis set to 0 using standard scripting, but should work for moving both axes when going through the Tommoniker interface (although with that, it may move one axis then the other). If the command crashes SerialEM or FEI-SEMserver, see notes under TiltDuringRecord On Hitachi scopes, the speed factor is relative to the stage speed that can be set with the property HitachiStageSpeed; with the default value of 80000, the factor can range from 0.0025 to 2. |
| BackgroundMoveStage #X #Y [#S] | Like 'BackgroundTilt', starts moving the stage in the background to X, Y with optional speed factor S The limitations described for 'MoveStageWithSpeed' apply. Command added in 4.1, 12-Sep-23. |
| StopBackgroundStage [#X #Y] | May stop the stage move started with 'BackgroundMoveStage' by issuing another call to move the stage with normal speed to the current position, or that position plus the optional increments X and <Y>. It probably will not work for any Thermo/FEI scopes. Command added in 4.1, 12-Sep-23. |
| ReportStageXYZ | Reports current stage position |
| ReportStageBusy | Reports if the stage is busy and set reportedValue1 to 1 if so, 0 if not. |
| TestRelaxingStage #X #Y [#B] [#R] | Moves stage by the micron increments in X and Y with backlash correction and a small relaxation in the opposite direction from the backlash correction. The optional #B can be set with the backlash amount, otherwise the value of the property 'StageMontageBacklash' will be used. The optional #R can be set with the relaxation amount in microns; otherwise the value of the property 'StageRelaxation' will be used (default 0.025). The backlash movement will be opposite to the stage movement unless #B is negative. To assess the value of relaxation, a measurement of the time it takes for drift to settle should be done after this command. |
| RelaxStage [#R] | If the stage is in a known backlash state, moves the stage in the opposite direction from its last movement by the amount given by the optional #R, or the StageRelaxation property (0.025 by default). A message is printed if the stage backlash state is not known. |
| ReportStageBAxis | Reports the B axis value of the stage in degrees, if such an item exists. |
| SetStageBAxis # | Sets the stage B axis to the given value in degrees. |
| Focus-Related Commands | |
| ChangeFocus # | Changes defocus by the given value in microns |
| SetDefocus # | Sets the defocus to the given value in microns |
| SetAbsoluteFocus # | Sets focus to an absolute (standardized) value as reported earlier by ReportAbsoluteFocus or ReportFocus |
| SetStandardFocus # | Same as 'SetAbsoluteFocus', which is preferred to avoid confusion with the calibrated standard or eucentric focus value |
| SetObjFocus # | Calls SetObjFocus on JEOL with the given #, an integer increment, and reports change in focus |
| SetDiffractionFocus # | Sets diffraction focus to the given # |
| ReportDefocus | Reports current defocus readout in microns |
| ReportAbsoluteFocus | Reports an absolute (standardized) value for the current focus setting |
| ReportFocus | Same as 'ReportAbsoluteFocus', which is a better description of the operation |
| SetEucentricFocus [#] | If in low mag, sets to the standard focus for the current mag or nearest LM mag if one has been set; otherwise on Thermo/FEI it assumes standard focus is 0 and on JEOL it stops with an error. If not in LM, sets to the standard focus for the nearest nonLM mag if one has been set. It stops with an an error if none were set unless the optional # is non-zero, in which case it suppresses the error and sets reportedValue1 to -1 instead of 0. On Thermo/FEI scopes, it issues a warning if it is using a calibrated value from a different mag. |
| CalEucentricFocus | Stores the current standardized focus value as the standard focus for the current mag, just as the Calibrate menu item Standard Focus does. |
| SaveFocus | Saves the current focus; the focus will be restored to this value either by RestoreFocus or when the script stops or exits. The script will not be resumable if it stops. |
| RestoreFocus | Restores the focus value when SaveFocus was run. After this is run, the focus will not be restored again when the script ends. |
| ResetDefocus | Sets the defocus readout to 0, just as Reset Defocus in Focus menu does. |
| Magnification-Related Commands | |
| SetMag #M [#D] | Sets the mag to an actual mag value in #M, first changing from diffraction to imaging mode if necessary. In STEM mode, set the optional #D non-zero to set STEM mag directly to the given value, without trying to find it in the mag table. |
| SetMagIndex # | Sets the magnification index to the given value, first changing from diffraction to imaging mode if necessary. |
| ChangeMag # | Changes mag by given number of mag steps, positive to increase mag index and negative to decrease it. If the property 'UseInvertedMagRange' is set, positive and negative increase or decrease the mag rather than the mag index in the inverted range. |
| ReportMag | Reports the current mag; also sets reportedValue2 to 1 if low mag mode, 0 if not, and reportedValue3 to 1 if in EFTEM, 2 if in STEM mode, or 0 otherwise. |
| ReportMagIndex | Reports the current mag index; also sets reportedValue2 to 1 if low mag mode, 0 if not |
| ReportCameraLength | Reports the camera length in meters, or 0 if not in diffraction mode. |
| SetCamLenIndex # | Sets the camera length index to the given number, first changing from imaging to diffraction mode if necessary. On a Thermo/FEI scope, values higher than 30 set the index to (# - 30) in LAD mode |
| SetMagAndIntensity # | Sets the mag to the actual film mag value and change the beam to maintain the same brightness. Two values are reported: the initial percent C2 value and the remaining factor of intensity change needed if it was not possible to change the intensity by the full amount needed. The C2 value should be used to restore intensity when the mag is restored. The remaining intensity change could be applied to the exposure time if necessary. The script will stop if there is an error in the intensity change. |
| ChangeMagAndIntensity # | Changes mag by the given number of mag steps and change the beam to maintain the same brightness. Behaves same as SetMagAndIntensity, and steps in the same way as ChangeMag. |
| IncMagIfFoundPixel # | Increases or decreases mag by one step if the pixel size has been found at the current mag with the Find Pixel Size routine, depending on whether # is positive or negative. Sets reportedValue1 to 1 if the mag is changed, 0 otherwise. |
| Beam-Related Commands | |
| SetSpotSize # | Sets the spot size to the given number |
| ReportSpotSize | Reports the current spot size |
| SetPercentC2 # | Sets the C2/C3 lens strength to the given percentage, or illuminated area on Titan to given value in microns. |
| IncPercentC2 # | Changes the C2/C3 lens strength percentage or illuminated area in microns by the given amount |
| ReportPercentC2 | Reports the percent C2/C3 (on a Thermo/FEI scope, this number matches the value in MUI) and the fractional lens strength. On a Titan, if illuminated area is being used for intensity, this reports the illuminated area value. |
| ReportCrossoverPercentC2 | Reports the percent C2/C3 and the fractional lens strength of the crossover at the current spot size and probe mode as calibrated. If illuminated area is being used for intensity, this reports the illuminated area value at crossover. |
| ReportIlluminatedArea | Reports the illuminated area on a Titan in the units that are used internally, which are microns times 0.01. |
| SetIlluminatedArea # | Sets the illuminated area on a Titan to the given value, expressed in microns times 0.01. |
| ReportImageDistanceOffset | Reports the offset of the distance from the condenser plane to the image plane on a Titan in the units from the scope. Older versions of the scripting software do not have this function, and with them, this command will crash SerialEM or FEI-SEMserver. |
| SetImageDistanceOffset # | Sets the offset of the distance from the condenser plane to the image plane on a Titan; the allowed range is +/- 0.02. Older versions of the scripting software do not have this function, and with them, this command will crash SerialEM or FEI-SEMserver. |
| SetIntensityForMean # | Adjusts beam intensity to yield the given number of counts in a Record image, based on counts in the tilt-foreshortened area of the image in A. In Low Dose mode, this operates only on Record images and will change the intensity only of the Record area. |
| SetExposureForMean #M [#K] | Adjusts Record exposure time to yield the given number of counts #M, based on counts in the tilt-foreshortened area of the image in A, which must be a Record image in Low Dose mode. For a K2/K3 camera taking dose-fractionated images, a non-zero value can be given for the optional #K to modify frame time so as to keep the same number of frames. |
| SetIntensityByLastTilt | Adjusts beam intensity by the change in cosine of the tilt angle from the last tilt change. In low dose mode, this changes the intensity only of the Record area. |
| ChangeIntensityBy # | Changes beam intensity by the given factor using calibrations. In low dose mode this changes the intensity of the current area. |
| SetDoseRate # | Changes the beam intensity to set the dose rate at the camera to the given value in electrons per physical pixel per second beam intensity, based on the image in buffer A. This command is the same as running Set Dose Rate in the Tasks menu. In low dose mode it changes the intensity of the current area. |
| SetAlpha # | Sets alpha value on JEOL. |
| ReportAlpha | Reports alpha value on JEOL. |
| SetBeamShift #X #Y | Sets the beam shift to the given values (nominal micron units) |
| ReportBeamShift | Reports the beam shift in nominal micron units |
| MoveBeamByMicrons #X #Y | Moves the beam by the given number of microns in X and Y. |
| MoveBeamByFieldFraction #X #Y | Moves the beam by the given fractions of the current camera field of view in X and Y; e.g. 0.5,0.5 would move the center of the beam from the center of the field to the upper right corner. |
| SetBeamTilt #X #Y | Sets the beam tilt to the given values (milliradians or % of full scale) |
| ReportBeamTilt | Reports the beam tilt in milliradians for Thermo/FEI, % of full-scale value for JEOL |
| SetImageBeamTilt #X #Y | Sets the image-beam tilt on a Thermo/FEI scope to the given values in milliradians. The Thermo/FEI scripting documentation cautions against using both this kind of beam tilt and the dark field tilt. |
| ReportImageBeamTilt | Reports the image beam tilt in milliradians on a Thermo/FEI scope. |
| SetDiffractionShift #X #Y | Sets the diffraction shift to the given values. |
| ReportDiffractionShift | Reports the diffraction shift. |
| SetProbeMode #|mode | Sets the mode to microprobe or nanoprobe on a Thermo/FEI scope. Follow with 0 or 'nano' for nanoprobe, or 1 or 'micro' for microprobe. |
| SaveBeamTilt | Saves the current X and Y beam tilt (specifically for the current probe mode on a Thermo/FEI scope). It will be restored to these values either by RestoreBeamTilt or when the script stops or exits. The script will not be resumable if it stops. |
| RestoreBeamTilt | Restores the beam tilt saved when SaveBeamTilt was run or another command saved the beam tilt (AdjustBeamTiltForIS or several ImageShift commands). After this is run, the beam tilt will not be restored again when the script ends. For a Thermo/FEI scope, it is restored for the current probe mode provided that a value was saved in that mode. As of 18-May-23, in both SerialEM 4.0.26 and 4.1.0, astigmatism is also restored if it was saved. |
| ReportProbeMode | Reports whether a Thermo/FEI scope is in nanoprobe or microprobe mode; sets reportedValue1 to 0 or 1, respectively. |
| Image Shift-Related Commands | |
| SetImageShift #X #Y [#D] [#A] | Sets the image shift to the given values (image shift units). The values correspond to the ones give by ReportImageShift, which are adjusted for tilt axis offset, image shift offset, and low dose area shift. Add the optional #D to impose a settling time before the next camera image equal to #D times the normal settling time (i.e., 1 for regular settling). Set the optional #A nonzero to use the Coma vs. Image Shift calibration to adjust beam tilt and objective stigmation for the incremental change in image shift from its current value. With that option, the command saves the current beam tilt, if it has not been saved before in the script, and it will be automatically restored when the script exits. The stigmator settings will also be saved and restored. |
| ImageShiftByPixels #X #Y [#D] [#A] | Changes image shift by given # of unbinned pixels in camera X and Y; optional #D and #A provide settling time and beam-tilt adjustment for the image shift as just described. As of SerialEM 4.1, 6/29/22, the shift is tested for staying within the standard limit and not done if the limited would be exceeded; reportedValue1 is set to 0 if it is within limits or 1 if it is not. |
| ImageShiftByUnits #X #Y [#D] [#A] | Changes image shift by given # of IS units in X & Y; optional #D and #A provide settling time and beam-tilt adjustment for the image shift as just described. The shift is tested and reportedValue1 is set as for 'ImageShiftByPixels'. |
| ImageShiftByMicrons #X #Y [#D] [#A] | Changes image shift by given distance on specimen (X is tilt axis); optional #D and #A provide settling time and beam-tilt adjustment for the image shift as just described. The shift is tested and reportedValue1 is set as for 'ImageShiftByPixels' |
| ImageShiftByStageDiff #X #Y [#D] [#A] | Changes image shift by the equivalent of the given stage shift in X and Y; optional #D and #A provide settling time and beam-tilt adjustment for the image shift as just described. The shift is tested and reportedValue1 is set as for 'ImageShiftByPixels' |
| ReportImageShift | Reports the image shift in IS units, adjusted for tilt axis offset, image shift offset, and low dose area shift; if image shift is calibrated, also report the equivalent shift in unbinned pixels on the current camera at the current magnification, and the amount the stage would need to be moved to compensate for resetting this image shift. Positive values of the camera shift will result from an image shift imposed by dragging an image to the upper right. |
| ReportSpecimenShift | Reports the image shift, as just described, in the "specimen" coordinates used internally by the program, which are coordinates in microns with X along the tilt axis. |
| ReportTiltAxisOffset | Reports the tilt axis offset in microns, which is a single value in 'specimen' coordinates, plus the corresponding X and Y stage units, X and Y IS units, and 1 or 0 for whether the user option to shift to tilt axis is selected. Command added in 4.1, 29-Jun-23. |
| ReportMaxImageShift # | Reports maximum image shift values for magnification index # or the current magnification if # is 0. Reports the limit from properties that is applied by various routines that test against this limit, and for a JEOL scope, the maximum image shift that can be applied without reaching the deflector limit, with neutral values and other offsets taken into account (or sets reportedValue2 0 for a non-JEOL scope). Values are in microns. Command added in 4.2, 02-Jan-24. |
| Miscellaneous Scope Commands | |
| GetFastScopeStatus | Sets a collection of variables with existing information about the microscope
state, with no calls to the microscope:
fastISX, fastISY: Image shift components as displayed (with scaling) in the scope status panel after all offsets have been subtracted (e.g., for low dose areas) fastRawISX, fastRawISY: Raw image shift values fastStageX, fastStageY, fastStageZ: Stage position in microns fastBlanked: 1 if beam blanked, 0 if not fastCameraLength: Camera length, valid in diffraction and STEM modes fastCamLenIndex: Camera length index, valid in diffraction and STEM modes fastProbeMode: 1 for microprobe, 0 for nanoprobe fastMagIndex: Magnification index fastMagnification: Magnification as displayed in the scope status panel fastDefocus: Defocus as displayed in the scope status panel fastSpotSize: Spot size fastAlpha: Alpha value on JEOL fastIntensity: Intensity value displayed in scope status panel fastRawIntensity: Raw intensity value (between 0 and 1) fastEMmode: 0 for TEM, 1 for EFTEM, 2 for STEM, 3 for diffraction fastDarkField: 1 if in dark field or 0 if not, for Thermo/FEI scopes only |
| SetObjectiveStigmator #X #Y | Sets the objective lens stigmator to the given values (between -1 and 1) |
| ReportObjectiveStigmator | Reports the X and Y values of the objective stigmator, between -1 and 1 |
| SetCondenserStigmator #X #Y | Sets the condenser lens stigmator to the given values (between -1 and 1) |
| ReportCondenserStigmator | Reports the X and Y values of the condenser stigmator, between -1 and 1 |
| SetDiffractionStigmator #X #Y | Sets the diffraction lens (IL on a JEOL) stigmator to the given values (between -1 and 1). Command added in 4.2, 21-Apr-24. |
| ReportDiffractionStigmator | Reports the X and Y values of the diffraction stigmator, between -1 and 1. Command added in 4.2, 21-Apr-24. |
| SetBeamBlank # | Blanks beam if # is 1, unblank if # is 0 |
| NormalizeLenses # | Normalizes selected lenses on a Thermo/FEI or Hitachi scope; # is the sum of 1 for projector, 2 for objective, 4 for condenser lenses |
| NormalizeAllLenses [#] | Normalizes all lenses, or in a lens group, on a Thermo/FEI scope. With # 0 or not present, it normalizes all lenses in one call. Otherwise, # can be the sum of 1 to normalize the illumination group (which includes condenser, minicondenser, and objective lenses) and 2 to normalize the projection group (which includes objective and projector lenses) in a separate call. |
| ReportColumnOrGunValve | Reports 0 or 1 if column/gun valve is closed or open on FEG scopes, or if filament on JEOL is clearly off or on. Reports -1 if the filament current is inconsistent with the beam switch state. |
| SetColumnOrGunValve # | Closes column/gun valve on FEG scope or turn off filament on JEOL if # is 0; open valve or turn on filament if # is 1. |
| ReportFilamentCurrent | Reports the filament current on a non-FEG JEOL scope. The value is between 0 and 100 unless the property 'FilamentCurrentScale' is set with a scaling other than 100. |
| SetFilamentCurrent # | Sets the filament current on a non-FEG JEOL to #, in the same units as 'ReportFilamentCurrent'. |
| ReportFEGEmissionState | Reports whether the FEG emission is on (non-zero) or off (0), on JEOL's only. |
| SetFEGEmissionState # | Turns the FEG emission off (for a 0 value) or one (for a non-zero value), on JEOL's only. This should be used only for a cold FEG. |
| ScreenUp | Raises the main screen |
| ScreenDown | Lowers the main screen |
| ReportScreen | Reports if screen is up or down; reportedValue1 is set to 0 or 1, respectively. |
| ReportScreenCurrent | Reports the unsmoothed screen current in nA. |
| ReportBeamStopPosition | Reports 0 or 1 if the beam stop is out or in, -1 if it is in an unknown position, and on Thermo/FEI scopes, 2 if it is inserted halfway or 3 if it is moving. Should work on newer generation JEOL scopes (F200, various ARM's, also 2200FS) and on Thermo/FEI scopes with the UTAPI interface. Command added in 4.1, 6-Oct-23. |
| SetBeamStopPosition # | Inserts or retracts the beam stop if # is non-zero or 0. Command added in 4.1, 6-Oct-23. |
| ReportLens name | For a Hitachi or JEOL scope, reports the lens value by its abbreviated name. For JEOL, allowed names are 'CL1', 'CL2', 'OM2', 'IL1', 'IL2', 'IL3', 'PL1', 'PL2', 'PL3', 'PL4', 'FLf', 'FLc', 'FLcomp1', 'FLcomp2'. Value cannot be assigned to a variable at end of command. For Hitachi, allowed names are 'C1', 'C2', 'OBJ', 'OM', 'I1', 'I2', 'P1', and 'P2'. |
| SetLensByName name # | For a Hitachi scope only, sets the lens with the abbreviated name to the value #, which ranges between 0 and 1. Allowed names are 'C1', 'C2', 'OBJ', 'OM', 'I1', 'I2', 'P1', and 'P2'. Command added in 4.1, 22-Jul-23. |
| ReportCoil name | For a Hitachi scope, reports the X and Y values of a deflector specified by its abbreviated name. Allowed names are 'GH', 'GT', 'CS', 'BH', 'BT', 'OS', 'ISF', 'IA', and 'PA'. |
| SetCoilByName name #X #Y #I | For a Hitachi scope, sets the X and Y values of a deflector specified by its abbreviated name with the values #X and #Y, with rounding indicated by the increment in #I The range of values is -1 to 1. Allowed names are 'GH', 'GT', 'CS', 'BH', 'BT', 'OS', 'ISF', 'IA', and 'PA'. Increments are set to 1 in the plugin for 'BH' and 'ISF', and 1024 for all others used there ('CS' is not used). The actual increment needed on newer interfaces or scopes is unknown; try setting with smaller increments and see if a change occurs or not. An integer increment of 1 corresponds to an increment of 0.000005 in the value. Command added in 4.2, 15-Mar-23. |
| SetFreeLensControl #L #S | On a JEOL with scripting support for free lens control, turns free lens control for the lens given by #L off if #S is 0 and on otherwise. Lens numbers are: 0: CL1, 2: CL3, 6: OL Coarse, 7: OL Fine, 8: OM, I0: IL1, 11: IL2, 12: IL3, 13: IL4, 14: PL1, 15 or 16: PL2, 19: FL Coarse, 20: FL Fine, 21: FL Ratio |
| SetLensWithFLC #L #V [#R] | Using free lens control, sets the lens given by #L (see SetFreeLensControl) to the value #V between 0 and 1 if the optional #R is 0 or absent, or changes it by #V if #R is non-zero. This command probably turns on FLC for that lens. |
| ReportLensFLCStatus #L | For the lens given by #L (see SetFreeLensControl), reports whether free lens control is on and the value for the lens. |
| ReportApertureSize # | For Thermo/FEI and JEOL scopes, reports the size for the aperture whose index is #. For JEOL, the value is the size in microns if there is an 'ApertureSizes' property for aperture #, a position index from 1 to 4 if there is no property, or 0 if the aperture is retracted. If the property JeolHasExtraApertures is not set, 1 and 2 are the condenser and objective apertures, others are 3:HCA, 4:SAA, 5:ENTA, 6:EDS. If that property is set (e.g., for CryoARM), indexes are 0:CL1, 1:CL2, 2:OL(OL Upper), 3:HC(OL Lower), 4:SA, 5:ENT, 6:HX, 7:BF, 8:AUX1, 9:AUX2, 10:AUX3, 11:AUX4. For Thermo/FEI scopes, # can be 0, 1, or 3 for Condenser 1, 2, or 3, 2 for Objective, or 4 for Selected Area. For both scopes, you can use aperture names starting with 'c' or 'C', 'o' or 'O', or 's' or 'S', which will be converted to 1, 2, or 4 respectively. The reported value can be: the size in microns; 0 if the aperture is retracted; 1 if it is moving or not enabled; or the position of a phase plate plus 1 for the objective aperture (e.g., 3 for 'Ph P2', but only if the phase plates are named that way in the combo box). See Controlling Apertures on Thermo/FEI Scopes for requirements and restrictions for using this command and 'SetApertureSize'. Command added in 4.1, 7-Feb-23. |
| SetApertureSize #I #S | For JEOL and Thermo/FEI scopes, attempts to set the size with #S for the aperture whose index is #I, where indexes and other requirements are as described for 'ReportApertureSize'. For JEOL, the size can be in microns if there is an 'ApertureSizes' property for aperture #I, otherwise it should be a position index from 1 to 4.. The value of #S can also be 0 to retract the aperture. For Thermo/FEI, #S can also be 0 to retract it or 1 to reinsert it without specifying a size, otherwise it should be the size in microns. For an objective aperture with phase plates, the size can also be 2 to 7 to specify the phase plates in position 1 to 6, provided that the phase plates are named like 'Ph Pn' (e.g., 'Ph P2') in the combo box. Command added in 4.1, 7-Feb-23. |
| RemoveAperture # | Removes the aperture whose index is the given # (JEOL, Hitachi, and Thermo/FEI scopes as described for 'ReportApertureSize'). The size and position of the aperture will be recorded before it is removed. For Hitachi, only the objective aperture can be removed and # must be 2. For Thermo/FEI scopes, valid indexes are 2 for Objective and 4 for Selected Area. |
| ReInsertAperture # | Replaces the aperture whose index is the given # after it has been removed with 'RemoveAperture' (JEOL, Hitachi and Thermo/FEI scopes as described for 'ReportApertureSize'). For JEOL, the aperture of the stored size will be inserted and it will be set to the stored position. For Hitachi, only the objective aperture can be reinserted and # must be 2. For Thermo/FEI scopes, valid indexes are 2 for Objective and 4 for Selected Area. |
| PhasePlateToNextPos | Moves phase plate to next position. Works on JEOL and Thermo/FEI scopes, but for Thermo/FEI scopes it requires server version 6.13 and a license for advanced scripting. |
| ReportPhasePlatePos | Reports the current phase plate position number, numbered from 1 (Thermo/FEI scopes only) |
| ReportHighVoltage | Reports the current value of the high tension in kV. |
| ManualFilmExposure # | Sets film exposure time in seconds for manual exposures; enter 0 for automatic exposure (the default) |
| ExposeFilm | Takes a film exposure |
| SpecialExposeFilm #D [#P] [#N] | Exposes film with special handling: #D specifies a delay in seconds after loading the plate; #P specifies a pre-exposure of the specimen before exposing the plate, in seconds. #N suppresses dimming of the screen if it is nonzero. This command command does not raise the screen if it is down. It requires the adaexp server to be installed. |
| SetupScopeMessage #B [#T] [text] | Sets properties for a message box to be shown on a Thermo/FEI microscope computer with the next command. #B specifies the type of buttons: 0 for OK, 1 for OK - Cancel, 2 for Yes - No, 3 for Yes - No - Cancel. The optional #T sets the time interval between message box displays, or 0 to display it unconditionally or -1 just to set the time of display to the current time. The optional rest of the line (text) specifies the text inside the message. If you just want to specify an interval, enter ' 0 interval'; if you just want to specify text for a box to be displayed unconditionally, enter '0 0 text'. |
| ShowMessageOnScope title | Opens a message box on a Thermo/FEI microscope computer with the given title, which can include spaces. The box is displayed with the "long operation" mechanism described below, so it is possible to have it displayed only after an interval has elapsed. If SetupScopeMessage was not used, the default is for a box with an OK button, opened unconditionally, with the text "SerialEM message". When the command is finished, reportedValue1 is set with 1 if the box was displayed or 0 if it was not, and reportedValue2 is set with the reply from the box: 2 for Yes or OK, 1 for No, 0 for Cancel, or -1 for an error. |
| ReportXLensDeflector #D | Reports the X and Y values of a deflector associated with the X lens, where #D should be 1 for shift, 2 for tilt, 3 for stigmators. To use X lens commands, the adatl module must be registered and the environment variable SEM_USE_ADATL must be set to any value on the microscope, and XL mode must be turned on in the microscope interface. |
| SetXLensDeflector #D #X #Y | Sets the X and Y values of an X lens deflector, where #D is 1 for shift, 2 for tilt, 3 for stigmator. |
| ReportXLensFocus | Reports the focus setting of the X lens. |
| SetXLensFocus # | Sets the focus setting of the X lens. |
| Energy Filter Commands | |
| SetSlitWidth # | Sets energy filter slit width in eV |
| SetSlitIn [#] | Inserts the slit; or if # is entered, inserts if 1 or retracts if 0 |
| SetEnergyLoss # | Sets the energy loss to the # |
| ChangeEnergyLoss # | Changes the energy loss by the # |
| ReportEnergyFilter | Reports the slit width, energy loss, and whether the slit is in or out (the latter is placed in reportedValue3 as a 1 or 0) |
| SetJeolGIF # | Calls JEOL function to set GIF mode on (if # is nonzero) or off. |
| ReportJeolGIF | Calls JEOL function to get whether GIF mode is on. |
| Autoloader, Refrigerant, Vacuum, and FEG Commands | |
| LoadCartridge # | Loads the cartridge from the given slot # (numbered from 1) if there is an Thermo/FEI autoloader. With a JEOL autoloader, unloads a cartridge on the stage, if any, into sample storage, then loads the cartridge at the given index in the cassette inventory array. The JEOL inventory must be obtained first with 'LongOperation In'. This command starts a long operation. |
| UnloadCartridge | If there is a Thermo/FEI or JEOL autoloader, unloads the cartridge. For JEOL, an inventory must be obtained first with 'LongOperation In'. This command starts a long operation |
| ReportSlotStatus # | Reports the status of the autoloader cartridge slot or index given by # (numbered from 1).
With a Thermo/FEI autoloader, the command takes the slot number and reports a one or two values:
first -1 for an error, 0 for empty, or 1 for occupied; then possibly a name. The name is
reported if the
microscope software is running on Windows 7 or above, the TEM user interface is not minimized, and
the 'Autoloader (User)' panel (not the 'Autoloader (Service)' panel)
is included on some tab in the Workset area of the TEM user interface. The tab will be switched
to if that panel is not currently visible. Names are obtained from
the text boxes in the panel with Microsoft 'UI Automation', not with Thermo/FEI scripting
commands. See 'ReportApertureSize' if the command hangs on a Windows 7 system. When
these names are available, a value of 0 for # will retrieve the full list
of names from the panel and place them in the persistent 1-D array 'autoloaderInfo'.
With a JEOL autoloader, a cassette inventory must be obtained first with 'LongOperation In'. The command takes the index of the cartridge in the array populated by the inventory. It reports just -1 if there is no information at that index (i.e., index out of range). Otherwise it reports 6 values: the cartridge ID; where it is located (0 for unknown, 1 for magazine, 2 for storage, 3 for stage); the slot number in that location; the cartridge type (0 for unknown, 1 for regular, 2 for rotating); the angle value (0 for unknown, 1 for 0 degrees, 2 for 90 degrees, or 3 for a regular cartridge); and the name. |
| FindCartridgeWithID # | For a JEOL autoloader, reports the index in the inventory array of the cartridge whose ID is # Values are numbered from 1 and suitable for use in the 'LoadCartridge'. Value may be assigned to a variable after the ID. COmmand added in 4.1, 19-Jan-23. |
| AreDewarsFilling | Reports whether any of the dewars in a temperature control system on a Thermo/FEI scope are busy filling, or whether a SimpleOrigin system is busy filling (reportedValue1 is set to 0 or 1). Also reports if tanks are being refilled on a JEOL if the interface exists for determining that (reportedValue1 is set to 1 for stage tank plus 2 for transfer tank). Value can be assigned to a variable at end of command. |
| DewarsRemainingTime | Reports the time in seconds remaining until next automatic dewar filling on a Thermo/FEI scope or -1 if none is scheduled. On a JEOL with the JeolHasNitrogenClass property set to 2, reports the minimum of the time remaining until either the stage or transfer tank is filled. Alternatively, with a SimpleOrigin filling system, reports the seconds left until the next filling, -1 if there are no remaining refills, or -2 if the system is not active. Value can be assigned to a variable at end of command. |
| RefrigerantLevel # | Reports the refrigerant level of the dewar given by #. On a Thermo/FEI scope, # can be 1 for autoloader, 2 for column, or 3 for liquid helium; on a JEOL scope with a recent enough version of TemExt.dll and with the JeolHasNitrogenClass property set to 2, the fraction of full is reported and # can be 1 for stage tank, 2 for transfer tank, or 0 for the minimum of the two. Value can be assigned to a variable at end of command. |
| SimpleOriginStatus | Reports the number of remaining refills, the minutes until the next refill (or a negative value if there are no refills left), whether filling is underway, whether the system is active, and the sensor temperature for a SimpleOrigin system. Values can be assigned to variables at end of command. |
| SetSimpleOriginActive # | Turns the Simple Origin system off if # is zero or on if it is non-zero. |
| ReportVacuumGauge name | Reports the status and pressure reading from a vacuum gauge identified by the given name. For Thermo/FEI scopes, name is of the style accepted in the WatchGauge property; status values are 0 for undefined, 1 for underflow, 2 for overflow, 3 for invalid, and 4 for valid; pressure is in pascals. For JEOL scopes, the command requires a relatively recent version of TemExt; names can be Pir0 to Pir9 or Pen0 to Pen9; status values are 0 for not ready, 1 for low, 2 for high, and 3 for ready; and pressure values are between 0 and 1 (the value returned by the scope is divided by 4095). |
| ReportVacuumStatus | For a Thermo/FEI scope, reports the index of the vacuum status in the Microscope panel as 0 for green, 1 for yellow, or 2 for red. Command added in 4.1, 12-May-23. |
| IsPVPRunning | Reports whether the PVP is running on a Thermo/FEI scope. Value can be assigned to a variable at end of command. |
| IsFEGFlashingAdvised # | Reports whether flashing of a cold FEG is advisable on a Thermo/FEI scope, where # should be 0 for a low-temperature flash and non-zero for a high-temperature flash. FEG flashing commands are available on Thermo/FEI scopes only if there is a Selectris filter or a property entry 'AdvancedScriptingVersion 4' or higher. Value can be assigned to a variable at end of command. |
| ReportFEGBeamCurrent | Reports the beam current of the FEG in nanoamps for a Thermo/FEI scope that can flash the FEG. This command will access the value on the scope every time, not use the value that gets store for up to 5 minutes. Command added in 4.1, 20-Sept-22. | NextFEGFlashHighTemp [#] | Sets the next FEG flashing done with 'LongOperation FF' on a Thermo/FEI scope to be high-temperature, unless the option # is 0. A call for a high-temperature flash will fail unless it is advisable, so test with' IsFEGFlashingAdvised 1' first. |
| LongOperation op # [op #...] | Starts one or more time-consuming operations: op can be Buffer cycle ('Bu'), Refill
refrigerant on Thermo/FEI or SimpleOrigin ('Re'), Inventory cassettes ('In') on Thermo/FEI
or JEOL, Loader buffer cycle ('Lo'), Unload cartridge ('Un') on Thermo/FEI only, Dark
reference update for K2 (or K3 with GMS 3.31+) ('Da'), Refill Stage tank ('RS') or Refill Transfer
tank ('RT') on JEOL, or Flash FEG ('FF') on JEOL or Thermo/FEI. Operations are identified by the first two
letters of whatever full word you use (case insensitive).
Each operation except Inventory and Unload cartridge must be followed by an interval in hours (#). If # is > 0, the operation is done only if the time since the last such operation is greater than #; if # is 0, the operation is done unconditionally; if # is -1, it simply records the current time as the time of the last operation; if # is < -1, it reports the time in hours since the last operation and places it into one of the reportedValue variables. The scope operations will occur sequentially and be started in the order that they are listed. The dark reference update will be done simultaneously with scope operations. If an error occurs in a scope operation, other operations will be finished and the error reported at the end. Errors other than in refilling refrigerant will cause the script to stop. The user interface should not hang during long operations, and users will be asked to confirm that they want to kill the operation threads if they press STOP or try to exit the program. The consequences of killing these threads are uncertain. If a tank refilling on a JEOL is included in the operations, a STOP will just stop all filling. In order for time intervals to be kept track of between runs of the program, the property IgnoreShortTermCals must not be set. The command sets reportedValue1 with a return code (currently just 1 if JEOL filling timed out and was stopped) and sets reportedValue2 to 0. With a JEOL autoloader, the Inventory does three things: fills an internal program array with the information about each cartridge, prints a table to the log, and creates a persistent variable autoloaderInfo with the same information in a 2D array. Each line of the 2D array has the 6 elements described above as reported by 'ReportSlotStatus'. Both this array and the internal program array are maintained with any changes resulting from 'LoadCartridge' and 'UnloadCartridge' commands, so it should not be necessary to run a new inventory unless the program is restarted or there are external operations with the autoloader. |
| ManageDewarsAndPumps [#] | Runs the scope management routine configured in the Dewar and Vacuum Management dialog. For the optional [#], enter -1 to skip the checks that would be most useful immediately before acquisition and 1 to do just those checks. For example, the command could be run early in the acquisition cycle with a -1 and again just before acquisition with a 1. |
| Piezo Drive Commands | |
| SelectPiezo #U #Z | Selects a piezo drive for reports or movements, follow with the plugin number #U (numbered from 0, enter 0 if there is only one plugin controlling piezos) and the piezo number #Z (numbered from 0). |
| ReportPiezoXY | Reports the X and Y position of the currently selected piezo, if there is a piezo plugin loaded, or of the piezos on a JEOL stage if not. |
| ReportPiezoZ | Reports the Z position, or the position of the only axis for a single-axis piezo, of the currently selected piezo |
| MovePiezoXY #X #Y [#R] | Sets the X and Y position to #X, #Y for the currently selected piezo, if a piezo plugin is loaded, or for the piezos on a JEOL stage if not. If #R is non-zero, moves the piezo by #X, #Y. |
| MovePiezoZ #Z [#R] | Sets the Z position, or position of a single-axis piezo, to #Z for the currently selected piezo, or if #R is non-zero, moves the piezo by #Z |
Higher Level Operations and Tasks
| Autoalign-Related Commands | |
| A or AutoAlign | Aligns buffer A to autoalign buffer. The script is suspended if there is an error such as memory allocation or mismatched binnings, but if a maximum shift limit has been set with 'LimitNextAutoAlign' and there are no eligible peaks with that distance, it will set reportedValue1 to -1 instead of 0 rather than stopping the script. |
| AlignTo buf [#N] [#T] [#P] [#S] [#X] [#Y] [#W] [#B] | Aligns buffer A to given buffer buf (e.g. B or 2). Optionally, enter 1 for #N to avoid changing microscope image shift; 1 for #T to prevent trimming of dark borders; 1 for #P to force it to analyze for a periodic specimen and erase peaks in the FFT or -1 to force it not to do that analysis; and 1 for #S to show the cross-correlation or 3 or 5 to show one of the filtered images being correlated. Enter expected shifts for [#X] and [#Y], and set #W with a sigma in pixels for weighting by deviation from the expected shift (all as reported by RealignToItem with debug output 'h'); and #B with 0 for normal padding (borders), -1 for extra-large padding, and 1 for small padding. Behaves like 'AutoAlign' on errors. |
| ClearAlignment [#N] | Clears the alignment shift of the image in buffer A. Optionally, enter 1 for #N to avoid changing microscope image shift. |
| LimitNextAutoAlign # | Sets a limit in microns to the amount of shift allowed in the next run of the autoalign function. If there are no correlation peaks within that limit, no shift will be imposed. |
| AlignWithRotation buf #C #R | Finds the best alignment between buffer A and buffer buf including a rotation; #C sets the center angle for the rotation search and #R sets the total angular range of the search. reportedValue1-3 are set with the rotation angle and the X and Y shift (after rotation), in the binned pixels of the image. Values can be assigned to variables after command. |
| ConicalAlignTo buf #R [#S] | Aligns buffer A to the given buffer buf assuming a specimen rotation given by #R. Optionally, enter 1 for #S to show the cross-correlation. Behaves like 'AutoAlign' on errors. |
| AlignBetweenMags buf #CX #CY #M [#S] [#A] [#I] | Aligns buffer A to the given buffer buf with an image from another magnification
or camera, or to the regular autoalign buffer if buf is -1. If a higher
magnification image is in A, then the default behavior is to scale up and rotate a region of the reference
centered on #CX, #CY and align to that, testing a small range of additional rotations and
scalings. Enter -1 for #CX and #CY to align to the center of the reference. The
scaled reference will be left in the B buffer. The size of scaled up region is
determined by #M, which sets the maximum allowed shift in microns in the autoalignments;
if possible, the size is set so that an aligned image at that shift will still fully
overlap the scaled reference. A negative value of #M specifies the number of fields
of view to add to the size of the image in A, or equivalently the number of FOVs of shift
that can occur with full overlap. A value of -1 would make the reference about 3 times as big
as the image in A. The optional #S sets the maximum percent change in size to be tested; the default is
the value of the property 'ScaledAliDfltPctChg', which defaults to 4
to test scalings from 0.96 to 1.04. Set #A to the maximum rotation to be tested; the
default is the value of the property 'ScaledAliDfltMaxRot', which defaults to 3 degrees. Set
#I greater than 0 to suppress the change in microscope image shift. This
same procedure can also be used if the images are from the same magnification
and camera, provided that the reference has a larger field off view. If the lower magnification image is in A or a negative value is entered for #S, the higher mag image is scaled down and an area of the lower mag image is cropped out, with the center determined by #CX and #CY and the size by #M as described for the other method. A and B end up with the two images being aligned; the original image from A is left in C and the reference is left in D if it came from a rolling buffer and there are at least 4 rolling buffers. Command added in 4.2, 19-Jan-24. |
| ReportAlignTrimming | Reports the sum of left and right borders and the sum of top and bottom borders in the last autoalign for the image in A and for the reference image. The numbers are in pixels of the respective images before the additional binning applied for correlation, and will thus differ from the binned values reported by the autoalign routine. |
| ReportAlignShift | Reports the X and Y alignment shift of the current image in A in unbinned pixels on image, in nanometers along the image shift axes, and in nanometers on the specimen, where the tilt axis is along X. |
| ReportISforBufferShift | Reports the image shift that corresponds to the shift stored and displayed for the current image in A, in image shift units. These values are the same as the ones that would be imposed on the scope typically when introducing such a shift, such as by autoaligning or dragging the image with the right mouse. |
| ReportShiftDiffFrom # | Reports the difference between the alignment shift of the current image and the given value # in microns, as percentage of the value; the cumulative sum of differences in microns, and the total sum of shifts in microns. For monitoring variability in successive stage movements. |
| ReportAccumShift | Reports sum of shifts given by ReportAlignShift or ReportShiftDiffFrom |
| ResetAccumShift | Resets the sum of shifts given by ReportAlignShift or ReportShiftDiffFrom to 0 |
| Autofocus/Autotuning-Related Commands | |
| G or AutoFocus [#M] [#A] | Runs the Autofocus routine; set #M to -2 to measure shift and drift, -1 to just measure defocus without changing, or 1 for normal autofocus that changes focus to target; set optional #A to 1 or 2 to focus with the View area in Low Dose mode, 3 or 4 to focus with the Search area, or -1 to focus with the Record area. With '-1 1' or '-1 3', the measured defocus is that of the View or Search area, i.e., not adjusted for View or Search defocus offset; with '-1 2' or '-1 4' the measured defocus is adjusted for the offset to give an estimate of defocus in the Record area. |
| IncTargetDefocus # | Changes the defocus target by # |
| SetTargetDefocus # | Sets the defocus target to # |
| CycleTargetDefocus #S #E #N [#C] | Changes the defocus target in #N steps from the starting value in #S to the ending value in #E then cycles it back to the starting value. The change depends only on the current target defocus; nothing is kept track of between invocations of this command. If the target is outside the given range, the first call will set it to the nearest end of the range. If the optional #C is nonzero, the microscope defocus wll be changed by the change in target. Command added in 4.1, 4-Sept-22. |
| ReportAutofocusOffset | Reports the current value of the defocus offset used for autofocusing |
| SetAutofocusOffset # | Sets the defocus offset for autofocusing to the given #. The first time it is set, the current value is saved, and it will be restored automatically when the script ends. |
| BeamTiltDirection # | Sets beam tilt direction for autofocusing to # (a value from 0 to 3) |
| OppositeAutoFocus [#] | In low dose mode, runs autofocus in area on opposite side of Record from the defined Focus area; if optional # is -1, just measure defocus without changing. Not available if 'Balance Shifts' is on. |
| FocusChangeLimits # # | Sets limits on the focus change during autofocus runs for the remainder of the script; follow with a negative and a positive number for the limits in microns. When an autofocus run exceeds a limit, it will abort and return to the starting defocus. Enter with '0 0' to cancel these limits. |
| AbsoluteFocusLimits # # | Sets limits on the absolute focus reached during autofocus runs. Follow with a lower and a upper limit as given by ReportAbsoluteFocus, or '0 0' to cancel these limits. Autofocus will abort when a limit is exceeded. These values will override the absolute limits that can be specified through the Focus menu, but a '0 0' will not prevent those limits from being applied. |
| ReportFocusDrift | Reports the drift estimate from the last autofocus, if available |
| ReportAutoFocus | Reports measured defocus from last autofocus, or whether it failed. The defocus is placed into reportedValue1 and a failure code in reportedValue2 (1 for inconsistent focus, 2 for absolute limits exceeded, 3 for focus change limits exceeded, or -1 for other error). |
| ReportTargetDefocus | Reports the defocus target |
| FixAstigmatismByCTF [#M] [#L] [#S] | Measures astigmatism by CTF fitting, outputs the stigmation change to the log, and corrects for those values (or just measures, if the optional #M is nonzero). Image shift is set to 0 unless the optional #L is non-zero. Set optional #S non-zero to suppress the message box on errors that occur after starting to take images. |
| FixComaByCTF [#M] [#L] [#F] [#S] | Measures beam-tilt misalignment by CTF fitting, outputs beam tilt change needed to the log, and corrects for it (or just measures, if the optional #M is nonzero). Image shift is set to 0 unless the optional #L is non-zero. The user setting for whether to do a full array of images is used unless optional #F is 0 for 5 images or > 0 for a full array. Set optional #S non-zero to suppress the message box on errors that occur after starting to take images. |
| CalibrateComaVsIS [#D] [#R] [#F] | Calibrates the beam tilt needed to fix coma as a function of image shift. The maximum distance in microns and rotation angle set in the Coma vs. Image Shift Calibration dialog will be used, unless the optional #D is entered with the maximum distance, and #R is entered with the rotation angle. The choice in the dialog for whether to do a full array of positions for the coma measurements will also be used, unless #F is entered with -1 to use the same choice as for fixing coma, 0 not to use a full array, or 1 to use a full array. (Enter 0 for the distance to modify just the rotation angle; enter -999 for rotation angle to set the full array option.) Command added in 4.1, 15-Dec-22. |
| CorrectAstigmatism [#] | Measures astigmatism by beam-tilt-induced displacements (BTID), outputs the stigmator values to the log, and corrects for those values (or do not correct, if the optional # is -1) |
| CorrectComa [#] | Measures beam-tilt misalignment by beam-tilt-induced displacements (BTID), outputs the estimated beam tilt to the log, and corrects to bring beam tilt to zero. If the optional # is -1, it will simply measure the misalignment once and report it without correcting it. If the # is 1, it will do another iteration of estimating beam tilt and average the result with the previous iterations. |
| ReportStigmatorNeeded | Reports the needed stigmator change in X and Y that was measured only, but not imposed, after running 'FixAstigmatismByCTF 1' or 'CorrectAstigmatism 1'. The last run of either astigmatism routine must be by one of these commands; otherwise it will return 0 and 0. |
| ReportComaTiltNeeded | Reports the needed change in X and Y beam tilt that was measured only, but not imposed, after running 'FixComaByCTF 1'. If the last run of the coma routine applied rather than just measured the tilt, it will return 0 and 0. |
| ZemlinTableau #T [#S] [#C] | Makes an array of 8 FFTs of beam-tilted images around a central FFT without beam tilt. The first value #T specifies the beam tilt to use, in milliradians on a Thermo/FEI scope or percent of full scale on other scopes. The optional entry #S sets the cropped size of each FFT in the array (default 340) and #C sets the number of pixels to crop (default 170). See Beam-Tilted FFT Array for other details. |
| ReportComaVsISmatrix | Reports the matrix computed from the
Coma vs. Image Shift
calibration. The 4 values are xpx, xpy, ypx, and ypy, where the change in
beam tilt for a given image shift (in IS units) is given by BTx = ISx * xpx + ISy * xpy BTy = ISx * ypx + ISy * ypy |
| AdjustBeamTiltforIS | Adjusts beam tilt to compensate for the current image shift (as displayed in the Scope Status panel), provided that the Coma vs. Image Shift calibration has been done. This command saves the current beam tilt, if it has not been saved before in the script, and it will be automatically restored when the script exits. Astigmatism will also be adjusted if that calibration includes an astigmatism estimate, unless the property 'SkipAstigAdjustmentForIS' is set. |
| CBAstigComa #T #C #A [#L] [#S] | FOR TESTING: Runs the routine for astigmatism and coma by CTF fitting. Set #T 0 for astigmatism, 1 for coma with 5 images, 2 for coma with full array; #C 0/1 to measure/calibrate; #A 0 to apply a measurement, 1 to just measure, 2 to measure from images in the buffers; #L non-zero to leave image shift as it is; #S non-zero to suppress the message box on errors that occur after starting to take images. |
| Low Dose Commands | |
| GoToLowDoseArea area | Switches to the low dose area given by area, which must be one of V, F, T, R, or S. This will not work if the screen is down. |
| SetLowDoseMode # | Turns low dose mode on for # nonzero or off for # 0; the previous state of low dose is saved in reportedValue1 as a 0 or 1. This value can be assigned to a variable at the end of the command. |
| ReportLowDose | Reports whether low dose is on or not and the current area, if it is defined. The number of the area (0 for V, etc.) is placed in reportedValue2. |
| UpdateLowDoseParams area [#K] | Activates continuous update of the area given by area; whenever necessary to reflect changes made by the script to any of the parameters that are recorded when 'Continuous update' is on the Low Dose panel. Specifically, the area is updated to the current parameters if it is the current area when this command is given (thus recording changes made before this entry), and also updated thereafter whenever one of the commands are used to change a relevant parameter. Set the optional #K non-zero to keep the parameter changes when the script ends; otherwise the parameters saved when this command is first given will be restored on script end. area must be one of V, F, T, R, or S. |
| CopyLowDoseArea from area | Copies parameters of low dose area from to the given area, both of which must be one of V, F, T, R, or S. The copying is the same as when one of the copy buttons is used in the Low Dose control panel. Low Dose must be on, area cannot be the same as from, and you cannot copy to the current area. The current area need not be set yet, i.e., if Low Dose has just been turned on. Command added in 4.1, 12-May-23. |
| SetLDAddedBeamButton [#] | Turns the 'Set' button in the Low Dose panel for recording additional beam shift on, or turns it off if the optional # is 0. The original state of the button will be restored on script end. |
| RestoreLowDoseParams [area] | Restores parameters saved for the given area when 'UpdateLowDoseParams' was entered for this area. Omit area to restore parameters for all areas, including ones marked to be kept when the script ends. |
| SetLDContinuousUpdate # | Turns "Continuous update" in the Low Dose panel on if # is non-zero or off if # is 0. Continuous update is not active while any script is running. If it is on, microscope parameter changes will have no effect on Low Dose settings during a script, but when the script ends, changes will update the current Low Dose area. |
| ReportAxisPosition area | Reports the axis position in microns and the rotation of the inter-area axis, for the given area: F (Focus) or T (Trial). The offset from center of the camera acquisition subarea is also reported in unbinned pixels (in left-handed camera coordinates). |
| SetAxisPosition area #D [#R] | Modifies the axis position, and optionally the rotation of the inter-area axis, for the Focus and/or Trial area. Follow with 'F' or 'T' to specify the area (both will be changed if Focus and Trial settings are being kept identical); with #D, the distance in microns; and optionally with #R, a rotation angle. If an angle is set, the option to apply the angle will be turned on in the Low Dose control panel. Low dose mode must be on to use this command. |
| ReportLDDefocusOffset area | Reports the defocus offset for the given area: 'V' for View or 'S' for Search. Command added in 4.2, 17-Aug-24. |
| SetLDDefocusOffset area #O | Sets the defocus offset to #O in microns for the given area: 'V' for View or 'S' for Search. Command added in 4.2, 17-Aug-24. |
| CurrentSettingsToLDArea area | Sets the parameters for low dose area given by area, which must be one of V, F, T, R, or S, from the current microscope settings. It must be run while not in low dose mode and after adjusting to scope state to the desired settings for the area. It clears out the parameters for the area, enters low dose mode, and goes to the area so that it is assigned the current state. |
| FindLowDoseShiftOffset #S [#M] [#S] [#A] | Runs a routine to determine the Low Dose View or Search shift offset if #S is 0 or 1 respectively, using the alignment method invoked by the 'AlignBetweenMagnifications' command. Preview is used to find the View offset, so there must be unique features for alignment present in a Preview. The higher magnification image is scaled down, so it does not need a particularly good signal-to-noise ratio. If no other values are entered, they are all taken from the values set with the Setup Auto Shift button in the Low Dose control panel. The lower magnification image is cropped based on the maximum allowed shift specified by #M: either a positive distance in microns, or the negative fraction of the field of view of the lower magnification image. Enter 0 for the value set for the particular image type in Setup Auto Shift. A lower limit may be needed if there are periodic features like holes. The maximum percent size change and rotation angle to be searched can be entered with #S and #A; otherwise the values set in Setup Auto Shift are used (enter -1 for #S to use a value set there and enter a specific value for #A. Command added in 4.2, 16-Feb-24. |
| RevertAutoLDShiftOffset | Restores a Low Dose shift offset to the value it had before the last use of 'FindLowDoseShiftOffset'. Command added in 4.2, 16-Feb-24. |
| ReportLDShiftOffset # | Reports the View shift offset if # is 0, the Search offset if # is 1, or the change in shift offset in the last use of 'FindLowDoseShiftOffset' if # is negative. Command added in 4.2, 16-Feb-24. |
| SetLowDoseShiftOffset # | Sets the View shift offset if # is 0 or the Search offset if # is 1. Command added in 4.2, 16-Feb-24. |
| Multiple Record-Related Commands | |
| MultipleRecords [#N] [#C] [#O] [#D] [#S] [#E] [#F] [#B] [#H] [#R2] [#N2] [#O2] | Acquires multiple Record images around the periphery of a hole and/or in multiple holes, using image
shift to move to each off-center position. The parameters set in the
Multiple Record Setup dialog control the
operation of this task, but any subset of them can be overridden by entering
optional parameters here. The value in the dialog is used if -9 is entered
for the corresponding parameter here, or if the optional entries end before the
given parameter. The parameters are: 1) #N for number of shots around the center 2) #C -1 or 1 for a shot in the center before or after the off-center shots, or 0 for none 3) #O for the distance from center of the off-center shots, in microns 4) #D for the extra delay after the image shift, in seconds 5) #S 1 to save a Record image at each position or 0 not to 6) #E 1 or 2 to use early return for a K2/K3 camera after the last shot or after all shots, or 3 for early return on all shots with a full sum returned on the first one 7) #F for the number of frames in the early returned image (or -1 for all, 0 for none) 8) #B 1 to adjust beam tilt to compensate for image shift or 0 not to 9) #H the sum of 1 to do shots around a center (within a hole) and 2 to do shots in multiple holes or specified positions. (In addition, the sum in #H can include 4 for testing image locations or 8 for testing the coma correction, plus 16 to force it to use a regular array of holes, 32 to force it to use custom holes, 64 to force it not to use a cross pattern, or 128 to force it to use a cross pattern if the hole pattern is 3 x 3. Note that arithmetic is allowed, so you can enter each flag separately with + signs and spaces between them) 10) #R2 greater than 0 to do a second ring of positions 11) #N2 with the number of positions in the second ring 12) #O2 for the distance from center of the second ring For example, 'MultipleRecords -9 -9 -9 4. 1' will use an extra delay of 4 seconds and save Records, but take all other parameters from the dialog. When the operation starts successfully, ReportedValue1 is set to the total number of Record images to be taken. |
| SetMultiShotParams #N [#C] [#O] [#D] [#S] [#E] [#F] [#B] [#H] [#R2] [#N2] [#O2] [#X #Y] [#DH] | Sets parameters for Multiple Records persistently. The first 12 parameters have
exactly the same meaning as for the 'MultipleRecords' command, except that the
entry for #H can be the sum of 1, 2, 16 or 32, and 64 or 128. In addition: 13-14) #X and #Y with the number of shots in X and Y for a rectangular pattern, or with the number of rings and -1 for a hexagonal array 15) Additional delay when moving between holes. Enter -9 for any parameter to skip setting it. Command added in 4.2, 18-Jan-24. |
| NextMultiShotUseNavItem [#] | Makes the next Multiple Records acquisition use the hole array specification and the list of holes to skip stored in the current Navigator item, or the item indicated by the optional #, which can be 0 for the current item, an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. This command has no effect if the Multiple Records are taken by the Navigator during Acquire at Items. Command added in 4.2, 3-Sep-24. |
| ReportMultishotParams # | Sets reportedvalues with particular parameters: With # set to 1: 1) number of shots in first ring inside hole; 2) -1, 0, or 1 for shot in center; 3) radius of ring; 4) 1 to do a second ring or 0 not; 5) number of shots in second ring; 6) radius of ring. With # set to 2: 1&2) number of holes in X and Y for rectangular pattern, -3 and -3 for a cross pattern, number of rings and -1 for a hexagonal pattern, or number of positions and 0 for a custom pattern; 3) sum of 1 for shots in hole, 2 for multiple holes, and 4 for custom holes; 4) 1 to save Records or 0 not to; 5) 0-3 for controlling early returns; 6) number of frames in early return. With # set to 3: 1) extra delay after image shift; 2) extra delay when moving between holes. Command added in 4.2, 18-Jan-24. |
| TestNextMultiShot # | Sets a variable so that the next MultipleRecords command will test image location by acquiring a Record or montage at each location (if # is 1) or by measuring coma at each location (if # is 2). See Testing Image Location and Coma Adjustment for details on this testing. |
| StageToLastMultiHole | Moves the stage to the center of the last hole position acquired with MultipleRecords. This command can be used to position over a hole for occasional post-acquisition tasks when using a hole pattern centered on the support film. There is no backlash correction. |
| ImageShiftToLastMultiHole | Changes image shift by the offset to the last hole position acquired with MultipleRecords. This command combined with 'ResetImageShift' will be more accurate than 'StageToLastMultiHole' if backlash correction is needed and enabled in the Image Alignment & Focus control panel. |
| RotateMultiShotPattern #A [#C] | Rotates the hole positions in the pattern set up in the Multiple Record Setup dialog by angle #A. Set optional #C positive to rotate the custom pattern or negative to rotate the hexagonal pattern instead of the regular one. Generates an error if the selected pattern is not defined or the needed transformation is not available. |
| AdjustMultiShotPattern # | Applies an adjusting transformation to a set of image shifts for multiple Records: to the regular rectangular array vectors if # is 0, or to hexagonal array vectors or custom shifts if # is -1 or 1, respectively. The transformation is the one recorded the last time that the Step To and Adjust IS procedure was run in the Multiple Record Setup dialog. Generates an error if the selected vectors are not defined, if they were defined in a way that provides enough information for them to be adjusted, if there is no adjusting transform, if this transformation was already applied, or if the magnification at which the given vectors were defined does not match the starting magnification of the adjusting transformation. Command added in 4.1, 9-Jul-23. |
| StepAndAdjustISVectors #M #D [#S] | Runs the 'Step and Adjust IS' procedure with #M set to 0 to use cross-correlation or 1 to use hole finding and centering, #D set to the hole diameter in microns, and optional #S to the maximum shift as a fraction of the hole size. Enter -1 for any of these to use the value in the Step To and Adjust IS Setup dialog. Other parameters are taken from existing settings for Multiple Records and Hole Finder. Command added in 4.2, 29-Oct-24. |
| OpenMultiShotFiles name | Opens a set of files, one for each of the positions specified in the current settings of the Multiple Record Setup dialog (which need not be open). The file names will be based on name (which can include a full path), with each name being rootname_ShotPosition.ext, where rootname and ext are the root and extension of name, amd ShotPosition is the same text used to label frame files from different positions. After this command is given, and until the files are closed with the next command, the Multiple Record routine will save the image at each position into its respective file, regardless of whether saving is selected in the dialog. This command is intended to allow parallel tilt series but is probably not useful until a more sophisticated alignment procedure is added. Command added in 4.1, 23-Apr-22. |
| CloseMultiShotFiles | Closes the set of files opened with 'OpenMultiShotFiles' and returns the Multiple Record routine to its normal operation of saving into a single file if at all. Command added in 4.1, 23-Apr-22. |
| SetCustomHoleShifts xvar yvar [#M] [#T] | Defines the custom hole shifts for multiple Records with the image shift values in two array variables, xvar and yvar, with the X and Y components, respectively. The optional entries #M and #T can specify the magnification index and tilt angle at which the image shift values apply (enter 0 for #M to specify a tilt angle without changing the magnification index). Command added in 4.1, 5-Sept-2. |
| SetCustomHoleDefocus var | Defines a defocus offset to be applied for each custom hole position to be acquired with the Multiple Records routine. If there are fewer defocus values than hole positions, the offset will be zero for the remaining positions. Command added in 4.1, 5-Sept-22. |
| SetRegularHoleVectors #X1 #Y1 #X2 #Y2 [#M] [#T] [#X3] [#Y3] | Defines the image shifts for multiple Records taken with a regular pattern with #X1, #Y1 specifying the X and Y components of image shift between adjacent holes in one direction and #X2, #Y2 specifying the shift in the orthogonal direction. The optional entries #M and #T can specify the magnification index and tilt angle at which the image shift values apply. For vectors of a hex grid, enter the third vector in #X3, #Y3. Enter 0 for #M to not change the magnification index, and -999 for #T to not change the tilt angle. Command added in 4.1, 1-Dec-22; hex added 7-Jan-24. |
| ReportMultishotVectors # | Reports the image shift vectors (in IS units) between holes in the X and Y directions for a rectangular pattern (if # is 0) and in three directions for a hexagonal pattern (if # is nonzero). Command added in 4.1, 2-Aug-23. |
| Other Task-Related Commands | |
| ResetImageShift [#B] [#R] | Resets image shift and move stage to compensate. Follow with a 1 or 2 for the optional #B to move the stage so as to retain or impose backlash, even if the user has not selected the option to do so in the Image Alignment & Focus control panel. With a value of 2, it will relax from the stage movement by the amount given in the optional #R, or by the value of the StageRelaxation property (0.025 by default). |
| ResetShiftIfAbove # | Resets image shift and realign image if image shift is greater than the given # in microns |
| Eucentricity [#W] [#V] | Refines eucentricity, or if optional #W is entered, do rough eucentricity only (1), refine only (2), both steps (3), refine and realign (6), or Eucentricity by Focus (-1). In the latter case, whether View is used to measure defocus in Low Dose mode depends on the setting in the Eucentricity by Focus Setup dialog, unless #V is entered as a 0 to use Focus or non-zero to use View. |
| LimitNextRoughEucen # | Limit the Z change in the next rough eucentricity run to #, stopping the procedure without changing Z when it would exceed that amount. |
| ReportRoughEucenFailed | Sets reportedValue1 to 1 if the last run of rough eucentricity failed because the Z change would have exceeded the limit set with 'LimitNextRoughEucen'. |
| ReportLastAxisOffset | Reports the total lateral offset of the tilt axis estimated from the last Refine Eucentricity run; aborts the script if no offset is available. |
| SetTiltAxisOffset # | Sets the lateral offset of the tilt axis to #. |
| WalkUpTo # | Tilts up to given angle in steps and track image position |
| ReverseTilt [#] | Works out backlash and realign image after reversing tilt direction; enter optional 1 or -1 to specify a specific direction for further tilts |
| RefineZLP [#I] [#T] | Reports time of day and runs Refine Zero Loss Peak procedure. If the optional #I is entered with an interval in minutes, the procedure is not run if the time since the last run is less than that interval. If the optional #T has a positive value, the procedure is run with Trial in Low Dose; if it has a negative value, the procedure is run with Preview; otherwise it is governed by the selection in the Filter Control panel. |
| AutoCenterBeam [#M] [#P] | Starts the Beam Autocenter routine. The optional #M sets a maximum beam shift in microns; the beam will not be moved if the shift determined from the circle fit to the beam edges exceeds this value. If the optional [#P] is set to 0 or a positive number, autocentering will be done using View with the specified percentage reduction in beam size; this may be useful for finding a badly mis-centered beam. The program must already be in Low Dose mode to use this option. |
| CookSpecimen | Runs the Specimen Cooker routine |
| WaitForDose #D [#R] | Starts accumulating dose and wait until it reaches the given #D in electrons per square Angstrom. Enter the optional #R to set how many times it reports progress while waiting (default is 10). Be sure that the screen is down and, if in low dose, that the beam is unblanked. |
| CenterBeamFromImage [#C] [#M] | Centers beam using the existing image in the active buffer by detecting the edges of the beam, or from the centroid of the image intensities if #C is nonzero. In the latter case the beam should be completely within the camera field. The optional #M sets a maximum beam shift in microns; the beam will not be moved if the shift determined from the circle fit to the beam edges exceeds this value. Sets reportedValue1 to -1 if no beam edges are detected, 5 if there is a failure fitting edges to a circle, 6 if beam was not moved because the radius was too high, and 7 if the beam was not moved because the fitting error was too high. |
| MeasureBeamSize [buf] | Measures the beam diameter by detecting its edges in the image in buffer A, or in the buffer given by the optional buf. The value is reported in microns. |
| MeasureBeamPosition [buf] | Measures the beam position by detecting its edges in the image in buffer A, or in the buffer given by the optional buf. Reports the X and Y offset of the position from image center in pixels (Y inverted), the number of quadrant with points found, and the fitting error. |
| MeasureBeamEllipse [buf] | Reports the offset from the center (with Y inverted), the long and shirt axis lengths, and the angle of the long axis (counterclockwise from the X axis) for an elliptical beam, using the centroid and second moments of image pixels above a threshold. The beam should be completely within the image for the measurement to be valid. Command added in 4.1, 6-Jul-22. |
| BacklashAdjust | Runs the routine to adjust for backlash by taking an image, applying the current montaging backlash, and aligning a new image to the original image. |
| DriftWaitTask [#R] [unit] [#M] [#I] [#G] [type] [#C] [#E] [#B] | Runs the Wait for Drift task using parameters set in the Wait for Drift Setup dialog if there are no optional entries. Any optional entry that is not zero overrides the parameter set in the dialog; enter a 0 to use the dialog setting for any parameter. The parameters are: #R for target drift rate; unit 'nm' or 'A'; #M for maximum time to wait in sec; #I for interval over which drift is measured in sec; #G 1 to generate an error when maximum time reached or -1 not to; type for type of measurement (T for Trial, F for Focus, A for within autofocus runs, or 0 for dialog setting); #C to correct drift with image shift; #E for Trial exposure, #B for Trial binning. |
| GetWaitTaskDrift | Places the final drift measurement from the last Wait for Drift task into reportedValue1 and a non-zero number if the task failed in reportedValue2. Values can be assigned to variables after command. |
| ConditionPhasePlate [#] | Runs the routine to condition a phase plate using parameters set in the Phase Plate Conditioning Setup dialog. If the optional # is non-zero, it will move to the next phase plate position first, provided this is supported by scripting on the microscope. |
| CalibrateImageShift [#] | Calibrates image shift at the current mag. Do the calibration from scratch if the optional # is nonzero. |
| ShiftCalSkipLensNorm [#] | Keeps projector lens normalization from being done before the next image or stage shift calibration provided that normalization was last done at the current magnification. Set the optional # to 0 to NOT skip normalization. |
| CalibrateHighFocusIS #D [#C] | Runs the High-Defocus Image Shift Calibration routine and stores the result with the defocus given by #D Set the optional #C to an amount to change defocus before starting; it is not restored afterwards. Command added in 4.1, 4-Jan-23. |
| CalibrateHighFocusMag #C | Runs the High-Defocus Mag Calibration routine and asks for confirmation that the calibration is good if #C is 1, or skips the confirmation and just stores the result if #C is 0. The script stops if an error is encountered or if the calibration is not accepted as good. Sets reportedValue1 and reportedValue2 with scale and rotation stored in the calibration. Images must already exist in buffer A and the autoalign buffer. Command added in 4.2, 27-Apr-24. |
| FindPixelSize | Runs the routine to find the pixel size in an image of a cross-line grating. If buffer A contains a montage center and B has a montage overview, B will be copied to A first. Sets reportedValue1 and 2 with the unbinned pixel size in nm and the grid angle; these can be assigned to variables at the end of the command. |
| AutoCorrPeakVectors buf #S [#T] [#D] | Analyzes the autocorrelation of the image in buffer buf with the pixel size routine and reports the average spacing between periodic features and the X and Y components of the vectors along the first then second axis. These values are in pixels of the image, not unbinned pixels. The entry #S should contain the expected spacing, which can be a rough value because it used only to determine the amount of image binning and does not affect the search for peaks. The optional #T can be set non-zero to skip trimming of dark borders, and #D can be set non-zero to skip displaying the autocorrelation. |
| QuickFlyback set #E | Runs the camera timing calibration routine in quick flyback mode for a Thermo/FEI STEM camera, where 'set' specifies the camera parameter set and must be V, F, T, R, or P, and #E is the exposure time to use. The routine will not ask for confirmation before saving the resulting flyback time and startup delay in the master list of flyback times. |
| ShiftImageForDrift #X #Y #U | Applies image shift during the next exposure to compensate for a drift in X and Y given by #X and #Y; #U should be 0 if the drift is in unbinned pixels/sec and 1 if it is in nm/sec |
| GetDoseSymmetricAngles var | Fills an array variable var with the list of angles for the currently defined dose-symmetric tilt series. The program must be in Low Dose mode and a dose-symmetric series must be specified in the current tilt series parameters; the Tilt Series Setup dialog must have been opened at least once and postponed. Command added in 4.1 28-Jun-23. |
| SetDoseSymmetricAngles var | Modifies the list of angles for a dose-symmetric series with the angles in the array variable var. Parameters must already be set, as for 'GetDoseSymmetricAngles'; the new list must have the same number of angles as the old one; and reversals of direction must all happen at the same places as originally (i.e., group sizes must be the same). The original list is restored whenever the dose-symmetric setup dialog is opened, and can be restored by using this command with a variable having a single value in it. Command added in 4.1 28-Jun-23. |
| Navigator Window and List Commands | ||
| ReportIfNavOpen | Reports whether the Navigator is open; sets reportedValue1 to 1 if it is open and 2 if there is a Navigator file defined. Virtually all of the commands described in this section will generate an error if the Navigator is not open. | |
| OpenNavigator [name] | Opens the Navigator window, which must not already be open unless there are no items defined. If the optional name is entered, this file is set as the Navigator file to save to. | |
| CloseNavigator | Closes the Navigator window, which must be open. If there are unsaved changes and the Autosave Nav File option is not on, the user will be asked whether to save. | |
| SaveNavigator [name] | If the optional name is not present, saves the Navigator data to the current file or opens a file chooser for saving if a file is not yet defined, unless there are no items defined. If a name is entered, it saves to this file instead. | |
| ReadNavFile name | Reads in the Navigator file with the given name, opening the Navigator if necessary. If there are unsaved changes in the Navigator, the user is asked whether to save those first as usual. A cancel from that, or an error opening, reading, or processing the file will generate an error message. | |
| MergeNavFile name | Merges the Navigator file with the given name into the current items in the Navigator, which must be open. An error opening, reading, or processing the file will generate an error message. | |
| ReportNavFile [#] | Reports the name of current Navigator file or generates an error if the Navigator is not open with a file defined. Sets the full name into reportedValue1; or if the optional # is entered with a 1, sets the root of the filename including the path in reportedValue1, the extension (including the dot) in reportedValue2, the path only in reportedValue3, and the rest of the rootname in reportedValue4. No optional assignment to variable. | |
| ReportNumTableItems | Reports the number of items in the Navigator table. | |
| NavIndexWithLabel text | Reports the index in the Navigator table of the item whose label is the given text, or 0 if there is none. Sets reportedValue1 with the index. The string can contain spaces and the comparison is not case-sensitive. | |
| NavIndexWithNote text | Reports the Navigator index of the item whose note is the given text, otherwise just like ItemIndexWithLabel. | |
| NavIndexItemDrawnOn # | Reports the Navigator index of the map that the specified item was drawn on, or 0 if it was not drawn on a map. For #, enter 0 for the current item or the item being acquired; an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. | |
| SetNavRegistration # | Sets the current registration of the Navigator window to the given number. No item registration values are changed. | |
| ReportLastMarkerShift | Reports the registration and shift in X and Y of the last Shift to Marker operation, or just 0 for the registration if no shift has been done or it was undone. | |
| Item and Group Commands | ||
| MoveToNavItem [#] | Moves the stage to a Navigator item; if no # is entered, move to the current Navigator item or to the item that this script is being run on, otherwise move to the item whose index in the table is # (numbered from 1) | |
| NavGoToMarker | Moves the stage to the position of the marker point in the active image. The Navigator must be open, there must be a marker point, and other conditions required to enable Go To Marker in the Navigator window must be satisfied. Command added in 4.2, 7-Aug-24. | |
| UpdateItemZ [#] | Assigns current stage Z value to the current Navigator item, or the item that this script is being run on, or the item whose index in the table is given by the optional # (numbered from 1). | |
| UpdateGroupZ [#] | Assigns current stage Z value to the whole group of either the current Navigator item, the item that this script is being run on, or the next item to be acquired if the optional [#] is non-zero. The item must have a non-zero group ID. Acquisition must be running to assign to the next group. If the group would show up on more than one line with 'Collapse groups' on, items on all lines will be updated, unlike with the 'Update Z' button. | |
| LoadNavMap [buf] | Loads the current Navigator item, or the item this script is being run on, if it is a map. If the optional buf is entered, loads to that buffer instead of the read buffer. | |
| LoadOtherMap # [buf] | Loads the Navigator item whose index in the table is #, if it is a map; or if # is negative, loads the item that many items from the end of the table, i.e., -1 loads on the last item. If the optional buf is entered, loads to that buffer instead of the read buffer. | |
| LoadAllGridMaps [buf] | When a session is defined for multiple grid operations and some grid maps have been obtained, loads all the maps available for the collection of grids, starting at the buffer given in [buf] if possible, but shifting the range of buffers used to hold as many maps as possible and to start after rolling buffers if possible. The default is to start after the read buffer. When there are no grid maps available or no session open, the program will find all the maps in the current navigator file at the lowest magnification and load them, as long as they were taken in LM mode. See the menu item Load All Grid Maps Command added in 4.2, 7-Aug-24. | |
| ReportNavItem | Reports in the log the index, stage X, Y, Z, label, and note string for the current
Navigator item, or the item this script is being run on. The index and stage
coordinates are placed in reportedValue variables as usual, and the item type
is placed in reportedValue5; (0 for point, 1 for polygon, 2 for map). In
addition, these named variables are set:
navLabel and navNote are set with the label and note strings, navIndex and navIntLabel are set with integer values of the item index (numbered from 1) and of the label (up to any non-numeric characters), navRegis is set with the item's registration value, navColor is set with the item's color (a value from 0 to 5), navNumHoles is set with the number of holes that would be acquired by 'MultipleRecords' with current parameters, or 0 if the item is not marked for Acquire. navAcqIndex is set with the number of items already acquired plus 1 If the Navigator is currently acquiring at items. Any of these variables can then be used to make filenames, and the latter three can be used in arithmetic and IF statements. |
|
| ReportOtherItem # | Reports similarly on the Navigator item whose index in the table is #, numbered from 1; or if # is negative, reports on item that many items from the end of the table, i.e., -1 reports on the last item. | |
| ReportNextNavAcqItem | Reports similarly on the next Navigator item to be acquired. The Navigator must be acquiring. If the last item is being acquired, navIndex is set to -1, and reportedValue1 and 2 are set to -1 and 0. | |
| ReportGroupStatus | For the current Navigator item or the item this script is being run on, reports a code for whether the item is first to be acquired in a group: -1 if Navigator not acquiring, 0 if not in a group, 1 if first to be acquired in a group, 2 if later in the group. If the group would show up on more than one line with 'Collapse groups' on, a value of 1 is returned for the first item to be acquired in each subgroup. It also reports the group ID of the item (ID is 0 for an item not in a group), the total number in the group, and the number in the group still marked for acquisition. | |
| SetSelectedNavItem #I [#D] | Makes Navigator item #I (numbered from 1) be the current item in the Navigator table and the only selected item; set optional #D non-zero to suppress redrawing the display. Command added in 4.2, 15-Feb-24. | |
| ReportItemImageCoords [#I] [buf] | Reports the pixel coordinates of navigator item #I on the image in buffer buf. If no #I is specified, the current item is used, negative numbers are items counted from the end of the list. If no buffer buf is specified, the image in buffer A is used. The X and Y coordinates are returned in reportedValue1 and 2, reportedValue3 is set to 0 if item #I is outside the buffer or to -1 if the transformation can not be completed. | |
| GetItemPointArray #I xvar yvar | Fills the variables xvar and yvar with the X and Y stage coordinates in the point array for the current Navigator item or the one being acquired if #I is 0, or for the item whose index in the table is #I if #I is positive, or that number of items from the end if it is negative. Command added in 4.2, 30-Jan-24. | |
| GetNavGroupStageCoords #I xvar yvar [zvar] | Returns the stage coordinates of all Navigator points with the group ID #I into variables named xvar and yvar, and also returns the Z coordinates if the optional name zvar is provided. Sets reportedValue1 to the number of points found, including 0 if none found. Command added in 4.1, 31-Oct-22. | |
| GetNavGroupImageCoords #I buf xvar yvar | Returns the image coordinates of all Navigator points within the image in buffer buf and having the group ID #I, placing them in variables named xvar and yvar. Sets reportedValue1 to the number of points found, including 0 if none found within the bounds of the image, and -1 if stage positions could not be transformed for this image. Command added in 4.1, 31-Oct-22; | |
| ChangeItemRegistration #I #R | Changes the registration number of the Navigator item with table index #I to #R. This works just like the Navigator menu entry Change Registration: the registration number must be in the legal range, the item cannot be a registration point, and you cannot change an item between imported and regular registrations. | |
| ChangeItemColor #I #C | Changes the color index of the Navigator item with table index #I to #C, which must be between 0 and 5. (0 = red; 1 = green; 2 = blue; 3 = yellow; 4 = magenta; 5 = no realign) | |
| ChangeItemGroupID #I #G | Changes the group ID of the Navigator item with table index #I to #G, which must not be negative. If groups are collapsed, the whole table is refilled, which can be time-consuming if more than a few items are being operated on in a loop. In that case, use the command 'SuspendNavRedraw' to prevent updating the table until all items are changed. Command added in 4.1, 19-Apr-2023. | |
| ChangeItemDraw #I [#D] | Changes if the Navigator item with table index #I is drawn or not. If no #D is specified, the option is toggled, if #D is 0, drawing is disabled, any other numeric values for #D enable drawing. | |
| ChangeItemLabel #I text | Changes the label of the Navigator item with table index #I to the given text. The text is limited to 16 characters; items with labels longer than 10 characters will not display their properties in the right columns in the table. | |
| ChangeItemNote #I [text] | Changes the note of the Navigator item with table index #I to the given text or deletes the note if text is not specified. | |
| SetMapAcquireState #I [#S] | Sets the state with which the specified map item was acquired. For #I, enter 0 for the current item or the item being acquired; an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. The optional #S determines whether taking frames is allowed in the camera parameter set; 0 allows frames to be saved, 1 (the default) turns off frame saving but allows frame aligning; 2 turns off aligning also. | |
| GoToImagingState name | Sets an imaging state listed in the table of the Imaging States dialog, which need not be open. The text on the rest of the line, name, can be either the full name of the state, a unique set of starting letters in the name of the state, or the number of the state in the table (numbered from 1). The comparison with state names is case-insensitive. If the command fails, a message is printed to the log and reportedValue1 is set to 1 for no matching name, 2 for more than one matching name, 3 for a number out of range, 4 if a map acquire state is already set, 5 if the camera that the state is defined for is not available, or 6 if it is a Low Dose state and there is already a state set with a different camera number. Command added in 4.1, 15-Sept-22. | |
| RestoreState [#] | Restores the state if one has been saved with 'SetMapAcquireState' or 'GoToImagingState' or with the Imaging States dialog. Set the optional # non-zero to generate an error if no state was saved. | |
| ForgetPriorState [#] | Forgets a state if one has been saved with 'SetMapAcquireState' or 'GoToImagingState' or with the Imaging States dialog, equivalent to pressing Forget Prior State in that dialog. Set the optional # non-zero to generate an error if no state was saved. Command added in 4.1, 16-Nov-22 | |
| OpenImagingStateDialog | Opens the Imaging States dialog if it is not already open. Command added in 4.1, 15-Sept-22. | |
| SkipPiecesOutsideItem #I | Sets the current montage to skip pieces outside the Navigator item whose position in the table is #I (numbered from 1). If #I is 0, uses the current item. If #I is < 0, disables the skipping of pieces. | |
| NavItemFileToOpen # | Reports the name of the file set to be opened for the specified Navigator item. Sets reportedValue1 to the filename or to 0 if there is none, and sets deereportedValue2 to 1 if there is a file or 0 if there is none. For #, enter 0 for the current item; an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. The command will not work for the item being acquired, as the stored name is cleared out when the file is opened. | |
| ItemForSuperCoord # | Sets the item number that Navigator supplies supermontage coordinates from when a montage image is acquired. Sets the number to 0 to restore Navigator to using coordinates from the item currently being acquired. | |
| SetItemTargetDefocus #I #D | Sets the target defocus to #D for the Navigator item specified by #I (positive for table index, 0 for current or acquired item, or negative for index from end). The item must be marked for acquisition or a tilt series. The target is not restored after acquisition, so the target would then apply for the next single image acquisition but be superceded by the value in the parameters for the next tilt series. If this command is used in a script run before the main action, the target will apply in a script or tilt series but not to an autofocus done by the Navigator before the main action. Items with this value set will have a line including 'F targ' and the target in the listing produced by the Navigator menu item List Files/Series/States. When TS Params is pressed for an item with this set, the target defocus that shows in setup dialog will be the one in the parameter set, which may apply to many tilt series, and not this set value. The label after the target will be um* to indicate that it is being overridden. | |
| SetItemSeriesAngles #I #S #E [#B] | Sets the starting and ending tilt series angles to #S and #E and optionally sets the bidirectional starting angle to #B for the Navigator item specified by #I (positive for table index, 0 for current or acquired item, or negative for index from end). The item must be marked for tilt series acquisition. The command can be used in a script run before the tilt series. In the listing produced by the Navigator menu item List Files/Series/States, the tilt series angles specified by this command will be shown, with a '*' to indicate the override. When TS Params is pressed for an item with angles set, the angles that appear in setup dialog will be the ones in the parameter set, which may apply to many tilt series, and not these set values. There will be a * after the text box to indicate that they are being overridden. | |
| SetNavItemUserValue #I #V [text] | Sets an arbitrary value for a Navigator item specified by #I (positive for table index, 0 for current or acquired item, or negative for index from end). Up to 8 user values are currently allowed, with a number from 1 to 8 specified by #V (numbers do not have to be used sequentially). The text on the rest of the line is assigned as the value after variable substitution but not arithmetic; text can be omitted to clear out a value. | |
| ReportItemUserValue #I #V | Reports an arbitrary value set for the Navigator item specified by #I (positive for table index, 0 for current or acquired item, or negative for index from end), or 'none' if no value is set. Sets reportedValue1 with the text value. | |
| Hole and Grid Square Finding Commands | ||
| FindHoles [buf] | Runs the Hole Finder routine on the image in the current buffer, or in the buffer optionally specified by buf, using all of the parameters set in the Hole Finder dialog. That dialog need not be open, but the Navigator must be. | |
| MakeNavPointsAtHoles [#A] [#L] [#U] [#S] [#B] [#E] [#H] | Makes positions found by the Hole Finder into Navigator points, using the various thresholds for exclusion set in the Hole Finder dialog. That dialog need not be open, but the Navigator must be. Optionally, #A may be entered with 0 to 2 to specify the arrangement of points (0 for zigzag, 1 for away from focus, 2 for divided into groups, or -1 to use the layout set in the dialog); #L and #U may be entered to set alternative lower and/or upper mean thresholds for excluding points (enter -999999 for #L or #U to use the dialog setting); #S may be entered to set the SD cutoff (or -1 to use the dialog value); #B may be entered to set the cutoff for the percentage of black pixels; #E may be entered to set the edge distance cutoff; and #H may be entered to use a 1/3 subset of points on a hex grid. | |
| ClearHoleFinder | Removes the display of points found by the Hole Finder and frees its memory. | |
| CombineHolesToMulti #S [#O] [#X #Y] | Combines a set of Navigator points marked for acquisition into a subset suitable for acquisition of a rectangular array with 'MultipleRecords', using the parameters set in the Multiple Record Setup dialog. See the Multiple Hole Combiner dialog for details and restrictions. Neither of those two dialogs need to be open, but the Navigator must be. Set #S to 0 to select points on the currently displayed image, 1 to select points within the current polygon, or 2 to select points in the same group as the current point. Set the optional #O to 1 to turn off points outside a polygon in the same groups as the ones combined, or 0 not to, overriding the selection in the dialog, or -1 to use the dialog setting. To override the number of holes specified in the dialog, add both #X and #Y with either the number of holes in X and Y in a rectangular pattern, or -3 and -3 for a cross pattern, or -1 and the number of rings in a hexagonal pattern. | |
| UndoHoleCombining | Removes the multi-shot acquisition points created by the last hole-combining operation (through script command or dialog) and restores the individual points to the Navigator table. All of the multi-shot points must still exist. | |
| ReportHoleFinderParams | Reports the diameter and center-to-center spacing in microns currently being used for hole finding, whether it is set to analyze for a hexagonal array, and the maximum error. | |
| SetHoleFinderParams #D #S #H [#M] [fvar] [tvar] | Sets the parameters for hole finding to #D for the diameter and #S for the center-to-center spacing in microns and sets it to analyze for a hexagonal array if #H is non-zero, in which case the hex-specific size and spacing are set. The maximum error is set with the optional #M if it is positive. If fvar is included with the name of an array variable, it is used to set the filter sigma values and median iterations (positive values for sigma, or negative number of iterations). If tvar is included with the name of an array variable, it is used to set the thresholds (use 'NONE' for fvar to set just the thresholds). Command added in 4.1, 30-Jan-23. | |
| FindMultiMapHoles #S #E #C | Runs a routine to find holes for all maps at one magnification with Navigator table indexes between #S and #E inclusive, and combining the resulting points for Multiple Records if there are at least #C points, or not combining if #C is 0. See Finding Holes in Multiple Maps for details. Command added in 4.2, 7-Aug-24. | |
| FindAndCenterOneHole buf #D [#C] [#S] | Runs the Hole Finder with parameters appropriate for finding the hole nearest to the center of an image with one or a few holes in it, and optionally centering on the hole with image shift. buf specifies the buffer and can be 0 for the currently displayed image. Set #D to the diameter in microns; optional #C to the number of circle sizes to try, or 0 for the default (generally 7); and optional#S to the maximum image shift allowed as a fraction of the hole diameter. Other hole-finding parameters such as geometry and spacing are taken from existing settings. Command added in 4.2, 29-Oct-24. | |
| ReportLastHoleVectors # | Reports the vectors between holes along the two axes from the last hole finding operation in one of 3 forms. If # is 0, the vectors are in stage coordinates, adjusted for View or Search defocus offset if there is a high-magnification defocus calibration. If # is negative, the vectors are in image coordinates, with Y inverted. If # is a magnification index, the vectors are in image shift coordinates at the given magnification. | |
| UseHoleVectorsForMulti [#] | Converts the vectors between holes from the last hole finding operation to image shift values and assigns them as the hole vectors for doing multiple records in a regular pattern of holes. If the optional [#] is absent or 0, the values are computed for the current Low Dose Record magnification; if it is positive, the vectors are computed for the given magnification index; if it is -1, they are computed for the magnification at which hole IS vectors were last defined; if it is < -1, they are computed for the magnification of the image in which holes were detected. The magnification associated with the image shift vectors in the multiple Record parameters is set to whatever value is used here, and the tilt angle stored in the parameters is that of the image in which holes were found. Use -2 to be able to apply a stored adjusting transformation to the vectors. | |
| UseMapItemHoleVectors # | For the Navigator item indicated by # (0 for current item or item being acquired, positive for index in table, negative for distance from end of table), assigns image shift values stored when holes were found on an associated image as the vectors for doing multiple records in a regular pattern of holes. If the given item is not a map, shift values are sought in the map that item was drawn on. This command has the same effect as running 'UseHoleVectorsFromMulti -2' when holes were first found. Command added in 4.1, 10-Jul-23. | |
| UseNavGroupForMultishot #K [#X] [#Y] | Converts the relative stage positions of items in the currently selected Navigator group, or the group currently being acquired if acquiring, to hole image shift vectors of the kind specified by #K: 0 for a regular rectangular pattern, 1 for a hexagonal pattern, or 2 for a custom pattern. There must be 4, 6, or at least 2 points in the group, respectively, and points in a rectangle or hexagon must occur in a regular progression around the pattern. Enter the optional #X and #Y to specify the number of holes in each direction over which these points apply for a regular pattern, or #X to specify the number of rings for a hexagonal pattern; otherwise the values in the Multiple Record dialog apply. Command added in 4.1, 18-Oct-23. | |
| AutoContourGridSquares buf [#R] [#H] [#T] [#S] [#L] [#P] | Finds areas above a threshold in the image in [buf] and makes contours around them, then divides them into groups
that are displayed in different colors, depending on the elimination criteria and settings in the
Autocontouring Grid Squares dialog, which need not be open. The
autocontouring routines in the IMOD model library are used and take byte input,
so the image will be scaled to bytes using the Black and White values in Image Display control panel. If
an optional input is omitted or negative, the value from the dialog will be used. Optional inputs are: #R - Either a pixel size in microns (if < 10) or a target size in pixels (if > 10) for image reduction. Some reduction is needed both to reduce noise and to speed up the processing, but too much reduction will give inaccurate contours. Whole grid maps should be reduced to ~1500-2000 pixels; a pixel size of ~1.2 um is useful. #H - Fraction used for setting a threshold based on a histogram analysis that finds two peak values in a bimodal distribution of image intensities. The contouring threshold is set to the given fractional distance between the peaks. If the analysis fails to find two peaks, a specific threshold must be set instead. #T - A specific threshold to use instead of doing a histogram analysis; enter 0 for #H and enter either an actual intensity value in the displayed image (a value > 1), or a relative threshold, the fraction of the way between the Black and White values in the current display. This value is ignored if #H is nonzero. #S - Smallest size, in microns, for an area; the square of this value is used to set the minimum area to retain as a polygon. #L - Largest size, in microns, for an area; again, the square is used to set the maximum area to retain as a polygon. #P - 1 to contour inside current polygon if any, or 0 not to. Command added in 4.1, 16-Nov-22; no longer makes Navigator polygons, 23-Dec-22. |
|
| SetAutocontourGroups #N #W [#O...] | Sets the number of groups of grid square contours with #N and the way in which contours are sorted into groups with #W (0 for size or 1 for mean). This can be followed by a series values to set the option to show a group on (1) or off (0); values need not be entered for all groups. Any of these entries can be -1 to leave the existing setting unchanged. This command modifies the user settings for these items, and if the Autocontouring Grid Squares dialog is open it will reflect these changes. Command added in 4.1, 9-Mar-23. | |
| ReportAutocontourStats | Reports the minimum, maximum, and median intensity inside of the current set of grid squares found with 'AutoContourGridSquares'. Command added in 4.1, 9-Mar-23. | |
| MakePolygonsAtSquares [#L] [#U] [#M] [#S] [#I] [#B] | Converts the current set of grid squares found with 'AutoContourGridSquares' to Navigator
polygons, equivalent to pushing the Make Polygons button in the
Autocontouring Grid Squares dialog. The values from the
dialog, or stored settings, are used for the various cutoffs, but they can be overridden by these optional
entries: (enter -1 for any of these to use the dialog or stored value instead:
#L - Lower mean cutoff, either an absolute value > 1, or a value between 0 and 1 for a relative cutoff, the fraction of the way between the minimum and median mean (which corresponds to the fractional position of the slider in the dialog). #U - Upper mean cutoff, either an absolute value > 1, or a value between 0 and 1 for a relative cutoff, the fraction of the way between the median and maximum mean. # - Minimum size cutoff in microns. # - Maximum SD cutoff. # - Maximum irregularity cutoff. # - Minimum border distance, in microns. |
|
| Other Item Generating Commands | ||
| NewMap [#N text] | Makes a new Navigator map from the current image in buffer A or the current montage with overview in buffer B. A montage must belong to the current open file; a single image in A must have been saved already, or be savable in the current file. If an optional #N is entered, text after that replaces, or is added to, the standard note for a map. text replaces the standard note if #N is 0, is added before it if #N is < 0, or is added after it if #N > 0. Places the index of the new map in reportedValue1. | |
| MakeAnchorMap | Calls the routine to make an anchor map and does the same tests and operations as when run from the button in the dialog, including saving the current image and making it a map if it is not already. | |
| GetUniqueNavID | Creates an ID value unique from any current Navigator items and places it in reportedValue1; it can be assigned to a variable after the command. The ID can be used with 'AddStagePosAsNavPoint' and 'AddImagePosAsNavPoint' to assign multiple points to a group. Command added in 4.1, 6-Jul-22 | |
| AdjustStagePosForNav #SX #SY [#IX #IY] [#C] [#M] [#T] | Adjusts a stage position #SX, #SY so that it is suitable for assigning to a Navigator item, accounting for the optional image shift values in #IX, #IY, with possible adjustments for tilt axis offset and image shift offsets. and a tilt angle given in the optional #T. These adjustments depend on the active camera number, which can be entered #C (numbered from 1, use -1 for current camera), on the magnification index, which can be entered with #M (use -1 for current magnification), and on the tilt angle, which can be entered with #T and defaults to the current angle. Command added in 4.1, 6-Jul-22. | |
| AddStagePosAsNavPoint #X #Y #Z [#I] [#D] | Adds a single stage position in #X, #Y, adjusted with 'AdjustStagePosForNav', as a Navigator point item with the Z value given by #Z. A group ID can be assigned with the optional #I, otherwise it will be 0. The optional #D can be set non-zero to suppress redrawing the display. Sets reportedValue1 with the index of the new item. Command added in 4.1, 6-Jul-22. | |
| AddStagePointsAsPolygon xvar yvar #Z [#D] | Adds the adjusted stage positions in two arrays, xvar and yvar, as a polygon item. The Z position must be supplied in #Z. The optional #D can be set non-zero to suppress redrawing the display. Sets reportedValue1 with the index of the new item. Command added in 4.1, 6-Jul-22. | |
| AddImagePosAsNavPoint buf #X #Y [#Z] [#I] [#D] | Adds a new Navigator point item with the position #X, #Y (Y inverted) in the image in buffer buf, with Z taken the stage Z position of the image, or from the optional #Z if it is greater than -990. If the image is a montage, the position must be valid for the way that it is currently displayed, i.e., with regular, very sloppy, or no alignment. A group ID can be assigned with the optional #I, otherwise it will be 0. The optional #D can be set non-zero to suppress redrawing the display. Sets reportedValue1 with the index of the new item. Command added in 4.1, 6-Jul-22. | |
| AddImagePointsAsPolygon buf xvar yvar [#Z] [#D] | Adds the image positions on the buffer buf in two arrays, xvar and yvar (Y inverted) as a polygon item. The points for 'AddImagePosAsNavPoint' about image alignment, Z position, drawing, and reportedValue1 apply here. Command added in 4.1, 6-Jul-22. | |
| AddCirclePolygon #R [#X #Y] | Adds a circle polygon with a radius #R in microns at stage position #X, #Y, or at the marker position if #X and #Y is omitted Command added in 4.1, 21-Jun-23. | |
| DeleteNavigatorItem # | Removes the Navigator item specified by #I (positive for table index, 0 for current item, or negative for index from end; this command cannot be used while acquiring. Command added in 4.1, 6-Jul-22. | |
| Alignment and Shift Commands | ||
| RealignToNavItem #R [#C] [#S #N #Z] [#P] | Realigns to the current Navigator item, or to the item that this script is being
run on. For #R, enter 1 to restore the microscope state to the current state after the procedure, or 0 not to. For optional #C, enter 1 to use continuous acquisition mode and end it at end of procedure, or 2 to leave it running if possible. The three optional entries #S, #N, #Z control the resetting of image shift at the end of the procedure when aligning to a single map. (Entries in the Navigator Align Setup dialog do not apply here). It will reset image shift and move the stage to compensate, realigning with a new image up to #N times and if the starting shift is more than the criterion #S. Enter 0 or 1 for #Z to end with nonzero or zero image shift, respectively, i.e. with the image realigned or with a final image shift reset and stage movement. This procedure occurs only if realignment is to a single map or a scaled map at a low enough magnification. All three values must be entered if any are, plus a value for #C. An entry of 0 for #N and 1 for #Z will make it move the stage to the target position and skip the regular realignment there. Enter -1 for any of these values to use the corresponding setting in the Navigator Align Setup dialog. Unlike more recent commands, these settings do not apply as defaults if none of these arguments are entered. The optional entry [#P] indicates a camera parameter set to use for a third round of alignment to a scaled-up extract from the map. It can be P, R, V, or S. |
|
| RealignToOtherItem #I #R [#C] [#S #N #Z] [#P] | Realigns to the Navigator item whose index in the table is #I, numbered from 1. Other entries are as described for 'RealignToNavItem'. | |
| RealignToMapDrawnOn #I #R | Centers on the specified item by first realigning to the map that the item was drawn on, then using image shift to center on the marked item. The specified item must have been drawn on a higher-magnification map that can be aligned to in two rounds using some lower mignification map, such as an anchor map. For #I, enter 0 for the current item or the item being acquired; an index greater than 0 for the item with that index in the table; or a value less than 0 to count back from the end of the table, where -1 is the last item. For #R, enter 1 to restore the microscope state to the current state after the procedure, or 0 not to. | |
| GetRealignToItemError | Gets the total stage error in X and Y and the second move error in X and Y from the last Realign to Item and assigns them to reportedValue1-4 and to optional variables included after the command. | |
| ForceCenterRealign | Makes Realign to Item align to the map center instead of skipping the first round because it was aligned to recently. | |
| SkipZMoveNextNavRealign [#] | Makes the Realign to Item routine leave Z unchanged when moving to the item's position for the next Realign run from a script, or turns off this flag if the optional # is 0 Command added in 4.1, 26-Feb-23. | |
| AlignToTemplate [#S] [#R] [#M] [#L] [label] | Runs the Align to Template routine using the parameters set in the Navigator Align Setup dialog, which can be modified by optional entries: #S with the maximum shift in the alignment in microns, #R with a threshold value in microns for resetting IS, moving the stage, and realigning, #M with the maximum number of times to reset IS or 0 not to, #L with 1 to leave IS at 0 (skip last realign) or 0 not to, and label as the label of the Navigator item to use as a template. For any of the numbers, enter -1 to use the value from the dialog. | |
| RealignReloadedGrid #I #E [#Z] [#R] [#T] | Runs a procedure to align a grid that has been reloaded or rotated to a montage map and transforms
Navigator items to a new registration. The procedure picks a montage piece near the stage
center and 4 pieces 3/4 of the way out from the map center in 4 directions, testing 4 pieces in
the vicinity to try to avoid particularly dark ones. Then it aligns to the center piece
with a rotation search, uses the result to refine the position at which to seek the peripheral
pieces, and aligns to those with the rotation corrected. From the 5 positions, it solves
for a transformation with rotation and shift. Finally, by default, it transforms items from the current
registration to a new one. #I specifies the maps and can be its index in the table, 0 for the current item, or the negative of the distance from the end of the table. #E specifies the expected rotation and should be 0 for mesh grids that might already have some small rotation (to make sure that it aligns to a map extract twice the size of piece, which should be more robust with grid bars present). The optional #Z can be set to 1 to set the stage Z to that of the map,or 0 not to. #R can be set with the maximum rotation to be tested in the search; 0 or a negative or no value will make it use the value set by the property 'GridReloadMaxRotation', whose default is 15 degrees. (If there is a known starting rotation from a previous reload that could make a difference, increase the search range.) Set #T to 0 to prevent transforming of items. The transformation is kept track of so the procedure can be run repeatedly. The routine has not yet been tested with large (i.e., 90 degree) rotations. Command added in 4.2, 16-Apr-24. |
|
| ShiftItemsByAlignment | Shifts items at the current registration by the alignment shift of the image in buffer A. If rerun on the same image, it applies the change in shift between the current and previous run. | |
| ShiftItemsByCurrentDiff # | Shifts items at the current registration by the difference between the current stage position and the recorded position of the current Navigator item or the item that this script is being run on. The shift is done only if the difference is less than the # in microns. | |
| ShiftItemsByMicrons #X #Y [#R] [#M] | Shifts items at the current registration, or at the registration given by the optional #R, by the amount in microns in #X and #Y. Each component of the shift must be less than 100 microns. Enter 1 for #M (and -1 for #R for the current registration) to have the shift stored in the items just like when running Shift to Marker. | |
| AlignAndTransformItems #C #R [#L] | Performs the image alignment and Navigator item transformation that can be done interactively in the Align with Rotation dialog. The same conditions apply here as in that dialog: there must be either a single-frame image in buffer A or a montage overview in buffer B at the current registration, and a map in the buffer for read-in images at a different registration. #C sets the center angle of the rotational search, and #R sets the total angular range to be searched. Set the optional #L to a limit for an acceptable rotation angle; above this, items will not be transformed. After finding the alignment, items at the registration of the map will be transformed to the current registration. | |
| Acquisition Control Commands | ||
| ReportIfNavAcquiring | Reports 1 if the Navigator is acquiring at items or 0 if not, and sets reportedValue2 with value for the state: 0 if not acquiring, 2 if paused, 3 or 4 if a tilt series is running or stopped, 5 or 6 if a script before or after a tilt series is running or stopped, 7 or 8 if a script started by the Navigator is running or stopped. Command added in 4.1, 6-Sep-23. | |
| ReportNumNavAcquire | Reports the number of Navigator items marked for Acquire and marked for Tilt Series as two values; returns each as -1 if Navigator is not open. | |
| ReportNumHoleAcquire [#M] [#S] [#E] | Reports the total number of hole positions that would be acquired at, the number of Navigator items moved to, and the total number of Record images by acquiring with 'MultipleRecords', based on current Multiple Record parameters and the number of hole positions specified for individual items. If the optional #M is set with a minimum number of holes, the totals will omit any items that have fewer than that number of hole position remaining after excluding some holes in the pattern. If the optional #S and #E are set with starting and ending item numbers in the Navigator table (numbered from 1), totals will include only items within those limits. Each value is returned as -1 if Navigator is not open. | |
| GetItemHolesToAcquire # var | Places the hole pattern geometry and indexes of holes to be acquired in variable var for the current item if # is 0, or the item whose index is specified in # with a positive or negative number (as in ReportItemAcquire). The item must have a stored hole pattern. The first two elements of the array are the number of positions n1 and n2 in the first and second direction for a rectangular pattern, -3, -3 for a cross (a subset of 3x3), or -1 and the number of rings for a hexagonal pattern. Following that are pairs of position indexes, in the order in which they would be acquired according to the current settings. For a rectangular pattern, each pair is the index of a position in the first direction and its index in the second direction, numbered from 0. The effective index of the center of the pattern is (n1 - 1) / 2., (n2 - 1) / 2. For a hexagonal pattern, the first index is the ring number (0 for the center), and the second index is the position in the ring, where position 0 is along the first hexagonal image shift vector. Command added in 4.1, 3-Aug-23. | |
| ReportItemAcquire [#] | Reports the Acquire state of the Navigator item whose index in the table is #, numbered from 1; or if # is negative, reports on item that many items from the end of the table (i.e., -1 reports on the last item), or if 0 or no # is specified, reports on the current item. | |
| SetItemAcquire [#I] [#A] | Enables or disables Acquire for a Navigator item: if #A is 0, Acquire is disabled, if this parameter is not specified or nonzero, Acquire becomes enabled. The item index is specified by #I with a positive or negative number (as in ReportItemAcquire); if 0 or no #I is specified the current item is changed. Acquire may not be turned on for an item marked for a tilt series. If this command is used from within a running acquisition for an item within the range from the current acquisition point to the end of the range being acquired, it can only turn Acquire off, not on. The end of the range is the original end of the Navigator table when acquisition was started, or the end of the subset if one is being acquired. | |
| ReportTiltSeriesAtItem # | Reports whether the item specified by # is set for a tilt series; set # 0 for the current item, positive for the index of the item in the table, or negative for the item that many items from the end of the table. Also sets reportedValue2 to 0 for now so that Python returns a tuple. Command added in 4.1, 1-Oct-23. | |
| SetTiltSeriesAtItem [#I] [#T] | Enables or disables a tilt series for a Navigator item: if #T is 0, a tilt series is disabled, if this parameter is not specified or nonzero, a tilt series is set up. The item index is specified by #I with a positive or negative number (as in ReportItemAcquire); if 0 or no #I is specified the current item is changed. Sets reportedValue1to 1 if the item is set for a tilt series and 0 if not; the latter is the value if the user cancels a dialog. A tilt series may not be set up for an item marked for Acquire. If acquisition is running, the same restrictions apply as in 'SetItemAcquire'. Command added in 4.1, 6-Sep-23. | |
| SkipNavPointsNearEdge #S #E #D [#E] [xvar yvar] | Finds the distance from a boundary for Navigator points from starting index #S to ending index #E and sets ones less than the distance in #D (in microns) or outside the boundary to not be acquired. The X and Y coordinates of boundary points can be entered with the optional variables xvar and yvar. If a boundary is not entered, the convex hull of all of the points will be used for the boundary, as in the Hole Finder dialog, or points not already marked as Acquire will be excluded from the analysis if the optional #E is non-zero. Command added in 4.1, 24-May-23. | |
| SkipAcquiringNavItem [#T] | Tells the Navigator to skip the current item and move on to the next. This command has an effect only when included in a script being run as a preliminary action before the main action. The item will still be marked for Acquire unless the optional #T is nonzero. | |
| SkipAcquiringGroup [#I] [#T] | Tells the Navigator to skip points whose group ID match either the group ID of the current acquire item, or the optional #I entered with the command. The items will still be marked for Acquire unless the optional #T is nonzero (in this case, enter 0 for #I to use the ID of the current item). The Navigator must be acquiring at points. | |
| EndAcquireAtItems [#] | Stops Navigator acquisition after the current item, equivalent to pressing 'End Nav' in the Camera & Script control panel. Acquisition must be either running or paused. Set the optional # to 1 to suppress the popup message about number of items acquire and 2 to also allow running a script set to run at the end, which is otherwise skipped. Command added in 4.1, 12-May-23. | |
| SkipMoveInNavAcquire [#] | Tells the Navigator to enable skipping the initial stage move for each following item to be acquired. This command is allowed only when the Navigator is already acquiring at items. It does not affect the user's selection in the Acquire at Items dialog for whether to skip this stage move. Thus a script that is going to use Realign to Item on each point can skip the stage move and there is no need for the user to make this selection. | |
| StartNavAcquireAtEnd | Starts the Navigator Acquire at Items operation after the script ends successfully, using the parameters last defined in the Navigator Acquire dialog. The command cannot be used when Navigator is already acquiring or a tilt series is running. | |
| NavAcqAtEndUseParams kind [file] | Selects the parameter set to use when starting Navigator acquisition with 'StartNavAcquireAtEnd' and copies parameters into temporary structures so that they can be modified without affecting the user's settings. kind should be 'M' or 'm' for Mapping, 'F' or 'f' for Final Data, or 'R' or 'r' to read from a file of saved parameters, in which case file should be entered with the filename. | |
| SetNavAcqAtEndParams opt val [opt val ...] | Sets values in the temporary Navigator acquire parameters set up by 'NavAcqAtEndUseParams', which must be used first. Multiple pairs of options
and values can be entered sequentially; this command can also be entered multiple
times. An option name can be longer than what is shown here. Thus far, these options can be specified: prim: set primary action with 0 for saving images, 1 for saving maps 2 to run a script, 3 to run tilt series, or 4 to do multiple Records scrp-p: set script number for primary action scrp-b: set script number to run before primary action, or 0 not to run a script scrp-a: set script number to run after primary action, or 0 not to run a script |
|
| RunScriptAfterNavAcquire # | Sets up for the script numbered # to be run after successful completion of the next Navigator Acquire at Items operation. | |
| SuffixForExtraFile suffix [suffix] [suffix] [...] | Sets one or more suffixes so that the Acquire at Items routine will open the corresponding number of extra files whenever it opens a regular file for output. Follow with the suffixes, separated by spaces (and thus a suffix cannot contain a space). An entry here overrides the corresponding entry in the Tilt Series Extra Output dialog; see the help there for details. The suffixes entered here are not persistent and the command needs to be included in a script run before the main action. | |
| Time-Related Commands | |
| ReportClock | Reports seconds elapsed since last ResetClock command |
| ResetClock | Resets the time reported by ReportClock to 0 |
| ReportMinuteTime | Reports an absolute time in minutes, a large integer. The difference between two such values will give an elapsed time in minutes. If a variable name is included after the command, the value will automatically be assigned to a persistent variable so that it is available across multiple runs of the script. |
| SetCustomTime name [#M] | Stores an absolute time in minutes in a 'custom time' with the given name. The current time is stored, or the time given by the optional #M. Custom times are stored in the short-term calibration file, like the times since the last long operations of various kinds. They can be used to perform actions periodically during Navigator acquisitions. Entries older than 20000 minutes will be removed when the file is read on program startup. |
| ReportCustomInterval name [#M] | Reports the time elapsed, in minutes, from the custom time with the given name to either the current time or the absolute time in minutes given by optional #M. If a time with that name has not be set, an interval of 40000 is returned. No optional assignment to variable. |
| ReportTickTime | Reports the time in seconds since the program started, like the times that prefix program debug output. The difference between two such values will give an elapsed time in seconds with nominal millisecond precision, as long as the program has been running for fewer than 50 days. If a variable name is included after the command, the value will automatically be assigned to a persistent variable so that it is available across multiple runs of the script. |
| ElapsedTickTime #S | Reports the time in seconds since the tick time given in #S, which should be a variable assigned with the result from 'ReportTickTime'. This command should be used to measure intervals between tick times if there is any chance that the program will run for more than 50 days. The value can be assigned to a variable at the end of the command. |
| ReportDateTime | Reports a numeric date in the form YYYYMMDD and a time to the minute in the form HHMM. |
| ProgramTimeStamps [#S] [#O] | Prints the program version and build date, plus the current date and time, or the date and time of program startup if the optional #S is positive. If the optional #O is nonzero, it also prints the report of special options set that is printed on program startup. If #s is negative, it prints only the current date and time. |
| Graphing Commands | These commands are used to display graphs using the Genhstplt program in IMOD. See Additional Packages for GPU and Python Support, and for Displaying Graphs and Using Ctfplotter for details on how to make this program available to SerialEM. This program opens a plotting window that can be resized. Right-clicking within the window brings up a menu allowing one to save the graph to a PNG file or print it (if there is a printer available). All commands here were added in 4.1, 27-Oct-22. |
| GraphValuesInArrays #T var1 [var2 ...] | Graphs values provided in a set of 1-D array variables var1, var2, etc,
where the a non-zero value of #T specifies that the first variable contains type
identifiers for graphing by type. These type numbers can be arbitrary numbers but must
be integers. The data are loaded
into a matrix and individual value variables (i.e, other than a type variable) correspond to columns
in the matrix. When there are no types, the default is to plot each column past the
first one versus the first column, all in one graph. If the 'ordinal' option is
given with the 'SetGraphOptions' command, all columns would be plotted versus their
index in the array. The 'SetGraphColumns' command can be used to plot specific
columns instead of all of them. When there are types, only two columns can be plotted, or only one if 'ordinal' is set. Either this command must contain only that number of value variables, or 'SetGraphColumns' must be used to set that number of columns. The various options set by the commands below are all cleared at the start of a script and after each graphing command. |
| GraphPreStoredValues #T | Graphs values that have already been stored, using types if #T is non-zero Values are stored for possible reuse whenever the 'GraphValuesInArrays' command is used. In addition, specific operations may store values for graphing (so far, just the 'ListISVectorsToGraph' command). |
| SetGraphTypes # [# ...] | Sets the list of data types to plot in the next graphing command If only one type is provided, its values will be plotted versus their index in the array. |
| SetGraphColumns # [# ...] | Sets the list of columns to be plotted in the next graphing command, numbered from 1. Columns after the first one will each be plotted versus the first column. |
| SetGraphSymbols # [# ...] | Sets a list of symbols to be substituted for the default ones in the next graphing command These can be numbers from -1 to 19: open and filled square (1 & 2), open and filled diamond (3 & 4), open and filled triangle (5 & 6), X and + (7 & 8), open and filled circle (9 & 10), open and filled inverted triangle (11 & 12), U (13), S (14), circle with vertical line (15), small dot (18), and horizontal line (19). In addition, 0 gives no symbol and -1 shows the point number for each data value instead of a symbol. |
| SetGraphOptions opt [#] [opt] [#]... |
This command can set multiple options by having a list of keywords, each one followed by
0, 1, or 2 values: ordinal Plot each data type or column versus each point's index in the data array (can be abbreviated to 'ord') connect Draw lines connecting successive data values (can be abbreviated 'con') color # Use colors for symbols, lines, and key label. If # is 0, the colors will be used in their fixed order (starting with dark blue, dark red, dark green, and magenta, with black not occurring until the 8th color). With a non-zero value of #, that curve will be drawn in black instead of its default color. xlog # Take the log of the X values after adding the base value in # xsqrt # Take the log of the Y values after adding the base value in # ylog # Take the square root of the X values after adding the base value in # ysqrt # Take the square root of the Y values after adding the base value in # xrange #L #H Set the range of the X axis with low and high values given by #L and #H yrange #L #H Set the range of the X axis with low and high values given by #L and #H Note that when taking the log or square root, the base value is used prevent negative numbers as well as to control the relative compression of the axis at the high end. The numeric labels on the axis correspond to values after, not before, this operation. |
| SetGraphAxisLabel text | Sets the label for the X axis in the next graph. |
| SetGraphKeyLabel text | Sets one label to appear after a symbol in the key on the right in the bext graph. This command can be used multiple times, once for each type or column being graphed. |
| SaveNextGraphAndExit #T file | Makes the next graph be saved in file as a PNG or a compressed TIFF if #T is 0 or non-zero, respectively, then exits the graph program. The filename should have the appropriate extension; it is not added automatically. Saving as TIFF requires IMOD 4.12.55 or higher. If you want to read in the graph to display in SerialEM, it must be a TIFF, and you should delay at least 2 seconds before trying to read it. Command added in 4.1, 19-Oct-23. |
| CloseAllGraphs | This command will close all graph windows that are still open. |
| GetLastTiltXYZToGraph | Stores the X/Y/Z values from the last tilt series in the graphing arrays, with tilt angles in column 1 and X, Y, Z values in columns 2-4. | Scale Matrix Commands | These commands output the 4 elements of the various scale matrices used to
convert between 4 different kinds of positional coordinates: camera coordinates in right-handed unbinned pixels; 'specimen' coordinates in microns, a right-handed rectilinear system with the X axis along the tilt axis; IS (image shift or projector shift) coordinates in their basic units; stage coordinates in microns. They report 4 values that specify an amount of change in a coordinate being scaled to per unit of change in a coordinate being scaled from, namely X per X, X per Y, Y per X, and Y per Y in that order. The coordinate transformation is Xout = Xin * XperX + Yin * XperY Yout = Xin * YperX + Yin * YperY All commands return a matrix for the current camera where relevant, and all require an entry #M for the magnification index, or 0 to use the current index. Variables to assign to can be placed after this entry. All of the matrices involving the camera apply to unbinned pixels from the camera unless a binning is provided with the 'BinningForCameraMatrix' command. Specifically, for a K2 or K3, the matrices are in terms of super-resolution pixels and will not give the correct result when applied to physical pixels (binning 1) or if scaled by the binning reported for an image; this problem can be avoided with 'BinningForCameraMatrix'. |
| ISToCameraMatrix #M | Converts from image shift or projector shift to camera coordinates |
| CameraToISMatrix #M | Converts from camera to image shift or projector shift coordinates |
| CameraToStageMatrix #M | Converts from camera to stage coordinates |
| StageToCameraMatrix #M | Converts from stage to camera coordinates. |
| ISToSpecimenMatrix #M | Converts from image shift or projector shift to specimen coordinates. |
| SpecimenToISMatrix #M | Converts from specimen to image shift or projector shift coordinates. |
| SpecimenToCameraMatrix #M | Converts from specimen to camera coordinates. |
| CameraToSpecimenMatrix #M | Converts from camera to specimen coordinates. |
| ISToStageMatrix #M | Converts from image shift or projector shift to stage coordinates. |
| StageToISMatrix #M | Converts from stage to image shift or projector shift coordinates. |
| SpecimenToStageMatrix #M | Converts from specimen to stage coordinates. The matrix should have two terms near 0 and two terms near +/-1. |
| StageToSpecimenMatrix #M | Converts from stage to specimen coordinates. |
| BinningForCameraMatrix # | Sets the binning to which one of the 6 matrices involving 'camera' will be scaled, so that the matrix applies to coordinates in an image of that binning. Enter 0 for # to disable the scaling. Command added in 4.2, 30-Sep-24. |
| Process-Running Commands | |
| RunInShell command | Runs the given command with the system command processor. It appears that any command that will run in a Command Prompt window can be run. Thus commands can include: '|' to pipe from one program to another; '&' to run successive programs unconditionally; '&&' or '||' to run successive programs conditionally; '> outfile' to redirect standard output to a file, '2> errfile' to redirect standard error output to a file, or '> outfile 2>&1' to redirect both to one file. Single arguments like filenames that contain spaces should be enclosed in double quotes. The exit status of the command will be placed in reportedValue1; if it is -1, this indicates an error before running the command, and reportedValue2 will be set with the following values: 1 if argument list too big, 2 or 3 if command interpreter cannot be found or is not executable, 4 for insufficient memory or other memory problem, 5 for unidentified error. In any case, a non-zero exit status will not be considered a script error, and you need to test for failure explicitly. These error codes are not very helpful - it seems that the exit status is 1 if the command cannot be found or cannot be started, so if you want to pass information back with the exit status, you cannot use a 1, and might want to use a value besides 1 for failure of the operation to distinguish it from failure to run the command. If STOP is used while the command is running, the script will stop and the thread that is running the command will be killed, but the command will keep running. If this feature or the DOS window that opens is a problem, see the if you can use the 'RunProcess' command |
| RunProcess command | Runs the program given by command with the argument list defined previously with the 'NextProcessArgs' command and input possibly defined previously with 'PipeToNextProcess', waits for the program to finish, and sets reportedValue1 with its exit status. See The Tools Menu and Running External Commands for a description of the rules governing this command. Failure to start the program generates a script error, but a non-zero exit status will not. Unlike 'RunInShell', this command avoids opening a DOS window (unless the property 'AllowWindowWithTools' is set). Redirection of input from a file and output to a file are possible, but if you need more elaborate shell features like piping, you need to use 'RunInShell'. If STOP is used while the command is running, the process will be terminated. Command added in 4.1, 24-Aug-22. |
| CreateProcess command | Like 'RunProcess' except that it starts the program without waiting for it to finish. See The Tools Menu and Running External Commands for a description of the rules governing this command. |
| NextProcessArgs arg [arg] [...] | Sets arguments for the next process run with 'CreateProcess' or 'RunExternalTool'. The argument list can contain script variables that are substituted, as well as several keywords that are replaced with path entries. See The Tools Menu and Running External Commands for a description of these keywords and the rules governing the arguments entry. The arguments are used up by running the process and must be defined with this command each time a process is run. |
| PipeToNextProcess var | Sets an input string to be piped into the next process run with 'CreateProcess' or 'RunExternalTool', which should be more efficient than writing the input to a file and redirecting input from it. The variable var would typically contain an array of strings or numeric values, one per line of input. |
| NextProcessPipeToVar var | Sets up a pipe to collect standard output from the next process started with 'RunProcess' and, when the process finishes, assigns the output to the variable var. ReportedValue2 is set to 0 if there is output or 1 if there is none (in which case the variable is not set). If there are multiple lines of output, the variable will contain an array of strings. The process arguments cannot include redirection to a file with '>'. This command has no effect with 'CreateProcess' or 'RunExternalTool'. Command added in 4.2, 17-Nov-24. |
| RunExternalTool #N|name | Starts an external tool shown in the Tools menu, where #N is either the number of the tool in the Tools menu, numbered from 1, or name is the full name of the tool in the menu. If arguments were set with 'NextProcessArgs', or input to be piped in set with 'PipeToNextProcess', they will be included when running the command. |
| ExternalToolArgPlace # | Specifies whether arguments set with 'NextProcessArgs' should be placed before (-1 for #) or after (1 for #) the arguments defined for an external tool in the properties file, or replace the defined arguments (0 for #). The default is 0 and a setting is retained for the duration of the script. |
| Other Commands | |
| OpenDialog name [#] | Opens the dialog indicated by the given name, which is case-insensitive and can be abbreviated to 3 letters. Currently the name can by 'Multishot' to open the Multiple Records dialog or 'Multigrid' to up the Multiple Grid Operations dialog; in the latter can enter a non-zero value for # to load the last session file. Command added in 4.1, 15-Nov-23. |
| CircleFromPoints #X1 #Y1 #X2 #Y2 #X3 #Y3 | Reports the X and Y center coordinate and the radius in microns for the circle through three points whose coordinates are given on the line as #X1:#Y1 #X2:#Y2 #X3:#Y3. Values can be assigned to variables at end of command. |
| SetCameraPLAOffset | Sets or refines a PLA offset between two cameras on a JEOL scope using PLA for
image shift. To use: Take an image with the camera to be aligned to (e.g., an on-axis camera). Center a feature and take a new image. Switch to the other camera (e.g., an off-axis camera). Use right mouse-shifting, or set the marker point and use the To Marker button or Shift P hot key to center the feature with image shift only. Run this command. It will report the existing and new offsets. Iterate if desired for a more accurate result. If aligning more than two cameras, use one camera as a reference for aligning each of the others to. |
| AccumulateRecordDose # | Adds # to a cumulative dose that will be assigned as the PriorRecordDose value for images that are taken while the script is running. This dose accumulator is disabled when a script starts. There are multiple dose accumulators available and the current one can be selected by the 'AreaForCumulRecordDose' command; but it is not necessary to use that command if only using one accumulator. Use this command with a # of 0 to enable the current accumulator and initialize it to 0; the next image will have a PriorRecordDose. Thereafter,for each Record image or montage, get the dose from a buffer ('A' after a Record, 'C' after a montage) with the 'ImageConditions' command and use this command with that dose value for #. Use -1 for # to disable an accumulator again if needed. Command added in 4.1, 1-Apr-22. |
| AreaForCumulRecordDose # | Sets the current dose accummulator to #, which must be between 1 and 250. If multiple accumulators are needed, use this command to set the area before the Record, take the Record, then gets it dose and use 'AccumulateRecordDose'. Command added in 4.1, 21-Jun-23. |
| ReportEDMDutyPercent | Reports the current duty percent setting of an IDES dose modulator. Command added in 4.2, 16-Nov-24. |
| SetEDMDutyPercent # | Sets the duty percent setting of an IDES dose modulator to #. If Continuous update is on in the Low Dose control panel, the current area will be set to this value. Command added in 4.2, 16-Nov-24. |
| Plugin name func [args] | Calls the function func in the plugin named name with an appropriate list of arguments for that function. name may be ':' to use the same plugin as was last called. Arguments (args) are entered as items separated by spaces, except that a string argument at the end may consist of multiple words. The return value of the function is reported and placed into reportedValue1; additional return values may be placed in reportedValues2-4. |
| ListPluginCalls | Lists the names of script-callable functions in all loaded plugins along with the arguments that they expect, in parentheses. For each argument, there should be one item provided on the command line calling the function, with all items separated by spaces as usual. Two exceptions to this are: a string argument at the end can include spaces; an argument listed as [out]double is a returned value, assigned to reportedValue2 or higher. When a function returns a string, it is assigned to reportedValue2. |
| ReportMontagePiece # | Reports the piece number in X and Y (numbered from 1), piece coordinates in X and Y, and the number of pieces in X and Y for the just-acquired piece of the montage being acquired if # is 0, or for the next piece if # is non-zero. This command can be used only in a script run from the montage, currently set by the property 'MontageScriptToRun'. The script is run between acquiring and saving an image. Command added in 4.1, 16-Jan-23. |
| MailSubject text | Sets subject line for an email message (default is 'Message from SerialEM script'). text can include variables to be substituted. |
| SetNextEmailAddress # [addr] | If # is 0, sets the email address(es) to be used on the next sending of email by any source to addr, which can contain several addresses separated by commas. If # is 1, it appends to the addresses defined in the user settings. If # is -1, an address set by a previous command and not used yet is canceled, and addr should not be entered. Command added in 4.1, 23-Apr-22. |
| SendEmail text | Sends an email containing the given text, which can include variables to be substituted. An SMTP server and address to send from must be defined in the properties file, and recipient(s) must be defined using either 'Set Email Address' in the Settings Menu or the 'SetNextEmailAddress' command. |
| ErrorBoxSendEmail text | Sends an email containing the given text if the script stops with a message box; the text can have variables to be substituted. Requirements are the same as for 'SendEmail'. If the message box occurs during Navigator Acquire at Items and the user has selected to send emails there, two emails will be sent, thus allowing more specific information from the one specified here. |
| SetDebugOutput keys | Set the debug output string with the letters in keys. Command added in 4.2, 11-Jun-24. |
| ReportProperty name [var] | Reports the value of one general program property given by name. The command can be used with nearly all of the general (non-camera-specific) properties that contain just a single numeric entry and can be set by name in SerialEMproperties.txt. Follow with the full name of the property (case insensitive) and with an optional variable name var for the value. An error will result if the name does not match one of the properties that can be reported. The list of available properties in the development version of SerialEM is in https://bio3d.colorado.edu/ftp/SerialEM/Scripts/ScriptableProperties.txt |
| ReportCameraProperty #C name [var] | Like 'ReportProperty', but reports the value of a camera property given by name, where #C is the active camera number in the Camera Setup dialog (numbered from 1), or 0 for the current camera. Command added in 4.1, 29-Apr-23. |
| SetProperty name value | Sets the value of one program property. This works just like 'ReportProperty'. Follow with the full name of the property (case insensitive) and with its new value. |
| SetCameraProperty # name value | Like 'SetProperty', but sets a camera property for active camera #C or the current camera if #C is 0. Command added in 4.1, 29-Apr-23. |
| ReportUserSetting name [var] | Reports the value of one user setting, using the name for it in SerialEMsettings.txt. The command can be used with nearly all of the general (non-camera-specific) settings that contain just a single numeric entry. Follow with the full name of the setting (case insensitive) and with an optional variable name var for the value. An error will result if the name does not match one of the settings that can be set. The list of available settings in the development version of SerialEM is in https://bio3d.colorado.edu/ftp/SerialEM/Scripts/ScriptableSettings.txt |
| SetUserSetting name val [#K] | Sets the value of one user setting. This works just like 'ReportUserSetting'. Follow with the name of the setting and its value val. The original value is automatically restored when the script stops unless the optional entry #K is non-zero to keep the setting. If the script is suspended, the new value will be set again when it is resumed. Multiple changes in the same setting can be done; the original value or last kept new value will be restored when the script stops, and the latest new value will be set on resume. If you have many settings to change, do them all in a row after a 'DeferSettingsUpdate' command to prevent control panels from flashing. |
| LoadScriptPackAtEnd #S name | Loads the script package with the given name after the script completes successfully. The current scripts are saved to the current package if #S is non-zero, otherwise they are not. |
| ReportEnvironVar name | Reports whether the environment variable given by name exists in reportedValue1 and its value in reportedValue2 if so or 'none' if not. The name must be a single word without spaces. |
| ReportSettingsFile | Reports the name of the current settings file and the name of the current script package file, or "None" if scripts were loaded from settings. |
| ReportSystemPath | Reports the 'system path', the directory where calibrations and properties files are located. Command added in 4.1, 16-Apr-23. |
| ReportNumExeFuncs | Reports the number of script commands defined in MacroMasterList.h; use with ReportNumModuleFuncs in a Python script to determine if the serialem module is up to date. Command added in 4.1, 3-Oct-23. |
Commands Allowing Arithmetic Expressions for Arguments
In addition to the commands starting with 'Set', these commands allow arithmetic arguments:AbsoluteFocusLimits AddImagePosAsNavPoint AddImages AddStagePosAsNavPoint AdjustStagePosForNav BackgroundMoveStage BackgroundTilt BeamTiltDirection CalibrateComaVsIS CalibrateHighFocusIS ChangeEnergyLoss ChangeFocus ChangeFrameAndExposure ChangeIntensityBy ChangeItemRegistration ChangeMag ChangeMagAndIntensity CircleFromPoints CropImage CtfFind Ctfplotter CycleTargetDefocus Delay DivideImages DoLoop DriftWaitTask EarlyReturnNextShot EchoEval EchoNoLineEnd EchoReplaceLine ElapsedTickTime ExposeFilm FocusChangeLimits FrameThresholdNextShot GetUniqueNavID ImageShiftByMicrons ImageShiftByPixels ImageShiftByUnits IncPercentC2 IncTargetDefocus LimitNextAutoAlign LimitNextRoughEucen LongOperation Loop ManualFilmExposure ModifyFrameTSShifts MoveBeamByFieldFraction MoveBeamByMicrons MovePiezoXY MovePiezoZ MoveStage MoveStageTo MoveStageWithSpeed MultipleRecords MultiplyImages PreCookMontage QuickFlyback RecordAndTiltTo ReduceImage RelaxStage ResetShiftIfAbove ScaleImage SetFreeLensControl SetSlitIn SetStageBAxis ShiftItemsByMicrons SmoothFocusNextShot SpecialExposeFilm StageShiftByPixels StepFocusNextShot StopBackgroundStage SubareaMean SubtractImages TestRelaxingStage TestSTEMshift TiltBy TiltDuringRecord TiltTo UpdateHWDarkRef WaitForDose WaitForMidnight WalkUpTo ZemlinTableau
This list is not kept up to date between stable releases. Set DebugOutput to '%' in the SerialEM properties file and start the program to see a current list.