acrtoana - DICOM and ACR/NEMA to Analyze

blue bar

Command line program to convert DICOM and ACR/NEMA to Analyze v7 or NIFTI-1 format. 

acrtoana [-over] [-isfil] [-mosaic n] [-rcv] [-noge] [-notime] [-scale]
	 [-diff [-fdt] [-fnomask] [-fnoeddy] [-pq] [-gfa]]
         [-fpv] [-dv] [-16 | -8 | -float | -autopixel] [-anon] [-anondate]
	 [-spos] [-itime] [-[no]spmo] [-sort | -nosort]
	 [-meta] [-mono] [-clip]
         [-analyze | -nif | -nii ] [-gz] [-v] [-exepath <path>]
         [-outpath path_for_converted_files] [path_to_ACR/NEMA_source_files]
-over
The converted Analyze files will overwrite existing Analyze files with the same name in the same subdirectory. If this option is not specified, existing Analyze files should not be overwritten but will be named with subsequent series numbers to the previously existing files.
-isfil
While converting to Analyze, try to determine whether images from a Siemens Vision are in mosaic format and if so, split them into individual images. This option will only work automatically if the mosaic image is not completely full of sub-images. If the mosaic is completely full then use the -mosaic option, below and accept that all images considered by acrtoana will be split up whether originally mosaic or not. The -sfil option is a compromise as it should only split obvious mosaic images which are not completely filled, however it may also misinterpret images with extreme rectangular field-of-views.
-mosaic n
While converting to Analyze, assume that all input images are in Siemens mosaic format, i.e., the input image is a mosaic of n sub-images where n is the number of images which would fill the mosaic, regardless of whether the mosaic is actually full or not. If n is not specified then the conversion may not perform as expected. Both this option and the previous option assume one dynamic non-interleaved volume per mosaic; if this is not the case then further processing of the Analyze image and header files may be necessary.
-rcv
Rotate Coronal VENDIE. If the images appear to be a coronal VENDIE acquisition (according to the sequence filename or protocol name stored in the ACR/NEMA header) then call the mirrot program to produce an additional Analyze file containing axial images.
-noge
Do not perform additional slice reordering on GE DICOM files. The slice order of GE DICOM files may be reversed depending on the direction in which the slices are prescribed on the MR console graphical interface. By default acrtoana attempts to standardise the slice order based on private GE messages in the DICOM header. Specifying -noge disables this additional correction.
-notime
The acquisition time ACR/NEMA message is ignored in the algorithm that determines which images belong together in an acquisition series. This may be useful when converted Analyze files are created with one image per file while the desire is to produce a combined Analyze file. This may occur from some manufacturer's images for dynamic acquisitions or when images have been post-processed on the scanner, e.g., a cardiac cine or rotating MIP.
-scale
If the intensity scaling factor stored in the ACR/NEMA header changes then start a new Analyze file. If this flag is not specified then changes in intensity scaling factor are ignored in the algorithm that determines which images belong togther in an acquisition series.
-diff
Attempt to recognise diffusion weighted acquisitions from information in the ACR/NEMA header. If a diffusion acquisition is detected, write the diffusion gradient vectors to an associated text file _dgv.txt, write a second Analyze file in which the images are ordered correctly for FSL's diffusion toolbox and also write associated the _bvecs, _bvals files, and write a text file containing the diffusion b matrices _bmat. It should work with DICOM images from Philips (release 10 and above), Siemens Syngo, and GE Excite systems, using product diffusion acquisitions. Data from acquisitions with more than two b values and which include a b=0 scan are written as both a single Analyze file and seperate Analyze files with pairs of b=0 and each b>0 diffusion scan in turn. This option is still being developed; in particular it can mistake DICOM images of on-line proceeded ADC and FA maps for actual diffusion images, although these should be easy to spot.
-fdt
If a diffusion acquisition is detected then after all file conversion has finished, perform basic post-processing using FSL's diffusion toolbox to perform eddy current correction, calculate the diffusion tensor, produce maps of Mean Diffusivity, Fractional Anisotropy, and an isotropic diffusion weighted image. This options requires that FSL is installed correctly and that the detected diffusion acquisition contained at least six diffusion directions. The processing is set running in the background and may take some time; no confirmation is given when processing is complete (other than appearence of the relevant image files) and this must be taken into consideration when rebooting the computer, especially if using Cygwin. Under UNIX or GNU/Linux, the background jobs are batched to run one after another which should prevent the system running too slowly, however, this feature is not available under Cygwin so be aware that using this option while converting DICOM images with more than one diffusion acquisition at any one time will slow down the computer significantly.
-fnomask
By default, the -fdt option, above, calls FSL's bet to create a brain mask. This may not be the appropriate choice for all data. Specifying this option disables creation of a brain mask.
-fnoeddy
By default, the -fdt option, above, calls FSL's eddy_correct script. To skip this step, specify this command line flag.
-pq
Also calculates the diffusion tensor isotropic p and anisotropic q components.
-gfa
Calculates the Generalised FA (thanks to Stam Sotiropoulos).
-mtr
If the acquisition is identified as having two volumes, one of which was acquired with a magnetization transfer saturation pulse (assuming to the the second volume), then an additional image file containing the MT ratio is calculated using FSL.
-fpv
Philips DICOM files contain two intensity scaling/offset values, a floating point scaling factor/offset and a display value scaling factor/offset. The floating point scaling factor/offset should best represent the MR signal. If the ACR/NEMA file contains Philips data then the floating point scale/offset will be stored in the Analyze header as funused1 and funused2 respectively, else the display value scaling factor/offset values will be stored in the Analyze header instead. This option is currently on by default.
-dv
The intensity scaling factor/offset stored in the Analyze header as funused1 and funused2 will always be the display value scale/offset regardless of whether the ACR/NEMA file contains Philips data or not. This is the current default for non-Philips data.
-8
Convert 16 bits-per-pixel data to 8 bits-per-pixel data in the final Analyze file. The maximum pixel intensity value will be scaled to 255 regardless of whether is was originally greater or less that 255. This option is not recommended.
-16
Converted Analyze files remain as unscaled 16 bits-per-pixel, regardless of whether the ACR/NEMA file contained 8 or 16-bits-per-pixel data.
-float
Converted Analyze files contain scaled floats (32 bits-per-pixel) with the intensity scaling and offset applied to the intensities in the image file.
-autopixel
If the pixel intensities will fit within 8 bits-per-pixel without scaling, regardless of the bits-per-pixel allocated in the source files, then do so. Else keep the unscaled pixel data as 16 bits-per-pixel. This is the default and recommended unless your supplementary post-processing software can only deal with images with 16 bits-per-pixel.
-anon
Pseudo-anonymization of patient identification is achieved by removing the patient's name in all converted files
-anon2
As above, except the real patient name remains in the .txt file associated with each Analyze file pair.
-anondate
Pseudo-anonymization of patient identification is achieved by replacing the patient's name by the numeric date and time of the first acquisition in each scanning session. The patient name is replaced by the date and time where ever it appears.
-anondate2
As above, except the real patient name remains in the .txt file associated with each Analyze file pair.
-weak
Convert ACR/NEMA files to Analyze format even if the length of the pixel data (i.e., image) does not agree with the expected size depending on the number of rows and columns and bits-per-pixel specified in the header. Use this option to convert ACR/NEMA files which appear otherwise to be correct, or files which may have extra messages stored after the image data. Note, currently acrtoana may not convert multiple images per single DICOM file correctly.
-acr
Assumes that input files are still in ACR/NEMA format even if the required message 0x00080010 is not found.
-nosave
Doesn't perform the actual conversion; just outputs what would be done. Useful to obtain a list of which ACR/NEMA images belong with which acquisition series.
-flipsag
Flip sagittal. If the ACR/NEMA image is a sagittal acquisition (or within 45 degrees of being sagittal) then flip the image left-right, to switch the default neuro nose pointing to the left, to nose pointing to the right. No other reordering if performed, i.e., no slice reordering.
-wild re
Only consider file in the source ACR/NEMA directory whose filenames match the regular expression re, where re is in shell-style regular expression format enclosed in quotes, e.g., -wild "*.img"
-wildnew re
Only consider file in the source ACR/NEMA directory whose filenames match the regular expression re, where re is in the new-style regular expression format (for systems that support this) enclosed in quotes, e.g., -wild "(.)+.img"
-sort
By default the ACR/NEMA images are considered in the order in which they are listed. By specifying this option, the filenames will be sorted in alphanumeric order according to the C strcmp command.
-nosort
Explicitly turn off additional sorting of ACR/NEMA filenames. The ACR/NEMA images are considered in the order in which they are listed. This is the default.
-meta
Save an additional text file containing some information from the DICOM header which may be required for subsequent scripting.
-mono
Indicates that any colour DICOM files should be converted and saved as a monochrome image.
-clip
Sets any intesity values greater than 32767 to be 32767. This ensures that unsigned data spanning all 16 bits will fit within signed short intensities. ('Unsigned short' is not a valid data type in the Analyze format, only in NIFTI, and as such, acrtoana would otherwise promote full range 16 bit unsigned short DICOM data to 'signed int', which is a valid Analyze datatype although twice the size.)
-limit [max_intensity]
Similar to the -clip option above, this older option clips high intensity values to max_intensity if specified, or 4096 if not. It was designed to be used with images containing 'burnt-in' overlays where the overlay intensity is considerably higher than the image intensities. Clipping the high overlay intensities to lower values allows both the image and overlay to be viewed without extreme windowing having to be performed. Its use is not recommended.
-analyze
Convert ACR/NEMA files to Analyze format, the default. If this flag is present with the -nif or -nii flags, the last occurance takes priority.
-nif
Save images in NIFTI-1 format, with separate .hdr and .img files, rather than in Analyze format. This option is only available if acrtoana was compiled using an ANSI C compiler. If this flag is present with the -analyze or -nii flags, the last occurance takes priority. This option is very slow converting data with a large number of images when the -gz option is also selected.
-nii
Save images in NIFTI-1 format as a combined .nii file, rather than in Analyze format. This option is only available if acrtoana was compiled using an ANSI C compiler. If this flag is present with the -analyze or -nif flags, the last occurance takes priority.
-gz
Compress the resultant Analyze or NIFTI files using gzip. This option is only available if the zlib libraries have been included during compilation with an ANSI C compiler.
-spos
Writes an additional text file containing slice positions for each slice in an Analyze file. If the DICOM header indicates a multistack acquisition, then examines the slice positions to determine whether the volume may contain overlapping stacks (with an integer number of overlapping slices). If so, then also write another text file containing command like options for mergestacks although mergestacks is not run automatically.
This option works for multistack anatomicals tyle acquisitions, however it may not work in a general case involving multivolume, multiecho, etc., acquisitions, so interpret the results carefully.
-itime
Writes an additional text file containing image acquisition time for each slice in the Analyze file. This information may be useful when attempting to synchronise image acquisition time with other recordings, such as fMRI stimulus delivery systems or physiological signal recordings.
This option works for standard fMRI style acquisitions, however it may not work in a general case involving multiecho, etc., acquisitions, so interpret the results carefully. Also, some DICOM images do not contain the acquisition date and time messages used by this option (DICOM messages 0x0008,0022 and 0x0008,0032) such as screen grabs and images post-processed on-line. In this case, dates and times of zeroes are written.
-spmo
The Analyze standard contains a text field for the institution name in the Originator field. SPM and other software overwrite this text field with three binary integers specifying the coordinate of an origin of the images. This option follows the SPM approach and writes the central voxel coordinate to the Analyze Originator field. The -nospmo flag causes the original Analyze format to be followed, writing a text string to this field instead. See below.
-pl
Indicates that a CSV file of the key MR acquisition parameters, extracted from the DICOM headers, should also be saved.
-quiet
Suppresses any of the normal progress output to the screen.
-d
Displays additional diagnostic output.
-v
Displays the date and time that acrtoana was compiled, and exits.
-exepath <path>
Depending on the options passed to acrtoana, the program may need to call other programs. The assumption is that these programs are already in the current PATH. If not, then the PATH to these programs maybe be specified here. If the PATH is explicitly specified here then the PATH inherited from the environment is not searched. If the path contains spaces it must be enclosed in double quotes. Note, enclosing a PATH in quotes in Windows may cause problems if the back-slash separator is taken as an escape character.
-outpath <path>
Specifies the destination subdirectory in which the converted Analyze files will be saved. If not specified then the converted files are saved in the same subdirectory as the source ACR/NEMA files. If the path contains spaces it must be enclosed in double quotes. Note, enclosing a PATH in quotes in Windows may cause problems if the back-slash separator is taken as an escape character.
path_to_ACR/NEMA_source_files
The subdirectory containing the source ACR/NEMA or DICOM files to be converted. Deeper subdirectories are not searched. If no directory is specified then the current directory is used by default.

acrtoana converts ACR/NEMA or DICOM files to Analyze format, and optionally to Windows BMP format. It examines all files in the path_to_ACR/NEMA_source_files directory that match the regular expression specified. If no regular expression is specified then it assumes the files will be named 0.img, 1.img, 2.img, etc. The program tries to determine which images belong together in the same Analyze file. As such, the filenames of the ACR/NEMA files should be ordered with increasing image number. If this is not the case, consider using dtoa as this renames the files depending on the image number specified in the ACR/NEMA header. Unfortunately there does not appear to be a standard algorithm for determining which images belong together in a single Analyze file especially for images in ACR/NEMA format. The program decides whether to start a new Analyze file if a crucial parameter in the current ACR/NEMA files differs from the same parameter in the previously read ACR/NEMA files, such as matrix size, echo time, image orientation, scanning protocol, image time, etc. Consideration of some of the more troublesome parameters may be controled using command-line flags. Analyze files are named setXX where XX is a number that is incremented when each new Analyze file is started. XX does not relate directly to the acquisition series number.

In addition to producing Analyze files, acrtoana also writes an associated .txt file containing the text output from the first ACR/NEMA or DICOM header used for each new Analyze file. The text file contains a lot of useful information which cannot be represented in the Analyze format. Also, the last few lines of the text file contain information relating to both the slice thickness and slice seperation of the images stored in the Analyze file, both quoted and measured values. Unfortunately the slice seperation can not be determined reliably from the DICOM and (in particular) ACR/NEMA files and so the z pixel size stored in the converted Analyze file is always the slice thickness, although for many post-processing applications, the slice seperation is the value that should be used. The z pixel size in the Analyze header may be editted manually using a wide range of programs including ibx or MRIcro. Also, the slice values quoted at the bottom of the text file may not be correct, especially for diffusion-weighted, multi-echo, and multi-stack acquisitions.

acrtoana follows the implication of the original Analyze v7 format and stores a text string of the institution name in the Originator field of the Analyze header. Some software, such as SPM assume that this field contains binary numbers specifying the anatomical origin of the volume. This results in what appears to be rubbish in this field if a SPM-aware program interprets the Originator text as numbers, and vice versa. See option -spmo above.

acrtoana.html cannot convert compressed image data stored in DICOM files; use MRIcro instead. DICOM also allows multiple images to be stored in a single file. acrtoana converts some of these DICOM files to Analyze but support is patchy. Colour DICOM files are converted to Analyze RGB format correctly. Apart from the -flipsag and -rcv flags above, acrtoana does not perform any flipping or mirroring of the image data; it remains in the same orientation as in the ACR/NEMA or DICOM file. The image order is defined by the order in which the source files are numbered (which, if used in combination with dtoa is defined by the image number specified in the DICOM header). As such, the converted Analyze files should be orientated in the same way as set on the scanner itself. This also includes the ordering of dynamic acquisitions as well as whether dynamic scans are grouped volume-by-volume or slice-by-slice. Converted Analyze files which are grouped slice-by-slice may be converted to the more usual volume-by-volume grouping by using swap34.

Siemens scanners have an option to combine images into a single large mosiac image which is often used for fMRI acquisitions. acrtoana should detect and unravel Siemens mosaic images from DICOM files exported from a syngo platform. To correctly interpret mosaic images written from a Siemens Vision MR scanner, explore the use of the -fil and -mosaic n command line options.

dtoa and acrtoana are similar programs with considerable overlap. Use dtoa routinely to convert DICOM to ACR/NEMA or Analyze format especially from a DICOM CD or DVD containing several patients' scans which need to be sorted and separated into unique subdirectories. Use acrtoana to convert DICOM or ACR/NEMA to Analyze format in a single subdirectory without sorting the input files in any way other than their filename. If conversion using dtoa fails then trying to identify the troublesome DICOM files may be more successful using acrtoana directly.

References