Provided by: medcon_0.14.1-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.

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
              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 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 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)