The Tools Menu and Running External Commands

The Tools menu contains items added by 'ExternalTool' entries in the SerialEMproperties.txt file.  This page describes how to add such entries, but has no information on the specific commands that you may see there.  The entries in the properties file for specifying the command to run and its arguments, 'ToolCommand' and 'ToolArguments', have the same format as the script commands for starting an external process, 'CreateProcess' and 'NextProcessArgs', respectively.

Selecting an entry in this menu, or running the 'CreateProcess' command, will start the external program, but SerialEM will not wait for it to exit.

The command entry

The command entry specifies the program to run.  It can be an executable program, or it can be a DOS batch file with extension '.bat' or '.cmd'.  It should not be enclosed in quotes even it contains spaces, as SerialEM will automatically wrap it in quotes.  The extension '.exe' may be omitted on any executable ending in that, but otherwise the extension must be included.  For .'bat' and '.cmd' files, the program knows how to run these with 'cmd.exe'; for any other kind of script, the script interpreter (e.g., 'python.exe')  must be entered for the command, and the script name must be entered as an argument.  The command name alone will work if the program is on the search path (i.e., the PATH variable), but otherwise the full path to the executable must be given.  The full path to a batch file should be entered unless the file is in the current directory, which will not be the case in general.

The arguments entry

This entry specifies a list of arguments to be supplied when running the command.  If a single argument such as filename might contain spaces, it should be enclosed in double quotes (single quotes will not work).  When running from script, the arguments can include variables that are evaluated (but not arithmetic expressions).  This is obviously not an option for Tools menu entries, but both kinds of argument lists can contain special keywords that will be substituted with a value.  These keywords are

• %imagefile% will be substituted with the full path of the current image file, but it will generate an error if there is no current file open..
• %currentdir% will be substituted with the full path to the current directory,
• %navfile% will be substituted with the full path of the Navigator file, if the Navigator is open and there is a Navigator file defined; otherwise it will generate an error.

The keyword can be embedded in a longer string.  The whole 'word' (set of characters not containing a space) containing the keyword will be enclosed in quotes automatically, as long as there is no double quote at either end of the word.  If you are following the current directory, for example, with a filename that might have spaces, you should put quotes around the '%curdir%' and filename yourself to prevent quotes from being in the wrong place.

Optional redirection of input from a file, output to a file, or input from a pipe

The standard output from the command can be written to a file by ending the arguments with '> filename'; standard error and output can be written together using '>& filename'.  The standard input to the command can be read from a file by including '< filename' in the arguments; this redirection must be placed at the end of the arguments, but before redirection of standard out if any.  These redirections are implemented by SerialEM connecting the command output to the output file, not by running in a shell, so no other standard piping or redirection is allowed in the command, unlike with the 'RunInShell script' command.  However, it is possible to pipe input to a process started with 'RunProcess', 'CreateProcess', or 'RunExternalTool' instead of redirecting it from a file, using 'PipeToNextProcess' to set the input strings from an array variable.  In this case, the argument string may not contain a '<' for input redirection.

Examples

ExternalTool Open Mdoc File
ToolCommand 1 notepad
ToolArguments 1 %imagefile%.mdoc
ExternalTool Open Nav File
ToolCommand 2 notepad
ToolArguments 2 %navfile%
ExternalTool 3dmod Image File
ToolCommand 3 C:\Program Files\3dmod\3dmod
ToolArguments 3 %imagefile%