Software at CIS: Brainworks: Modules

Tutorials | Modules | Change Log


BrainWorks scripts are text files that contain legal BrainWorks script commands and their parameters. The command syntax is described below. The BrainWorks script can be executed in two ways:

  1. Command line:
    bw -s <script file name>
  2. GUI Menu: File->Script. Select your BrainWorks script file.

Existing BrainWorks script command syntax:

<Required parameters>
[Optional parameters]


Converts 3D landmarks to 2D landmarks and 2D vice versa. Input can be either BW .lmk format (landmarks) or .lmi format (index) The user also has an option of outputing an index file (.lmi) if the input is a landmark file (.lmk).

Usage:  3D2Dlmk <3Dsurface.byu> <2Dsurface_er.p> <infile> <option 1> <option 2> <outfile>

                infile:  3D or 2D landmark filename (.lmi or .lmk, include extension)
                option 1:  if inputfile is a 3D landmark file then option 1 param is "3D".
                           if inputfile is a 2D landmark file then option 1 param is "2D".
                           if inputfile is a index file then option 1 param is "ind".
                option 2:  if Landmarks are to be saved as an index file the param is "1".
                           if Landmarks are not to be saved as an index file the param is "0" (Enter "0" if the input is a .lmi index file).
                outfile:  Output file name (do not include any extension).

SSD (Surface to Surface Distance Extraction)

If any of the points in surface 1 are greater than "max distance" to surface 2, they are removed from surface 1. Write surface 1 to the outputFile.

Usage: SSD <surface 1> <surface 2> <output file> <distance>

SD (Surface Distance)

Given a byu and its associated img and segmentation, calculate euclidean norm distances from voxels in img to closest surface vertices. Outputs are 2 float imgs
Usage:  SD <Surface.byu> <Volume.img> <Segmentation.img> <whitematter label> <output_distance file> <output_Indices file>


Distance from voxels to surface vertices. Takes an sMap generated by SD, and a 3 Peak segmentation file. Outputs are 3 .txt files containing raw distance data of GM/WM/CSF distances.
Usage:  ANTSY3P <Segmentation.img> <Smap.img> <RawDistance>
                 [Seg Tags: BG CSF GM WM]
                RawDistance:  Output file name (e.g. 1234_L_ant)
                Default Segmentation Tag Values:
                    BG = 0
                    CSF = 25
                    GREY = 75
                    WHITE = 125


Write the surface area and the volume of a surface to a file. Reads in a Surface File, determines the Surface Area and the Volume, then writes, or appends, these values to the specified output file.
Usage:  SurfStats <Surface.byu> <Stats output>
            [Output file options:  0 = overwrite, 1 = append (default = 0)]
            [X pixel size (default = 1.0)]
            [Y pixel size (default = 1.0)]
            [Z pixel size (default = 1.0)]

                Stats output: Enter output file name (e.g. 1234_L_ant.txt)


Extract a surface from the intersection of a surface and an image and/or segmentation. Reads in a Surface File, Image File, and Segmentation File. Determines, based on Image and Segmentation Files, and user parameters, which triangles should be discarded.
Usage:  SurfaceExtractRegion <Surface.byu> <image_vol.img> <segmentation.img> <ExtractedSurface.byu>
                [Min X (def = 0)] [Min Y (def = 0)] [Min Z (def = 0)]
                    Note - for Max values, -1 indicates use size of volume/segmentation
                [Max X (def = -1)] [Max Y (def = -1)] [Max Z (def = -1)]
                [keep where segmentation non-zero (0/1, default 1)]
                [keep where image non-zero (0/1, default 1)]
                [keep where seg value equals ... (0/1, default 0)] [seg value (default 0)]
                [keep where seg value not equal ... (0/1, default 0)] [seg value (default 0)]
                [keep where segmentation neighbors non-zero (0/1, default 0)]
                [keep where normals face non-zero in segmentation (0/1, default 0)]
                [keep where normals face value in segmentation (0/1, default 0)] [seg value (default 0)]
                [length of normals (default 1.0)]


