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

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.

       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 one 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 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.

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

                                                                                        MEDCON(1)