.\" Man page generated from reStructuredText. . .TH "PLASTIMATCH" "1" "Nov 03, 2022" "Plastimatch 1.9.4" "Plastimatch" .SH NAME plastimatch \- register, convert, warp, and manipulate 3D images . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch command [options] .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp The plastimatch executable is used for a variety of operations on either 2D or 3D images, including image registration, warping, resampling, and file format conversion. The form of the options depends upon the command given. The list of possible commands can be seen by simply typing "plastimatch" without any additional command line arguments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ plastimatch plastimatch version 1.9.4 Usage: plastimatch command [options] Commands: add adjust average bbox boundary crop compare compose convert dice diff dmap dose drr dvh fdk fill filter gamma header intersect jacobian lm\-warp mabs mask maximum ml\-convert multiply probe register resample scale segment sift stats synth synth\-vf threshold thumbnail union warp wed xf\-convert xf\-invert For detailed usage of a specific command, type: plastimatch command .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH ADD .sp The \fIadd\fP command is used to add one or more images together and create an output image. The contributions of the input images can be weighted with a weight vector. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch add [options] input_file [input_file ...] Options: \-\-average produce an output file which is the average of the input files (if no weights are specified), or multiply the weights by 1/n \-\-output output image \-\-weight specify a vector of weights; the images are multiplied by the weight prior to adding their values .ft P .fi .UNINDENT .UNINDENT .SS Examples .sp To add together files 01.mha, 02.mha and 03.mha, and save the result in the file output.mha, you can run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch add \-\-output output.mha 01.mha 02.mha 03.mha .ft P .fi .UNINDENT .UNINDENT .sp If you wanted output.mha to be 2 * 01.mha + 0.5 * 02.mha + 0.1 * 03.mha, then you should do this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch add \e \-\-output output.mha \e \-\-weight "2 0.5 0.1" \e 01.mha 02.mha 03.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH ADJUST .sp The \fIadjust\fP command is used to adjust the intensity values within an image. The adjustment operations available are truncation, linear scaling, histogram matching as well as global and local linear matching. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch adjust [options] Options: \-h, \-\-help display this help message \-\-hist\-levels number of histogram bins for histogram matching, default is 1024 \-\-hist\-match reference image for histogram matching \-\-hist\-points number of match points for histogram matching, default is 10 \-\-hist\-threshold threshold at mean intensity (simple background exclusion) for histogram matching \-\-input input directory or filename \-\-input\-mask input image mask, only affects \-\-linear\-match and \-\-local\-match \-\-linear shift and scale image intensities, provide a string with " " \-\-linear\-match reference image for linear matching with mean and std \-\-local\-match reference image for patch\-wise shift and scale. You must specify the \-\-patch\-size \-\-local\-blending\-off no trilinear interpolation of shifts and scales \-\-local\-scale\-out filename to store pixel\-wise scales \-\-local\-shift\-out filename to store pixel\-wise shifts \-\-output output image \-\-patch\-size patch size for local matching; provide 1 "n" or 3 values "nx ny nz" \-\-pw\-linear a string that forms a piecewise linear map from input values to output values, of the form "in1,out1,in2,out2,..." \-\-ref\-mask reference image mask, only affects \-\-linear\-match and \-\-local\-match \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .sp The adjust command can be used to make a piecewise linear adjustment of the image intensities. The \-\-pw\-linear option is used to create the mapping from input intensities to output intensities. The input intensities in the curve must increase from left to right in the string, but output intensities are arbitrary. Input intensities below the first pair or after the last pair are transformed by extrapolating the curve out to infinity with a slope of +1. A different slope may be specified out to positive or negative infinity by specifying the special input values of \-inf and +inf. In this case, the second number in the pair is the slope of the curve, not the output intensity. You can do a simplified linear transformation of gray levels with the \-\-linear option. For this, you need to provide a string with " ". .sp In addition, you can adjust the image intensities based on a reference image. With \-\-linear\-match, a linear transformation (shift and scale) is determined from mean and standard deviation of pixel values in reference and input image. If the input image feaures local intensity inconsistencies, you can choose a patch\-based intensity correction using the \-\-local\-match option. Similar to \-\-linear\-match, shift and scale are computed patch\-wise from mean and standard deviation. For both options, you can provide masks that specify the regions taken into account. Finally, choose \-\-hist\-match to perform histogram matching. .sp You can only choose one of \-\-linear, \-\-pw\-linear, \-\-linear\-match, \-\-local\-match and \-\-hist\-match. Beware that a reference filename has to be added for matching options. .SS Examples .sp The following command will add 100 to all voxels in the image: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-pw\-linear "0,100" .ft P .fi .UNINDENT .UNINDENT .sp The following command does the same thing, but with explicit specification of the slope in the extrapolation area: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-pw\-linear "\-inf,1,0,100,inf,1" .ft P .fi .UNINDENT .UNINDENT .sp The following command truncates the inputs to the range of [\-1000,+1000]: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-pw\-linear "\-inf,0,\-1000,\-1000,+1000,+1000,inf,0" .ft P .fi .UNINDENT .UNINDENT .sp The following command scales and then shifts all voxel values by 2.5 and +1000, respectively. (Use either comma or space to separate the values): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-linear "1000,2.5" .ft P .fi .UNINDENT .UNINDENT .sp The following command matches the histogram of infile.nrrd to be similar to that of reference.nrrd: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-hist\-match reference.nrrd \e \-\-hist\-levels 1000 \-\-hist\-points 12 .ft P .fi .UNINDENT .UNINDENT .sp The following command matches mean and standard deviation of intensities in the input image to equal those of the reference image: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-linear\-match reference.nrrd .ft P .fi .UNINDENT .UNINDENT .sp The following command also matches mean and standard deviation, but calculates statistics only from inside the mask regions (note that masks are only used for statistic calculations, you would need to use plastimatch mask to reset outside values): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-linear\-match reference.nrrd \e \-\-input\-mask inmask.nrrd \-\-ref\-mask refmask.nrrd .ft P .fi .UNINDENT .UNINDENT .sp Finally, you can apply patch\-wise local intensity adjustment using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-local\-match reference.nrrd \e \-\-patch\-size "20 20 10" .ft P .fi .UNINDENT .UNINDENT .sp The \-\-local\-match option requires the input and reference to be spatially aligned. In order to reduce the influence of background pixels at the border, you can provide foreground masks for both images (if only one mask is given, it as also used for the second image): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch adjust \e \-\-input infile.nrrd \-\-output outfile.nrrd \e \-\-local\-match reference.nrrd \e \-\-patch\-size "20 20 10" \e \-\-input\-mask inmask.nrrd \e \-\-ref\-mask refmask.nrrd .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH AVERAGE .sp The \fIaverage\fP command is used to compute the (weighted) average of multiple input images. It is the same as the plastimatch \fIadd\fP command, with the \-\-average option specified. Please refer to \fI\%plastimatch add\fP for the list of command line arguments. .SS Example .sp The following command will compute the average of three input images: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch average \e \-\-output outfile.nrrd \e 01.mha 02.mha 03.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH AUTOLABEL .sp The \fIautolabel\fP command is an experimental program the uses machine learning to identify the thoracic vertibrae in a CT scan. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch autolabel [options] Options: \-h, \-\-help Display this help message \-\-input Input image filename (required) \-\-network Input trained network filename (required) \-\-output Output csv filename (required) .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH BOUNDARY .sp The \fIboundary\fP command takes a binary label image as input, and generates an image of the image boundary as the output. The boundary is defined as the voxels within the label which have neighboring voxels outside the label. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch boundary [options] input_file Required: \-\-output filename for output image .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH CROP .sp The \fIcrop\fP command crops out a rectangular portion of the input file, and saves that portion to an output file. The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch crop [options] Required: \-\-input=image_in \-\-output=image_out \-\-voxels="x\-min x\-max y\-min y\-max z\-min z\-max" (integers) .ft P .fi .UNINDENT .UNINDENT .sp The voxels are indexed starting at zero. In other words, if the size of the image is M \etimes N \etimes P, the x values should range between 0 and M\-1\&. .SS Example .sp The following command selects the region of size 10 \etimes 10 \etimes 10, with the first voxel of the output image being at location (5,8,12) of the input image: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch crop \e \-\-input in.mha \e \-\-output out.mha \e \-\-voxels "5 14 8 17 12 21" .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH COMPARE .sp The \fIcompare\fP command compares two files by subtracting one file from the other, and reporting statistics of the difference image. The two input files must have the same geometry (origin, dimensions, and voxel spacing). The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch compare image_in_1 image_in_2 .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command subtracts synth_2 from synth_1, and reports the statistics: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ plastimatch compare synth_1.mha synth_2.mha MIN \-558.201904 AVE 7.769664 MAX 558.680847 MAE 85.100204 MSE 18945.892578 DIF 54872 NUM 54872 .ft P .fi .UNINDENT .UNINDENT .sp The reported statistics are interpreted as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MIN Minimum value of difference image AVE Average value of difference image MAX Maximum value of difference image MAE Mean average value of difference image MSE Mean squared difference between images DIF Number of pixels with different intensities NUM Total number of voxels in the difference image .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH COMPOSE .sp The \fIcompose\fP command is used to compose two transforms. The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch compose file_1 file_2 outfile Note: file_1 is applied first, and then file_2. outfile = file_2 o file_1 x \-> x + file_2(x + file_1(x)) .ft P .fi .UNINDENT .UNINDENT .sp The transforms can be of any type, including translation, rigid, affine, itk B\-spline, native B\-spline, or vector fields. The output file is always a vector field. .sp There is a further restriction that at least one of the input files must be either a native B\-spline or vector field. This restriction is required because that is how the resolution and voxel spacing of the output vector field is chosen. .SS Example .sp Suppose we want to compose a rigid transform (rigid.tfm) with a vector field (vf.mha), such that the output transform is equivalent to applying the rigid transform first, and the vector field second. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch compose rigid.tfm vf.mha composed_vf.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH CONVERT .sp The \fIconvert\fP command is used to convert files from one format to another format. As part of the conversion process, it can also apply (linear or deformable) geometric transforms to the input images. In fact, \fIconvert\fP is just an alias for the \fIwarp\fP command. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch convert [options] Options: \-\-algorithm algorithm to use for warping, either "itk" or "native", default is native \-\-ctatts ct attributes file (used by dij warper) \-\-default\-value value to set for pixels with unknown value, default is 0 \-\-dicom\-with\-uids set to false to remove uids from created dicom filenames, default is true \-\-dif dif file (used by dij warper) \-\-dim size of output image in voxels "x [y z]" \-\-direction\-cosines oriention of x, y, and z axes; Specify either preset value, {identity,rotated\-{1,2,3},sheared}, or 9 digit matrix string "a b c d e f g h i" \-\-dose\-scale scale the dose by this value \-\-fixed fixed image (match output size to this image) \-\-input input directory or filename; can be an image, structure set file (cxt or dicom\-rt), dose file (dicom\-rt, monte\-carlo or xio), dicom directory, or xio directory \-\-input\-cxt input a cxt file \-\-input\-dose\-ast input an astroid dose volume \-\-input\-dose\-img input a dose volume \-\-input\-dose\-mc input an monte carlo volume \-\-input\-dose\-xio input an xio dose volume \-\-input\-prefix input a directory of structure set images (one image per file) \-\-input\-ss\-img input a structure set image file \-\-input\-ss\-list input a structure set list file containing names and colors \-\-interpolation interpolation to use when resampling, either "nn" for nearest neighbors or "linear" for tri\-linear, default is linear \-\-metadata patient metadata (you may use this option multiple times), option written as "XXXX,YYYY=string" \-\-modality modality metadata: such as {CT, MR, PT}, default is CT \-\-origin location of first image voxel in mm "x y z" \-\-output\-colormap create a colormap file that can be used with 3d slicer \-\-output\-cxt output a cxt\-format structure set file \-\-output\-dicom create a directory containing dicom and dicom\-rt files \-\-output\-dij create a dij matrix file \-\-output\-dose\-img create a dose image volume \-\-output\-img output image; can be mha, mhd, nii, nrrd, or other format supported by ITK \-\-output\-labelmap create a structure set image with each voxel labeled as a single structure \-\-output\-pointset create a pointset file that can be used with 3d slicer \-\-output\-prefix create a directory with a separate image for each structure \-\-output\-prefix\-fcsv create a directory with a separate fcsv pointset file for each structure \-\-output\-ss\-img create a structure set image which allows overlapping structures \-\-output\-ss\-list create a structure set list file containing names and colors \-\-output\-type type of output image, one of {uchar, short, float, ...} \-\-output\-vf create a vector field from the input xf \-\-output\-xio create a directory containing xio\-format files \-\-patient\-id patient id metadata: string \-\-patient\-name patient name metadata: string \-\-patient\-pos patient position metadata: one of {hfs,hfp,ffs,ffp} \-\-prefix\-format file format of rasterized structures, either "mha" or "nrrd" \-\-prune\-empty delete empty structures from output \-\-referenced\-ct dicom directory used to set UIDs and metadata \-\-series\-description series description metadata: string \-\-simplify\-perc delete percent of the vertices from output polylines \-\-spacing voxel spacing in mm "x [y z]" \-\-version display the program version \-\-xf input transform used to warp image(s) \-\-xor\-contours overlapping contours should be xor\(aqd instead of or\(aqd .ft P .fi .UNINDENT .UNINDENT .SS About referenced\-ct .sp The referenced\-ct option allows you to (a) create a dicom object which refers to existing objects and (b) copy metadata. The first function, referring to existing objects, uses the following logic to determine how references are made. .INDENT 0.0 .IP \(bu 2 If the input objects contain a RTSTRUCT but not an Image (CT), the Frame Of Reference UID (0020,0052), the Series Instance UID (0020,000e) within the RT Referenced Series Sequence (3006,0014), the Referenced SOP Instance UIDs (0008,1155), and the Referenced Frame Of Reference UID (3006,0024) are all set to UIDs of the Image of the referenced\-ct. .IP \(bu 2 If the input objects contain a RTDOSE but not a RTSTRUCT, the Referenced Structure Set Sequence (0008,1155) is set to the UID of the RTSTRUCT of the referenced\-ct. .IP \(bu 2 If the input objects contain a RTDOSE but not a RTPLAN, the Referenced Structure Set Sequence (0008,1155) is set to the UID of the RTPLAN of the referenced\-ct. .UNINDENT .sp For the second function, the following data are copied from the referenced\-ct. They are copied from the Image. .INDENT 0.0 .IP \(bu 2 Patient Name (0010,0010) .IP \(bu 2 Patient ID (0010,0020) .UNINDENT .SS Examples .sp The first example demonstrates how to convert a DICOM volume to NRRD. The DICOM images that comprise the volume must be stored in a single directory, which for this example is called "dicom\-in\-dir". Because the \-\-output\-type option was not specified, the output type will be matched to the type of the input DICOM volume. The format of the output file (NRRD) is determined from the filename extension. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input dicom\-in\-dir \e \-\-output\-img outfile.nrrd .ft P .fi .UNINDENT .UNINDENT .sp This example further converts the type of the image intensities to float. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input dicom\-in\-dir \e \-\-output\-img outfile.nrrd \e \-\-output\-type float .ft P .fi .UNINDENT .UNINDENT .sp The next example shows how to resample the output image to a different geometry. The \-\-origin option sets the position of the (center of) the first voxel of the image, the \-\-dim option sets the number of voxels, and the \-\-spacing option sets the distance between voxels. The units for origin and spacing are assumed to be millimeters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input dicom\-in\-dir \e \-\-output\-img outfile.nrrd \e \-\-origin "\-200 \-200 \-165" \e \-\-dim "250 250 110" \e \-\-spacing "2 2 2.5" .ft P .fi .UNINDENT .UNINDENT .sp Generally speaking, it is tedious to manually specify the geometry of the output file. If you want to match the geometry of the output file with an existing file, you can do this using the \-\-fixed option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input dicom\-in\-dir \e \-\-output\-img outfile.nrrd \e \-\-fixed reference.nrrd .ft P .fi .UNINDENT .UNINDENT .sp This next example shows how to convert a DICOM RT structure set file into an image using the \-\-output\-ss\-img option. Because structures in DICOM RT are polylines, they are rasterized to create the image. The voxels of the output image are 32\-bit integers, where the i^th bit of each integer has value one if the voxel lies with in the corresponding structure, and value zero if the voxel lies outside the structure. The structure names are stored in separate file using the \-\-output\-ss\-list option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input structures.dcm \e \-\-output\-ss\-img outfile.nrrd \e \-\-output\-ss\-list outfile.txt .ft P .fi .UNINDENT .UNINDENT .sp In the previous example, the geometry of the output file wasn\(aqt specified. When the geometry of a DICOM RT structure set isn\(aqt specified, it is assumed to match the geometry of the DICOM (CT, MR, etc) image associated with the contours. If the associated DICOM image is in the same directory as the structure set file, it will be found automatically. Otherwise, we have to tell plastimatch where it is located with the \-\-referenced\-ct option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch convert \e \-\-input structures.dcm \e \-\-output\-ss\-img outfile.nrrd \e \-\-output\-ss\-list outfile.txt \e \-\-referenced\-ct ../image\-directory .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH DICE .sp The plastimatch \fIdice\fP compares binary label images using Dice coefficient, Hausdorff distance, or contour mean distance. The input images are treated as boolean, where non\-zero values mean that voxel is inside of the structure and zero values mean that the voxel is outside of the structure. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch dice [options] reference\-image test\-image Options: \-\-all Compute Dice, Hausdorff, and contour mean distance (equivalent to \-\-dice \-\-hausdorff \-\-contour\-mean) \-\-contour\-mean Compute contour mean distance \-\-dice Compute Dice coefficient (default) \-\-hausdorff Compute Hausdorff distance and average Hausdorff distance .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command computes all three statistics for mask1.mha and mask2.mha: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch dice \-\-all mask1.mha mask2.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH DIFF .sp The plastimatch \fIdiff\fP command subtracts one image from another, and saves the output as a new image. The two input files must have the same geometry (origin, dimensions, and voxel spacing). .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch diff image_in_1 image_in_2 image_out .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command computes file1.nrrd minus file2.nrrd, and saves the result in outfile.nrrd: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch diff file1.nrrd file2.nrrd outfile.nrrd .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH DMAP .sp The plastimatch \fIdmap\fP command takes a binary label image as input, and creates a distance map image as the output. The output image has the same image geometry (origin, dimensions, voxel spacing) as the input image. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch dmap [options] Required: \-\-input input directory or filename \-\-output output image Optional: \-\-algorithm a string that specifies the algorithm used for distance map calculation, either "maurer", "danielsson", or "itk\-danielsson" (default is "danielsson") \-\-inside\-positive voxels inside the structure should be positive (by default they are negative) \-\-maximum\-distance voxels with distances greater than this number will have the distance truncated to this number \-\-squared\-distance return the squared distance instead of distance .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command computes a distance map file dmap.nrrd from a binary labelmap image label.nrrd.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch dmap \-\-input label.nrrd \-\-output dmap.nrrd .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH DRR .sp A digitally reconstructed radiograph (DRR) is a synthetic radiograph which can be generated from a computed tomography (CT) scan. It is used as a reference image for verifying the correct setup position of a patient prior to radiation treatment. .sp The drr program that comes with plastimatch takes a CT image as input, and generates one or more output images. The output images can be either pgm, pfm, or raw format. The command line usage is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch drr [options] [infile] Options: \-i, \-\-algorithm Choose algorithm {exact,uniform} \-\-autoscale Automatically rescale intensity \-\-autoscale\-range Range used for autoscale in form "min max" (default: "0 255") \-z, \-\-detector\-size The physical size of the detector in format "row col", in mm \-r, \-\-dim The output resolution in format "row col" (in mm) \-e, \-\-exponential Do exponential mapping of output values \-y, \-\-gantry\-angle Gantry angle for image source in degrees \-N, \-\-gantry\-angle\-spacing Difference in gantry angle spacing in degrees \-G, \-\-geometry\-only Create geometry files only \-h, \-\-help display this help message \-P, \-\-hu\-conversion Choose HU conversion type {preprocess,inline,none} \-c, \-\-image\-center The image center in the format "row col", in pixels \-I, \-\-input Input file \-s, \-\-intensity\-scale Scaling factor for output image intensity \-o, \-\-isocenter Isocenter position "x y z" in DICOM coordinates (mm) \-n, \-\-nrm Normal vector of detector in format "x y z" \-a, \-\-num\-angles Generate this many images at equal gantry spacing \-O, \-\-output Prefix for output file(s) \-t, \-\-output\-format Select output format {pgm, pfm, raw} \-S, \-\-raytrace\-details Create output file with complete ray trace details \-\-sad The SAD (source\-axis\-distance) in mm (default: 1000) \-\-sid The SID (source\-image\-distance) in mm (default: 1500) \-w, \-\-subwindow Limit DRR output to a subwindow in format "r1 r2 c1 c2",in pixels \-A, \-\-threading Threading option {cpu,cuda,opencl} (default: cpu) \-\-version display the program version \-\-vup The vector pointing from the detector center to the top row of the detector in format "x y z" .ft P .fi .UNINDENT .UNINDENT .sp An input file is required. The drr program can be used in either \fIsingle image mode\fP or \fIrotational mode\fP\&. In single image mode, you specify the complete geometry of the x\-ray source and imaging panel for a single image. In rotational mode, the imaging geometry is rotated in a circular arc around the isocenter, with a fixed source to axis distance (SAD), and projection images generated at fixed angular intervals. .SS Examples .sp The following example illustrates the use of single image mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C drr \-nrm "1 0 0" \e \-vup "0 0 1" \e \-g "1000 1500" \e \-r "1024 768" \e \-z "400 300" \e \-c "383.5 511.5" \e \-o "0 \-20 \-50" \e input_file.mha .ft P .fi .UNINDENT .UNINDENT .sp In the above example, the isocenter is chosen to be (0, \-20, \-50), the location marked on the CT image. The orientation of the projection image is controlled by the \fBnrm\fP and \fBvup\fP options. Using the default values of (1, 0, 0) and (0, 0, 1) yields the DRR shown on the right: [image] [image] .sp By changing the normal direction (\fBnrm\fP), we can choose different beam direction within an isocentric orbit. For example, an anterior\-posterior (AP) DRR is generated with a normal of (0, \-1, 0) as shown below: [image] .sp The rotation of the imaging panel is selected using the \fBvup\fP option. The default value of \fBvup\fP is (0, 0, 1), which means that the top of the panel is oriented toward the positive z direction in world coordinates. If we wanted to rotate the panel by 45 degrees counter\-clockwise on our AP view, we would set \fBvup\fP to the (1, 0, 1) direction, as shown in the image below. Note that \fBvup\fP doesn\(aqt have to be normalized. [image] .sp In rotional mode, multiple images are created. The source and imaging panel are assumed to rotate in a circular orbit around the isocenter. The circular orbit is performed around the Z axis, and the images are generated every \fB\-N ang\fP degrees of the orbit. This is illustrated using the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C drr \-N 20 \e \-a 18 \e \-g "1000 1500" \e \-r "1024 768" \e \-z "400 300" \e \-o "0 \-20 \-50" \e input_file.mha .ft P .fi .UNINDENT .UNINDENT .sp In the above example, 18 images are generated at a 20 degree interval, as follows: [image] .SH PLASTIMATCH DVH .sp The \fIdvh\fP command creates a dose value histogram (DVH) from a given dose image and structure set image. The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch dvh [options] Options: \-\-bin\-width specify bin width in the histogram in units of Gy (default=0.5) \-\-cumulative create a cumulative DVH (this is the default) \-\-differential create a differential DVH instead of a cumulative DVH \-\-dose\-units specify units of dose in input file as either cGy as "cgy" or Gy as "gy" (default="gy") \-h, \-\-help display this help message \-\-input\-dose dose image file \-\-input\-ss\-img structure set image file \-\-input\-ss\-list structure set list file containing names and colors \-\-normalization specify histogram values as either voxels "vox" or percent "pct" (default="pct") \-\-num\-bins specify number of bins in the histogram (default=256) \-\-output\-csv file to save dose volume histogram data in csv format \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .sp The required inputs are \-\-input\-dose, \-\-input\-ss\-img, \-\-input\-ss\-list, and \-\-output\-csv. The units of the input dose must be either Gy or cGy. DVH bin values will be generated for all structures found in the structure set files. The output will be generated as an ASCII csv\-format spreadsheet file, readable by OpenOffice.org or Microsoft Excel. .sp The default is a differential (standard) histogram, rather than the cumulative DVH which is most common in radiotherapy. To create a cumulative DVH, use the \-\-cumulative option. .sp The default is to create 256 bins, each with a width of 1 Gy. You can adjust these values using the \-\-num\-bins and \-\-bin\-width option. .SS Example .sp To generate a DVH for a single 2 Gy fraction, we might choose 250 bins each of width 1 cGy. If the input dose is already specified in cGy, you would use the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch dvh \e \-\-input\-ss\-img structures.mha \e \-\-input\-ss\-list structures.txt \e \-\-input\-dose dose.mha \e \-\-output\-csv dvh.csv \e \-\-input\-units cgy \e \-\-num\-bins 250 \e \-\-bin\-width 1 .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH FDK .sp The term FDK refers to the authors Feldkamp, Davis, and Kress who wrote the seminal paper "Practical cone\-beam algorithm" in 1984. Their paper describes a filtered back\-projection reconstruction algorithm for cone\-beam geometries. The fdk program in plastimatch is an implmenetation of the FDK algorithm. It takes a directory of 2D projection images as input, and generates a single 3D volume as output. .sp The command line usage is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch fdk [options] Options: \-x, \-\-detector\-offset The translational offset of the detector "x0 y0", in pixels \-r, \-\-dim The output image resolution in voxels "num (num num)" (default: 256 256 100 \-f, \-\-filter Choice of filter {none,ramp} (default: ramp) \-X, \-\-flavor Implementation flavor {0,a,b,c,d} (default: c) \-h, \-\-help display this help message \-a, \-\-image\-range Use a sub\-range of available images "first ((skip) last)" \-I, \-\-input Input file \-s, \-\-intensity\-scale Scaling factor for output image intensity \-O, \-\-output Prefix for output file(s) \-A, \-\-threading Threading option {cpu,cuda,opencl} (default: cpu) \-\-version display the program version \-z, \-\-volume\-size Physical size of reconstruction volume "s1 s2 s3", in mm (default: 300 300 150) .ft P .fi .UNINDENT .UNINDENT .sp The usage of the fdk program is best understood by following along with the tutorials: fdk_tutorial_i and fdk_tutorial_ii\&. .sp Three different formats of input files are supported. These are: .INDENT 0.0 .IP \(bu 2 Pfm format image files with geometry txt files .IP \(bu 2 Raw format image files with geometry txt files .IP \(bu 2 Varian hnd files .UNINDENT .sp The pfm and raw files are similar, in that they store the image as an array of 4\-byte little\-endian floats. The only difference is that the pfm file has a header which stores the image size, and the raw file does not. .sp Each pfm or raw image file must have a geometry file in the same directory with the .txt extension. For example, if you want to use image_0000.pfm in a reconstruction, you should supply another file image_0000.txt which contains the geometry. A brief description of the geometry file format is given in proj_mat_file_format\&. .sp The sequence of files should be stored with the pattern: .INDENT 0.0 .INDENT 3.5 XXXXYYYY.ZZZ .UNINDENT .UNINDENT .sp where XXXX is a prefix, YYYY is a number, and .ZZZ is the extension of a known type (either .hnd, .pfm, or .raw). .sp For example the following would be a good directory layout for pfm files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Files/image_00.pfm Files/image_00.txt Files/image_01.pfm Files/image_01.txt etc... .ft P .fi .UNINDENT .UNINDENT .sp The Varian hnd files should be stored in the original layout. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Files/ProjectionInfo.xml Files/Scan0/Proj_0000.hnd Files/Scan0/Proj_0001.hnd etc... .ft P .fi .UNINDENT .UNINDENT .sp No geometry txt files are needed to reconstruct from Varian hnd format. .sp By default, when you generate a DRR, the image is oriented as if the virtual x\-ray source were a camera. That means that for a right lateral film, the columns of the image go from inf to sup, and the rows go from ant to post. The Varian OBI system produces HND files, which are oriented differently. For a right lateral film, the columns of the HND images go from ant to post, and the rows go from sup to inf. An illustration of this idea is shown in the figure below. .INDENT 0.0 .INDENT 2.5 [image] .UNINDENT .UNINDENT .SH PLASTIMATCH FILL .sp The \fIfill\fP command is used to fill an image region with a constant intensity. The region filled is defined by a mask file, with voxels with non\-zero intensity in the mask image being filled. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch fill [options] Options: \-\-input input directory or filename; can be an image or dicom directory \-\-mask input filename for mask image \-\-mask\-value value to set for pixels within mask (for "fill"), or outside of mask (for "mask" \-\-output output filename (for image file) or directory (for dicom) \-\-output\-format arg should be "dicom" for dicom output \-\-output\-type type of output image, one of {uchar, short, float, ...} .ft P .fi .UNINDENT .UNINDENT .SS Examples .sp Suppose we have a file prostate.nrrd which is zero outside of the prostate, and non\-zero inside of the prostate. We can fill the prostate with an intensity of 1000, while leaving non\-prostate areas with their original intensity, using the following command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch fill \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-mask\-value 1000 \e \-\-mask prostate.nrrd .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH FILTER .sp The \fIfilter\fP command applies a filter to an input image, and creates a filtered image as its output. The filter can be either built\-in, or custom. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch filter [options] input_image Options: \-\-gabor\-k\-fib choose gabor direction at index i within fibonacci spiral of length n; specified as "i n" where i and n are integers, and i is between 0 and n\-1 \-\-gauss\-width the width (in mm) of a uniform Gaussian smoothing filter \-\-kernel kernel image filename \-\-output output image filename \-\-output\-kernel output kernel filename \-\-pattern filter type: {gabor, gauss, kernel}, default is gauss .ft P .fi .UNINDENT .UNINDENT .sp The built\-in filters supported are "gabor" and "gauss". For a Gaussian, the width of the Gaussian can be controlled using the \-\-gauss\-width option. The Gabor filter is currently limited to automatic selection of filter directions, which are spaced quasi\-uniformly on the unit sphere. Custom filters are specified by supplying a kernel file, which is convolved with the image. .SS Example .sp The following command will generate a filtered image from the first gabor filter within a bank of 10 filters.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch filter \-\-pattern gabor Testing/rect\-1.mha \e \-\-gabor\-k\-fib "0 5" \-\-output g\-05.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH GAMMA .sp The \fIgamma\fP command compares two images using the so\-called gamma criterion. The gamma criterion specifies that images are similar at a givel location within a reference image if there exists a voxel with similar intensity nearby in the comparison image. Both local gamma and global gamma can be performed using this command. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch gamma [options] image_1 image_2 Options: \-\-analysis\-threshold Analysis threshold for dose in float (for example, input 0.1 to apply 10% of the reference dose). The final threshold dose (Gy) is calculated by multiplying this value and a given reference dose (or maximum dose if not given). (default is 0.1) \-\-compute\-full\-region With this option, full gamma map will be generated over the entire image region (even for low\-dose region). It is recommended not to use this option to speed up the computation. It has no effect on gamma pass\-rate. \-\-dose\-tolerance The scaling coefficient for dose difference. (e.g. put 0.02 if you want to apply 2% dose difference criterion) (default is 0.03) \-\-dta\-tolerance The distance\-to\-agreement (DTA) scaling coefficient in mm (default is 3) \-\-gamma\-max The maximum value of gamma to compute; smaller values run faster (default is 2.0) \-\-inherent\-resample Spacing value in [mm]. The reference image itself will be resampled by this value (Note: resampling compare\-image to ref\-image is inherent already). If arg < 0, this option is disabled. (default is \-1.0) \-\-interp\-search With this option, smart interpolation search will be used in points near the reference point. This will eliminate the needs of fine resampling. However, it will take longer time to compute. \-\-local\-gamma With this option, dose difference is calculated based on local dose difference. Otherwise, a given reference dose will be used, which is called global\-gamma. \-\-output Output image \-\-output\-failmap File path for binary gamma evaluation result. \-\-output\-text Text file path for gamma evaluation result. \-\-reference\-dose The prescription dose (Gy) used to compute dose tolerance; if not specified, then maximum dose in reference volume is used \-\-resample\-nn With this option, Nearest Neighbor will be used instead of linear interpolation in resampling the compare\-image to the reference image. Not recommended for better results. .ft P .fi .UNINDENT .UNINDENT .SS Example .sp A gamma image is produced from two input images using the default parameters. This will be a global gamma, using maximum intensity of the reference image as the gamma normalization value.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch gamma \-\-output gamma.mha \e reference\-image.mha compare\-image.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH HEADER .sp The \fIheader\fP command is used to display simple properties about the volume, such as the image data type and image geometry. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch header [options] input_file [input_file ...] Options: \-h, \-\-help display this help message \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .SS Example .sp We can display the geometry of any supported file type, such as mha, nrrd, or dicom. We can run the command as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ plastimatch header input.mha Type = float Planes = 1 Origin = \-180 \-180 \-167.75 Size = 512 512 120 Spacing = 0.7031 0.7031 2.5 Direction = 1 0 0 0 1 0 0 0 1 .ft P .fi .UNINDENT .UNINDENT .sp From the header information, we see that the image has 120 slices, and each slice is 512 x 512 pixels. The slice spacing is 2.5 mm, and the in\-plane pixel spacing is 0.7031 mm. .SH PLASTIMATCH JACOBIAN .sp The \fIjacobian\fP command computes the Jacobian determinant of a vector field. Either a Jacobian determinant image, or its summary statistics, can be computed. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch jacobian [options] Options: \-\-input input directory or filename of image \-\-output\-img output image; can be mha, mhd, nii, nrrd, or other format supported by ITK \-\-output\-stats output stats file; .txt format .ft P .fi .UNINDENT .UNINDENT .SS Example .sp To create a Jacobian determinant image from a vector field file vf.mha, run the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch jacobian \e \-\-input vf.mha \-\-output\-img vf_jac.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH LM-WARP .sp The landmark_warp executable performs landmark\-based deformable registration by matching corresponding point landmarks on the fixed and moving images. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch lm\-warp [options] Options: \-a, \-\-algorithm RBF warping algorithm {tps,gauss,wendland} \-d, \-\-default\-value Value to set for pixels with unknown value \-\-dim Size of output image in voxels "x [y z]" \-F, \-\-fixed Fixed image (match output size to this image) \-f, \-\-fixed\-landmarks Input fixed landmarks \-h, \-\-help display this help message \-I, \-\-input\-image Input image to warp \-v, \-\-input\-vf Input vector field (applied prior to landmark warping) \-m, \-\-moving\-landmarks Output moving landmarks \-N, \-\-numclusters Number of clusters of landmarks \-\-origin Location of first image voxel in mm "x y z" \-O, \-\-output\-image Output warped image \-L, \-\-output\-landmarks Output warped landmarks \-V, \-\-output\-vf Output vector field \-r, \-\-radius Radius of radial basis function (in mm) \-\-spacing Voxel spacing in mm "x [y z]" \-Y, \-\-stiffness Young modulus (default = 0.0) \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .sp Options "\-a", "\-r", "\-Y", "\-d" are set by default to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-a=gauss Gaussian RBFs with infinite support \-r=50.0 Gaussian width 50 mm \-Y=0.0 No regularization of vector field \-d=\-1000 Air .ft P .fi .UNINDENT .UNINDENT .sp You may want to choose different algorithm: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-a=tps Thin\-plate splines (for global registration) \-a=wendland Wendland RBFs with compact support (for local registration) .ft P .fi .UNINDENT .UNINDENT .sp In the case of Wendland RBFs "\-r" option sets the radius of support. .sp Regularization of vector field is available for "gauss" and "wendland" algorithms. To regularize the output vector field increase "\-Y" to \(aq0.1\(aq and up with increment \(aq0.1\(aq. .SS Example .sp To create a vector field from coresponding landmarks in fixed.fcsv and moving.fcs using Gaussian radial basis functions, do the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch lm\-warp \e \-\-output\-vf vf.nrrd \e \-\-fixed\-landmarks fixed.fcsv \-\-moving\-landmarks moving.fcsv .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH MABS .sp The \fImabs\fP command performs a multi\-atlas based segmentation (MABS) operation. The command can operate in one of several training mode, or in segmentation mode. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch mabs [options] command_file Options: \-\-atlas\-selection run just atlas selection \-\-convert pre\-process atlas \-\-output output (non\-dicom) directory when doing a segmentation \-\-output\-dicom output dicom directory when doing a segmentation \-\-pre\-align pre\-process atlas \-\-segment use mabs to segment the specified image or directory \-\-train perform full training to find the best registration and segmentation parameters \-\-train\-atlas\-selection run just train atlas selection \-\-train\-registration perform limited training to find the best registration parameters only .ft P .fi .UNINDENT .UNINDENT .sp Prior to running the mabs command, you must create a configuration file, and you must arrange your training data into the proper directory format. For a complete description of the command file syntax and usage examples, please refer to the mabs_guidebook and the segmentation_command_file_reference\&. .SH PLASTIMATCH MASK .sp The \fImask\fP command is used to fill an image region with a constant intensity. The region filled is defined by a mask file, with voxels with zero intensity in the mask image being filled. Thus, it is the inverse of the \fIfill\fP command. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch mask [options] Options: \-\-input input directory or filename; can be an image or dicom directory \-\-mask input filename for mask image \-\-mask\-value value to set for pixels within mask (for "fill"), or outside of mask (for "mask" \-\-output output filename (for image file) or directory (for dicom) \-\-output\-format arg should be "dicom" for dicom output \-\-output\-type type of output image, one of {uchar, short, float, ...} .ft P .fi .UNINDENT .UNINDENT .SS Examples .sp Suppose we have a file called patient.nrrd, which is zero outside of the patient, and non\-zero inside the patient. If we want to fill in the area outside of the patient with value \-1000, we use the following command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch mask \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-negate\-mask \e \-\-mask\-value \-1000 \e \-\-mask patient.nrrd .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH ML-CONVERT .sp To be written. .SH PLASTIMATCH PROBE .sp The plastimatch \fIprobe\fP command is used to examine the image intensity or vector field displacement at one or more positions within a volume. The probe positions can be specified in world coordinates (in mm), using the \-\-location option, or as image indices using the \-\-index option. The locations or indices are linearly interpolated if they lie between voxels. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch probe [options] file Options: \-i, \-\-index List of voxel indices, such as "i j k;i j k;..." \-l, \-\-location List of spatial locations, such as "i j k;i j k;..." .ft P .fi .UNINDENT .UNINDENT .sp The command will output one line for each probe requested. Each output line includes the following fields.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PROBE# The probe number, starting with zero INDEX The (fractional) position of the probe as a voxel index LOC The position of the probe in world coordinates VALUE The intensity (for volumes) or displacement (for vector fields) .ft P .fi .UNINDENT .UNINDENT .SS Example .sp We use the index option to see an image intensity at coordinate (2,3,4), and the location option to see image intensities at two different locations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch probe \e \-\-index "2 3 4" \e \-\-location "0 0 0; 0.5 0.5 0.5" \e infile.nrrd .ft P .fi .UNINDENT .UNINDENT .sp The output will include three probe results. Each probe shows the probe index, voxel index, voxel location, and intensity. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 0: 2.00, 3.00, 4.00; \-22.37, \-21.05, \-19.74; \-998.725891 1: 19.00, 19.00, 19.00; 0.00, 0.00, 0.00; \-0.000197 2: 19.38, 19.38, 19.38; 0.50, 0.50, 0.50; \-9.793450 .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH REGISTER .sp The plastimatch \fIregister\fP command is used to peform linear or deformable registration of two images. The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch register command_file .ft P .fi .UNINDENT .UNINDENT .sp The command file is an ordinary text file, which contains a single global section and one or more stages sections. The global section begins with a line containing only the string "[GLOBAL]", and each stage begins with a line containing the string "[STAGE]". .sp The global section is used to set input files, output files, and global parameters, while the each stage section defines a sequential stage of processing. For a complete description of the command file syntax, please refer to the registration_command_file_reference\&. .SS Examples .sp If you want to register image_2.mha to match image_1.mha using B\-spline registration, create a command file like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # command_file.txt [GLOBAL] fixed=image_1.mha moving=image_2.mha img_out=warped_2.mha xform_out=bspline_coefficients.txt [STAGE] xform=bspline impl=plastimatch threading=openmp max_its=30 regularization_lambda=0.005 grid_spac=100 100 100 res=4 4 2 .ft P .fi .UNINDENT .UNINDENT .sp Then, run the registration like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch register command_file.txt .ft P .fi .UNINDENT .UNINDENT .sp The above example only performs a single registration stage. If you want to do multi\-stage registration, use multiple [STAGE] sections. Like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # command_file.txt [GLOBAL] fixed=image_1.mha moving=image_2.mha img_out=warped_2.mha xform_out=bspline_coefficients.txt [STAGE] xform=bspline impl=plastimatch threading=openmp max_its=30 regularization_lambda=0.005 grid_spac=100 100 100 res=4 4 2 [STAGE] max_its=30 grid_spac=80 80 80 res=2 2 1 [STAGE] max_its=30 grid_spac=60 60 60 res=1 1 1 .ft P .fi .UNINDENT .UNINDENT .sp For more examples, please refer to the image_registration_guidebook\&. .SH PLASTIMATCH RESAMPLE .sp The \fIresample\fP command can be used to change the geometry of an image. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch resample [options] Options: \-\-default\-value value to set for pixels with unknown value, default is 0 \-\-dim size of output image in voxels "x [y z]" \-\-direction\-cosines oriention of x, y, and z axes; Specify either preset value, {identity,rotated\-{1,2,3},sheared}, or 9 digit matrix string "a b c d e f g h i" \-F, \-\-fixed fixed image (match output size to this image) \-h, \-\-help display this help message \-\-input input directory or filename; can be an image or vector field \-\-interpolation interpolation type, either "nn" or "linear", default is linear \-\-origin location of first image voxel in mm "x y z" \-\-output output image or vector field \-\-output\-type type of output image, one of {uchar, short, float, ...} \-\-spacing voxel spacing in mm "x [y z]" \-\-subsample bin voxels together at integer subsampling rate "x [y z]" \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .SS Example .sp We can use the \-\-subsample option to bin an integer number of voxels to a single voxel. So for example, if we want to bin a cube of size 3x3x1 voxels to a single voxel, we would do the following. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch resample \e \-\-input infile.nrrd \e \-\-output outfile.nrrd \e \-\-subsample "3 3 1" .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH SCALE .sp The \fIscale\fP command scales an image or vector field by multiplying each voxel by a constant value. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch scale [options] input_file Options: \-\-output filename for output image or vector field \-\-weight scale the input image or vector field by this value (float) .ft P .fi .UNINDENT .UNINDENT .SS Example .sp This command creates an output file with image intensity (or voxel length) twice as large as the input values: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch scale \-\-output output.mha \-\-weight 2.0 input.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH SEGMENT .sp The \fIsegment\fP command does simple threshold\-based semgentation. The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch segment [options] Options: \-h, \-\-help Display this help message \-\-input Input image filename (required) \-\-lower\-threshold Lower threshold (include voxels above this value) \-\-output\-dicom Output dicom directory (for RTSTRUCT) \-\-output\-img Output image filename \-\-upper\-threshold Upper threshold (include voxels below this value) .ft P .fi .UNINDENT .UNINDENT .SS Example .sp Suppose we have a CT image of a water tank, and we wish to create an image which has ones where there is water, and zeros where there is air. Then we could do this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch segment \e \-\-input water.mha \e \-\-output\-img water\-label.mha \e \-\-lower\-threshold \-500 .ft P .fi .UNINDENT .UNINDENT .sp If we wanted instead to create a DICOM\-RT structure set, we should specify a DICOM image as the input. This will allow plastimatch to create the DICOM\-RT with the correct patient name, patient id, and UIDs. The output file will be called "ss.dcm". .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch segment \e \-\-input water_dicom \e \-\-output\-dicom water_dicom \e \-\-lower\-threshold \-500 .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH STATS .sp The plastimatch stats command displays a few basic statistics about the image onto the screen. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch stats file [file ...] .ft P .fi .UNINDENT .UNINDENT .sp The input files can be either 2D projection images, 3D volumes, or 3D vector fields. .SS Example .sp The following command displays statistics for the 3D volume synth_1.mha. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ plastimatch stats synth_1.mha MIN \-999.915161 AVE \-878.686035 MAX 0.000000 NUM 54872 .ft P .fi .UNINDENT .UNINDENT .sp The reported statistics are interpreted as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MIN Minimum intensity in image AVE Average intensity in image MAX Maximum intensity in image NUM Number of voxels in image .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command displays statistics for the 3D vector field vf.mha: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ plastimatch stats vf.mha Min: 0.000 \-0.119 \-0.119 Mean: 13.200 0.593 0.593 Max: 21.250 1.488 1.488 Mean abs: 13.200 0.594 0.594 Energy: MINDIL \-6.79 MAXDIL 0.166 MAXSTRAIN 41.576 TOTSTRAIN 70849 Min dilation at: (29 19 19) Jacobian: MINJAC \-6.32835 MAXJAC 1.15443 MINABSJAC 0.360538 Min abs jacobian at: (28 36 36) Second derivatives: MINSECDER 0 MAXSECDER 388.82 TOTSECDER 669219 INTSECDER 1.524e+06 Max second derivative: (29 36 36) .ft P .fi .UNINDENT .UNINDENT .sp The rows corresponding to "Min, Mean, Max, and Mean abs" each have three numbers, which correspond to the x, y, and z coordinates. Therefore, they compute these statistics for each vector direction separately. .sp The remaining statistics are described as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MINDIL Minimum dilation MAXDIL Maximum dilation MAXSTRAIN Maximum strain TOTSTRAIN Total strain MINJAC Minimum Jacobian MAXJAC Maximum Jacobian MINABSJAC Minimum absolute Jacobian MINSECDER Minimum second derivative MAXSECDER Maximum second derivative TOTSECDER Total second derivative INTSECDER Integral second derivative .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH SYNTH .sp The \fIsynth\fP command creates a synthetic image. The following kinds of images can be created, by specifying the appropriate \-\-pattern option. Each of these patterns come with a synthetic structure set and synthetic dose which can be used for testing. .INDENT 0.0 .IP \(bu 2 donut \-\- a donut shaped structure .IP \(bu 2 gauss \-\- a Gaussian blur .IP \(bu 2 grid \-\- a 3D grid .IP \(bu 2 lung \-\- a synthetic lung with a tumor .IP \(bu 2 rect \-\- a uniform rectangle within a uniform background .IP \(bu 2 sphere \-\- a uniform sphere within a uniform background .IP \(bu 2 xramp \-\- an image that linearly varies intensities in the x direction .IP \(bu 2 yramp \-\- an image that linearly varies intensities in the y direction .IP \(bu 2 zramp \-\- an image that linearly varies intensities in the z direction .UNINDENT .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch synth [options] Options: \-\-background intensity of background region \-\-cylinder\-center location of cylinder center in mm "x [y z]" \-\-cylinder\-radius size of cylinder in mm "x [y z]" \-\-dicom\-with\-uids set to false to remove uids from created dicom filenames, default is true \-\-dim size of output image in voxels "x [y z]" \-\-direction\-cosines oriention of x, y, and z axes; Specify either preset value, {identity,rotated\-{1,2,3},sheared}, or 9 digit matrix string "a b c d e f g h i" \-\-donut\-center location of donut center in mm "x [y z]" \-\-donut\-radius size of donut in mm "x [y z]" \-\-donut\-rings number of donut rings (2 rings for traditional donut) \-\-dose\-center location of dose center in mm "x y z" \-\-dose\-size dimensions of dose aperture in mm "x [y z]", or locations of rectangle corners in mm "x1 x2 y1 y2 z1 z2" \-\-fixed fixed image (match output size to this image) \-\-foreground intensity of foreground region \-\-gabor\-k\-fib choose gabor direction at index i within fibonacci spiral of length n; specified as "i n" where i and n are integers, and i is between 0 and n\-1 \-\-gauss\-center location of Gaussian center in mm "x [y z]" \-\-gauss\-std width of Gaussian in mm "x [y z]" \-\-grid\-pattern grid pattern spacing in voxels "x [y z]" \-\-input input image (add synthetic pattern onto existing image) \-\-lung\-tumor\-pos position of tumor in mm "z" or "x y z" \-\-metadata patient metadata (you may use this option multiple times) \-\-noise\-mean mean intensity of gaussian noise \-\-noise\-std standard deviation of gaussian noise \-\-origin location of first image voxel in mm "x y z" \-\-output output filename \-\-output\-dicom output dicom directory \-\-output\-dose\-img filename for output dose image \-\-output\-ss\-img filename for output structure set image \-\-output\-ss\-list filename for output file containing structure names \-\-output\-type data type for output image: {uchar, short, ushort, ulong, float}, default is float \-\-patient\-id patient id metadata: string \-\-patient\-name patient name metadata: string \-\-patient\-pos patient position metadata: one of {hfs,hfp,ffs,ffp} \-\-pattern synthetic pattern to create: {cylinder, donut, dose, gabor, gauss, grid, lung, noise, rect, sphere, xramp, yramp, zramp}, default is gauss \-\-penumbra width of dose penumbra in mm \-\-rect\-size width of rectangle in mm "x [y z]", or locations of rectangle corners in mm "x1 x2 y1 y2 z1 z2" \-\-spacing voxel spacing in mm "x [y z]" \-\-sphere\-center location of sphere center in mm "x y z" \-\-sphere\-radius radius of sphere in mm "x [y z]" \-\-volume\-size size of output image in mm "x [y z]" .ft P .fi .UNINDENT .UNINDENT .SS Examples .sp Create a cubic water phantom 30 x 30 x 40 cm with zero position at the center of the water surface: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch synth \e \-\-pattern rect \e \-\-output water_tank.mha \e \-\-rect\-size "\-150 150 0 400 \-150 150" \e \-\-origin "\-245.5 245.5 \-49.5 449.5 \-149.5 149.5" \e \-\-spacing "1 1 1" \e \-\-dim "500 500 300" .ft P .fi .UNINDENT .UNINDENT .sp Create lung phantoms with two different tumor positions, and output to dicom: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch synth \e \-\-pattern lung \e \-\-output\-dicom lung_inhale \e \-\-lung\-tumor\-pos "0 0 10" plastimatch synth \e \-\-pattern lung \e \-\-output\-dicom lung_exhale \e \-\-lung\-tumor\-pos "0 0 \-10" .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH SYNTH-VF .sp The \fIsynth\-vf\fP command creates a synthetic vector field. The following kinds of vector fields can be created, by specifying the appropriate option. .INDENT 0.0 .IP \(bu 2 gauss \-\- a gaussian warp .IP \(bu 2 radial \-\- a radial expansion or contraction .IP \(bu 2 translation \-\- a uniform translation .IP \(bu 2 zero \-\- a vector field that is zero everywhere .UNINDENT .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch synth\-vf [options] Options: \-\-dim size of output image in voxels "x [y z]" \-\-direction\-cosines oriention of x, y, and z axes; Specify either preset value, {identity, rotated\-{1,2,3}, sheared}, or 9 digit matrix string "a b c d e f g h i" \-\-fixed An input image used to set the size of the output \-\-gauss\-center location of center of gaussian warp "x [y z]" \-\-gauss\-mag displacment magnitude for gaussian warp in mm "x [y z]" \-\-gauss\-std width of gaussian std in mm "x [y z]" \-\-origin location of first image voxel in mm "x y z" \-\-output output filename \-\-radial\-center location of center of radial warp "x [y z]" \-\-radial\-mag displacement magnitude for radial warp in mm "x [y z]" \-\-spacing voxel spacing in mm "x [y z]" \-\-volume\-size size of output image in mm "x [y z]" \-\-xf\-gauss gaussian warp \-\-xf\-radial radial expansion (or contraction) \-\-xf\-trans uniform translation in mm "x y z" \-\-xf\-zero Null transform .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH THRESHOLD .sp The \fIthreshold\fP command creates a binary labelmap image from an input intensity image. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch threshold [options] Options: \-\-above value above which output has value high \-\-below value below which output has value high \-h, \-\-help display this help message \-\-input input directory or filename \-\-output output image \-\-range a string that forms a list of threshold ranges of the form "r1\-lo,r1\-hi,r2\-lo,r2\-hi,...", such that voxels with intensities within any of the ranges ([r1\-lo,r1\-hi], [r2\-lo,r2\-hi], ...) have output value high \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command creates a binary label image with value 1 when input intensities are between 100 and 200, and value 0 otherwise.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch threshold \e \-\-input input_image.nrrd \e \-\-output output_labe.nrrd \e \-\-range "100,200" .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH THUMBNAIL .sp The \fIthumbnail\fP command generates a two\-dimensional thumbnail image of an axial slice of the input volume. The output image is not required to correspond exactly to an integer slice number. The location of the output image within the slice is always centered. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch thumbnail [options] input\-file Options: \-\-input file \-\-output file \-\-thumbnail\-dim size \-\-thumbnail\-spacing size \-\-slice\-loc location .ft P .fi .UNINDENT .UNINDENT .SS Example .sp We create a two\-dimensional image with resolution 10 x 10 pixels, at axial location 0, and of size 20 x 20 mm: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch thumbnail \e \-\-input in.mha \-\-output out.mha \e \-\-thumbnail\-dim 10 \e \-\-thumbnail\-spacing 2 \e \-\-slice\-loc 0 .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH UNION .sp The \fIunion\fP command creates a binary volume which is the logical union of two input images. Voxels in the output image have value one if the voxel is non\-zero in either input image, or value zero if the voxel is zero in both input images. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch union [options] input_1 input_2 Options: \-h, \-\-help display this help message \-\-output filename for output image \-\-version display the program version .ft P .fi .UNINDENT .UNINDENT .SS Example .sp The following command creates a volume that is the union of two input images: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch union \e \-\-output itv.mha \e phase_1.mha phase_2.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH WARP .sp The \fIwarp\fP command is an alias for \fIconvert\fP\&. Please refer to \fI\%plastimatch convert\fP for the list of command line parameters. .SS Examples .sp To warp an image using the B\-spline coefficients generated by the plastimatch register command (saved in the file bspline.txt), do the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input infile.nrrd \e \-\-output\-img outfile.nrrd \e \-\-xf bspline.txt .ft P .fi .UNINDENT .UNINDENT .sp In the previous example, the output file geometry was determined by the geometry information in the bspline coefficient file. You can resample to a different geometry using \-\-fixed, or \-\-origin, \-\-dim, and \-\-spacing. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input infile.nrrd \e \-\-output\-img outfile.nrrd \e \-\-xf bspline.txt \e \-\-fixed reference.nrrd .ft P .fi .UNINDENT .UNINDENT .sp When warping a structure set image, where the integer bits correspond to structure membership, you need to use nearest neighbor interpolation rather than linear interpolation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input structures\-in.nrrd \e \-\-output\-img structures\-out.nrrd \e \-\-xf bspline.txt \e \-\-interpolation nn .ft P .fi .UNINDENT .UNINDENT .sp Sometimes, voxels located outside of the geometry of the input image will be warped into the geometry of the output image. By default, these areas are "filled in" with an intensity of zero. You can choose a different value for these areas using the \-\-default\-value option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input infile.nrrd \e \-\-output\-img outfile.nrrd \e \-\-xf bspline.txt \e \-\-default\-value \-1000 .ft P .fi .UNINDENT .UNINDENT .sp In addition to images and structures, landmarks exported from 3D Slicer can also be warped. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input fixed_landmarks.fcsv \e \-\-output\-pointset warped_landmarks.fcsv \e \-\-xf bspline.txt .ft P .fi .UNINDENT .UNINDENT .sp Sometimes, it may be desirable to apply a transform explicitly defined by a vector field instead of using B\-spline coefficients. To allow this, the \-\-xf option also accepts vector field volumes. For example, the previous example would become. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch warp \e \-\-input fixed_landmarks.fcsv \e \-\-output\-pointset warped_landmarks.fcsv \e \-\-xf vf.mha .ft P .fi .UNINDENT .UNINDENT .SH PLASTIMATCH XF-CONVERT .sp The \fIxf\-convert\fP command converts between transform types. A transform can be either a B\-spline transform, or a vector field. There are two different kinds of B\-spline transform formats: the plastimatch native format, and the ITK format. In addition to converting the transform type, the \fIxf\-convert\fP command can also change the grid\-spacing of B\-spline transforms. .sp The command line usage is given as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Usage: plastimatch xf\-convert [options] Options: \-\-dim Size of output image in voxels "x [y z]" \-\-grid\-spacing B\-spline grid spacing in mm "x [y z]" \-\-input Input xform filename (required) \-\-nobulk Omit bulk transform for itk_bspline \-\-origin Location of first image voxel in mm "x y z" \-\-output Output xform filename (required) \-\-output\-type Type of xform to create (required), choose from {bspline, itk_bspline, vf} \-\-spacing Voxel spacing in mm "x [y z]" .ft P .fi .UNINDENT .UNINDENT .SS Example .sp We want to convert a B\-spline transform into a vector field. If the B\-spline transform is in native\-format, the vector field geometry is defined by the values found in the transform header.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch xf\-convert \e \-\-input bspline.txt \e \-\-output vf.mha \e \-\-output\-type vf .ft P .fi .UNINDENT .UNINDENT .sp Likewise, if we want to convert a vector field into a set of B\-spline coefficients with a control\-point spacing of 30 mm in each direction. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plastimatch xf\-convert \e \-\-input vf.mha \e \-\-output bspline.txt \e \-\-output\-type bspline \e \-\-grid\-spacing 30 .ft P .fi .UNINDENT .UNINDENT .SH AUTHOR Plastimatch is a collaborative project. For additional documentation, please visit http://plastimatch.org. For questions, comments, and bug reports, please visit http://groups.google.com/group/plastimatch. .SH COPYRIGHT Plastimatch development team (C) 2010-2022. You are free to use, modify, and distribute plastimatch according to a BSD-style license. Please see LICENSE.TXT for details. .\" Generated by docutils manpage writer. .