mrimagesetdicom__define.pro


Name:
mrImageSetDicom
Superclass:
mrImageSet
Methods:
Constructor
mrImageSetDicom::init             : d1, d2, d3, name=name, class=class

Public variables (get)
mrImageSetDicom::name             : see mrImageSet::name
mrImageSetDicom::class            : see mrImageSet::class
mrImageSetDicom::xsize            : see mrImageSet::xsize
mrImageSetDicom::ysize            : see mrImageSet::ysize
mrImageSetDicom::d0               : see mrImageSet::d0
mrImageSetDicom::nz               : see mrImageSet::nz
mrImageSetDicom::nSlices          : see mrImageSet::nSlices
mrImageSetDicom::d1               : see mrImageSet::d1
mrImageSetDicom::nt               : see mrImageSet::nt
mrImageSetDicom::nShots           : see mrImageSet::nShots
mrImageSetDicom::d2               : see mrImageSet::d2
mrImageSetDicom::size             : see mrImageSet::size
mrImageSetDicom::nImgs            : see mrImageSet::nImgs
mrImageSetDicom::palette          : see mrImageSet::palette
mrImageSetDicom::imgdata          : see mrImageSet::imgdata
mrImageSetDicom::path             : see mrImageSet::path
mrImageSetDicom::seriesNumber     : series number of loaded images
mrImageSetDicom::studyUID         : unique study ID
mrImageSetDicom::dicomData        : returns pointer to mrDicom object matrix

Public variables (set)
mrImageSetDicom::setName          : see mrImageSet::setName
mrImageSetDicom::setClass         : see mrImageSet::setClass

Image handling
mrImageSetDicom::set              : see mrImageSet::set
mrImageSetDicom::get              : see mrImageSet::get
mrImageSetDicom::delete           : deletes one or all images from the set
mrImageSetDicom::condense         : see mrImageSet::condense
mrImageSetDicom::load             : load a single image
mrImageSetDicom::loadSequence     : load an image sequence
mrImageSetDicom::loadTimeSequence : load a 2-dim (time/space) image sequence
mrImageSetDicom::errNo            : see mrImageSet::errNo
mrImageSetDicom::errMsg           : see mrImageSet::errMsg
mrImageSetDicom::mrImageSet       : creates copy of the underlying mrImageSet

Callback
mrImageSetDicom::notify           : see mrImageSet::notify

Private functions
mrImageSetDicom::loadImgs         : the basic load method
mrImageSetDicom__define           : the constructor
mrImageSetDicom::cleanup          : the destructor

