mrdisplay__define.pro


Name:
mrdisplay
Methods:
Constructor
mrdisplay::init             : constructor, 2nd part

Public variables (get)
mrdisplay::img              : returns a pointer to currently used image data
mrdisplay::imgXsize         : return image size in x in pixels
mrdisplay::imgYsize         : return image size in y in pixels
mrdisplay::imgMinval        : return minimum absolute image value
mrdisplay::imgMaxval        : return maximum absolute image value
mrdisplay::interpolate      : return current interpolation mode
mrdisplay::scaling          : return the scaling factor
mrdisplay::location         : return current image location within window
mrdisplay::contrast         ; return current contrast center and width
mrdisplay::gamma            ; return the currently used gamma value
mrdisplay::grWindow         : return the main window object
mrdisplay::screenXsize      : return visible canvas size in x in pixels
mrdisplay::screenYsize      : return visible canvas size in y in pixels
mrdisplay::labelView        : return the view meant for labels
mrdisplay::imgView          : return the view which holds the image
mrdisplay::palette          : return the currently used palette

Public variables (set)
mrdisplay::setInterpolate   : switch interpolation on or off
mrdisplay::setScaling       : set the scaling factor
mrdisplay::setLocation      : set image location in window
mrdisplay::setContrast      : same, but via center and width
mrdisplay::setGamma         ; set the gamma value of the used palette
mrdisplay::setPalette       : set the palette colors by passing RGB vectors
mrdisplay::setPaletteRGB    : set RGB colorset of the palette or a predefined color table

General
mrdisplay::setImg           : set the image to be displayed
mrdisplay::updateImg        : as setImg, but keep all settings
mrdisplay::clear            : clear the display - automatically displays
mrdisplay::display          : display object content on screen
mrdisplay::scroll           : scroll image by the specified amount
mrdisplay::centerImg        : center image in the middle of the screen
mrdisplay::fitToScreen      : resize image so it fits screen size

Event handling
mrdisplay::activate         : generate events
mrdisplay::deactivate       : no events no more
mrdisplay::registerEvt      : register an event
mrdisplay::requestDisplay   : call display after callbacks are done
mrdisplay::unregisterEvt    : unregister an event
mrdisplay::unregisterObj    : unregister a whole object
mrdisplay::unregisterAll    : remove all entries from callback tables

Private
mrdisplay_evthandler        : non-object event handler calls the object handler
mrdisplay::evthandler       : the object handler
mrdisplay::resolveTypeStr   : translate an event string into an event type
mrdisplay__define           : constructor, 1st part
mrdisplay::cleanup          : the destructor
Description:
An object to display a single indexed image. Full support for true color
images will be available in the next version.

!!! events need cleanup to include only the fields which are defined !!!
Event handling:
mrDisplay issues events on different conditions. The following event types are
presently defined - objects may register for one or more event types:

Event types:
Type (number)     string             occurence
0                'press'             any button press event
1                'dblclick'          any button double click event
2                'release'           any button release event
3                'motion'            mouse has been moved inside window
4                'keypress'          a key has been pressed inside window
5                'imgchange'         an image has been set or deleted
6                'palettechange'     the used palette has been changed (setpalette)

The event structure
> x = { mrdisplayEvt          ,$
>     type      :   0           ,$ ; (all) an integer denoting the event type, see below
>     top       :   0L          ,$ ; (0-4) the top widget id
>     display   :   obj_new()   ,$ ; (0-4) the display object itself
>     grWindow  :   obj_new()   ,$ ; (0-4) the IDLgrWindow object within the draw widget
>     imgView   :   obj_new()   ,$ ; (0-4) this objects image view window
>     lblView   :   obj_new()   ,$ ; (0-4) this objects label view window
>     x         :   0           ,$ ; x position of the event, device coordinates
>     y         :   0           ,$ ; y position of the event, device coordinates
>     dx        :   0           ,$ ; x difference since last event
>     dy        :   0           ,$ ; y difference since last event
>     imgx      :   0           ,$ ; x position of the event, image coordinates
>     imgy      :   0           ,$ ; y position of the event, image coordinates
>     key       :   0L          ,$ ; key off an ASCII key press
>     modifiers :   0L          ,$ ; bitmask: 1 = shift, 2 = control
>     button    :   0           ,$ ; bitmap, left, middle right mouse button, pressed/released
>                                $ ; button for press/release events, current status in motion evts
>     buttonstatus: 0            $ ; current status of pressed/released mouse buttons, bitmap
> }


