MEDCON(1)

📦

version 0.26.1-gtk3 · 7 versions

0.26.1-gtk3 · ubuntu stonking (latest)
0.26.2 · nixos 26.05, nixpkgs unstable
0.24.1 · fedora 43
0.21.2 · ubuntu jammy
0.25.3 · fedora 43, fedora 44
0.23.0-gtk3 · debian bookworm, ubuntu noble
0.25.1-gtk3 · debian trixie, ubuntu questing, ubuntu resolute

, in ubuntu stonking

✨ medcon(1) — General Commands Manual ✨

okay bestie, sit down, hydrate, because this is the medcon(1) page and it's a whole journey 💖

🎀 NAME 🎀

medcon — (X)MedCon's CLI — Medical Image Conversion Utility

🌸 SYNOPSIS 🌸

medcon [options] -f files ...

🦋 DESCRIPTION 🦋

MedCon is the command line interface for (X)MedCon's medical image conversion library. It's literally built to read a bunch of medical image formats that can stash multiple images inside a single file, which is giving "everything bagel" energy but for your scans 🥯

Need more help? Type medcon --help, or go vibe with the documentation on the project's website.

The supported formats are, and yes I'm listing every single one because we do not skip:

Ascii — raw ascii image arrays without header — notation: 'ascii'
Binary — raw binary image arrays without header — notation: 'bin'
Gif89a — annimated GIF with colormap — notation: 'gif'
Acr/Nema — Papyrus, Siemens (vers 2.0) — notation: 'acr'
INW — RUG local format (vers 1.0) — notation: 'inw'
ECAT — Siemens CTI ECAT 6 — notation: 'ecat6' or 'ecat'
ECAT — Siemens CTI ECAT 7 — notation: 'ecat7'
InterFile — version 3.3 — notation: 'intf'
Analyze — with consideration to SPM software — notation: 'anlz'
DICOM — uses the VT-DICOM library — notation: 'dicom'
PNG — Portable Network Graphics — notation: 'png'
Concorde — Concorde/microPET — notation: 'conc'
NIfTI — Neuroimaging Informatics Technology Initiative — notation: 'nifti'

💅 FLAGS 💅

-f, --file, --files <files> ... — Read a list of files. In case of a dual file format, like InterFile and Analyze, just mention its header filename. (Just the header bestie, the rest comes along for the ride 🫶)

👑 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. No glow-down 💅
-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. (that last bit is important, don't say I didn't warn you 😭)
-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.

bestie the manpage literally says "You don't want this." that's the most real thing on this whole page 💀

-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 CT) centre/width contrast window on pixel values. Any manufacturer independent pixel values (like SUV, HU, ...) from 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). the way that -cs and -cu are a matched set… iconic.
-cw=<centre>:<width> — Apply contrast window 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.

Then you get asked:

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. (script girlies, this one's for you 🫶)
-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! (imagine not supporting color. couldn't be my formats 🙈)
-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 ... 💀

"can fail badly" — the drama, the honesty, the range 💀✨

-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. main character scripting energy fr fr 🔥

-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 <file|number> — Load an external LUT color scheme. If a number is given, load internal palette instead. cute palette moment 🎀
-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. 🌈 bestie a rainbow colormap?? it's giving exactly what it says on the tin 💅
-mc, --map-combined — picks the combined colormap. Only useful for GIF89a or PNG, bestie. ✨
-mi, --map-inverted — picks the inverse colormap. Again, only for GIF89a or PNG. 💅
-mfixv, --mosaic-fix-voxel — extra option for when you're forcing mosaic (-fmosaic). It rescales the real world voxel dimensions by the mosaic factor. Also check out -fmosaic and -interl. 🧩
-mosaic, --enable-mosaic — turns on mosaic file support for DICOM or Acr/Nema format. The stamps get split into separate slices based on values in the file. This autodetect routine always fixes the voxel sizes. For other mosaic types, see -fmosaic. 🖼️
-n, --negatives — keeps negative values. Without it, all negative values go to zero. When you're doing quantitation (see -qs or -qc), the format you request must support float pixels, a global rescale factor, or the slope/intercept thing to keep those negative and positive quantified values. 📉
-nf, --norm-over-frames — normalize using min/max values found over images in a frame group (if the original format has different frames). Default is normalizing using min/max over all images. This matters when the requested format needs rescaling to a new pixeltype; the original pixel values then need to be rescaled to the new pixeltype boundaries based on those min/max values. 📊
-nometa, --write-without-meta — writes DICOM files without the part 10 meta header (group 0x0002). 🚫
-nopath, --ignore-path — ignores the absolute path in the "name of data file" key of an interfile header. Then make sure the data file is in the same directory as the header file. 📁
-noprefix, --without-prefix — disables the numbered prefix in the output filename. Combine with -alias to make human readable and alphabetically sorted files from DICOM or Acr/Name multiple file volumes. 🔤
-o, --output-name <filename> — changes output filename for all files to be created. You can specify a directory path too, but that disables unique filename prefixing. 📝
-one, --single-file — writes header and image to the same file; allowed for InterFile. 📄
-optgif, --options-gif — define some GIF options when converting to GIF. Without this, a loop and background color are defined by default. This interactive routine asks:

Select color map?
Insert a display loop?
Delay 1/100ths of a second?
Insert a transparent color?
Transparent color?
Background  color?

Note the double space in Background color? — keep it exact. 🎨

-optspm, --options-spm — define some SPM options (origins) when converting to Analyze format. Quantification is not set. See also -spm and -ar. The interactive routine asks:

Origin X?
Origin Y?
Origin Z?

🧭

-p, --print-values — show some specified pixel values. Interactive routine. Calibration and negative pixels are preserved automatically. You need to specify -qs to preserve quantification instead of calibration. You can't use this with -c. See also -pa 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)

Then it asks interactively:

                 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. Same as -p but no user input needed. 🤖
-pad, --pad-around — padding mode (see below). 🛋️
-padtl, --pad-top-left — padding mode (see below). ↖️
-padbr, --pad-bottom-right — padding mode (see below). ↘️

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 — use acquisition value in the numbered prefix (see below). 📅
-preser, --prefix-series — use series value in the numbered prefix (see below). 📚

Respectively 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 an alias for -qc option). 🔢
-qs, --quantification — first scaling option to preserve (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; super important for merging. When the format can't hold a rescale factor for each image, the quantified values are saved as floats. So the highest pixel precision for correct quantitation is float, not double!

If the format doesn't 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 — second quantitation option to preserve (ECAT) quantification as well as (ECAT) calibration (a) or in general, using two rescale slopes with an intercept (b). These should normally transform pixels into manufacturer independent values. So after calibration, the new pixels 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; super important for merging. The calibr_fctr rescales the qpv-values to a new unit. When the format can't hold a compound factor for each image, the quantified values will be saved as floats. So the highest pixel precision for correct quantitation is float and not double!

If the format doesn't 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. Only useful in case of conversion. 🏷️
-rs, --reverse-slices — reverse all the slices along the Z-axis. Parameters like slice orientation are NOT changed. See also -fh and -fv. 🔄
-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 allowed within this option. 🎯
-skip1, --skip-preview-slice — skip the first image in an InterFile. In other words, the first image in the array is simply ignored. Use this only when you're sure the InterFile does contain an annoying/confusing preview slice. 🙈
-split4d, -splitf, --split-frames — write out a study into separate files, one for each volume in a time frame (see below). 🗂️
-split3d, -splits, --split-slices — write out a study into separate files, one for each image slice (see below). 📂

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.

📝 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

The extension mapping is giving:

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

a) reading from stdin: 🧚

Enable this by using an - mark instead of the list of input files.

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.

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. no cap

b) writing to stdout: 🚀

Enabled by using an extra - mark on the conversion list.

medcon -f inputfile -c - format

Only one inputfile is allowed. The converted output will be send to stdout.

In case of dual file formats such as Analyze or InterFile, the header information will be send to stderr. The reference to the image file in the header of an InterFile will ofcourse be wrong (since the program is not capable of knowing the resulting filename).

In case of RAW or ASCII output, the program will print the content of the internal FILEINFO struct to stderr as well. Please note that the (t)csh shells do not allow one to catch stderr or stdout separately. In case of the bash shell, it is possible to say:

medcon -f inputfile -c - intf -b16.12 -qc 1>image 2>header

🌟 EXAMPLES 🌟

Display image headers:

medcon -f filename1 filename2

Convert files:

medcon -f filename1 filename2 -c gif acr intf

Interactive reading:

medcon -i -f filename -c ecat

Extract alternate images:

medcon -e 1:2:20 -f filename -c gif

Print pixel values

medcon -p -f filename

Retrieve raw binary images and send to standard output:

medcon -f filename -c - bin

📁 FILES 📁

/usr/local/xmedcon/include/ — Directory with header files.
/usr/local/xmedcon/lib/ — Directory with libraries.
/usr/local/xmedcon/bin/ — Directory with executables.
/usr/local/xmedcon/man/ — Directory with man-pages.
/usr/local/xmedcon/etc/ — Directory with rcfiles.

👀 SEE ALSO 👀

xmedcon(1), xmedcon-config(1)
m-acr(4), m-anlz(4), m-gif(4), m-inw(4), m-intf(4), m-ecat(4)
medcon(3)

💖 AUTHOR 💖

(X)MedCon project was originally written by Erik Nolf (eNlf) for the former PET-Centre at Ghent University (Belgium).

e-mail: enlf-at-users.sourceforge.net www: http://xmedcon.sourceforge.net

And that's a whole wrap on MEDCON(1), bestie — you ate that manual fr fr 💅✨🦋

📦 where this page comes from

ubuntu stonking: medcon 0.26.1-gtk3+dfsg-1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms