Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

XMRI-READ-RGB-IMAGE

source files: xmri.[ch] ge.[ch]

SYNTAX

(XMRI-READ-RGB-IMAGE
       :FILENAME <string:filename>
    [  :MIN <fix:min>               ]
    [  :MAX <fix:max>               ]
    [  :RESULT-IN <grl:image>       ]
    [  :FILE-OFFSET <fix:offset>
       :ROWS <fix:rows>
       :COLS <fix:cols>       
     [ :PLANE  { :PIXEL-RED   |
                 :PIXEL-GREEN |
                 :PIXEL-BLUE }    ]
     [ :DEPTH-IN-BITS { 8 | 16 }  ]
     [ :ENDIAN { :BIG | :LITTLE } ]
     [ :PADDING <fix:padding>     ]
                                    ]
)

DESCRIPTION

This function takes a filename as a string, which should be of a GE-format MRI/CAT image file, and returns the pixel data in the same format as (for example) XTIF-LOAD-TIFF-FILE, a graphic relation suitable for immediate display using the camera :DRAW message, with a :PIXEL-GREEN array of CLASS-UNIT-FLOAT-ARRAY.

(This is the usual Skandha4 convention for handling monochrome images; the missing :PIXEL-RED and :PIXEL-BLUE values default to using the supplied :PIXEL-GREEN array.)

If any of :FILE-OFFSET, :ROWS or :COLS are provided, then all must be provided; In this case, the file need not be GE format: All the call does is seek offset bytes into the file and read rows*cols 16-bit (by default) values from the file, which are returned in image.

This behavior may be fine-tuned via the :PLANE, :DEPTH-IN-BITS, :ENDIAN and :STRIDE keywords:

The :PLANE parameter defaults to :PIXEL-GREEN. By making successive calls with this set to :PIXEL-RED, :PIXEL-GREEN and :PIXEL-BLUE, a complete RGB image may be read in.

The :DEPTH-IN-BITS parameter defaults to 16, but may be set to 8 to read byte data. Specifying 16 currently results in two eight-bit bytes being read, but only twelve bits of data being extracted from them. Mail jsp@biostr.washington.edu if you'd like to see this generalized further.

The :ENDIAN value has meaning only if :DEPTH-IN-BITS is greater than eight, and may be used to swap the byte order. It defaults to :BIG, the byte ordering used by SGI, Macs and Suns (but not PCs or Vaxen).

The :PADDING value defaults to zero, and represents the number of bytes to skip after each sample. By setting this nonzero, you can read a plane interleaved with other information, typically the other two color planes and perhaps an alpha channel.

If a :RESULT-IN value is supplied, and is of appropriate type, the result will be placed in it and 'image' returned; otherwise, a fresh image relation will be allocated and returned.

Since the input MRI/CAT file contains twelve-bit data packed in sixteen-bit words, and displayable graphic relations use eight-bit values, the data read must be folded from twelve to eight bits.

By default, this folding is done by mapping to 255 all values greater than that.

This folding may be controlled by supplying the :MIN and :MAX parameters:

pixel values <  min get set to min;
pixel values >= max get set to max-1.

(These default to 0 and 256 respectively, implementing the default folding.)

A linear mapping is done from the input interval [MIN, MAX) into the output interval [0,256).


Go to the first, previous, next, last section, table of contents.