Scripts

The purpose of the scripting feature is to allow robust and repeatable automation of tasks in Stradwin - i.e. batch processing. Scripts support multiple commands on the currently loaded data, and also the sequential loading, processing and saving of many '.sw' files and results.

Scripts have mainly been designed for automating cortical bone mapping over multiple files, and also for the creation of movies from the 3D and reslice windows. However, since they allow the setting of all of the resources in stradwin, and also quite a few other functions and key presses, they can also be used for other tasks. There are some examples of each of these operations below.

Each script is a text file, which can be loaded or created by the script task page. They must be saved prior to running the script. A script output (a list of actions performed and any warnings or errors that occured) is produced when a script is run. The output appears in a non-editable text box in this task page, and it can be cleared or saved.

Commands

Scripts support several commands. Each different type of command is specified with a separate key word: results_dir, script_name, write_header, open, param, func, write, loop, repeat, end, close. Each of these is described in detail below.

The order in which these commands are included in the script is important. The results_dir, optionally script_name, and write_header commands must be called before the open command. In addition, write can only be called after write_header. Any commands listed after the close command will be ignored.

results_dir

results_dir dir\path\ dir_back_count

The results_dir specifies the directory into which all log files and other Stradwin outputs will be written. It also specifies how the results files should be named. If not specified, results_dir defaults to the directory specified by the open command and dir_back_count is ignored.

For instance, assuming

results_dir d1\d2\results 0,-1
open d1\d2\ filter_string (see below for the usage of open)

and that within directory d2 there are several other folders, F1, F2, F3, F4, each containing a '.sw' file called 'Femur.sw', the resulting results files will start with: Femur_F1_..., Femur_F2_..., Femur_F3_..., Femur_F4_...

script_name

script_name string

The script_name is an optional command that specifies the name of the experiment; it is appended to all result outputs. If not specified, the script_name defaults to an empty string and nothing is appended onto the results.

write_header

write_header NAME1 NAME2 ...

The write_header is an optional command that specifies the resources to print out to the comma-delimited log file. This command is used in conjunction with the write command. See the write subsection for details.

The comma-delimited file is called 'log_script_name.txt', where the '_script_name' is only included if specified in the script. It is stored in the results directory. The first line of the printed file gives the column names. The following lines are the values specific to each write command call during the execution of the body of the script. The first four columns are automatically defined as 'file number', 'full file name', 'results file name' and 'current surface'. The 'results file name' is the tag that would be appended to any results produced at this time, and the 'current surface' is the currently selected surface. These are followed with an additional column for each NAME specified.

write

The write command triggers the values specified by the write_header arguments to be written to a comma-delimited file.

open

open [filter_number] dir\path\ [filter_string]

The open command specifies the Stradwin files to process.

This command must be used in conjunction with the close command. See the close subsection for details.

All the commands between an open and close will be run on each of the Stradwin files which are opened, in turn.

close

The close command signifies the end of the script. Any subsequent commands are ignored.

loop

loop [filter_string]

The loop command specifies that the following commands should be repeated for a variety of objects within this file.

This command implicitly selects each object in turn and executes the commands in the loop on them. This command must be used in conjunction with the end command. See the end subsection for details.

Nested loops are not supported, hence each loop or repeat must be followed by an end command prior to another loop or repeat command.

repeat

repeat count

The repeat command specifies that the following commands should be repeated a number of times.

Nested repeats are not supported, hence each loop or repeat must be followed by an end command prior to another loop or repeat command.

end

The end command signifies the end of either a loop or repeat.

param

param NAME value

The param command sets the value of any available stradwin resource.

func

func FUNC_NAME [argument]

The func command mimics pressing a button, selecting an item from a menu, or cursor key input.

Functions and key input

The following are all the FUNC_NAME values with optional arguments which can follow the func command. For backwards compatability, old function names beginning with SWC_ and SWM_ will still work correctly.

Functions related to the file menu:

Functions related to key or mouse input:

Functions related to the draw task page:

Functions related to the cortical bone mapping task page:

Other functions:

Notes

Currently only a selection of GUI interactions are supported with the func command. These include a few of the 'file menu' options, cursor key input, and a few of the 'draw task page' and 'thickness task page' drop-down menus and buttons. It should be noted that scripts do not support execution of GUI interactions that would be disabled in the same manual work-flow.

Syntax details

Examples

The following are example of a simple movie, a more complex movie and also a cortical bone mapping script.

Simple outine movie

# where to put the images
results_dir D:\movies\movie1\

# rotate the outline window using the default (5 degrees) steps
# and with the current viewpoint and visualisations
# save results as 'outline_000' etc
repeat 72
  func ROTATE_3D left
  func SAVE_3D outline_
end

More complex multiple movies

# where to put the images
results_dir D:\movies\movie2\

# disable frames and centres-of-gravity
param DISPLAY_FRAME false
param DISPLAY_COG false

# determine what the steps are for movement, rotation and zoom
param CURSOR_ROTATION 5    # degrees
param CURSOR_MOVEMENT 5    # pixels
param SCROLL_ZOOM 5        # percent

# set up initial zoom etc in the outline window
param OUTLINE_ZOOM 1.2
func ORIENT_3D 1 0 0 0 -1 0    # corresponds to pressing 'v' in 3D window
func LOCATE_3D 0 -10 -21.5     # corresponds to pressing 'c' in 3D window

# start with 20 frames of movement
# saving both 'outline_000' etc and 'reslice_000' etc
repeat 20
  func ZOOM_3D up              # zoom in the 3D window
  func ROTATE_3D left          # and rotate
  func ROTATE_RESLICE_3D right # rotate the reslice the other way, so stays still in 3D
  func MOVE_3D down            # also move the 3D window
  func MOVE_3D right
  func SAVE_3D outline_
  func SAVE_RESLICE reslice_
end

# record some more images whilst gradually changing the opacity of object 'L1'
# an opacity of '0' would disable display of this object in all windows
func OBJECT_OPACITY L1 0.8
func SAVE_3D outline_
func SAVE_RESLICE reslice_
func OBJECT_OPACITY L1 0.6
func SAVE_3D outline_
func SAVE_RESLICE reslice_
func OBJECT_OPACITY L1 0.4
func SAVE_3D outline_
func SAVE_RESLICE reslice_
func OBJECT_OPACITY L1 0.2
func SAVE_3D outline_
func SAVE_RESLICE reslice_
func OBJECT_OPACITY L1 0.0
func SAVE_3D outline_
func SAVE_RESLICE reslice_

# reverse the previous animation (note also reverse order of commands)
repeat 20
  func MOVE_3D left
  func MOVE_3D up
  func ROTATE_RESLICE_3D left
  func ROTATE_3D right
  func ZOOM_3D down
  func SAVE_3D outline_
  func SAVE_RESLICE reslice_
end

# return object opacity to 1.0 (there is no automatic undo-ing of script changes)
func OBJECT_OPACITY L1 1.0

Cortical bone mapping

# 'fractures' and file name appended to all results
script_name fractures
results_dir /dir/results/ 0

# resource values to write to file each time 'write' is called
write_header DICOM_BMD_SCALE DICOM_BMD_OFFSET DICOM_BMD_PHANTOM THICKNESS_B THICKNESS_GAUSS THICKNESS_RECT

# files to open and loop over, the first 11 files called 'Femur*' in '/dir/data/'
open 0-10 /dir/data/ Femur*

  # thickness related initialisation
  param THICKNESS_LINE 1.8
  param THICKNESS_WIDTH 0
  param THICKNESS_TYPE 4   # corresponds to 'CBM v2' 

  # drawing initialisation
  param SURFACE_COVER true # triangulate over ends when within data
  func SURFACE_RESOLUTION High
  func SURFACE_SMOOTH_TYPE Standard
  func SURFACE_SMOOTHING Low
  func SURFACE_ALL             # actually update all surfaces

  # BMD calibration
  func DICOM_CALIBRATE         # determins HU given 4x phantom landmarks

  # loop over all objects matching '*femur*'
  loop *femur*

    # Thickness estimation and saving
    func THICKNESS_EST_DENSITY
    func THICKNESS_SURF_FIT
    func THICKNESS_SURF_SAVE

    # write out resources defined by 'write_header' at this point
    write

  # end of loop
  end

# end of file open
close