Name:
mrdisplay::init
Syntax:
obj = obj_new('mrdisplay', baseid, x, y, xscroll, yscroll, /interpolate)
Arguments:
baseid
The base widget in which to create the drawing widget
x, y
Widget screen size in x and y in pixels
xscroll, yscroll
Canvas size in x and y in pixels. If canvas size is greater than
screen size, scroll bars are automatically added.
interpolate
Set to '1' for interpolation. Default is '0' (off)
Description:
initialization of the mrdisplay widget
Example code:
disp = obj_new('MRdisplay', baseid, 512, 512, 512, 512, interpolate=0)
img = indgen( 512, 512 )
imgptr = ptr_new( img, /no_copy )
disp->setImg, imgptr
disp->display
Example code:
For code examples on how to handle call back events, see e.g. the
source of the mrcontrast object, specfically mrcontrast::selfregister
and mrcontrast::mrdisplayEvtHandler
See mrdisplay::registerEvt for the available event types.
Inline doc:
 one view for the image, which scales and moves
 one view for labels, fixed to the image frame,
 one Scene to display it all,
 in the land of IDL, where the shadows lie

Name:
mrdisplay::cleanup
Syntax:
obj_destroy, obj
Description:
The destructor

Name:
mrdisplay::setImg
Syntax:
obj->setImg, image, top=integer, /no_copy, /update
Arguments:
image
Pointer to a two-dimensional matrix with the image data.
top
Integer: top byte value to which to scale the image in the range
[0,255], default is 255
no_copy
Don't make a copy of the image data, but use the reference directly.
Mind that the image will be free'd, when a new image is set or the
object destroyed!
update
Equivalent to calling mrdisplay::updateImg - which will go
eventually.
Description:
Hand the image over to mrdisplay. Unless the /no_copy keyword is set,
mrDisplay will make a copy of the image data. Note that the image
will not be displayed until the user calls mrdisplay::display
Setting an image causes a 'ImgChange' event.

Name:
mrdisplay::updateImg
Syntax:
Deprecated!
Use
obj->setImg, image, top=integer, /no_copy, /update
instead
Description:
As mrdisplay::setImg, but all image settings (scaling, location,
contrast) are kept - only the image data is replaced. The new image
must have the same size and the same palette as the old one, or the
results may be unexpected.
Calling this routine causes 'ImgChange' events.

Name:
mrdisplay::clear
Syntax:
obj->clear
Description:
Clear the screen. The currently displayed image is free'd, that is
if mrdisplay::setImg was called with keyword no_copy set, the
image data is gone.
This method creates imgchange events.

Name:
mrdisplay::img
Syntax:
img = obj->img()
Description:
Return pointer to currently used image data

Name:
mrdisplay::interpolate
Syntax:
ip = obj->interpolate()
Description:
Return the current interpolation status

Name:
mrdisplay::setInterpolate
Syntax:
obj->setInterpolate, /onoff
Arguments:
onoff
It's either 1 (on) or 0 (off)
Description:
Set ot unset interpolation. Does not automatically redisplay.

Name:
mrdisplay::scaling
Syntax:
s = obj->scaling()
Description:
Returns the scaling factor

Name:
mrdisplay::setScaling
Syntax:
obj->setScaling, scaling_factor
Arguments:
scaling_factor
The new scaling factor
Description:
Set the scaling factor - this will not redisplay the image

Name:
mrdisplay::imgXsize
Syntax:
xSize = obj->imgXsize()
Return value:
Returns the image's original (i.e. unscaled) size in x

Name:
mrdisplay::imgYsize
Syntax:
ySize = obj->imgYsize()
Return value:
returns the image's original (i.e. unscaled) size in y

Name:
mrdisplay::imgMinval
Syntax:
min = obj->imgMinval()
Return value:
returns the image's real (i.e. not scaled to [0:top]) minimum pixel value

Name:
mrdisplay::imgMaxval
Syntax:
max = obj->imgMaxval()
Return value:
returns the image's (unscaled) maximum pixel value

Name:
mrdisplay::contrast
Syntax:
cw = obj->contrast()
Return value:
Returns double array with two elements, both in range [0.,1.]
cw[0] = current contrast center
cw[1] = current contrast width

Name:
mrdisplay::setContrast
Syntax:
obj->setContrast, center, width
Arguments:
center
Relative contrast center, 0. <= center <= 1.
width
Relative contrast width, 0. <= width <= 1.
Description:
Set center and width of the image contrast. Both values are relative
(i.e. [0.,1.]) and internally scaled to absolute image values
Example code:
mrdisplay->setContrast, .5, 1.       ; resets to full width

Name:
mrdisplay::setGamma
Syntax:
obj->setGamma, gamma
Arguments:
gamma
Gamma value for the image's palette 0.1 < gamma < 10.
Description:
Set the gamma value for the image's palette

Name:
mrdisplay::gamma
Syntax:
gamma = obj->gamma()
Description:
Return the current gamma value of the image palette

Name:
mrdisplay::setLocation
Syntax:
obj->setLocation, x, y
Arguments:
x,y
New x,y location of the image
Description:
Scroll the image position to the given values

Name:
mrdisplay::location
Syntax:
loc = obj->location()
Description:
Return the image position within the window in a 2-element array.
(It's the view's position, to be precise)

Name:
mrdisplay::screenXsize
Syntax:
win = obj->screenXsize()
Return value:
Returns the visible canvas size in x in pixels ('x' argument in init)

