Docs / ProgramCLI
The command-line interface program has a few more features than its graphical user interface counterpart. It can be used for batch conversion, debugging image headers, printout pixel values, hack files with Acr/Nema tags and a little more. Besides, it can be very useful in powerfull Unix shell-scripts too! All you have to do is giving it the proper options ... ;-)
The man-page <medcon.1> tells you all about its options:
medcon [options] -f <files> ...
-f, --file, --files <files> ...
Read a list of files. In case of a dual file format, like InterFile and Analyze, just mention its header filename.
This color mode forces 24-bit RGB color images being reduced to an 8-bit indexed colormap. For color reduction in combination with dithering, see the -dith option.
This color mode keeps a 24-bit image as is.
Generate filenames based on patient and study information. The resulting basename is:
with the latter three id's applied in case the originating format is DICOM or Acr/Nema. See also -noprefix. Since Analyze does not have a patient_name, patient_id is used instead.
Make patient and study related entries anonymous (filled with 'X'). This option can not be used with option -ident.
Force writing of Uint8 or Int16 pixels. The special option -b16.12 only uses 12 bits, as unsigned however. With these options one can lose the quantified float values when the new format doesn't support a global rescale factor or slope/intercept.
Force writing of file in BIG endian type when supported by the format (see -little).
Set sort order in ECAT by frames, instead of the default anatomical sort (based on slice location). Indentical planes in each frame will be grouped together. You don't want this.
-c, --convert <output_format> <output_format> ...
Convert to the output formats mentioned on the command line listing. You can't use this option with -p.
Apply (DICOM) window centre/width contrast remapping. Although this may improve the display of images, any manufacturer independent pixel values (like HU, SUV) with quantitation options -qc or -qs will be lost.
Reslice the images of a volume into a coronal projection while preserving the real world dimensions.
This option allows to crop an equal frame from all images at <X>:<Y> where width and height are <W>:<H>. The upper-left corner of an image is at 0:0.
Apply cine sorting, 1st image of each time frame, 2nd image of each time frame, 3rd image of each time frame and so on. Reapplying does NOT undo this sorting. For this you need option -cu.
Undo the cine sorting (as a result from the option -cs).
Remap contrast using specified centre/width values. No spaces are allowed within this option. See also -contrast option.
Show debug info. After reading a file, the program will display the contents of the internal FILEINFO structure.
Only prints main header of CTI ECAT files to standard output.
Use dithering to improve quality of color reduction (from RGB to 8-bit indexed).
-e, --extract [image ranges ...]
A routine to extract images interactively, unless you specify normal style image ranges directly on the command-line separated by spaces. In normal style it is also possible to reorder the sequence of images. You need to specify an output conversion format (see option -c). Note that the extraction does NOT addapt the centre-centre slice separations. In other words, proper volume measurements could be lost.
Selection Type? 1=normal 2=ecat Normal Style ------------ - Any number must be one-based (0 = All reversed) - Syntax of range: X...Y or X-Y - Syntax of interval: X:S:Y (S = step) - The list is sequence sensitive! Give a list of images to extract? Ecat Style ---------- - Any number must be one-based (0 = All) - Syntax of range: X...Y or X-Y - Syntax of interval: X:S:Y (S = step) Give planes list? Give frames list? Give gates list? Give beds list?
A convenience function which quickly echoes the alias or human readable filename on screen, without any delay of image processing. For the syntax of this alias filename, see option -alias. The output could then be used in a script, for example to make interpretable links towards cryptic numbered files resulting from a DICOM series.
Disable or specify a fallback read format in case the autodetect failed.
Flip images horizontal (-fh) along the X-axis, vertical (-fv) along the Y-axis respectively. Parameters such as slice orientation are NOT changed. See also -rs option.
Enforce the mosaic file support for DICOM or Acr/Nema formats. The *stamps* will be splitted into separate slices according to the values supplied on the command-line. See also extra options -interl and -mfixv. The preset arguments are:
<W> = pixel width of image stamps (X) <H> = pixel height of image stamps (Y) <N> = total number of image stamps (Z) medcon -f imagefile -fmosaic=64x64x32
Remap coloured images to gray. This is necessary when you convert to formats which only support a grayscale colormap!
The spacing between slices is the true gap/overlap between sequential slices. In contrary to the default behaviour where the spacing between slices is measured from the centre to centre of two adjacent slices, therefor including the gap/overlap. Applied in DICOM and Acr/Nema.
Enables you to hack a file that contains Acr/Nema tags hidden somewhere. Some proprietary image formats do contain tags but are placed after some unknown headerinformation. This option will try to find some readable tags in the first 2048 bytes after which it will give some possible hints to get the images out of the file with the use of the interactive reading procedure (see -i). Ofcourse, this experimental procedure can fail badly ...
Selects the interactive reading procedure. Normally the program automatically detects the format or uses 'ecat' (or 'dicom') as default. With the interactive procedure it could be possible to read an uncompressed, unsupported format by answering the following questions:
Number of images? General header offset to binary data? Image header offset to binary data? Image header repeated before each image? Swap the pixel bytes? Same characteristics for all images? --- Absolute offset in bytes? Image columns? Image rows? Pixel data type? Redo input for next file?
The GUI allows to save such raw predef input (RPI) files, that can be used in a redirect statement:
medcon -f unsupported.img -c intf -i < predef.rpi
Doing so, you can create small scripts that will read and convert your unsupported images at once.
An interactive routine to specify the patient and study related information. This option can not be used with the option -anon. The questions asked are:
Give patient name? Give patient id? Select patient sex? Give study description? Give study name/p-number?
Another DICOM related option to enforce the implicit VR little transfer syntax as output, instead of the default explicit transfer syntax.
An extra option used in combination with forced mosaic (-fmosaic). The option indicates that the slices in the original mosaic are in fact interlaced. See also options -fmosaic and -mfixv.
Force writing of LITTLE endian files when supported by the format (see -big).
-lut, --load-lut <filename>
Load an external LUT color scheme: a dead simple file of 768 bytes consisting of 256 x red, 256 x green and 256 x blue byte values to make up the necessary 256 RGB triplets.
Selects the hotmetal, rainbow, invers (gray) or combined colormap. This is only usefull to GIF89a or PNG.
Another extra option used in combination with forced mosaic (-fmosaic). Choosing this option will rescale the real world voxel dimensions by the mosaic factor. See also -fmosaic and -interl.
Enable mosaic file support in DICOM or Acr/Nema format. The *stamps* will be splitted into separate slices according to values found in the file. To support other type of mosaic files, see option -fmosaic.
Preserve negative values. When not selected, all negative values are put to zero. In combination with quantitation (see -qs or -qc) the requested format must support pixels of type float, a global rescale factor or the more generic slope/intercept concept in order to preserve the (negative and positive) quantified values.
Normalize with minimum/maximum values found over images in a frame group (in case the original format has different frames). The default behaviour is normalization with minimum/maximum values found over all images. This can be important when the requested format requires a rescaling to a new pixeltype. The original pixel values then need to be rescaled to the new pixeltype boundaries based on the minimum/maximum values.
Write DICOM files without the part 10 meta header (group 0x0002).
Ignore absolute path mentioned in the "name of data file" key of an InterFile header. Do make sure then that the data file resides in the same directory as the header file.
This option disables the numbered prefix in the output filename. In combination with the -alias option, one could create human readable and alphabetical sorted files from DICOM or Acr/Nema multiple file volumes.
-o, --output-name <filename>
Changes output filename for all files to be created. It is allowed to specify a directory path as well. However, a directory path disables unique filename prefixing.
Write header and image to same file, as allowed for InterFile.
Define some GIF options when converting to the GIF format. Without this option a loop and background color are defined by default. This interactive routine asks the following questions:
Select color map? Insert a display loop? Delay 1/100ths of a second? Insert a transparent color? Transparent color? Background color?
Define some SPM options (origins) when converting to the Analyze format. The quantitation is not set. See also -spm & -ar. The interactive routine asks the following questions:
Origin X? Origin Y? Origin Z?
Show some specified pixel values. This is an interactive routine. Calibration and negative pixels are preserved automatically. You need to specify the -qs to preserve the quantification instead of the calibration. You can not use this option with -c. See also -pa option for a non-interactive routine.
- Finish the list with a negative number - Any number must be one-based (0 = All) - The syntax of a range: X...Y or X-Y - Just type <enter> for the entire range Selection Type? 1=normal 2=ecat Normal Style ------------ Give a list of image numbers? Give a list of pixels x,y ? Ecat Style ---------- Give planes list? Give frames list? Give gates list? Give beds list? Give a list of pixels x,y ?
Show all pixel values. This option is identical to -p, but doesn't require user input.
Increasing the slice matrix is done by padding an image with the lowest pixel value. The options above allow for different padding modes. Matrix changes happen when the output format does not allow differently sized images, and in case an -sqr or -sqr2 option was selected.
Respectivily use acquisition or series value in the numbered prefix of the new filename. This is useful for alphabetical file ordering, where leading zeros in DICOM elements are missing. See also -alias.
Enable quantitation using all scale factors (for now alias for -qc option).
A first scaling option to preserve the (ECAT) quantification (a) or to consider a first linear scaling slope with intercept (b).
qpv = ppv * quant_scale [counts/second/pixel] (a) qpv = ppv * slope + intercept (b) qpv = quantified pixel value ppv = plain pixel value
The 'quant_scale' factor normalizes all images in the file; quite important for merging purposes. When the corresponding format can not hold a 'quant_scale' factor for each image, the pixel values are saved as floats. Therefore, the highest pixel precision for correct quantitation is float, not double!
If the format does not support floats, the quantified pixel values get rescaled to an integer. Then only formats that support a global scaling factor or slope/intercept pair will preserve those quantified values.
Note that this option can not be used with -qc.
A second quantitation option to preserve the (ECAT) quantification as well as the (ECAT) calibration (a) or in general, using two rescale slopes with an intercept (b). These should normally transform pixels into manufacturer independent values. So one can assume that after a calibration, the new pixels will represent a real world unit (like concentration values (SUV), hounsfield units (HU) and alike).
cpv = ppv * quant_scale * calibr_fctr [uCi/ml] (a) cpv = ppv * slope1 * slope2 + intercept (b) cpv = calibrated pixel value ppv = plain pixel value qpv = quantified pixel value = ppv * quant_scale
The 'quant_scale' factor normalizes all images in the file; very important for merging purposes. The 'calibr_fctr' rescales the qpv-values to a new unit. When the corresponding format can not hold a compound factor for each image, the quantified values will be saved as floats. Therefore, the highest pixel precision for correct quantification is float and not double!
If the format does not support floats, the calibrated pixel values are rescaled to an integer type. Only formats that support a global scaling factor or slope/intercept pair preserve those calibrated values.
Note that in case of conversion, this option can not be used with -qs.
Rename the file basename. This option is only useful in case of conversion.
Reverse all the slices along the Z-axis. Parameters such as slice orientation are NOT changed. See also the -fh and -fv options.
Suppress all message, warning and error dialogs.
Reslice the images of a volume into a sagittal projection while preserving the real world dimensions.
Force remap of pixel values using specified slope/intercept
Skip the first image in an InterFile. In other words, the first image in the array will simply be ignored. Use this only when you are sure that the InterFile does contain an annoying/confusing preview slice.
-split4d, -splitf, --split-frames
Write out a study into separate files, one for each volume in a time frame (--split-frames) or each image slice (--split-slices) individually. The names of the files created will have an extra index number. See also -stack3d and -stack4d as opposite options.
Considering Analyze files for/from SPM. In this case the global scaling factor hidden in imd.funused will be used, as well as the hidden offset value in imd.funused.
In case of quantitation, the default output pixel type is float. This option allows to write integers combined with a global scale factor. To actually use the scaling factor, you must select a quantitation option like -qs or -qc as well.
See also -ar & -optspm.
Make all image matrices square, using the largest dimension.
Make all image matrices square, using the nearest power of two (between 64, 128, 256, 512 and 1024).
-stack4d, -stackf, --stack-frames
Write separate studies into one file. The --stack-slices option allows to write single image slice files into one 3D volume, while the --stack-frames option allows volumes of different time frames being written into one 4D file. The sequence of stacking is based on the file sequence given at the argument line. See also -split3d and -split4d as the opposite options.
Reslice the images of a volume into a transverse projection while preserving the real world dimensions.
-uin, --use-institution-name namestring
Change the program's default institution name, which is applied on studies without one. This does not override existing values. For a namestring with spaces, group between double quotes.
Verbose mode. Show some explaining messages during the reading and writing of files.
An interactive routine for editing voxel, array, slice and orient related entries in the FILEINFO structure.
Allow overwrite of existing files, without warning.
When no conversion was selected, the program will display the header information of each file.
When conversion was choosen, the program will automatically create new filenames in the current directory with the following syntax:
mXXX-filename.ext 'XXX' a number representing the XXX-th conversion 'ext' a corresponding extension of the new format Acr/Nema -> .ima Analyze -> .hdr + .img Dicom -> .dcm Ecat -> .img Gif -> .gif InterFile -> .h33 + .i33 INW -> .im NIfTI -> .nii PNG -> .png Raw Ascii -> .asc Raw Binary -> .bin
Some special remarks related to reading from stdin or writing to stdout.
a) reading from stdin:
Enable this by using an "-" mark instead of the list of input files.
This is supported for all formats and shouldn't cause any particular problems. Ofcourse, interactive routines are disabled because stdin is now in use by the image input.
Actually, this way only one or two formats are supported since seek() calls are not possible during pipes. The fact is that most of our formats are read using those seek() calls. In normal operation we already need a quick sneak in the file to determine the format. Because this fseek() isn't allowed, you must supply at least the input format too.
b) writing to stdout:
Enabled by using an extra "-" mark on the conversion list.
Only one inputfile is allowed. The converted output will be send to stdout.
In case of dual file formats such as Analyze or InterFile, the header information will be send to stderr. The reference to the image file in the header of an InterFile will ofcourse be wrong (since the program is not capable of knowing the resulting filename).
In case of RAW or ASCII output, the program will print the content of the internal FILEINFO struct to stderr as well. Please note that the (t)csh shell does not allow to catch stderr or stdout separately. In case of the bash shell, it is possible to say: