mrimageset__define.pro


Name:
mrImageSet
Methods:
Constructor
mrImageSet::init             :

Public variables (get)
mrImageSet::name             : an image set may be given a name for identification
mrImageSet::class            : a 'class' name to group image sets
mrImageSet::xsize            : number of pixels in 'x'
mrImageSet::ysize            : number of pixels in 'y'
mrImageSet::d0               : matrix dimension 0
mrImageSet::nz               : alias for mrImageSet::d0
mrImageSet::nSlices          : alias for mrImageSet::d0
mrImageSet::d1               : matrix dimension 1
mrImageSet::nt               : alias for mrImageSet::d1
mrImageSet::nShots           : number of 'shots' (= images in time)
mrImageSet::d2               : matrix dimension 2
mrImageSet::size             : combination of the above, similar to idl's 'size'
mrImageSet::nImgs            : total number of images
mrImageSet::palette          : the palette object
mrImageSet::imgData          : pointer to matrix holding image pointers
mrImageSet::path             : last used path in load/save
mrImageSet::uvalue           : return the user definable pointer
mrImageSet::parent           : a reference to an image set from which this set is derived

Public variables (set)
mrImageSet::setName          : set the name
mrImageSet::setClass         : set the class name
mrImageSet::setUvalue        : set the user definable value (a pointer, sigh)
mrImageSet::setParent        : store reference to a parent mrImageSet(Dicom) object
mrImageSet::setPalette       : copies RGB values from a passed palette
mrImageSet::setPaletteRGB    : sets the RGB values of the internally stored palette object

Image handling
mrImageSet::set              : set an image
mrImageSet::get              : get a specific image
mrImageSet::delete           : delete one or all images
mrImageSet::condense         : condense a matrix dimension into the image data
mrImageSet::load             : load an image from harddisc
mrImageSet::save             : save one or all images to harddisc
mrImageSet::errMsg           : returns an error description of the last I/O error

Notifications
mrImageSet::notify           : see mrNotify::notify and below
mrImageSet::enableNotify     : see mrNotify::enableNotify
mrImageSet::disableNotify    : see mrNotify::disableNotify

Private functions
mrImageSet__define           : the constructor
mrImageSet::cleanup          : the destructor
Description:
Load and save functionality are not fully implemented, yet.

General
mrImageSet serves as a container for a set of images that have the same
size and share a common palette. The size may be set upon instanciation
of the object - otherwise the first loaded/set image determines the image
size for this instance. The same mechanism is applied to the RGB palette.
An image set may have a user definable 'name' and 'class' for identification
and grouping.

Image sets
Image sets are stored as matrices of image pointers. These matrices may have
up to three dimensions, e.g. for perfusion sequences one dimension for the
slice number, a second dimension for point in time.
nx and ny denote the size of the images itself in pixels.
d0, d1 and d2 denote the extensions of above mentioned matrix. Since this
doesn't mean anything, there's a number of aliases for better readability
of the source code that uses this object:
d0 can also be accessed as nz or nSlices (number of images in z)
d1 can also be accessed as nt or nShots  (number of images in time)
d2 got no aliases yet

Data organization
There's no reason why the images should have only two dimensions (x,y) -
in many cases calculation routines can make better use of IDL syntax if
some of above listed matrix dimensions could be condensed into the image
data.
The mrImageSet::condense method serves this purpose by folding one dimension
of the pointer matrix into the images.

Load and Save(not implemented yet)
The object supports some standard image formats for which IDL provides
loading and saving routines. Image sets based on the DICOM format are
special and are handled via mrImageSetDicom, which is a subclass to
mrImageSet and provides special load and save functionality for DICOM.

Notifications
External objects can register with an mrImageSet object for notification
upon data change via mrImageSet::notify
Available events are 'set', 'delete' and 'palettechange'

