Provided by: medcon_0.10.5-2.1_i386 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.

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

                                                                     MEDCON(1)