1MEDCON(1)                   General Commands Manual                  MEDCON(1)
2
3
4

NAME

6       medcon - MedCon conversion of medical image formats
7

SYNOPSIS

9       medcon [options] -f files ...
10

DESCRIPTION

12  MedCon  is  a  conversion utility intended for reconstructed nuclear medical
13  images.
14
15  The supported formats are:
16
17  Format                      Explanation                         Notation
18  ------                      -----------                         --------
19 Ascii       Raw ascii  image arrays without header           'ascii'
20 Binary      Raw binary image arrays without header           'bin'
21 Gif89a      annimated GIF with colormap                      'gif'
22 Acr/Nema    Papyrus, Siemens    (vers 2.0)                   'acr'
23 INW         RUG local format (vers 1.0)                      'inw'
24 ECAT        Siemens CTI ECAT 6                               'ecat6' or 'ecat'
25 ECAT        Siemens CTI ECAT 7                               'ecat7'
26 InterFile   version 3.3                                      'intf'
27 Analyze     with consideration to SPM software               'anlz'
28 DICOM       uses the VT-DICOM library                        'dicom'
29 PNG         Portable Network Graphics                        'png'
30 Concorde    Concorde/microPET                                'conc'
31 NIfTI       Neuroimaging Informatics Technology Initiative   'nifti'
32

FLAGS

34       -f, --file, --files <files> ...
35              Read a list of files. In case of a dual file format, like Inter‐
36              File and Analyze, just mention its header filename.
37
38

OPTIONS

