Introduction
Scripting is one of MRIcroGL’s most powerful features. New users can drag-and-drop the script files from MRIcroGL’s ‘script’ folder onto the program to learn about some of the useful features of this software. Advanced users can develop their own macros to automate repetitive tasks or create nice demos.
Pascal is used as the scripting language. To write a script, simply select View/Scripting to open the script engine. Type your commands into the text window and select Script/Compile to execute your script. You can also save and open scripts using the File menu. Here is a very simple script. It does one thing, which is to open the file named ch256.
begin LOADIMAGE('ch256'); end.
Note that MRIcroGL is pretty intelligent. It will use files named ch256.nii, ch256.nii.gz, and ch256.hdr in the program folder and the script’s folder. If no file is found, a dialog box allows the user to find the file. You could also be more explicit by running “Loadimage(‘c:\mri\dataset.hdr’)”, but this is not required.
Below is a list of all of the commands that are specific to this program, but one can also use regular Pascal commands (like loops, variables and constants). Here we use the constant ktime to specify the delay (100 msec between steps), and the variable i to loop through a series of views, creating an animation of a rotating image. Excellent examples of these techniques are demonstrated on the MRIcroGL examples web page.
LIST OF COMMANDS
ADDNODE (INTENSITY, R,G,B,A: byte) This command adds a new point to the color table. Consider the default color table that has only two nodes - black is node zero and white is node one. Running ADDNODE(192,255,0,0,64) would make images with 75% intensity (192/255) appear bright red, and be 25% opaque (64/255).
AZIMUTH (DEG: integer) This command rotates the rendering. For example, AZIMUTH(-20) rotates the image 20 degrees counter-clockwise
AZIMUTHELEVATION (AZI, ELEV: integer) Sets the viewer location. For example, AZIMUTHELEVATION(90,10) will show a sagittal (right side) view from a slightly inclined viewpoint. Zero degree azimuth refers to posterior, while 180 degrees is directly anterior. Note that these values are absolute, while the AZIMUTH and ELEVATION commands refer to relative changes in viewpoint.
BACKCOLOR (R,G,B: byte) Changes the background color. For example, BACKCOLOR(255, 0, 0) will show images on a bright red background
CAMERADISTANCE (Z: single) Sets the viewing distance from the object. Values near zero will appear inside the object (near the center of the object), values near 1 will appear at a reasonably close distance, and larger values will make the object appear quite small.
CHANGENODE(INDEX, INTENSITY, R,G,B,A: byte) This command adjusts a point in the color table. Consider the default color table that has only two nodes - black is node zero and white is node one. Running CHANGENODE(1,255,255,0,0,128) would change the formerly black-to-white color table to be black to bright red. Note that node zero can only have an intensity of zero and the final node must have an intensity of 255.
CLIP (DEPTH: single) Creates a clip plane that hides information close to the viewer. For example, CLIP(0.5) will hide all surfaces on the nearest half of the image.
CLIPFORMVISIBLE (VISIBLE: boolean) Shows or hides the clipping form. For example CLIPFORMVISIBLE(TRUE) shows the form, CLIPFORMVISIBLE(FALSE) hides the form.
COLORBARCOORD (L,T,R,B: single) Sets the position of the colorbar based on the Left, Top, Right and Bottom coordinates. The left and right coordinates are in the range 0..1 from the left to right of the screen, while the top and bottom components range from 0 near the bottom to 1 near the top. If the distance between L-R is greater than T-B then a horizontal colorbar will be shown, else a vertical colorbar is displayed.
COLORBARFORMVISIBLE (VISIBLE: boolean) Shows or hides the window that allows the user to interactively control the size and location of the colorbar. For example COLORBARFORMVISIBLE (TRUE) shows the form, COLORBARFORMVISIBLE (FALSE) hides the form.
COLORBARTEXT (VISIBLE: boolean) If set to true, then colorbars will include text that indicates intensity range. For example COLORBARTEXT(true).
COLORBARVISIBLE (VISIBLE: boolean) Shows a colorbar on the main images.
COLORNAME (FILENAME: string) Loads the requested colorscheme for the background image. For example, running COLORNAME(CT_KIDNEY) will apply the kidney color scheme.
CONTRASTFORMVISIBLE (VISIBLE: boolean) Shows or hides the contrast and color window. For example CONTRASTFORMVISIBLE (TRUE) shows the form, CONTRASTFORMVISIBLE (FALSE) hides the form.
CONTRASTMINMAX (MIN,MAX: single) Sets the minimum and maximum value for the color lookup table. For example, consider CONTRASTMINMAX(-200,500). In this case, a voxel with the value of -200 will be displayed with the darkest value in the color table, and voxel with a value of 500 will be shown with the brightest value
CUTOUT (L,A,S,R,P,I: single) Selects a sector to remove from rendering view. For example CUTOUT(0,0,0,0.5,0.5,0.5) will hide the left-anterior-superior hemiquadrant.
CUTOUTFORMVISIBLE (VISIBLE: boolean) Shows or hides the cutout window. For example CUTOUTFORMVISIBLE (TRUE) shows the form, CUTOUTFORMVISIBLE (FALSE) hides the form.
EDGEDETECT (THRESH: single; DILATECYCLES: integer) This procedure attempts to hide regions of consistent color from your image. Therefore, only the edges will remain. Thresh adjusts the erosion, and is a value greater than zero – values near zero will only leave the most salient edges, while values around 10 will only erode regions with a very consistent intensity. After the initial erosion, surviving edges can be regrown by using DILATECYCLES. For example, 2 dilate cycles will add two voxels on all sides of ach edge.
ELEVATION (DEG: integer) Changes the render camera up or down. For example, Elevation(20) moves the viewpoint 20-degrees above the object.
FRAMEVISIBLE (VISIBLE: boolean) Shows or hides the cube that appears around the rendered object. For example FRAMEVISIBLE(false) will hide the frame.
LOADIMAGE (FILENAME: string) Opens a NIfTI format image to view. For example, LOADIMAGE(’c:\mri\image.nii’) will open the file named ‘image.nii’.
MAXIMUMINTENSITY (MIP_ON: boolean) Changes the rendering mode between standard (which highlights surfaces of objects) and Maximum Intensity Projection that shows the brightest object, regardless of depth. For example MAXIMUMINTENSITY(false) switches to standard rendering.
MODALMESSAGE (STR: string) Displays a dialog box with a message. The script will wait until the user responds prior to continuing.
MODELESSMESSAGE (STR: string) A text message is shown on the main window. This message requires no response from the user, and the script does not pause for a response. The message is visible until the script sends a MODELMESSAGE(‘’) or until the application is restarted.
MOSAIC (STR: string) Shows a series of 2D slices. For example MOSAIC(V 0.1 H 0.2 A 0.3, 0.6, 0.9; A 0.5 S 0.5 C 0.5) shows two rows of images, each with three columns - the top row shows three axial views, while the bottom shows an axial, coronal and vertical slice. The vertical slices overlap 10% (V 0.1) and the horizontal slices overlap 20% (H 0.2).
- A: subsequent slices in axial orientation
- C: subsequent slices in coronal orientation
- H: Horizontal overlay, e.g. H 0.5 means each slice has 50% overlap. Values can range from –1 to 1.
- L: turns on (L+) or off (L-) text labels for slices
- S: subsequent slices in sagittal orientation
- V: Vertical overlap, from –1 to 1, e.g. V 0 means no vertical overlap
- Z: mirrored sagittal slice
- Numbers are used for each slice, with semicolons denoting new rows, so 0.1 0.2 0.6; 0.8 0.9 is a mosaic with five images, three in the first row and two in the second.
MOSAICFORMVISIBLE (VISIBLE: boolean) Shows or hides the mosaic designer window. For example CLIPFORMVISIBLE(TRUE) shows the form, CLIPFORMVISIBLE(FALSE) hides the form.
ORTHOVIEW (X,Y,Z: single) Shows a 2D projection view of the brain, with an axial slice at the Z coordinate, a coronal slice at the Y value, and a sagittal slice at the X coordinate. For example ORTHOVIEW(0.5,0.5,0.5) shows a slice inthe middle of the brain.
OVERLAYCLOSEALL This function has no parameters. All open overlays will be closed. The background image (if any) will remain opened.
OVERLAYCOLORFROMZERO (FROMZERO: Boolean) If set to false, then the full color range is used to show the overlay.If set to false, then the color range spans from zero to the most intense color. For example, consider an overlay with a color scheme that goes from black to bright red and a OVERLAYMINMAX(1,2). With colorfromzero set to false, a voxel with an intensity of 1 will appear black (minimum in the range 1..2). On the other hand, if colorfromzero is true, then this same voxel will appear dark red (as 1 is half way between 0 and 2). Note that in this case voxels darker than 1 will still be invisible (as they must exceed the 1..2 threshold set by overlayminmax).
OVERLAYCOLORNAME (OVERLAYNUMBER: integer; LUTFILENAME: string) Set the colorscheme for the target overlay to a specified name. For example OVERLAYCOLORNAME(1,’ CT_Kidneys’) will make the first overlay show intermediate brightness regions as red and very bright regions as white.
OVERLAYCOLORNUMBER (OVERLAYNUMBER,LUTINDEX: integer) Sets the color scheme for a overlay. For example, consider that you load a single overlay and want it to make it appear blue, you could call OVERLAYCOLORNUMBER(1,2). The LUTindex refers to the order of the colorscheme in the overlay menu’s drop down menu, such that 0=grayscale, 1=red, 2=blue, etc.
OVERLAYFORMVISIBLE (VISIBLE: boolean) Shows or hides the overlay window. For example OVERLAYFORMVISIBLE (TRUE) shows the form, OVERLAYFORMVISIBLE (FALSE) hides the form.
OVERLAYLOAD (FILENAME: string): integer Will add the overlay named filename and return the number of the overlay (as an integer value). Will return zero if unable to find the file or if there are too many overlays already loaded.
OVERLAYLOADSMOOTH (SMOOTH: boolean) Determines whether overlays are interpolated using trilinear interpolation (SMOOTH = true) or nearest neighbor (SMOOTH= false). Smoothed images will not appear jagged, but a thresholded map (where values below say Z=2.3 are set to zero) may appear to have dark edges. Note that this command does not influence currently loaded images; rather it sets how future images will be smoothed when overlayload is called.
OVERLAYMASKEDBYBACKGROUND (MASK: BOOLEAN) If true, than all overlays will be transparent on any voxel where the background image is transparent. If false, the overlay will always be shown, regardless of the background image. Sometimes it is nice to mask an overlay, so for example brain activity does not appear outside the brain. On the other hand, consider the glassbrain script, where we want to see overlays that are inside the brain’s shell. In this case, we would want to set this value to false.
OVERLAYMINMAX (OVERLAYNUMBER: integer; MIN,MAX: single) Sets the color range for the overlay. Values outside this range but closer to zero will not be displayed, voxels with more extreme values will appear with the maximum color from the color scheme For example OVERLAYMINMAX(1,2 9) will set the first overlay to have an intensity range of 2..9.
OVERLAYTRANSPARENCYONBACKGROUND (PERCENT: integer) Controls the opacity of the overlays on the background. For example, setting this to 50 will equally blend the overlays with the background, while 90 means that the overlays will be barely visible. Use –1 for an additive mixture (where the largest red, green and blue components are taken from each image).
OVERLAYTRANSPARENCYONOVERLAY (PERCENT: integer) Controls the opacity of the overlays on other overlays. For example, setting this to 50 will equally blend the overlays, while 90 means that the top overlay will be barely visible against a lower overlay. Use –1 for an additive mixture (where the largest red, green and blue components are taken from each image).
PERSPECTIVE (USEPERSPECTIVE: boolean) Toggles the usage of perspective on or off. If set on, closer objects will appear larger than more distant objects in the rendering window. If off, an orthographic projection is used (where size is not influenced by distance from viewer).
RESETDEFAULTS Sets all of the user adjustable settings to their default values. Calling this at the beginning of a script ensures that an image will always look identical, regardless of user-implemented changes.
SAVEBMP (FILENAME: string) Saves the currently viewed image as a JPG or PNG format bitmap image (format depends on FILENAME extension, if none specified the file is saved as JPG). If no file path is specified, the image is saved to the user’s desktop.
SCRIPTFORMVISIBLE (VISIBLE: boolean) Shows or hides the scripting window. For example SCRIPTFORMVISIBLE(TRUE) shows the form, SCRIPTFORMVISIBLE(FALSE) hides the form.
SETCOLORTABLE (TABLENUM: integer) Changes the color scheme used to display an image. For example, SETCOLORTABLE(0) applies the default gray-scale color scheme. To determine the color scheme number, open the Color and Transparency Window and check the pull-down menu. For example, the first item is the default talbe, so it has a value of zero, while Kidneys is the second item and has a value of 1.
SLICETEXT (VISIBLE: boolean) If true, the 2D slices will be displayed with text indicating which side is left and numbers indicating slice coordinates.
VIDEOCAPTUREFRAME Saves the current screen image to the movie animation. This call must be preceded by VIDEOSTART command. Call VIDEOCAPTUREFRAME once for each frame you wish to save in the movie. This command is only available when running Windows.
VIDEOEND Saves a movie to disk and stops recording. This command must be proceeded by a VIDEOSTART call and at least one VIDEOCAPTUREFRAME call, otherwise no action is taken. This function is called automatically when any script finishes execution or when a call to VIDEOSTART is made. Therefore, since this command is implicitly called, there is no need to explicitly include this command in your scripts, though it might improve the readability of your scripts. This command is only available when running Windows.
VIDEOSTART (FILENAME: string; FPS: integer; DEFAULTCODEC: boolean) Creates an avi format video. The frames per second of the video is set to FPS (or 20 if the value for FPS is less than 1). If DEFAULTCODEC is false, the user will be requested to select the compression method used. Note that VIDEOSTART must be followed by at least one VIDEOCAPTUREFRAME call, otherwise no video will be generated. Video recording stops when the script ends, a call to VIDEOEND is made or another call to VIDEOSTART is made (which closes the previous video and starts a new one). This command is only available when running Windows.
VIEWAXIAL (STD: boolean) Creates rendering from an axial viewpoint. VIEWAXIAL(true) shows a bird’s eye view (from directly above), while VIEWAXIAL(false) shows an image from directly below.
VIEWCORONAL (STD: boolean) Creates rendering from a coronal viewpoint. VIEWCORONAL(true) shows a view from directly in front, while VIEWCORONAL(false) shows an image from directly behind.
VIEWSAGITTAL (STD: boolean) Creates rendering from an sagittal viewpoint. VIEWAXIAL(true) shows a profile view with the anterior dimension on the right side, while VIEWSAGITTAL(false) has the anterior dimension on the left side.
WAIT (MSEC: integer) The program pauses for the specified duration. For example WAIT(1000) delays the script for one second.