The MP Command Listing is intended to provide detailed and specific information on each available command offered through Measurement Plan (MP) scripts. If you need to figure out what is expected as an input or return from a command, this is where you will find the answer. The Measurement Plan chapter of the SA Users Manual is also available and includes an overview of the MP Editor and the scripting process.
Additional Steps that should be considered when running MP:
Set Logging State. With logging active each MP step will be recorded into the log file. This can be very helpful in tracking changes to the job file, but can also grow the log into a huge and cumbersome file if repeated MP executions are used.
Set Automatic Backup State. Is another one to consider carefully. Automatic backups can interrupt operations but not backing up can also be dangerous.
Clear All Ascii Files. When opening and closing external files such as text or excel files these files can be left open as background processes. This command clears these open files.
Referencing specific items or objects in the tree requires a naming sequence. We use the Collection:: Object:: Name convention (which can also include a ::type specification at the end) in order to provide a path to a specific instance of an item.
Items within an SA job file can be categorized as follows:
Items. Items are the largest most generic category and includes anything within SA. Commands such as Show Items in Tree provide a means to access any item of any Type.
Instruments. Instruments are handled separately from all other types of items within SA and are referenced using a Collection:: Instrument ID. This includes the collection name and the index of the instrument within that collection.
Objects. Objects are a subcategory that includes only 3D features within SA’s graphics such as CAD entities, Geometry, point groups or point clouds. They do not include pictures, callouts or reports. They are measurable features displayed within the graphics.
Points. Points are not objects in themselves but are included as identifiers within a specific Point Group. A Point Name Ref List therefore include both the Collection Object Name for the Point Group and a point name. As an example the point group A::Nominals would include the point A::Nominals::P1.
Every argument has a data type. A data type indicates the type of information that an argument is expecting. You must feed an argument data of a compatible data type otherwise, SA will prevent the operation or the script will fail at runtime.
Basic Data Types Within MP Include:
Boolean. Booleans are the simplest data type. They are either True or False, much like a switch is either on or off. You can use the shorthand “1” for True and “0” for False in entering a Boolean value.
String. Strings are sequence of one or more alpha- numeric characters, such as a sentence or prompt.
Integer. Integers are whole numeric values without any decimals. Integers are represented exactly and can be used to reference a particular item in a list.
Double. Doubles are numeric values with decimal precision, either positive or negative. The precision of the decimal representation (such as such as 3.1415926535) beyond 8-10 decimals will depend on they system and any rounding applied which can influence trying to compare one double value to another. You may expect them to be the same but they may actually be very slightly different.
Reference Lists. Reference lists are also a data type. A point list for example is composed of a list of points in a specific order.
Most data types can also be designated as a variable. Variables allow you to define a name that is associated with a value. This allows you to refer to that value by name. The advantage of this is that while a script is running, you may change or overwrite the value of that variable, but anywhere you refer to it by name, you’ll always retrieve its current value.
Defined variables appear in the variables view panel. Some lists, such as Point Name Reference Lists and Collection Object Name Lists also support a special Ctr+Shift double click option to display a new panel with the names of the items defined in the variable while in debug mode.
A variable name can also be use to define a variable. This allows a placeholder variable to be established in a script that reference a specific name to retrieve the variable values.
Note that the variables panel cannot track changes in variable type.
Runtime Select. Runtime select provides a means to bypasses the need to identify items as part of the script. It allows a user to the selected the necessary items manually while the script is running (runtime).
Wildcard Selection. Wildcard search terms provide a means to build a list based upon name matching. An asterisks (*) represent a set of contiguous characters, and a question mark (?) represent a single character. You can also use brackets ([]) as an escape sequence if needed to search for special characters, for example [*] will search for names containing an asterisk (*). Also [!] provides a means to exclude items from the search. Wildcard selection criteria, like all names in SpatialAnalyzer, are not case sensitive.
Supported wild-characters include: ‘*’, ‘?’; sets: [a-z],
‘!’ negation
Examples include:
‘[a-g]l*i?n’ matches ‘florian’
‘[!abc]*e’ matches ‘smile’
‘[-z] matches ‘a’
Wildcard selection automatically adds an asterisk (*) at the beginning and end of your search text. Each search string is automatically wrapped as *search string*. This allows you to search for “P1” and find “AP123”. However, this may result in selection of more items than desired. To control this operation use the command Set Wild Card Asterisk Mode.
Loops within SA are performed using the following step structure:
Counter. A counter is required for a look in order to keep track of the index or status as an element is retrieved from a list and an action in performed.
Get i-th. In order to sequentially perform operations with items from within a list a script needs to be able to access those items in an ordered way. Each item in a list contains an index (i), item 1, 2, 3, etc. “Get i-th” commands provide a means to access a specific item at a specific index in a list by returning the i-th object. Note that a list (array) starts at 0 as the first entry and 1 is the second.
Increment Counter. In order for an MP to work through a list the index of a counter must be adjusted to retrieve the next element in the list.
Integer Comparison. In order to exit a loop a comparison needs to be made. Either to verify that a target has been found or that the end of the list has been reached. An integer comparison that references the counter is an effective way to verify that the end of the list has been reached. A comparison step also provides a means to jump back to the Get-ith step in order to retrieve the next element from the list.
of the list has been reached. A comparison step also provides a means to jump back to the Get-ith step in order to retrieve the next element from the list.
Many command such as Get i-th Point Name From Point Name Ref List also have an (iterator) option. These steps have a built in counter and integer comparison. Each time the step is run the internal counter indexes by one and checks to see if it has reached the end of the list. If it has, it uses the “Step to Jump at End of List” argument to jump out of the loop.
A loop using an iterator is as simple as:
Build a list
Add a get i-th step with (iterator)
Perform any operations you wish
Jump to Get i-th to get the next element.
This built in Iterator concept works great when an MP is executed a single time. It will not work correctly when a loop is set within a loop (nested loop) as an iterator will not reset once it reaches the end of the list.
Command arguments that designate a directory support both absolute paths (“C:\Analyzer Data\MP Work\test.xit”) and relative paths (“.\test.xit”). Relative paths are both faster to type and allow a directory to be moved without breaking the MP path designation. Note that relative paths may also relate to the working directory, depending on the command, which may be the SA install directory unless specified using Set Working Directory.
“.\” designates the current directory.
If a relative path is provided and the MP is embedded, the path will be relative to the current SA file location. But, if executing an external MP the file that will be opened will be opened with respect to the MPs directory.
Relative paths can also be expanded relative to the current directory. For example, to access a text file in the directory (C:\Analyzer Data\MP Work\Fit\Nominals.txt) from an SA file running from “.\MP Work” folder you can enter:
“.\Fit\Nominals.txt “
This can be expanded further to browse up:
“..\” designates one folder above the current directory
Following the same example, a template file in “C:\Analyzer Data\Templates” could be accessed from C:\Analyzer Data\ MP Work using “..\Templates\MyTemplate.xit64”. To browse up two levels use “..\..\”.