Provided by: medcon_0.10.7-1build1_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)