Takes an image and a threshold value and creates a triangulated isocontour surface. Writes the resulting surface to the specified output file.
Usage:  SurfaceGeneration <Image.img> <IsoSurface Threshold> <IsoSurface.byu>
                [Optional Downsample Values:  x y z (def = 1.0)]


Surface vs. Surface Statistics. Calculates statistics on the distance data between two surfaces.
Usage:  SvSStats <Surface1.byu> <Surface2.byu> <Raw Stats output file> <Text Stats output file>
                [Surface1 dX dY dZ pixel sizes (default = 1.0)]
                [Surface2 dX dY dZ pixel sizes (default = 1.0)]


Creates an image of voxels from an input image that are no greater than the maximum distance from the input surface mask.
Usage:  MinDistFromSurfaceMask <Image.img> <SurfaceMask.byu> <MaskedImage.img> <MaximumDistance>
                [Optional WM Threshold: (def = -1.0, i.e., don't use)]


Reclassifies a 5 compartment bayesian segmentation into a 3 compartment segmentation using optimal thresholds derived from N-P likelihood ratio testing

Usage:  RESEG <Volume.img> <Segmentation.img> <stats> <PV1> <PV2> <Resegmentation.img>
                [Seg Tag Values:  BG CSF CSF/Grey Grey Grey/White White]
                PV1 - Partial Volume 1: Enter 0 to use default value 0.835
                PV2 - Partial Volume 2: Enter 0 to use default value 0.08
                Default Segmentation Tag Values:
                    BG = 0
                    CSF = 25
                    CSF/GREY = 50
                    GREY = 75
                    GREY/WHITE = 100
                    WHITE = 125

SubSD (Sub-surface Distance)

Given a parent surface and a child surface, calculate euclidean norm distances of voxels in img that are associated with child surface only

Usage:  SubSD <SurfaceP.byu> <SurfaceC.byu> <Segmentation.img> <output_distance file>  

CM (CurveMatch)

Takes coordinates of 2 curves as inputs and returns their corresponding matched coordinates.

Usage:  CM <Curve1> <Curve2> <coord1> <coord2> <#samp> <#lmk> <polyorder> <nghbsize> <a_coeff> <c_coeff> <t_coeff> [L];

                coord1: Output file that saves Curve1 landmarks
                coord2: Output file that saves Curve2 landmarks
	            #samp: Number of Samples (BW default = 100)
                #lmk: Number of Landmarks (BW default = 12)
                polyorder: Polynomial Order (BW default = 8)
                nghbsize: Neighborhood Size (BW default = 10)
                a_coeff: Arclength Co-efficient (BW default = 1)
                c_coeff: Curvature Co-efficient (BW default = 1)
                t_coeff: Torsion Co-efficient (BW default = 1)
                L = 1 saves Landmarks in BrainWorks .lmk format (default = 0)


Usage:  polyRedist <Surface.byu> <NewSurface.byu> <Redistribute alpha> <Redistribute iterations>

	            redistribute alpha (BW default = 0.005)
	            redistribute iterations (BW default = 50)


Given a set of landmarks defined on the original surface, find corresponding set of landmarks on the downsampled surface and calculate euclidiean distance between original and downsampled landmarks.

Usage:  newlmk <lmkfile.lmk> <downsampsrf.byu> <outputlmk> <Option 1>

                Option 1 saves Euclidean distances
                    1 Saves it to [outputlmk.txt].
                    0 Does not save the Euclidean Distances.


Curvature - Generate Surface Curvature Calculate the curvature of a surface and write it to a file

Usage:  Curvature <curvature type> <surface.byu> <output curvature file>
                [Curvature Depth (default = 2.0)]
                [Surface dX dY dZ pixel sizes (default = 1.0)]

                curvature type (def = 0):
                    0 = Maximum
                    1 = Minimum
                    2 = Mean
                    3 = Gaussian


Curvature - Generate Curve
Calculate a curve on a surface and write it to a file

Usage:  CurveGen <Surface.byu> <curve type> <output curve file>
                <Index1> <Index2> <distance output file>
                [Distance output file options:  0 = overwrite, 1 = append (default = 0)]


        CurveGen <Surface.byu> <curve type> <output curve file>
                <vertex1 x> <vertex1 y> <vertex1 z>
                <vertex2 x> <vertex2 y> <vertex2 z> <distance output file>
                [Distance output file options:  0 = overwrite, 1 = append (default = 0)]

        curve type:
                0 = Sulcus
                1 = Gyrus
                2 = Geodesic


SurfaceExtract - keeps vertices of largest connected component and deletes all other nodes

Usage:  SurfaceExtract <Surface.byu> <index> <NewSurface.byu> 


Segment - Create an image segmentation
Takes a volume and desired peaks, and creates an output segmentation and stats file with the specified file name prefix

Usage:  Segment <input volume> <segmentation type> <output file prefix>
                 <# CSF Peaks> [PK(1), PK(2), ..., PK(# CSF Peaks)] 
                 <# PV1 Peaks> [PK(1), PK(2), ..., PK(# PV1 Peaks)] 
                 <# Grey Peaks> [PK(1), PK(2), ..., PK(# Grey Peaks)] 
                 <# PV2 Peaks> [PK(1), PK(2), ..., PK(# PV 2 Peaks)] 
                 <# White Peaks> [PK(1), PK(2), ..., PK(# White Peaks)]
                 [CalculateDataMinMax (0 = don’t calculate, 1 = calculate; default = 0)]
                 [fix means:  0 = don't fix means, 1 = fix means (default = 0)]
                 [use weights for thresholds:  0 = don't use, 1 = use (default = 1)]
                  Segmentation type:
                      0 = Planes
                      1 = Cubes
                      2 = Chunks
Note - there are 5 compartments,  sum of compartmentCounts must equal number of peaks


L1Dist - Calculate the L1 Distance between an auto segmentation and a manual segmentation
Compare an automatic segmentation against a hand segmentation and return a value that represents the distance between the two.

Usage: L1Dist <Auto Segmentation.img> <Hand Segmentation.img> <Volume.img>
                 <Stats File.stats> <Output Distance File>
                 <L1 Distance Type> [Distance Type Parameters]
                 [Distance output file option:  0 = overwrite, 1 = append (default = 0)]
                 [Optional Seg Tag Values:  BG CSF PV1 Grey PV2 White]
        Segmentation Types and their Parameters:
            3/5 Peak = 0
            3/5 Peak Optimal PV = 1
            3/5 Peak PV1/2 = 2
            3 Peak w/IMIN = 3 
            GM Only w/IMIN = 4 
            GM Only = 5
            2 Peak GW = 6
            3 Peak C/G/W = 7
            3/5 Peak Select PV1/2 = 8 
        Default Segmentation Tag Values:
            BG = 0
            CSF = 25
            PV1 = 50
            GREY = 75
            PV2 = 100
            WHITE = 125


smoothSurfaceAvg - smooth a Surface by averaging.

Usage:   smoothSurfaceAvg <SurfaceIn.byu> <SmoothedSurface.byu> <NumIterations>


FlipPolyNormals - reorder the edges of the polys of a surface so as to flip the normals

Usage:   FlipPolyNormals <SurfaceIn.byu> <FlippedSurface.byu>


Below is a list of key programs I have identified as being used extensively by many BW users, that can benefit from a scriptable version and have an anxious audience awaiting the arrival of their command line counterparts:
  1. Surface/Contour distance - calculates distance between hand contours (manually generated) and polygonal mesh

Last Modified: Thursday, 02nd May, 2013 @ 10:46am