1MEDCON(3) Library Functions Manual MEDCON(3)
2
6 medcon - MedCon C project for conversion of medical images
7
9 Local MedCon C library ( libmdc.a )
10
13 #include "medcon.h"
14 -----------------------------------------------------------------------
15 Important Global Variables
16 -----------------------------------------------------------------------
17 char prefix[MDC_MAX_PREFIX+1]; /* prefix for new filenames */
19 /* command-line input data */
21 char *mdc_arg_files[]; /* pointers to input files */
22 int mdc_arg_convs[]; /* conversions selected */
23 int mdc_arg_total[]; /* total files & conversions*/
24 /* options set at command-line */
27 Int8 MDC_INFO; /* print image info */
28 Int8 MDC_INTERACTIVE; /* interactive read */
29 Int8 MDC_CONVERT; /* do conversion */
30 Int8 MDC_EXTRACT; /* extract images */
31 Int8 MDC_PIXELS; /* print pixel values */
32 Int8 MDC_SKIP_PREVIEW; /* skip first preview image*/
33 Int8 MDC_DICOM_MOSAIC; /* support mosaic files */
34 Int8 MDC_TRUE_GAP; /* spacing true gap/overlap */
35 Int8 MDC_DEBUG; /* show debug info */
36 Int8 MDC_ANLZ_REV; /* analyze reverse images */
37 Int8 MDC_ANLZ_SPM; /* analyze for SPM */
38 Int8 MDC_GIF_OPTIONS; /* define gif options */
39 Int8 MDC_COLOR_MAP; /* gray colormap selected */
40 Int8 MDC_MAKE_GRAY; /* remap color to gray */
41 Int8 MDC_DITHER_COLOR; /* dither color reduction */
42 Int8 MDC_FORCE_INT; /* force writing BIT?_? pixs*/
43 Int8 MDC_NEGATIVE; /* preserve negative pixels */
44 Int8 MDC_QUANTIFY; /* preserve quantification */
45 Int8 MDC_CALIBRATE; /* preserve calibration */
46 Int8 MDC_VERBOSE; /* verbose mode */
47 Int8 MDC_NORM_OVER_FRAMES /* normalize over frames */
48 /* 'QUANTIFY' & 'CALIBRATE' may NOT be ON at the same time! */
49 -----------------------------------------------------------------------
51 Important Defines
52 -----------------------------------------------------------------------
53 /* representation of supported formats */
55 #define MDC_FRMT_NONE 0 /* unsupported format */
56 #define MDC_FRMT_RAW 1 /* Read Interactive */
57 /* Write RAW Binary */
58 #define MDC_FRMT_ASCII 2 /* Write RAW Ascii */
59 #define MDC_FRMT_GIF 3 /* GIF89a or GIF87a */
60 #define MDC_FRMT_ACR 4 /* Acr/Nema 2.0 (Papyrus) */
61 #define MDC_FRMT_INW 5 /* INW (RUG) */
62 #define MDC_FRMT_ECAT6 6 /* Siemens/CTI ECAT 6.4 */
63 #define MDC_FRMT_ECAT7 7 /* Siemens/CTI ECAT 7.2 */
64 #define MDC_FRMT_INTF 8 /* Interfile v3.3 */
65 #define MDC_FRMT_ANLZ 9 /* Analyze */
66 #define MDC_FRMT_DICM 10 /* DICOM 3.0 */
67 #define MDC_FRMT_PNG 11 /* PNG */
68 #define MDC_FRMT_CONC 12 /* Concorde uPet */
69 #define MDC_MAX_FMTS 13 /* total + 1 */
71 /* supported color maps */
73 #define MDC_MAP_PRESENT 0 /* 256 RGB colormap */
74 #define MDC_MAP_GRAY 1 /* grayscale colormap */
75 #define MDC_MAP_INVERTED 2 /* inverted colormap */
76 #define MDC_MAP_RAINBOW 3 /* rainbow colormap */
77 #define MDC_MAP_COMBINED 4 /* combined colormap */
78 #define MDC_MAP_HOTMETAL 5 /* hotmetal colormap */
79 #define MDC_MAP_LOADED 6 /* extern LUT loaded */
80 -----------------------------------------------------------------------
82 Important Definitions
83 -----------------------------------------------------------------------
84 typedef struct Gated_Data_t {
86 Int8 gspect_nesting; /* gated spect nesting */
88 float nr_projections; /* number of projections */
89 float extent_rotation; /* extent of rotation */
90 float study_duration; /* study duration (ms) */
91 float image_duration; /* image duration (ms) */
92 float time_per_proj; /* time per proj (ms) */
93 float window_low; /* lower limit (ms) */
94 float window_high; /* higher limit (ms) */
95 float cycles_observed; /* cardiac cycles observed */
96 float cycles_acquired; /* cardiac cycles acquired */
97 } GATED_DATA;
99 typedef struct Acquisition_Data_t {
102 Int16 rotation_direction; /* direction of rotation */
104 Int16 detector_motion; /* type detector motion */
105 float angle_start; /* start angle (interfile) */
106 float angle_step; /* angular step */
107 float scan_arc; /* angular range */
108 } ACQ_DATA;
110 typedef struct Dynamic_Data_t {
112 Uint32 nr_of_slices; /* images in time frame */
114 float time_frame_start; /* start time frame (ms) */
115 float time_frame_delay; /* delay this frame (ms) */
116 float time_frame_duration; /* duration frame (ms) */
117 float delay_slices; /* delay each slice (ms) */
118 } DYNAMIC_DATA;
120 typedef struct Bed_Data_t {
122 float hoffset; /* horizontal position (mm) */
124 float voffset; /* vertical position (mm) */
125 } BED_DATA;
127 typedef struct Static_Data_t {
129 char label[MDC_MAXSTR]; /* label name of image */
131 float total_counts; /* total counts in image */
132 float image_duration; /* duration of image (ms) */
133 Int16 start_time_hour; /* start time hour */
134 Int16 start_time_minute; /* start time minute */
135 Int16 start_time_second; /* start time second */
136 } STATIC_DATA;
138 typedef struct Image_Data_t {
140 /* ** general data ** */
142 Uint32 width,height; /* image dimension */
143 Int16 bits,type; /* bits/pixel & datatype */
144 Uint16 flags; /* extra flag */
145 double min, max; /* min/max pixelvalue */
146 double qmin, qmax; /* quantified min/max */
147 double fmin, fmax; /* min/max in whole frame */
148 double qfmin, qfmax; /* in whole frame (quant) */
149 float rescale_slope; /* rescale slope */ /* P */
151 float rescale_intercept; /* rescale intercept */ /* P */
152 Uint32 frame_number; /* part of frame (1-based) */ /* P */
154 float slice_start; /* start of slice (ms) */ /* P */
155 Uint8 *buf; /* pointer to raw image */
156 long load_location; /* load start in file */
157 /* ** internal items ** */
159 Int8 rescaled; /* rescaled YES or NO */
160 double rescaled_min; /* new rescaled max */
161 double rescaled_max; /* new rescaled min */
162 double rescaled_fctr; /* new rescale fctr */
163 double rescaled_slope; /* new rescaled slope */
164 double rescaled_intercept; /* new rescaled intercept */
165 /* ** ecat64 items ** */
167 Int16 quant_units; /* quantification units */
168 Int16 calibr_units; /* calibration units */
169 float quant_scale; /* quantification scale */
170 float calibr_fctr; /* calibration factor */
171 float intercept; /* scale intercept */
172 float pixel_xsize; /* pixel size X (mm) */
173 float pixel_ysize; /* pixel size Y (mm) */
174 float slice_width; /* slice width (mm) */
175 float recon_scale; /* recon magnification */
176 /* ** Acr/Nema items ** */
178 float image_pos_dev[3]; /* image pos. device (mm) */
179 float image_orient_dev[6]; /* image orient device (mm) */
180 float image_pos_pat[3]; /* image pos. patient (mm) */
181 float image_orient_dev[6]; /* image orient patient (mm) */
182 float slice_spacing; /* space btw centres (mm) */
183 float ct_zoom_fctr; /* CT image zoom factor */
184 /* ** Miscellaneous **
186 STATIC_DATA *sdata; /* extra static entries */
187 unsigned char *plugb; /* like to attach here? */
189 } IMG_DATA;
191 typedef struct File_Info_t {
193 FILE *ifp; /* pointer to input file */
195 FILE *ifp_raw; /* pointer to raw input file*/
196 FILE *ofp; /* pointer to output file */
197 FILE *ofp_raw; /* pointer to raw output file*/
198 char ipath[MAX_PATH]; /* path to input file */
199 char opath[MAX_PATH]; /* path to output file */
200 char *idir; /* dir to input file */
201 char *odir; /* dir to output file */
202 char *ifname; /* name of input file */
203 char *ofname; /* name of output file */
204 int iformat; /* format of input file */
205 int oformat; /* format of output file */
206 Int8 rawconv; /* FRMT_RAW | FRMT_ASCII */
207 Int8 endian; /* endian type of file */
208 Int8 compression; /* file compression */
209 Int8 truncated; /* truncated ? */
210 Int8 diff_type; /* images with diff type */
211 Int8 diff_size; /* images with diff size */
212 Int8 diff_scale; /* images with diff rescale? */
213 Uint32 number; /* total number of images */ /* P */
214 Uint32 mwidth, mheight; /* global max dimensions */
215 Uint16 bits, type; /* global bits & datatype */
216 Int16 dim[8]; /* [0] = # of dimensions */
217 /* [1] = X-dim (pixels) */
218 /* [2] = Y-dim (pixels) */
219 /* [3] = Z-dim (planes) */
220 /* [4] = (frames) */
221 /* [5] = (gates) */
222 /* [6] = (beds) */
223 /* ... */
224 /* values must be 1-based */
225 float pixdim[8]; /* [0] = # of dimensions */
227 /* [1] = X-dim (mm) */
228 /* [2] = Y-dim (mm) */
229 /* [3] = Z-dim (mm) */
230 /* [4] = time (ms) */
231 /* ... */
232 double glmin, glmax; /* global min/max value */
234 double qglmin, qglmax; /* quantified min/max */
235 Int8 contrast_remapped; /* contrast remap applied? */
237 float window_centre; /* contrast window centre */
238 float window_width; /* contrast window width */
239 Int8 slice_projection; /* projection of images */
241 Int8 pat_slice_orient /* combined flag */
242 char pat_pos[MDC_MAXSTR]; /* patient position */
243 char pat_orient[MDC_MAXSTR]; /* patient orientation */
244 char patient_sex[MDC_MAXSTR]; /* sex of patient */
245 char patient_name[MDC_MAXSTR]; /* name of patient */
246 char patient_id[MDC_MAXSTR]; /* id of patient */
247 char patient_dob[MDC_MAXSTR]; /* birth of patient YYYYMMDD */
248 float patient_weight; /* weight of patient (kg) */
249 char study_descr[MDC_MAXSTR]; /* study description */
250 char study_id[MDC_MAXSTR]; /* study id */
251 Int16 study_date_day; /* day of study */
252 Int16 study_date_month; /* month of study */
253 Int16 study_date_year; /* year of study */
254 Int16 study_time_hour; /* hour of study */
255 Int16 study_time_minute; /* minute of study */
256 Int16 study_time_second; /* second of study */
257 Int16 dose_time_hour; /* hour of dose start */
258 Int16 dose_time_minute; /* minute of dose start */
259 Int16 dose_time_second; /* second of dose start */
260 Int16 nr_series; /* number of series */
261 Int16 nr_acquisition; /* number of acquisition */
262 Int16 nr_instance; /* number of instance (image)*/
263 Int16 acquisition_type; /* acquisition type */
264 Int16 planar; /* planar of tomo ? */
265 Int16 decay_corrected; /* decay corrected ? */
266 Int16 flood_corrected; /* flood corrected ? */
267 Int16 reconstructed; /* reconstructed ? */
269 char recon_method[MDC_MAXSTR]; /* reconstruction method */
270 char institution[MDC_MAXSTR]; /* name of institution */
272 char manufacturer[MDC_MAXSTR]; /* name of manufacturer */
273 char series_descr[MDC_MAXSTR]; /* series description */
274 char radiopharma[MDC_MAXSTR]; /* radiopharmaceutical */
275 char filter_type[MDC_MAXSTR]; /* filter type */
276 char organ_code[MDC_MAXSTR]; /* organ */
277 char isotope_code[MDC_MAXSTR]; /* isotope */
278 float isotope_halflife; /* isotope halflife (sec) */
279 float injected_dose; /* amount injected (MBq) */
280 float gantry_tilt; /* gantry tilt */
281 Uint8 map; /* indexed 256 colormap */
283 Uint8 palette[768]; /* global palette */
284 char *comment; /* whatever comment */
285 Uint32 comm_length; /* length of comment */
286 Uint32 gatednr; /* number of gated entries */
288 GATED_DATA *gdata; /* array of GATED_DATA */
289 Uint32 acqnr; /* number acq. data entries */
291 ACQ_DATA *acqdata; /* array of ACQ_DATA entries */
292 Uint32 dynnr; /* number of time frames */
294 DYNAMIC_DATA *dyndata; /* array of DYNAMIC_DATA */
295 Uint32 bednr; /* number bed data entries */
297 BED_DATA *beddata; /* array of BED_DATA entries */
298 IMG_DATA *image; /* array of IMG_DATA images */
300 MOD_INFO *mod; /* modalities specific info */
302 unsigned char *pluga; /* want to attach stuff? */
304 } FILEINFO;
306 ------------------------------------------------------------------------
308 Important Functions
309 ------------------------------------------------------------------------
310 void MdcInit (void);
312 void MdcFinish (void);
313 int MdcHandleArgs ( FILEINFO *fi,int argc,char *argv[],int MAXFILES );
315 void MdcPrintUsage ( char *pgrname );
316 int MdcOpenFile ( FILEINFO *fi, char *path );
318 int MdcReadFile ( FILEINFO *fi, int filenr, char *(*ReadFile)(FILEINFO *fi) );
319 int MdcWriteFile ( FILEINFO *fi, int format, int prefixnr, char *(*WriteFile)(FILEINFO *fi) );
320 void MdcInitFI ( FILEINFO *fi, char *path );
322 void MdcFreeIDs ( FILEINFO *fi );
323 void MdcCleanUpFI ( FILEINFO *fi );
324 void MdcResetIDs ( FILEINFO *fi );
325 void MdcPrintFI ( FILEINFO *fi );
326 void MdcCloseFile ( FILEINFO *fi );
327 void MdcSplitPath ( char path[], char **dir, char **fname );
328 int MdcGetFrmt ( FILEINFO *fi );
329 void MdcGetColorMap ( int map, Uint8 palette[] );
331 char *MdcImagesPixelFiddle( FILEINFO *fi);
332 void MdcPrntMesg ( char *fmt, ... );
334 void MdcPrntWarn ( char *fmt, ... );
335 void MdcPrntErr ( int code, char *fmt, ... );
336 char *MdcReadGIF ( FILEINFO *fi );
338 char *MdcReadACR ( FILEINFO *fi );
339 char *MdcReadINW ( FILEINFO *fi );
340 char *MdcReadECAT6 ( FILEINFO *fi );
341 char *MdcReadECAT7 ( FILEINFO *fi );
342 char *MdcReadINTF ( FILEINFO *fi );
343 char *MdcReadANLZ ( FILEINFO *fi );
344 char *MdcReadRAW ( FILEINFO *fi );
345 char *MdcReadDICM ( FILEINFO *fi );
346 char *MdcReadPNG ( FILEINFO *fi );
347 char *MdcReadCONC ( FILEINFO *fi );
348 char *MdcReadNIFTI ( FILEINFO *fi );
349 char *MdcWriteRAW ( FILEINFO *fi );
351 char *MdcWriteGIF ( FILEINFO *fi );
352 char *MdcWriteACR ( FILEINFO *fi );
353 char *MdcWriteINW ( FILEINFO *fi );
354 char *MdcWriteECAT6 ( FILEINFO *fi );
355 char *MdcWriteINTF ( FILEINFO *fi );
356 char *MdcWriteANLZ ( FILEINFO *fi );
357 char *MdcWriteDICM ( FILEINFO *fi );
358 char *MdcWritePNG ( FILEINFO *fi );
359 char *MdcWriteCONC ( FILEINFO *fi );
360 char *MdcWriteNIFTI ( FILEINFO *fi );
361
364 The MedCon library is intended for easy use of read/write routines for the
365 various medical image formats. Our main test format is Ecat 6.4. The FILE‐
366 INFO structure holds all the interesting data and pointers to the images. A
367 fast introduction ...
368 MdcInit(), MdcFinish()
370 The very first and very last function to call when using this
371 library. Currently changes occur to the signal handler for
372 floating point exceptions and the program's locale.
373 MdcHandleArgs()
375 Parser for the command-line arguments. Last function argument
376 determines the maximum of input files allowed. The absolute max‐
377 imum is MDC_MAX_FILES defined in the library.
378 MdcPrintUsage()
380 Prints possible MedCon command-line options and terminates the
381 program.
382 MdcOpenFile()
384 Initializes FILEINFO struct and opens the file with or without
385 decompression.
386 MdcReadFile()
388 Reads the (decompressed) file with format autodetection or by
389 trying a fallback format, initializes a (grayscale) colormap and
390 does the obligated pixel handling. The last argument enables the
391 use of an external read function.
392 MdcWriteFile()
394 Writes a file in the supplied format. Last argument is a number
395 used in the prefix of the output filename. Give a negative value
396 when a personal prefix was prepared. The last argument enables
397 the use of an external write function.
398 MdcCloseFile()
400 Closes the file and sets the pointer to NULL.
401 MdcInitFI()
403 Initializes the FILEINFO structure.
404 MdcFreeIDs()
406 Cleans the IMG_DATA structures by freeing all allocated memory.
407 MdcCleanUpFI()
409 Cleans the FILEINFO structure. The routine makes use of
410 FreeIDs().
411 MdcResetIDs()
413 Resets the IMG_DATA structures. This is necessary after each
414 conversion.
415 MdcPrintFI()
417 Prints the content of the FILEINFO structure. Useful for debug
418 purposes.
419 MdcSplitPath()
421 Splits the path in a string pointer to directory and filename.
422 MdcGetFrmt()
424 Checks the format of the file. For the return value, see the
425 representation of the supported formats under the section
426 `Important Defines'. With the INTERACTIVE variable ON, the func‐
427 tion returns F_RAW; see also ReadRaw().
428 MdcGetColorMap()
430 Fills a 256 byte RGB palette with the requested grayscale col‐
431 ormap.
432 MdcImagesPixelFiddle()
434 Performs all the pixel by pixel processes such as swapping
435 bytes, make positive values, quantification, rescaling, filling
436 the FILEINFO structure with global & image variables and check
437 some important parameters. This function is required after a
438 file was read!
439 MdcPrntMesg()
441 Prints a message. Argument is a variable parameter list.
442 MdcPrntWarn()
444 Prints a warning. Argument is a variable parameter list.
445 MdcPrntErr()
447 Prints an error and quits the program. The first argument is the
448 error code.
449 MdcReadRAW() - MdcWriteRAW()
452 Reads files of an unknown format interactively and writes raw
453 image arrays with out headers. ReadInterActive() is an alias for
454 MdcReadRAW().
455 MdcReadGIF() - MdcWriteGIF()
457 Reads GIF87a & GIF89a, writes annimated GIF89a files.
458 MdcReadACR() - MdcWriteACR()
460 Reads and writes Acr/Nema files.
461 MdcReadINW() - MdcWriteINW()
463 Reads and writes RUG INW files.
464 MdcReadECAT6(), MdcReadECAT7() - MdcWriteECAT6()
466 Reads ECAT 6 (resp. 7). Writes ECAT 6.4 files.
467 MdcReadINTF() - MdcWriteINTF()
469 Reads and writes Interfile 3.3 files.
470 MdcReadANLZ() - MdcWriteANLZ()
472 Reads and writes Analyze (SPM) files.
473 MdcReadDICM() - MdcWriteDICM()
475 Reads DICOM files. Writes DICOM files.
476 MdcReadPNG() - MdcWritePNG()
478 Reads PNG files. Writes PNG files.
479 MdcReadCONC() - MdcWriteCONC()
481 Reads and writes Concorde microPET.
482 MdcReadNIFTI() - MdcWriteNIFTI()
484 Reads and writes NIH's NIfTI files.
485
488 A sample C-source code to show the usage of the functions. Please, look into
489 the project source code for more details.
490 -----------------------------------------------------------------------
492 /* filename: testit.c */
494 #include <stdio.h>
496 #include "medcon.h"
498 #undef VERSION /* prevent any conflict */
500 #define VERSION "TestIt v2.3"
501 void NewPrefix(int n)
503 {
504 sprintf(prefix,"my%02d-",n); /* max of 5 chars */
505 }
506 int main(int argc, char *argv[])
508 {
509 FILEINFO fi;
510 int *total = mdc_arg_total; /* total arguments of files & conversions */
511 int *convs = mdc_arg_convs; /* counter for each conversion format */
512 char **files = mdc_arg_files; /* array of pointers to input filenames */
513 int f, c; /* some counters */
514 int t=0; /* counter for the output name prefix */
515 int convert, err=MDC_OK; /* some variables */
516 /* check arguments */
518 if (argc < 2) {
519 printf("%s - %s\n",VERSION,MdcGetLibLongVersion());
520 MdcPrintUsage(argv[0]);
521 }
522 /* init library */
524 MdcInit();
525 /* handle arguments, last one determines max inputfiles */
527 if (MdcHandleArgs(&fi,argc,argv,MDC_MAX_FILES) != MDC_OK)
528 MdcPrintUsage(argv[0]);
529 /* check output/conversion formats */
531 if (total[MDC_CONVS] == 0) {
532 printf("\n%s: ERROR : No output format specified\n\n",argv[0]);
533 return(MDC_BAD_CODE);
534 }
535 /* do the stuff for each input file */
537 for (f=0; f<total[MDC_FILES]; f++) {
538 if ((err = MdcOpenFile(&fi, files[f])) != MDC_OK) return(err);
540 if ((err = MdcReadFile(&fi, f+1, NULL)) != MDC_OK) return(err);
542 /* do the conversions */
544 if (total[MDC_CONVS] > 0) {
545 /* go through conversion formats */
547 for (c=1; c<MDC_MAX_FRMTS; c++) {
548 convert = convs[c];
549 /* write output format when selected */
550 while (convert -- > 0) {
551 if ((err = MdcWriteFile(&fi, c, t++, NULL)) != MDC_OK) {
552 MdcCleanUpFI(&fi);
553 return(err);
554 }
555 }
556 }
557 }
558 /* clean up FILEINFO struct */
559 MdcCleanUpFI(&fi);
560 }
561 /* finish library */
563 MdcFinish();
564 return(err);
566 }
568 -----------------------------------------------------------------------
569 Example `Makefile' for compiling `testit.c':
571 -----------------------------------------------------------------------
573 # filename: Makefile
574 CC = gcc
575 CCOPTS = -Wall -g
576 CFLAGS = $(CCOPTS)
577 INCS = `xmedcon-config --cflags`
579 LIBS = `xmedcon-config --libs`
580 testit: testit.c
582 $(CC) $(CFLAGS) $(INCS) -o testit testit.c $(LIBS)
583 # don't forget a <tab> before $(CC). You can lose this with copy/paste
585 -----------------------------------------------------------------------
586
588 /usr/local/xmedcon/include/ Directory with header files..
589 /usr/local/xmedcon/lib/ Directory with libraries.
590 /usr/local/xmedcon/bin/ Directory with executables.
591 /usr/local/xmedcon/man/ Directory with man-pages.
592 /usr/local/xmedcon/etc/ Directory with rcfiles.
593
595 medcon(1), xmedcon(1), xmedcon-config(1)
596 m-acr(4), m-anlz(4), m-gif(4), m-intf(4), m-ecat(4), m-inw(4)
598
600 (X)MedCon project was originally written by Erik Nolf (eNlf) for the former
601 PET-Centre at Ghent University (Belgium).
602 e-mail: enlf-at-users.sourceforge.net www: http://xmedcon.sourceforge.net
604 MEDCON(3)