Customizing Instrument Script

The result of a simulation in SScanSS 2 is a set of positioner offsets for each measurement which would move the positioning system to desired position and orientation. These positioner offsets can be exported as a text file or “Instrument script” which can be run on the real-world instrument.

SScanSS 2 allows for some customization of the format of the “Instrument scripts” using Mustache templating system. Each instrument can utilize a different script template by specifying the path to a new template in the instrument description file with the script_template key. The default template will be used when no script template is specified, the default template for all instruments is:

{{header}}
{{#script}}
{{position}}    {{mu_amps}}
{{/script}}

For a 4 DOF positioning system and 2 measurements, the default template would generate a script that is simillar to:

X    Y       Z       T       mu_amps
xi   yi      zi      ti      0.000000
xj   yj      zj      tj      0.000000

where “xi yi zi ti” are the positioner offsets for measurement i, “X Y Z T” are the names of the positioning system’s joints in the order specified in the instrument description file and “mu_amps” is the number of microamps to measure on the instrument.

Anatomy of script template

The minimum template required in SScanSS 2 is

{{#script}}
{{position}}
{{/script}}

This template will print each positioner offset from the simulation on a new line. The {{#script}} and {{/script}} tags are the opening and closing section tags required to render a block of n positioner offsets. {{position}} is a string of tab-separated positioner offsets. Any variable in the section tag will be rendered n times also; similar to the {{mu_amps}} variable in the default template. The order of variables and arrangement in the section tag can be modified if necessary. In the example below, the output will print microamps before the i^th positioner offset all in a single line.

{{#script}}{{mu_amps}} {{position}} {{/script}}

Static text can be added to the template without any problem, for example

This script was generated by SScanSS 2
{{#script}}
{{position}}
{{/script}}

In addition to static text, other variables can be added to the template, the following are supported.

1. {{filename}}: The SScanSS 2 project filename, it is an empty string if project has not been saved.

2. {{mu_amps}}: This is a user specified value which indicates the number of microamps to measure on the instrument.

3. {{count}}: The number of measurements in simulation.

4. {{header}}: A string of tab-separated column names for every variable in the {{#script}}{{/script}} section tag.

The ENGIN-X script template shown below uses most of the available variables:

SScanSS project file: {{filename}}
1
{{count}}
{{#script}}
{{position}}    {{mu_amps}}
{{/script}}

Complex example

The script template could be written as a Python script as shown in the example below. This example prints the positioner offsets but can be modified to control the real-world positioning system. The header string is split to get the individual column names (Line 5) and the positioner offsets are separated by a space instead of a new line so splitting this give a 1D array of offsets (Line 6); then the data is printed using for loops.

# This script is generated from SScanSS 2

def do_something():
    mu_amp = {{mu_amps}}
    header = str.split('{{header}}', '\t')
    position = str.split("{{#script}}{{position}} {{/script}}")

    rows = {{count}}
    columns = len(header)

    for i in range(rows):
        print('')
        for j in range(columns):
            print(position[i*columns + j], end='\t')


if __name__ == '__main__':
    do_something()