Name:
mrImageSet::init
Syntax:
obj = obj_new('mrImageSet', d0, d1, d2, name=name, class=class, xsize=xsize,
ysize=ysize, red=red, green=green, blue=blue
Arguments:
d0, d1, d2
Dimensions of the image pointer matrix
name, class
Two optional strings to set the class attributes 'name' and 'class'.
xsize, ysize
Size in pixels of the images in this set. If not set here, the first
image loaded/set will determine the values. All images in a set must be
of the same size.
red, green, blue
Image palette. If not set, the palette is determined by the first image
added to the set. See also mrImageSet::set and mrImageSet::load
All images in a set share the same palette ('cause it rhymes)
Description:
Instanciates an object of class mrImageSet. The optional arguments
red, green and blue must be set all at once or not at all.
Example code:
obj=obj_new('mrImageSet', 10, 60, name='signal', class='perfusion')

Name:
mrImageSet::cleanup
Syntax:
obj_destroy, obj
Description:
The destructor - deletes all data by calling mrImageSet::unload

Name:
mrImageSet::name
Return value:
This mrImageSet's user defined name, a string.

Name:
mrImageSet::class
Return value:
This mrImageSet's user defined class name, a string.

Name:
mrImageSet::xsize
Return value:
number of image pixels in x

Name:
mrImageSet::ysize
Return value:
number of image pixels in y

Name:
mrImageSet::d0
Return value:

Name:
mrImageSet::nz
Return value:

Name:
mrImageSet::nSlices
Return value:

Name:
mrImageSet::d1
Return value:

Name:
mrImageSet::nt
Return value:

Name:
mrImageSet::nShots
Return value:

Name:
mrImageSet::d2
Return value:

Name:
mrImageSet::size
Syntax:
res = obj->size( /dimensions, /n_dimensions, /n_elements )
Return value:
An array denoting the dimensions of the image matrix.
The array format resembles the format returned by IDL's size function.
ret[0] = the number of dimensions
ret[1:#dims] = size of each dimension
second last element: -1
last array element : total number of images in this image set
If the number of dimensions is zero (i.e. the matrix consists of just
a single element/pointer), the method returns [0,-1,1], if the image
pointer is valid or [0,-1,0], if not.

Name:
mrImageSet::nImgs
Return value:
Returns the number of images.
Please be careful in case of mrimagsetdicom objects - after condensing
data, the number of images and the number of dicom objects does not
match any more! If you're looking for the number of DICOM objects,
use mrImageSetDicom::nDicom instead

Name:
mrImageSet::palette
Return value:
Returns a reference to the palette object. The user may modify the
object properties, but destroying the object means asking for
trouble.

Name:
mrImageSet::setPalette
Syntax:
obj->setPalette, palette
Arguments:
palette
An IDLgrPalette object
Description:
Copies (!) the rgb values from the palette object to the internal
palette.

Name:
mrImageSet::setPaletteRGB
Syntax:
obj->setPaletteRGB, red=intarr, green=intarr, blue=intarr, colorTable=integer
Arguments:
red, green, blue
Integer arrays with 256 elements holding the red/green/blue values of
the palette
colorTable
An integer value between 0 and 41 indexing one of IDL's predefined
color tables. If set to 42, a logarithmically divided colortable is
loaded.
Description:
Sets the red/green/blue values of the internal image palette.

Name:
mrImageSet::imgData
Return value:
Returns the pointer to the image pointer matrix.

Name:
mrImageSet::path
Return value:

Name:
mrImageSet::uvalue
Return value:

Name:
mrImageSet::parent
Return value:
The parent imageSet (of class mrImageSet or mrImageSetDicom) of this
image set - as set in mrImageSet::setParentSet.

Name:
mrImageSet::errMsg
Syntax:
print, obj->errMsg()
Return value:
Returns a message text corresponding to the last I/O error.

Name:
mrImageSet::setName
Syntax:
obj->setName, name
Description:
Sets the name of this object

Name:
mrImageSet::setClass
Syntax:
obj->setClass, classname
Description:
Sets the classname of this object (which has nothing to do with
'classes' as used in OO programming, of course).

Name:
mrImageSet::setUvalue
Syntax:
obj->setUvalue, value, /no_copy
Arguments:
value
Value may be anything, a single value, an array, a structure.
The function will internally create a pointer to this value and store
the pointer (although this is transparent to the user when retrieving
the uvalue.
no_copy
Well, of course it is not transparent to the user. Normally the method
will create a copy of the specified value. if the no_copy keyword is
used, no copy will be created, but the value variable is invalid after
setting of the uvalue.
Description:
Sets a uvalue

Name:
mrImageSet::setParent
Syntax:
obj->setParent, mrImageSetObject
Description:
mrImageSets might be created from other mrImageSet or mrImageSetDicom
objects. To store these dependencies it is possible to save the
parent set in an object variable.
Might be useful, e.g. to store a parent mrImageSetDicom object to
keep the dicom data without the need to create a full mrImageSetDicom
which would only mean an unnecessary overhead.

Name:
mrImageSet::set
Syntax:
obj->set, index, image, /no_copy
Arguments:
index
integer array, containing the coordinates of the image, i.e.
the matrix indices of the image pointer matrix. Obviously the number
of elements of the array must match the number of dimensions of the
pointer matrix.
image
Pointer to the image
no_copy
flag. By default, the method makes a copy of the passed image data.
To conserve space, this may be suppressed. Note, however, that
destroying the mrImageSet object will free all stored image pointers!
Also changing the image size later means asking for trouble.
Description:
Adds an image to the dataset

Name:
mrImageSet::get
Syntax:
image = obj->get( index, /all )
Arguments:
index
integer array, containing the coordinates of the image to set, i.e.
the matrix indices of the image pointer matrix. Obviously the number
of elements of the array must match the number of dimensions of the
pointer matrix.
all
If set, the method returns a pointer to the whole image matrix
i.e. the same as mrImageSet::imgdata() would return
Description:
Returns the image pointer

Name:
mrImageSet::delete
Syntax:
obj->delete, index, /progressbar, /all
Arguments:
index
See mrImageSet::set
progressbar
If set, a progressbar will be instanciated and update to show
deletion progress. Only appropriate for very large data sets or very
slow machines.
all
If set to '1', all images will be 'free'd. Arguments slice
and shot are ignored in this case (and need not be set).
Description:
Deletes one or all image(s) from the data set.

Name:
mrImageSet::condense
Syntax:
res = obj->condense( index, /progressbar, /no_copy )
Arguments:
index
The matrix dimension to add to the image data
The image matrix itself will subsequently be reduced by that
dimension, e.g.
obj->condense, 0
will  turn former d1 into d0 (i.e. 'shots' into 'slices')
and d2 into d1 while the original d0 dimension is added to the
image data itself, which will thus become a 3-dim array with
dimensions [nx,ny,d0].
progressbar
Displays a progressbar while resorting the images. Only
appropriate for very large datasets or slow machines.
no_copy
By default, the new image data is stored in a newly created
mrImageSet object which is returned to the user. A reference to
the parent imageset is stored in the new set in this case.
If the no_copy keyword is set, the condensed data will replace
the existing.
Return value:
either obj_new() or, if the /copy keyword is set, a reference to
the newly created mrImageSet object.
Description:
Condenses one matrix dimension into the image data itself.
Example: 128x128 images, 20 slices (d1), 60 shots(d2)
newset = obj->condense(1)
will leave you with 60 images of dimension [128,128,20]
The image matrix will afterwards only be 1-dimensional with 60
image pointers. If the no_copy keyword is set, a new mrImageSet object
is created with the new data. Otherwise, the original images are
lost (though they can of course be easily recreated)
Limit
Before calling the 'condense' method, the images must be two-
dimensional, i.e. at most one matrix dimension can be condensed
into an image as of now.

Name:
mrImageSet::load
Syntax:
res = obj->load( filename, position, type=type)
Arguments:
!!! WIP !!!
filename
The file to load
type
One of the image file formats supported by IDL, i.e.
'BMP', 'PNG', 'TIFF' or 'DICOM'. Note that access to dicom data is
not possible - mrImageSetDicom is to be used for that.
Return value:
0 in case of error, 1 in case of success.
mrImageSet::lastErrMsg can be used to obtain the error message.
Description:
Loads a single image and stores a pointer to the data at the
specified matrix location.
The first image loaded defines the image size and RGB colors for
this imageset object. Subsequently loaded images are checked to
be of same size and are rejected if they are not. RGB colors are
not checked, though.
Not all IDL supported file types are supported here because of
their color handling. Can be extended when needed.
The method is called 'load', not 'read'. IMO, load/save methods
include opening and closing of a file, while read/write methods
read from/write to an already opened file.

Name:
mrImageSet::save
Syntax:
not implemented, yet. Needed?
Arguments:
Return value:
Description:

Name:
mrImageSet__define
Description:
The constructor.

Last modified: Mon Nov 29 13:30:06 2004