Name:
mrdisplay::screenYsize
Syntax:
win = obj->screenYsize()
Return value:
Returns the visible canvas size in y in pixels ('y' argument in init)

Name:
mrdisplay::grWindow
Syntax:
win = obj->grWindow()
Return value:
The IDLgrWindow object associated with the drawing widget
The return value is obj_new(), if the draw widget has not been
realized yet.

Name:
mrdisplay::labelView
Syntax:
view = obj->labelView()
Return value:
The used IDLgrView object for display of labels. The user may
add models to this object which then are displayed at a fixed position
on the screen. Changing any of the view's properties means asking for
trouble, so don't do it. You may only add models to this view.
The view's coordinates are normalized!

Name:
mrdisplay::imgView
Syntax:
view = obj->imgView()
Return value:
The used IDLgrView object for display of the image. Again the
user may add image related objects to this view (e.g. rois) which will
be scaled and moved along with the image.

Name:
mrdisplay::setPalette
Syntax:
obj->setPalette, palette
Arguments:
palette
An object of class IDLgrPalette
Description:
Copies the RGB values of the argument palette object to mrdisplay's
internal palette object. Please note: copies! Otherwise there's the
risk that the user destroys the palette object.

Name:
mrdisplay::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. If colorTable is set, keywords red/green/blue are ignored.
Description:
Sets the red/green/blue values of the image palette used to display
the image.

Name:
mrdisplay::palette
Syntax:
palette = obj->palette()
Description:
Returns an object reference to mrDicoms internal IDLgrPalette object.
Destroying this object means asking for trouble.

Name:
mrdisplay::display
Syntax:
obj->display
Description:
(re-)draw the current image

Name:
mrdisplay::scroll
Syntax:
obj->scroll, dx, dy
Arguments:
dx, dy
Integer. Scroll the image by the given offset
Description:
Scroll the image position by the given values in pixels

Name:
mrdisplay::centerImg
Syntax:
obj->centerImg
Description:
Center the image on the canvas

Name:
mrdisplay::fitToScreen
Syntax:
obj->fitToScreen
Description:
Rescale the image, so it fits the canvas. This will also center the
image on the canvas.

Name:
mrdisplay::requestDisplay
Syntax:
obj->requestDisplay
Description:
Request a redisplay, but don't call mrdisplay::display immediately.
Instead, a redisplay of the screen is only performed after all external
event handlers have been called - thus avoiding possible overhead by
multiple calls to mrdisplay::display from each event handler.

Name:
mrdisplay::activate
Syntax:
obj->activate
Description:
Switch on event handling

Name:
mrdisplay::deactivate
Syntax:
obj->deactivate
Description:
Switch off event handling

Name:
mrdisplay::unregisterAll
Syntax:
obj->unregisterAll
Description:
Clear all entries in the callback table
(done by deleting the old one and creating a new)

Name:
mrdisplay::registerEvt
Syntax:
obj->registerEvt, object, event_type
Arguments:
object
The object which provides the call back function
event_type
String or string array denoting the event type (s.b.)
Description:
Register an event with mrdisplay.
Possible event types are:
'Press'         : any button press
'Release'       : any button release
'DblClick'      : any button double click
'Motion'        : any mouse motion
'KeyPress'      : any key press
'ImgChange'     : called after setImg or updateImg
'PaletteChange' : called after call to setImgPaletteRGB
Event type strings are case insensitive.
The object must provide a method named 'mrdisplayEvtHandler' which
dispatches the incoming events. This method will be called
with a pointer to mrdisplay's event structure as an argument (see
above for the event structure definition)
Registering the same object with the same event type a second
type will not cause the handler function to be called twice,
but implicitly only move the function call to the end of the list.
Example code:
disp = new_object('mrdisplay', base, 256, 256, 256, 256)
zoom = new_obj('mrzoom')
disp->registerEvt, zoom, ['Press','Release']

Name:
mrdisplay::unregisterEvt
Syntax:
obj->unregisterEvt, object, event_type
Arguments:
object
The call back object to be removed
event_type
String (or string array) denoting the event type(s) to remove
Description:
unregister an event/events from mrdisplay callback

Name:
mrdisplay::unregisterObj
Syntax:
obj->unregisterObj, object
Arguments:
object
The call-back object to remove
Description:
Unregister a whole object from mrdisplay callback

Name:
mrdisplay::resolveTypeStr
Syntax:
type_id = self->resolveTypeStr, event_type
Description:
Convert the type string into an index, case insensitive

Name:
mrdisplay_evthandler
Syntax:
mrdisplay_evthandler, evt
Calls:
mrdisplay::evtHandler
Description:
Get object from event and call the object's event handler

Name:
mrdisplay::evthandler
Syntax:
self->evthandler, evt
Description:
Handles events from the window and passes them on to registered
objects, i.e. creates events of type '0' to '4'.
imageChange and paletteChange events are created by their respective
methods.

Name:
mrdisplay__define
Type:
Constructor

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