Ubuntu Manpage: medcon - MedCon conversion of medical image formats

Provided by: medcon_0.23.0-gtk3+dfsg-1_amd64

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. In case of a dual file format, like InterFile and Analyze,
              just mention its header filename.

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 one 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
split 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 one 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 useful to GIF89a or PNG.

-mr, --map-rainbow
Selects the rainbow colormap. This is only useful to GIF89a or PNG.

-mc, --map-combined
Selects the combined colormap. This is only useful to GIF89a or PNG.

-mi, --map-inverted
Selects the invers colormap. This is only useful 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 split
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
directory path as well. However, a directory 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 one 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.

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 one 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.  Display image headers:
            medcon -f filename1 filename2

  2.  Convert files:
            medcon -f filename1 filename2 -c gif acr intf

  3.  Interactive reading:
            medcon -i -f filename -c ecat

  4.  Extract alternate images:
            medcon -e 1:2:20 -f filename -c gif

  5.  Print pixel values
            medcon -p -f filename

  6.  Retrieve raw binary images and 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.

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

                                                                                        MEDCON(1)