40       -8, --indexed-color
41              This  color mode forces 24-bit RGB color images being reduced to
42              an 8-bit indexed colormap. For color  reduction  in  combination
43              with dithering see the -dith option.
44
45
46       -24, --true-color
47              This color mode keeps a 24-bit image as is.
48
49
50       -alias, --alias-naming
51              Generate  filenames  based on patient and study information. The
52              syntax of the resulting basename is:
53
54              <patient_name>+<study_id>+<study_date>+<study_time>
55                            and
56                <series>+<acquisition>+<instance>
57
58              with the latter three id's applied in case the originating  for‐
59              mat is DICOM or Acr/Nema. See also -noprefix. Since Analyze does
60              not have a patient_name, patient_id is used instead.
61
62
63       -anon, --anonymous
64              Make patient and study related entries  anonymous  (filled  with
65              'X'). This option can not be used with option -ident.
66
67
68       -b8, --unsigned-char
69
70       -b16, --signed-short
71
72       -b16.12
73              Force  writing  of  Uint8  or  Int16  pixels. The special option
74              -b16.12 only uses 12  bits,  as  unsigned  however.  With  these
75              options  one  can  lose the quantified float values when the new
76              format doesn't support a global rescale factor  or  slope/inter‐
77              cept.
78
79
80       -big, --big-endian
81              Force writing of big endian files when supported by the format.
82
83
84       -byframe, --sort-by-frame
85              Set sort order in ECAT by frames, instead of the default anatom‐
86              ical sort (based on slice location). Identical  planes  in  each
87              frame will be grouped together. You don't want this.
88
89
90       -c, --convert <format> ...
91              Convert  with  a list of formats to convert to. Use the notation
92              without quotes as specified in the above table. You can not  use
93              this option with -p.
94
95
96       -contrast, --enable-contrast
97              Apply  (DICOM)  window centre/width contrast remapping. Although
98              this may improve the display of images, any  manufacturer  inde‐
99              pendent  pixel  values  (like HU, SUV) with quantitation options
100              -qc or -qs will be lost.
101
102
103       -cor, --coronal
104              Reslice the images of a volume into a coronal  projection  while
105              preserving the real world dimensions.
106
107
108       -crop=<X>:<Y>:<W>:<H>, --crop-images=<X>:<Y>:<W>:<H>
109              This option allows one to crop an equal frame from all images at
110              <X>:<Y> where width and height are <W>:<H>. The upper-left  cor‐
111              ner of an image is at 0:0.
112
113
114       -cs, --cine-sorting
115              Apply  cine  sorting, 1st image of each time frame, 2nd image of
116              each time frame, 3rd image of each time frame,  ...  (applicable
117              on gated SPECT). Reapplying does NOT undo this sorting. For this
118              you need option -cu.
119
120
121       -cu, --cine-undo
122              Undo the cine sorting (as a result of the option -cs).
123
124
125       -cw=<centre>:<width>
126              Remap contrast using specified centre/width pair. No spaces  are
127              allowed within this option. See also -contrast options.
128
129
130       -d, --debug
131              Show  debug info. After reading a file, the program will display
132              the contents of the internal FILEINFO structure.
133
134
135       -db    Only print main header of CTI ECAT files to standard output.
136
137
138       -dith, --dither-color
139              Use dithering to improve quality of color reduction (from RGB to
140              8-bit indexed).
141
142       -e, --extract [image ranges ...]
143              A  routine  to  extract images interactively, unless you specify
144              normal style image ranges directly on the command-line separated
145              by  spaces.  In  normal style it is also possible to reorder the
146              sequence of images. You need to  specify  an  output  conversion
147              format (see option -c). Note that the extraction does NOT addapt
148              the centre-centre slice separations. In other words, proper vol‐
149              ume measurements could be lost.
150
151                   Selection Type?  1=normal    2=ecat
152
153                 Normal Style
154                 ------------
155
156          - Any number must be one-based (0 = All reversed)
157          - Syntax of range   : X...Y or X-Y
158          - Syntax of interval: X:S:Y    (S = step)
159          - The list is sequence sensitive!
160
161                 Give a list of images to extract?
162
163                 Ecat Style
164                 ----------
165
166          - Any number must be one-based (0 = All)
167          - Syntax of range   : X...Y or X-Y
168          - Syntax of interval: X:S:Y    (S = step)
169
170                 Give planes list?
171                 Give frames list?
172                 Give gates  list?
173                 Give beds   list?
174
175
176       -ean, --echo-alias-name
177              A  convenience  function which quickly echoes the alias or human
178              readable filename on screen, without any delay of image process‐
179              ing.  For  the syntax of this alias filename, see option -alias.
180              The output could then be used in a script, for example  to  make
181              interpretable  links  towards  cryptic  numbered files resulting
182              from a DICOM series.
183
184
185       -fb-none, --without-fallback
186
187       -fb-anlz, --fallback-analyze
188
189       -fb-conc, --fallback-concorde
190
191       -fb-dicom, --fallback-dicom
192
193       -fb-ecat, --fallback-ecat
194              Disable or specify a fallback read  format  in  case  autodetect
195              failed.
196
197
198       -fh, --flip-horizontal
199
200       -fv, --flip-vertical
201              Flip  images  horizontal  (-fh) along the X-axis, vertical (-fv)
202              along the Y-axis respectively. Parameters such as slice orienta‐
203              tion are NOT changed. See also the -rs option.
204
205
206       -fmosaic=<W>x<H>x<N>, --force-mosaic=<W>x<H>x<N>
207              Enforce  the  mosaic file support for DICOM or Acr/Nema formats.
208              The *stamps* will be split into separate slices according to the
209              values  supplied  on  the  command-line.  See also extra options
210              -interl and -mfixv. The preset arguments are:
211
212                   <W> = pixel width  of image stamps (X)
213
214                   <H> = pixel height of image stamps (Y)
215
216                   <N> = total number of image stamps (Z)
217
218                   medcon -f imagefile -fmosaic=64x64x30
219
220
221       -g, --make-gray
222              Remap coloured images to gray. This is necessary when  you  con‐
223              vert to formats which only support a grayscale colormap!
224
225
226       -gap, --spacing-true-gap
227              The spacing between slices is the true gap/overlap between adja‐
228              cent slices. In contrary to  the  default  behaviour  where  the
229              spacing  between slices is measured from the centre to centre of
230              two adjacent slices (including gap/overlap). Applied in DICOM  &
231              Acr/Nema.
232
233
234       -hackacr, --hack-acrtags
235              Enables  you  to  hack a file that contains Acr/Nema tags hidden
236              somewhere.  Some proprietary image formats do contain  tags  but
237              are  placed  after  some  unknown headerinformation. This option
238              will try to find some readable tags  in  the  first  2048  bytes
239              after  which  it will give some possible hints to get the images
240              out of the file with the use of the interactive  reading  proce‐
241              dure  (see  option  `-i').  This experimental procedure can fail
242              badly ...
243
244
245       -i, --interactive
246              Selects the interactive reading procedure. Normally the  program
247              automatically  detects the format or uses 'ecat' (or 'dicom') as
248              default. With the interactive procedure it could be possible  to
249              read  an  uncompressed, unsupported format by answering the fol‐
250              lowing questions:
251
252          Number of images?
253          General header offset to binary data?
254          Image   header offset to binary data?
255          Image   header repeated before each image?
256          Swap the pixel bytes?
257          Same characteristics for all images?
258          Absolute offset in bytes? (overrides above, 0 = unused)
259          Image columns?
260          Image rows?
261          Pixel data type?
262          Redo input?
263
264       The GUI allows one to save such raw predef input (RPI) files, that  can
265       be used in a redirect statement:
266
267          medcon -f unsupported.img -c intf -i < predef.rpi
268
269       Doing  so  you can create small scripts that will read and convert your
270       unsupported images at once.
271
272
273       -ident, --identify
274              An interactive routine to specify the patient and study  related
275              information.  This option can not be used with the option -anon.
276              The questions asked are:
277
278
279          Give patient name?
280          Give patient id?
281          Select patient sex?
282          Give study description?
283          Give study id/name/p-number?
284          Give series description?
285
286
287       -implicit, --write-implicit
288              Another DICOM related option to enforce the implicit  VR  little
289              transfer  syntax  as  output,  instead  of  the default explicit
290              transfer syntax.
291
292
293       -interl, --mosaic-interlaced
294              An extra option used in combination with  forced  mosaic  (-fmo‐
295              saic).  The  option  indicates  that  the slices in the original
296              mosaic are in fact interlaced.  See also  options  -fmosaic  and
297              -mfixv.
298
299
300       -little, --little-endian
301              Force  writing of little endian files when supported by the for‐
302              mat.
303
304
305       -lut, --load-lut <filename>
306              Load an external LUT color scheme.
307
308
309       -mh, --map-hotmetal
310              Selects the hotmetal colormap. This is only useful to GIF89a  or
311              PNG.
312
313
314       -mr, --map-rainbow
315              Selects  the rainbow  colormap. This is only useful to GIF89a or
316              PNG.
317
318
319       -mc, --map-combined
320              Selects the combined colormap. This is only useful to GIF89a  or
321              PNG.
322
323
324       -mi, --map-inverted
325              Selects  the invers   colormap. This is only useful to GIF89a or
326              PNG
327
328
329       -mfixv, --mosaic-fix-voxel
330              Another extra option used  in  combination  with  forced  mosaic
331              (-fmosaic).  Choosing  this  options will rescale the real world
332              voxel dimensions by the mosaic factor.  See  also  -fmosaic  and
333              -interl.
334
335
336       -mosaic, --enable-mosaic
337              Enable  mosaic  file  support  in  DICOM or Acr/Nema format. The
338              *stamps* will be splitted into separate slices according to val‐
339              ues  found  in the file. This autodetect routine will always fix
340              the voxel sizes. To support other  type  of  mosaic  files,  see
341              option -fmosaic.
342
343
344       -n, --negatives
345              Preserve negative values. When not selected, all negative values
346              are put to zero. In combination with quantitation  (see  -qs  or
347              -qc)  the  requested format must support pixels of type float, a
348              global rescale factor or the more generic  slope/intercept  con‐
349              cept in order to preserve the (negative and positive) quantified
350              values.
351
352
353       -nf, --norm-over-frames
354              Normalize with minimum/maximum values found  over  images  in  a
355              frame  group (in case the original format has different frames).
356              The default behaviour is normalization with minimum/maximum val‐
357              ues  found  over  all  images.   This  can be important when the
358              requested format requires a rescaling to a  new  pixeltype.  The
359              original pixel values then need to be rescaled to the new pixel‐
360              type boundaries based on the minimum/maximum values.
361
362
363       -nometa, --write-without-meta
364              Write DICOM  files  without  the  part  10  meta  header  (group
365              0x0002).
366
367
368       -nopath, --ignore-path
369              Ignore absolute path mentioned in the "name of data file" key of
370              an interfile header. Do  make  sure  then  that  the  data  file
371              resides in the same directory as the header file.
372
373
374       -noprefix, --without-prefix
375              This option disables the numbered prefix in the output filename.
376              In combination with the -alias option, one  could  create  human
377              readable  and  alphabetical  sorted files from DICOM or Acr/Name
378              multiple file volumes.
379
380
381       -o, --output-name <filename>
382              Changes output filename for all  files  to  be  created.  It  is
383              allowed  to  specify a directory path as well. However, a direc‐
384              tory path disables unique filename prefixing.
385
386
387       -one, --single-file
388              Write header and image to same file; as allowed for InterFile.
389
390
391       -optgif, --options-gif
392              Define some GIF options when converting to the GIF format. With‐
393              out  this  option  a  loop  and  background color are defined by
394              default. This interactive routine asks the following questions:
395
396          Select color map?
397          Insert a display loop?
398          Delay 1/100ths of a second?
399          Insert a transparent color?
400          Transparent color?
401          Background  color?
402
403       -optspm, --options-spm
404              Define some SPM options (origins) when converting to the Analyze
405              format.  The quantification is not set. See also '-spm' & '-ar'.
406              The interactive routine asks the following questions:
407
408          Origin X?
409          Origin Y?
410          Origin Z?
411
412       -p, --print-values
413              Show some specified pixel values. This is  an  interactive  rou‐
414              tine.  Calibration  and  negative pixels are preserved automati‐
415              cally. You need to specify the -qs to preserve  the  quantifica‐
416              tion  instead  of  the  calibration. You can not use this option
417              with -c. See also -pa option for a non-interactive routine.
418
419          - Any number must be one-based (0 = All)
420          - Syntax of range   : X...Y or X-Y
421          - Syntax of interval: X:S:Y    (S = step)
422
423                   Selection Type?  1=normal    2=ecat
424
425                 Normal Style
426                 ------------
427
428                   Give a list of image numbers?
429                   Give a list of pixels x,y ?
430
431                 Ecat Style
432                 ----------
433
434                   Give planes list?
435                   Give frames list?
436                   Give gates  list?
437                   Give beds   list?
438                   Give a list of pixels x,y ?
439
440
441       -pa, --print-all-values
442              Show all pixel values. This  option  is  identical  to  -p,  but
443              doesn't require user input.
444
445
446       -pad, --pad-around
447
448       -padtl, --pad-top-left
449
450       -padbr, --pad-bottom-right
451              Increasing the slice matrix is done by padding an image with the
452              lowest pixel value. The options above enable  different  padding
453              modes.
454
455
456       -preacq, --prefix-acquisition
457
458       -preser, --prefix-series
459              Respectivily  use  acquisition  or  series value in the numbered
460              prefix of the new filename. This is useful for alphabetical file
461              ordering, where leading zeros in DICOM elements are missing. See
462              also -alias.
463
464
465       -q, --quantitation
466              Enable quantitation using all scale factors (for now  alias  for
467              -qc option).
468
469
470       -qs, --quantification
471              A first scaling option to preserve the (ECAT) quantification (a)
472              or to consider a first linear scaling slope with intercept (b).
473
474          qpv = ppv * quant_scale   [counts/second/pixel] (a)
475          qpv = ppv * slope + intercept (b)
476
477          qpv = quantified pixel value
478          ppv = plain pixel value
479
480       The "quant_scale" factor normalizes  all  images  in  the  file;  quite
481       important  for  merging purposes. When the corresponding format can not
482       hold a rescale factor for each image, the quantified values  are  saved
483       as floats. Therefore, the highest pixel precision for correct quantita‐
484       tion is float, not double!
485
486       If the format does not support floats, the quantified pixel values  get
487       rescaled to an integer. Then only formats that support a global scaling
488       factor or slope/intercept pair will preserve those quantified values.
489
490       Note that this option can not be used with -qc.
491
492
493       -qc, --calibration
494              A second quantitation option to preserve the (ECAT)  quantifica‐
495              tion  as well as the (ECAT) calibration (a) or in general, using
496              two rescale slopes with an intercept (b). These should  normally
497              transform  pixels  into  manufacturer independent values. So one
498              can assume that after a calibration, the new pixels will  repre‐
499              sent  a  real  world  unit  (like  concentration  values  (SUV),
500              hounsfield units (HU) and alike).
501
502
503          cpv = ppv * quant_scale * calibr_fctr  [uCi/ml] (a)
504          cpv = ppv * slope1 * slope2 + intercept (b)
505
506          cpv = calibrated pixel value
507          ppv = plain pixel value
508          qpv = quantified pixel value = ppv * quant_scale
509
510       The "quant_scale" factor normalizes  all  images  in  the  file;  quite
511       important for merging purposes. The "calibr_fctr" rescales the qpv-val‐
512       ues to a new unit. When the corresponding format can not  hold  a  com‐
513       pound  factor  for  each  image, the quantified values will be saved as
514       floats. Therefore, the highest pixel precision for correct quantitation
515       is float and not double!
516
517       If  the format does not support floats, the calibrated pixel values are
518       rescaled to an integer type. Only formats that support a global scaling
519       factor or slope/intercept pair preserve those calibrated values.
520
521
522       Note that this option can not be used with -qs.
523
524
525       -r, --rename-file
526              Rename  the file basename. This option is only useful in case of
527              conversion.
528
529
530       -rs, --reverse-slices
531              Reverse all the slices along  the  Z-axis.  Parameters  such  as
532              slice  orientation  are  NOT  changed.  See also the -fh and -fv
533              options.
534
535
536       -s, --silent
537              Suppress all message, warning and error dialogs.
538
539
540       -sag, --sagittal
541              Reslice the images of a volume into a sagittal projection  while
542              preserving the real world dimensions.
543
544
545       -si=<slope>:<intercept>
546              Force remap of pixel values using specified slope/intercept (y =
547              s*x + i). The quantitation option -qc is enabled by default.  No
548              spaces are allowed within this option.
549
550
551       -skip1, --skip-preview-slice
552              Skip  the first image in an InterFile. In other words, the first
553              image in the array will simply be ignored. Use  this  only  when
554              you are sure that the InterFile does contain an annoying/confus‐
555              ing preview slice.
556
557
558       -split4d, -splitf, --split-frames
559
560       -split3d, -splits, --split-slices
561              Write out a study into separate files, one for each volume in  a
562              time frame (--split-frames) or each image slice (--split-slices)
563              individually. The names of the files created will have an  extra
564              index  number.  See  also  -stack3d  and  -stack4d  as  opposite
565              options.
566
567
568       -spm, --analyze-spm
569              Considering Analyze files for/from SPM. In this case the  global
570              scaling factor hidden in imd.funused[1] will be used, as well as
571              the hidden offset value in imd.funused[0].
572
573       In case of quantitation, the default output pixel type is  float.  This
574       option  allows  one to write integers combined with a global scale fac‐
575       tor. To actually use this scaling factor, you must select  a  quantita‐
576       tion option like -qs or -qc as well.
577
578       See also -ar & -optspm.
579
580
581       -sqr, --make-square
582              Make  all  image  matrices  square, using the largest dimension.
583              Images are padded with the lowest pixel  value.  See  also  -pad
584              related options.
585
586
587       -sqr2, --make-square-two
588              Make  all  image matrices square, using the nearest power of two
589              (between 64, 128, 256, 512 and 1024). Images are padded with the
590              lowest pixel value. See also -pad related options.
591
592
593       -stack4d, -stackf, --stack-frames
594
595       -stack3d, -stacks, --stack-slices
596              Write  separate studies into one file. The --stack-slices option
597              allows one to write single image slice files into one 3D volume,
598              while the --stack-frames option allows volumes of different time
599              frames being written into one 4D file. The sequence of  stacking
600              is  based  on  the file sequence given at the argument line. See
601              also -split3d and -split4d as the opposite options.
602
603
604       -tra, --transverse
605              Reslice the images of a  volume  into  a  transverse  projection
606              while preserving the real world dimensions.
607
608
609       -uin, --use-institution-name <namestring>
610              Change  the  program's default institution name which is applied
611              on studies without one. However, this does not override existing
612              values.  For  a  namestring  with  spaces,  group between double
613              quotes.
614
615
616       -v, --verbose
617              Verbose mode. Show some explaining messages during  the  reading
618              and writing of files.
619
620
621       -vifi, --edit-fileinfo
622              An  interactive routine for editing voxel,array,slice and orient
623              related entries in the FILEINFO struct.
624
625
626       -w, --overwrite-files
627              Allow overwrite of existing files, without warning.
628
629

NOTES

631  When no conversion was specified, the program will display the header infor‐
632  mation of each image.
633
634  When  conversion  was  specified,  the program will automatically create new
635  filenames in the current directory with the following syntax:
636
637                               mXXX-filename.ext
638
639               `XXX-' a number representing the XXX-th conversion
640               `ext' a corresponding extension of the new format
641
642                         Binary raw   ->   .bin
643                         Ascii  raw   ->   .asc
644                         Gif89a       ->   .gif
645                         Acr/Nema     ->   .ima
646                         INW          ->   .im
647                         ECAT         ->   .img
648                         Interfile    ->   .h33 + .i33
649                         Analyze      ->   .hdr + .img
650                         DICOM        ->   .dcm
651                         PNG          ->   .png
652                         CONC         ->   .hdr + .dat
653
654  Some special remarks related to reading from stdin or writing to stdout.
655
656     a) reading from stdin:
657
658       Enable this by using an "-" mark instead of the list of input files.
659
660          1. redirect: medcon -f - < inputfile
661
662       This is supported for all formats and shouldn't  cause  any  particular
663       problems. Interactive routines are disabled because stdin is now in use
664       by the image input.
665
666          2. pipes   : cat inputfile | medcon -f - format
667
668       Actually, this way only one or two formats are supported  since  seek()
669       calls  are not possible during pipes. The fact is that most of our for‐
670       mats are read using those seek() calls. In normal operation we  already
671       need  a  quick  sneak in the file to determine the format. Because this
672       fseek() isn't allowed, you must supply at least the input format too.
673
674     b) writing to stdout:
675
676       Enabled by using an extra "-" mark on the conversion list.
677
678          medcon -f inputfile -c - format
679
680       Only one inputfile is allowed. The converted output  will  be  send  to
681       stdout.
682
683       In  case  of dual file formats such as Analyze or InterFile, the header
684       information will be send to stderr. The reference to the image file  in
685       the header of an InterFile will ofcourse be wrong (since the program is
686       not capable of knowing the resulting filename).
687
688       In case of RAW or ASCII output, the program will print the  content  of
689       the  internal  FILEINFO  struct to stderr as well. Please note that the
690       (t)csh shells do not allow to catch stderr  or  stdout  separately.  In
691       case of the bash shell, it is possible to say:
692
693       medcon -f inputfile -c - intf -b16.12 -qc 1>image 2>header
694

EXAMPLES

696  1.  To display the image headers:
697            medcon -f filename1 filename2
698
699  2.  To convert the images:
700            medcon -f filename1 filename2 -c gif acr intf
701
702  3.  To read interactively
703            medcon -i -f filename -c ecat
704
705  4.  To extract alternate images:
706            medcon -e 1:2:20 -f filename -c gif
707
708  5.  To print out pixel values
709            medcon -p -f filename
710
711  6.  Convert to raw binary images, send to standard output:
712            medcon -f filename -c - bin
713

FILES

715  /usr/local/xmedcon/include/   Directory with header files.
716
717  /usr/local/xmedcon/lib/       Directory with libraries.
718  /usr/local/xmedcon/bin/       Directory with executables.
719  /usr/local/xmedcon/man/       Directory with man-pages.
720  /usr/local/xmedcon/etc/       Directory with rcfiles.
721

SEE ALSO

723  xmedcon(1), xmedcon-config(1)
724
725  m-acr(4), m-anlz(4), m-gif(4), m-inw(4), m-intf(4), m-ecat(4)
726
727  medcon(3)
728

AUTHOR

730  (X)MedCon  project was originally written by Erik Nolf (eNlf) for the former
731  PET-Centre at Ghent University (Belgium).
732
733  e-mail:   enlf-at-users.sourceforge.net   www:   http://xmedcon.sourceforge.net
734
735
736
737                                                                     MEDCON(1)
Impressum