Description:
An image set of dicom images. Subclass to mrimageset with additional
means to store the DICOM objects and to load whole image sequences
at once.
A dataset is identified via its name and class - these two strings
are freely definable by the user - and the series number and the
unique study ID - these latter two come from the loaded dicom objects.
There's essentially two ways to use this object.
  •  as a container for dicom objects which are loaded individually
  • one after the other via the load function
  •  as an object that holds a set of images loaded all at once and
  • automatically sorted into a matrix via the loadSequence method.
  •  as a container for user created dicom objects which will be
  • saved later.
    In the first case, the dimensions of the image matrix have to be
    passed to the constructor. Otherwise (since loadSequence destroys all
    existing dicom objects) the dicom matrix is created automatically
    from information in the dicom file - slice position and/or time.

    Name:
    mrImageSetDicom::init
    Syntax:
    obj = obj_new('mrImageSetDicom', d0, d1, d2, name=name, class=class )
    Arguments:
    d0, d1, d2
    Dimensions of the image pointer matrix - optional!
    name, class
    Two optional strings to set the class attributes 'name' and 'class'.
    Description:
    Instanciates an object of class mrImageSetDicom
    If d0/d1/d2 are not provided, they are set after loading a sequence or
    time sequence.

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

    Name:
    mrImageSetDicom::seriesNumber
    Syntax:
    data = obj->dicomData()
    Return value:

    Name:
    mrImageSetDicom::studyUID
    Syntax:
    data = obj->dicomData()
    Return value:

    Name:
    mrImageSetDicom::mrImageSet
    Syntax:
    data = obj->mrImageSet
    Return value:
    Returns a newly created mrImageSet object which is a copy of the
    underlying mrImageSet object to this mrImageSetDicom object.
    The original reason to introduce this method was related to
    the condense method.
    Maybe this method should go.

    Name:
    mrImageSetDicom::dicomData
    Syntax:
    data = obj->dicomData()
    Return value:
    Returns a pointer to the matrix of pointers to mrDicom objects

    Name:
    mrImageSetDicom::getTagValue
    Syntax:
    res = mrImageSetDicom::getTagValue( dicom, group, element )
    Description:
    Private method!
    Given group and element id, the function returns the dicom value that
    does not belong to a sequence (i.e. the one whose parent id is -1)
    We do that here instead of mrDicom since the filling of mrDicom
    internal structures takes quite some time - too long time for the
    loading of ~ 1k images.

    Name:
    mrImageSetDicom::load
    Syntax:
    res = obj->load( filename, index, /rotate )
    Arguments:
    filename
    The file to load, full path
    index
    An n-element array (where n is the number of matrix dimensions)
    holding the position where to store the loaded image internally.
    rotate
    If set, the image is rotated by 180 degrees and sides flipped
    (via rotate( image, 7) )
    Return value:
    0 in case of error, 1 in case of success.
    Description:
    Load a single image.
    Example code:
    set = obj_new('mrImageSetDicom', 10, 60)
    ok  = set->load( filename, [9,37])
    if( ok ) then print, 'Loading succeeded' else print, 'Fail'

    Name:
    mrImageSetDicom::loadSequence
    Syntax:
    res = obj->loadSequence( filename, filter=filter, /rotate, /progressbar )
    Arguments:
    filename
    One of the files in the set to load
    filter
    The method loads a complete image series, i.e. images that have the
    same series number, into memory, where the series number is taken from
    the initial file.
    To do this, the method needs to load each single file in the directory
    to check whether the series numbers match - a huge overhead, if many
    files do not belong to the desired series.
    If the filter keyword is set, only files are loaded and checked which
    match the filter criteria. If it is possible to narrow down the selection
    via some filter, loading might speed up considerably.
    rotate
    If set, rotate the loaded images via rotate( image, 7)
    progressbar
    If set, a progressbar is displayed while loading
    Return value:
    1 in case of success, else 0.
    Description:
    Loads a sequence of images (i.e. images that have the same series number)
    and stores them in an array.
    The pictures in the data array as well as the raw data (dicom array)
    are ordered by image number.
    Known bugs:
    The method returns with an error if only one image is loaded, requiring
    sequences to consist of more than one single image. It should return
    without an error message.

    Name:
    mrImageSetDicom::loadTimeSequence
    Syntax:
    res = obj->loadTimeSequence( filename, /progressbar )
    Arguments:
    filename
    One of the files in the set to load
    filter
    See the comment in mrImageSetDicom::loadSequence
    rotate
    If set, rotate the loaded images via rotate( image, 7)
    progressbar
    If set, a progressbar is displayed while loading
    Return value:
    1 in case of success, else 0 - check mrImageSet::errMsg for an
    error description in that case.
    Description:
    As mrImageSetDicom::loadSequence, but loads a time sequence of images and
    stores them in a two dimensional matrix. The first matrix index denotes the
    slice number, the second one the shot number (i.e. position in time).
    The decision is based on the 3rd element (z-position) of the patient
    image position (dicom tag (0020,0032)), which obviously requires different
    z-positions for the slices. I.e. if the slices should be aligned parallel
    to the z-axis, the sorting algorithm will not work.
    Known bugs:
    Attempts to load a 'normal' set of images via loadTimeSequence will
    result in a (caught) IDL error message. It should be a 1xn matrix.

    Name:
    mrImageSetDicom::loadImgs
    Syntax:
    res = obj->loadImgs( mode, index, filename, filter=filter, /progressbar, /rotate)
    Inline doc:
     Scan all files in the directory, load them, get the series number
     and store them in our list if the series number equals self.seriesnumber.
     A failed load will not cause a routine break but continue with the next file.
     If the failed load was crucial, this will lead to an error message further
     down when doing the validity checks
     check whether all image numbers are present and sort images
     get number of different slice positions
     total number of images must be a multiple of nofslices
     find out whether images are ordered in time or in space, then
     store the image data in an array

    Name:
    mrImageSetDicom::delete
    Syntax:
    obj->delete, slice, shot, /progressbar, /all
    Arguments:
    slice, shot
    Slice and shotnumber of the image to delete. Shot is '1' by
    default.
    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:
    mrImageSetDicom__define
    Description:
    The constructor.

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