NAME
medcon - MedCon conversion of medical image formats
SYNOPSIS
medcon [options] -f files ...
DESCRIPTION
MedCon is a conversion utility intended for reconstructed nuclear medical
images.
The supported formats are:
Format Explanation Notation
------ ----------- --------
Ascii Raw ascii image arrays without header 'ascii'
Binary Raw binary image arrays without header 'bin'
Gif89a annimated GIF with colormap 'gif'
Acr/Nema Papyrus, Siemens (vers 2.0) 'acr'
INW RUG local format (vers 1.0) 'inw'
ECAT Siemens CTI ECAT 6 'ecat6' or 'ecat'
ECAT Siemens CTI ECAT 7 'ecat7'
InterFile version 3.3 'intf'
Analyze with consideration to SPM software 'anlz'
DICOM uses the VT-DICOM library 'dicom'
PNG Portable Network Graphics 'png'
Concorde Concorde/microPET 'conc'
NIfTI Neuroimaging Informatics Technology Initiative 'nifti'
FLAGS
-f, --file, --files <files> ...
Read a list of files.
OPTIONS
-8, --indexed-color
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.
-24, --true-color
This color mode keeps a 24-bit image as is.
-alias, --alias-naming
Generate filenames based on patient and study information. The
syntax of the resulting basename is:
<patient_name>+<study_id>+<study_date>+<study_time>
and
<series>+<acquisition>+<instance>
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.
-anon, --anonymous
Make patient and study related entries anonymous (filled with
'X'). This option can not be used with option -ident.
-b8, --unsigned-char
-b16, --signed-short
-b16.12
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.
-big, --big-endian
Force writing of big endian files when supported by the format.
-byframe, --sort-by-frame
Set sort order in ECAT by frames, instead of the default
anatomical sort (based on slice location). Identical planes in
each frame will be grouped together. You don't want this.
-c, --convert <format> ...
Convert with a list of formats to convert to. Use the notation
without quotes as specified in the above table. You can not use
this option with -p.
-contrast, --enable-contrast
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.
-cor, --coronal
Reslice the images of a volume into a coronal projection while
preserving the real world dimensions.
-crop=<X>:<Y>:<W>:<H>, --crop-images=<X>:<Y>:<W>:<H>
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.
-cs, --cine-sorting
Apply cine sorting, 1st image of each time frame, 2nd image of
each time frame, 3rd image of each time frame, ... (applicable
on gated SPECT). Reapplying does NOT undo this sorting. For this
you need option -cu.
-cu, --cine-undo
Undo the cine sorting (as a result of the option -cs).
-cw=<centre>:<width>
Remap contrast using specified centre/width pair. No spaces are
allowed within this option. See also -contrast options.
-d, --debug
Show debug info. After reading a file, the program will display
the contents of the internal FILEINFO structure.
-db Only print main header of CTI ECAT files to standard output.
-dith, --dither-color
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?
-ean, --echo-alias-name
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.
-fb-none, --without-fallback
-fb-anlz, --fallback-analyze
-fb-conc, --fallback-concorde
-fb-dicom, --fallback-dicom
-fb-ecat, --fallback-ecat
Disable or specify a fallback read format in case autodetect
failed.
-fh, --flip-horizontal
-fv, --flip-vertical
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 the -rs option.
-fmosaic=<W>x<H>x<N>, --force-mosaic=<W>x<H>x<N>
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=64x64x30
-g, --make-gray
Remap coloured images to gray. This is necessary when you
convert to formats which only support a grayscale colormap!
-gap, --spacing-true-gap
The spacing between slices is the true gap/overlap between
adjacent slices. In contrary to the default behaviour where the
spacing between slices is measured from the centre to centre of
two adjacent slices (including gap/overlap). Applied in DICOM &
Acr/Nema.
-hackacr, --hack-acrtags
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 option `-i'). This experimental procedure can
fail badly ...
-i, --interactive
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? (overrides above, 0 = unused)
Image columns?
Image rows?
Pixel data type?
Redo input?
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.
-ident, --identify
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 id/name/p-number?
Give series description?
-implicit, --write-implicit
Another DICOM related option to enforce the implicit VR little
transfer syntax as output, instead of the default explicit
transfer syntax.
-interl, --mosaic-interlaced
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.
-little, --little-endian
Force writing of little endian files when supported by the
format.
-lut, --load-lut <filename>
Load an external LUT color scheme.
-mh, --map-hotmetal
Selects the hotmetal colormap. This is only usefull to GIF89a or
PNG.
-mr, --map-rainbow
Selects the rainbow colormap. This is only usefull to GIF89a or
PNG.
-mc, --map-combined
Selects the combined colormap. This is only usefull to GIF89a or
PNG.
-mi, --map-inverted
Selects the invers colormap. This is only usefull to GIF89a or
PNG
-mfixv, --mosaic-fix-voxel
Another extra option used in combination with forced mosaic
(-fmosaic). Choosing this options will rescale the real world
voxel dimensions by the mosaic factor. See also -fmosaic and
-interl.
-mosaic, --enable-mosaic
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. This autodetect routine will always
fix the voxel sizes. To support other type of mosaic files, see
option -fmosaic.
-n, --negatives
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.
-nf, --norm-over-frames
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.
-nometa, --write-without-meta
Write DICOM files without the part 10 meta header (group
0x0002).
-nopath, --ignore-path
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.
-noprefix, --without-prefix
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/Name
multiple file volumes.
-o, --output-name <filename>
Changes output filename for ALL files to be created. It is
allowed to specify a full directory path as well. However, a
full path disables unique filename prefixing.
-one, --single-file
Write header and image to same file; as allowed for InterFile.
-optgif, --options-gif
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?
-optspm, --options-spm
Define some SPM options (origins) when converting to the Analyze
format. The quantification is not set. See also '-spm' & '-ar'.
The interactive routine asks the following questions:
Origin X?
Origin Y?
Origin Z?
-p, --print-values
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.
- Any number must be one-based (0 = All)
- Syntax of range : X...Y or X-Y
- Syntax of interval: X:S:Y (S = step)
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 ?
-pa, --print-all-values
Show all pixel values. This option is identical to -p, but
doesn't require user input.
-pad, --pad-around
-padtl, --pad-top-left
-padbr, --pad-bottom-right
Increasing the slice matrix is done by padding an image with the
lowest pixel value. The options above enable different padding
modes.
-preacq, --prefix-acquisition
-preser, --prefix-series
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.
-q, --quantitation
Enable quantitation using all scale factors (for now alias for
-qc option).
-qs, --quantification
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 rescale factor for each image, the quantified 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.
-qc, --calibration
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; quite
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 quantitation
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 this option can not be used with -qs.
-r, --rename-file
Rename the file basename. This option is only useful in case of
conversion.
-rs, --reverse-slices
Reverse all the slices along the Z-axis. Parameters such as
slice orientation are NOT changed. See also the -fh and -fv
options.
-s, --silent
Suppress all message, warning and error dialogs.
-sag, --sagittal
Reslice the images of a volume into a sagittal projection while
preserving the real world dimensions.
-si=<slope>:<intercept>
Force remap of pixel values using specified slope/intercept (y =
s*x + i). The quantitation option -qc is enabled by default. No
spaces are allowed within this option.
-skip1, --skip-preview-slice
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
-split3d, -splits, --split-slices
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.
-spm, --analyze-spm
Considering Analyze files for/from SPM. In this case the global
scaling factor hidden in imd.funused[1] will be used, as well as
the hidden offset value in imd.funused[0].
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 this scaling factor, you must select a quantitation option
like -qs or -qc as well.
See also -ar & -optspm.
-sqr, --make-square
Make all image matrices square, using the largest dimension.
Images are padded with the lowest pixel value. See also -pad
related options.
-sqr2, --make-square-two
Make all image matrices square, using the nearest power of two
(between 64, 128, 256, 512 and 1024). Images are padded with the
lowest pixel value. See also -pad related options.
-stack4d, -stackf, --stack-frames
-stack3d, -stacks, --stack-slices
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.
-tra, --transverse
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. However, this does not override existing
values. For a namestring with spaces, group between double
quotes.
-v, --verbose
Verbose mode. Show some explaining messages during the reading
and writing of files.
-vifi, --edit-fileinfo
An interactive routine for editing voxel,array,slice and orient
related entries in the FILEINFO struct.
-w, --overwrite-files
Allow overwrite of existing files, without warning.
NOTES
When no conversion was specified, the program will display the header
information of each image.
When conversion was specified, 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
Binary raw -> .bin
Ascii raw -> .asc
Gif89a -> .gif
Acr/Nema -> .ima
INW -> .im
ECAT -> .img
Interfile -> .h33 + .i33
Analyze -> .hdr + .img
DICOM -> .dcm
PNG -> .png
CONC -> .hdr + .dat
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.
1. redirect: medcon -f - < inputfile
This is supported for all formats and shouldn't cause any particular
problems. Interactive routines are disabled because stdin is now in use
by the image input.
2. pipes : cat inputfile | medcon -f - format
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.
medcon -f inputfile -c - format
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 shells do not allow to catch stderr or stdout separately. In
case of the bash shell, it is possible to say:
medcon -f inputfile -c - intf -b16.12 -qc 1>image 2>header
EXAMPLES
1. To display the image headers:
medcon -f filename1 filename2
2. To convert the images:
medcon -f filename1 filename2 -c gif acr intf
3. To read interactively
medcon -i -f filename -c ecat
4. To extract alternate images:
medcon -e 1:2:20 -f filename -c gif
5. To print out pixel values
medcon -p -f filename
6. Convert to raw binary images, send to standard output:
medcon -f filename -c - bin
FILES
/usr/local/xmedcon/include/ Directory with header files.
/usr/local/xmedcon/lib/ Directory with libraries.
/usr/local/xmedcon/bin/ Directory with executables.
/usr/local/xmedcon/man/ Directory with man-pages.
/usr/local/xmedcon/etc/ Directory with rcfiles.
SEE ALSO
xmedcon(1), xmedcon-config(1)
m-acr(4), m-anlz(4), m-gif(4), m-inw(4), m-intf(4), m-ecat(4)
medcon(3)
AUTHOR
(X)MedCon project was originally written by Erik Nolf (eNlf) for the former
PET-Centre at Ghent University (Belgium).
e-mail: enlf-at-users.sourceforge.net www: http://xmedcon.sourceforge.net