# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# filename: REMARKS                                                       #
#                                                                         #
# UTILITY text: Medical Image Conversion Utility                          #
#                                                                         #
# purpose     : most important remarks on the code                        #
#                                                                         #
# project     : (X)MedCon by Erik Nolf                                    #
#                                                                         #
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
# $Id: REMARKS,v 1.1.1.1 2000/10/28 16:50:30 enlf Exp $

GENERAL:
=======

- Hey, wake up! As I would say, "to convert IS to delete"

           !! ALWAYS PRESERVE YOUR ORIGINAL IMAGE DATA !!

- "Floating exception (core dumped)" with use of (X)MedCon library

   This can occur on DEC Alpha systems ...

       1) You can simply prevent this by adding the following functions
          to your main code: (see also `./source/medcon.c')
  ...
MdcIgnoreSIGFPE()   /* ignore signal Floating exception */
  ...
MdcAcceptSIGFPE()   /* accept signal Floating exception */
  ...

       2) Possible reasons:

          On a DEC Alpha, floating exceptions are not handled by default,
          which is just great ... but unwanted in the following cases:

           1) Perhaps you read a raw image with type float,
              but didn't swap the bytes (= wrong endian choice).
 
           2) The headers/images contain bad float values.


- pixel types:  Int8,  Int16,  Int32,  Int64
               Uint8, Uint16, Uint32, Uint64, 
               float, double

    Most pixel types will be read, internally we want the types:

       1) 1-BIT  converted to `Uint8'
       2) ASCII  converted to `double'
       3) VAX    converted to   IEEE

    Quantifications/Calibrations only use the `float' type! 
    Therefore, `double' values must be downscalable to `float', 
    otherwise the integrity of the data can not be guaranteed!

- patient/slice orientations: 

   a) Only orthogonal values are supported.
   b) (X)MedCon does NOT support to change the slices in other orientation.

   
- automatic filename generation:

   The filenames are automatically generated with the following sequence:

    m00-...m99-,mA0-...mA9-,mB0-...mZZ-

   So an `ls` command will show the files in sequence as they were generated.
   However, this allows a maximum of 1036 files to be read and converted
   in one execution. After this filenames could overlap ... luckily (X)MedCon 
   does NOT overwrite an existing file. For MsDos this could be the case
   since we truncate filenames to 8 chars (including the mXX- prefix).
   Therefore the MDC_MAX_FILES is set to 1036, the maximum files (X)MedCon
   will handle during one process call.
 
   
- NEGATIVE = ZERO: potential danger reading (RAW) images with negative pixels

     As default, (X)MedCon deals with Medical Images (ECAT in particulary)
     for which pixels have a "quantified" value for example [uCi/ml].

     This means that negative pixel values are neglected and put to zero!!
     a) because they do not posses any valid quantification
     b) remap to another pixeltype is possible with one rescale factor only.
         Doing so, we still preserve the quantification indirectly.

     The last reason implies that negative & quantification are mutually
     exclusive situations ... unless you can help me out here?

      { /* rescale to a new pixeltype */
        scale = max_new_pixeltype / (max_image_value - min_image_value);
        new_pixeltype_value = (original_image_value - min_image_value) * scale;
      }
      note: `max_image_value' and/or `min_image_value' could be negative!

     So, for a `min_image_value=0' we only need a factor for rescaling.
     In fact a `min_image_value > 0' poses the same problem but in case
     of quantification/calibration we simply do:
        scale = max_new_pixeltype / max_image_value;
        new_pixeltype_value = original_image_value * scale;

     When you read an image which lost a lot of pixel information this is 
     probably because the negative pixels apparently where important!
     This can for example happen when reading RAW unsupported image arrays ...

     1) RAW images:  (interactive reading procedure)
        ==========

       When reading RAW unsupported image arrays, (X)MedCon will change its 
       behaviour during this process call by
         - disabling any quantification (since there is none to be done ;-)
         - enabling  negative pixel values
       Ofcourse, the user will be notified of this change in settings.
       Would this be OK? Or should I still persist on the user to implicitly
       select and allow negative pixel values ... hmmm. A dilemma!
       Now the user won't be confused by missing pixel info but we do lose
       a certain degree of freedom ...

     2) Supported images:
        ================

       Sorry, but (X)MedCon doesn't posses any A.I. to "see" whether the
       negative pixel values are important. You will have to figure it out
       for yourself. If you need to preserve negative pixels, please use
       the following settings.
 
           command-line: use the `-n' option (without any quantification)

              graphical: select in Options|MedCon => positives & negatives
                         (do not select any other setting afterwards ;)

     Ofcourse, you are free to change the default behaviour of (X)MedCon
     from the sourcecode ...  (see the file: m-global.c)
      
                            *************

FORMATS:
=======

ECAT: We check the format on the value of `mh.system_type==ECAT_SYST_TYPE'. 

      Change the value of ECAT_SYST_TYPE to your approriate system type in
      the source code (see the file: m-ecat64.h).

      This is important for XV to be able to read your ECAT files! 

      For (X)MedCon however, if DICOM is unsupported, we automatically try 
      to read as ECAT when the format was not found or you can use the
      option '-fb-ecat' to select ECAT as the fallback read format.

      The patient/slice orientation (see Acr/Nema) is always considered as
      MDC_SUPINE_HEADFIRST_TRANSVERSAL ...

                            *************

DICOM: We check the format on the presence of the signature "DICM"

      Therefore, XV will only read DICM files with MetaHeader!

      (X)MedCon however, will automatically try to read as DICOM when the format
      was not found. So DICOM files without MetaHeader can be read.

      Writing only supported for reconstructed PT or NM modalities
      and Int16 pixel types.

      To use the rescale slope/intercept or window center/width you should 
      select a quantification option '-qs' or '-qc'.

                            *************
      
GIF:  We found one image that didn't compress well with the original code.
      See "eNlf: BUG??" notes in the code. However, our solution of 
      (byte_offset >= 253) could perhaps fail on other images!
      Up until now we did not find an image that failed with our solution.

                            *************

Acr/Nema: 
      We do attempt to preserve some extra (DICOM) tags in our Acr/Nema files 
      concerning the patient/slice orientation and position.

                            *************

InterFile: 
      We do attempt to preserve the patient/slice orientation and position.
      But the format misses some specifications for slice thickness
        - Tomographic   : all voxel dimensions defineable
        - Static/Dynamic: loses slice thickness (no format specification)

                            *************

Analyze: 
      We would like to preserve the patient/slice orientation and position, 
      however, the SPM software doesn't seem to interpret the value of 
      `orient' (patient orientation)! For our main format ECAT this was 
      no problem, except that we had to change the direction of all axis with
      the use of option `-ar'.

      Another problem are the "flipped" versions of `orient': we don't know
      what the meaning of "flipped" is (feet first instead of head first, or
      prone instead of supine, or vice versa ...) so we ignore this and 
      always consider the patient orientation as MDC_SUPINE_HEADFIRST_ ...

      Filenames are no longer truncated to 18 chars for filling up the 
      db_name[18] entry in the header. If you need this, uncomment the 
      line with ANLZ_SHORT_FILENAME (see the file: m-anlz.h)


                            *************
