Scripts
The purpose of the scripting feature is to allow robust and repeatable automation of tasks in Stradview - i.e. batch processing. Scripts support multiple commands on the currently loaded data, and also the sequential loading, processing and saving of many '.sw' (or other) 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 stradview, 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 (if they are used at all) before the open command. In addition, write can only be called after write_header. Any commands listed after the close command will be ignored.
Writing results from the script
results_dir dir\path\ dir_back_count
The results_dir specifies the directory into which all log files and other Stradview 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.
- dir\path\ - the results directory path. This must exist and will not be created dynamically. This is intentional to protect against unintended directory creation resulting from a typo in the specified directory path.
- dir_back_count - a comma separated list of numbers which specify (in order) what is used in the results file name. '0' means use the name of the current Stradwin file, a positive number means use a directory name counting from '1' as the highest level directory, a negative number means use a directory name counting from '-1' as the lowest level directory.
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 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.
- string - the string to appended to the results.
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.
- NAME ... - the names of the resource values to print to the file. These can either start with RES_ or this can be omitted.
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.
Opening data sets
open [filter_number] dir\path\ [filter_string]
The open command specifies the Stradwin (or other) files to process.
- filter_number - an optional range of numbers that specifies the set of filtered files to actually open. For instance, '1-10,12' will open the first ten and the twelfth files.
- dir\path\ - the directory to search (including subdirectories) for all '.sw' files.
- filter_string - an optional string which will be used to filter the files opened. Normal string wild-cards are supported. If no extension is included, '.sw' is presumed, so if you want to specifically load a DICOM file with no extension, finish the name with a trailing '.'.
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.
Changing Stradview resources
param NAME value
The param command sets the value of any available Stradview resource.
- NAME - the name of the resource to be set, the same as that saved in '.sw' files or the configuration file. These can either start with RES_ or this can be omitted.
- value - the value the resource will be set to.
func FUNC_NAME [argument]
The func command mimics pressing a button, selecting an item from a menu, or cursor key input.
- FUNC_NAME - the tag of the button or menu item: see below for a list of supported tags.
- argument - some function calls may require single or multiple arguments.
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:
- FILE_SAVE - saves the currently opened '.sw' file.
- FILE_SAVEAS string - saves the currently opened '.sw' file with the specified 'string' appended after a '_' separator to the file name of the '.sw' file. The '.sw' file is saved in the same directory as the initially opened '.sw' file.
- SAVE_3D string - grabs the 3D window and saves it in the results directory with the name 'string????' where '????' is a number starting from zero which increments each time this function is called with the same 'string'.
- SAVE_REVIEW string - as above but for the review window.
- SAVE_RESLICE string - as above but for the reslice window.
- SAVE_ORTHO_LEFT string - as above but for the left ortho window.
- SAVE_ORTHO_RIGHT string - as above but for the right ortho window.
Functions related to key or mouse input:
- ORIENT_3D lx ly lz fx fy fz - orients the 3D window, in the same way as using the 'v' key.
- LOCATE_3D cx cy cz - locates the centre-of-gravity for the 3D window, in the same way as using the 'c' key.
- SCROLL_3D sx sy - sets the scroll point for the (zoomed) 3D window, in the same way as using the 's' key.
- ROTATE_3D cursor - rotates the 3D window by an amount defined by the cursor rotation in the direction given by 'cursor', which must be one of left, right, up or down.
- ROTATE_RESLICE cursor - rotates the reslice window by an amount defined by the cursor rotation in the direction given by 'cursor', which must be one of left, right, up or down.
- ROTATE_RESLICE_3D cursor - same as above, except that the rotation is with respect to the outline window.
- TWIST_3D cursor - twists the 3D window by an amount defined by the cursor rotation in the direction given by 'cursor', which must be one of left, right, up or down.
- TWIST_RESLICE cursor - twists the reslice window by an amount defined by the cursor rotation in the direction given by 'cursor', which must be one of left, right, up or down.
- TWIST_RESLICE_3D cursor - same as above, except that the twist is with respect to the outline window.
- MOVE_3D cursor - moves the 3D window by an amount defined by the cursor movement in the direction given by 'cursor', which must be one of left, right, up or down.
- MOVE_RESLICE cursor - as above, but for the reslice window.
- MOVE_ORTHO_LEFT cursor - as above, but for the left ortho window.
- MOVE_ORTHO_RIGHT cursor - as above, but for the right ortho window.
- OFFSET_REVIEW cursor - implements cursor key movements in the review window as defined in keys.
- OFFSET_RESLICE cursor - offsets the reslice window in the same way as cursors are implemented for the ortho windows, defined in keys.
- OFFSET_ORTHO_LEFT cursor - implements cursor key movements in the left ortho window as defined in keys.
- OFFSET_ORTHO_RIGHT cursor - implements cursor key movements in the right ortho window as defined in keys.
- ZOOM_3D cursor - mimics clicking with a mouse scroll-wheel in the 3D window, with left and down reducing zoom by a percentage given by scroll zoom, and right and up increasing it.
- ZOOM_REVIEW cursor - as above, but for the review window.
- ZOOM_RESLICE cursor - as above, but for the reslice window.
- ZOOM_ORTHO_LEFT cursor - as above, but for the left ortho window.
- ZOOM_ORTHO_RIGHT cursor - as above, but for the right ortho window.
Functions related to the draw task page:
- CURRENT_OBJECT object_string - sets the current object to 'object_string'.
- RENAME_CURRENT object_string - sets the name of the current object to 'object_string'.
- IMPORT_SURFACE surface_string - loads the surface or surfaces defined by surface_string, which can contain directories and wildcards, into separate objects. If the full path (including volume) is specified, the same file will be loaded for all data, otherwise the directory in surface_string is relative to the currently loaded data. A '*' is presumed before the file name. If an extension has been included, any files of the form 'data_file*surface_string' will be loaded, or, if not found, '*surface_string'. Otherwise any loadable file of the form '*surface_string.*' will be loaded. Note that the search includes all sub-directories.
- IMPORT_CONTOURS data_string - loads the label data defined by data_string into separate objects. The file search is the same for IMPORT_SURFACE above.
- SURFACE_RESOLUTION resolution_string - sets the surface resolution. The resolution string must be one of: "Uber Low", "Super Low", "Very Low", Low, Medium, High or "Very High".
- SURFACE_SMOOTHING smoothing_string - sets the smoothing strength. The smoothing string must be one of: None, "Very Low", Low, Medium, High or "Very High".
- SURFACE_CURRENT - executes the 'Update' draw tab button.
- SURFACE_ALL - executes the 'Update all' draw tab button. Call after setting the surface resolution or smoothing strength and before calling the thickness tab commands.
- SAVE_CURRENT_SURFACE name extension - saves the current surface using the object name appended with 'name', in a form given by 'extension', which can be 'wrl', 'ply', 'nii.gz' or 'nhdr'. Note that 'name' can be omitted.
- OBJECT_OPACITY object_string alpha - sets the opacity of the object 'object_string' to the value 'alpha', which should be between 0.0 and 1.0. A value of 0.0 disables display of surfaces from this object in any window.
- THICKNESS_EST_DENSITY - executes the 'Estimate cortical density' button. This either runs over all 'Current Surfaces' if '(none)' is the currently selected surface, or only the selected 'Current Surface'.
- THICKNESS_SURFACE object_string - allows selection of one of the 'Current Surfaces' from the 'Current Surface' drop down menu in the thickness tab.
- THICKNESS_SURF_FIT - executes the 'Map over current' button.
- THICKNESS_SURF_SAVE - executes the 'Save results for current' button. This is applied to the current surface. The file name is automatically generated from the object and placed in the results directory.
- THICKNESS_SURF_LOAD - executes the 'Load results to current' button. This is applied to the current surface. The file name is the same as above.
- THICKNESS_ALTERNATE object_string - allows selection of one of the 'Alternate Surfaces' from the 'Alternate Surface' drop down menu in the thickness tab.
- THICKNESS_COMPARE - executes the 'Compare current to alternate' button.
- THICKNESS_CREATE - executes the 'Create surface in alternate' button.
- THICKNESS_SAVE_ALTERNATE name extension - saves the alternate surface using the object name appended with 'name', in a form given by 'extension', which can be 'wrl', 'ply', 'nii.gz' or 'nhdr'. Note that 'name' can be omitted.
Other functions:
- DICOM_CALIBRATE - performs a BMD calibration on DICOM data, as described here.
Running commands over multiple objects, or multiple times
loop [filter_string]
The loop command specifies that the following commands should be repeated for a variety of objects within this file.
- filter_string - an optional string which will be used to filter the 'current objects'. Normal string wild-cards are supported. Otherwise the loop will be over all objects.
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 count
The repeat command specifies that the following commands should be repeated a number of times.
- count - a number which defines the number of repeats.
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.
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
- When an argument or a file path contains a space, the entire string must be enclosed in double quotes.
- The script is only tab or space delimited. It does not support commas.
- Text following '#' is interpreted as a comment.
The following are example of a simple movie, a more complex movie and also a cortical bone mapping script.
# 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
# where to put the images
results_dir D:\movies\movie2\
# disable frames and centres-of-gravity
param SEE_OUTLINES 0
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
# '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