Is it possible for a DigitalMicrograph script object to be notified of an ROI change on an image?

Question

The DigitalMicrograph scripting documentation alludes to various types of Listener objects that can be used to notify a script object of various types of events. In particular,

Answer 1

Yes there are. In fact, as far as ROIs are concerned there are two possibilities.

---

First option: Listen to a specific ROI

Any ROI in DigitalMicrograph has a unique ID number. You can add a listener to that particular ROI-ID as with the script below. Note, that the identical ROI can be placed on more than one ImageDisplay at the same time. ("linked ROIs"). The connected listener object will not be released as long as the ROI object is not released, but you can also explicitly remove the connection.

Class myRListen : object
{
    myRListen( object self )  { Result( "\n myRListen " + self.ScriptObjectGetID() + " created.\n" ); }
    ~myRListen( object self ) { Result( "\n myRListen " + self.ScriptObjectGetID() + " destroyed.\n" ); }   
    void DoStuff( object self, ROI thisROI ){ Result( "ROI ID:" + thisROI.ROIGetID() + " acted!\n" ); }
}

// Main 
{
    Image   img1 := RealImage( "Test 1", 4, 256, 256 )
    img1 = iradius
    img1.ShowImage()
    Image   img2 := RealImage( "Test 2", 4, 256, 256 )
    img2 = icol
    img2.ShowImage()

    ROI testROI = NewROI()
    testROI.ROISetVolatile(0)
    testROI.ROISetRectangle( 50, 50, 100, 100 )
    img1.ImageGetImageDisplay(0).ImageDisplayAddROI(testROI)
    img2.ImageGetImageDisplay(0).ImageDisplayAddROI(testROI)

    // Connect the ROI of specific ID to the "DoStuff" method of listener on "changed" message.
    // The signature of the "DoStuff" method has to be of form ( object self , ROI thisROI )
    // The method returns a unique ID for this connection.

    Number roiID    = testROI.ROIGetID()
    object listener = Alloc(myRListen)          
    ConnectObject( roiID, "changed", "ConnectionID", listener, "DoStuff" )      
    if ( TwoButtonDialog( "Immediately disconnect?", "Yes", "No" ) )
        DisConnectObject( roiID, "changed", "ConnectionID" )
}

This method only accepts "changed" as a message, and the 3rd parameter string (ConnectionID) should be unique, so that it can be used to remove this particular connection as shown. The main advantage of this method is its simplicity.

---

Second option: Listen to a specific imageDisplay

There are also listeners which you can connect to an imageDisplay object. This allows catching messages from 'any' ROI on this imageDisplay, but you can again use the unique-ROI-ID to filter out those you are interested in. The listener object will not be released as long as the imageDisplay is not released, but again you can unregister it manually.

Class myRListen : object
{
    myRListen( object self )  { Result( "\n myRListen " + self.ScriptObjectGetID() + " created.\n" ); }
    ~myRListen( object self ) { Result( "\n myRListen " + self.ScriptObjectGetID() + " destroyed.\n" ); }   
    void DoROIStuff( object self, Number e_fl, ImageDisplay idisp, Number r_fl, Number r_fl2, ROI thisROI ){ Result( "ROI ID:" + thisROI.ROIGetID() + " acted!\n" ); }
}

// Main 
{
    Image   img := RealImage( "Test", 4, 256, 256 )
    img = iradius
    img.ShowImage()

    ROI testROI1 = NewROI()
    testROI1.ROISetVolatile( 0 )
    testROI1.ROISetRectangle( 50, 50, 100, 100 )
    ROI testROI2 = NewROI()
    testROI2.ROISetVolatile( 0 )
    testROI2.ROISetRectangle( 150, 150, 200, 200 )
    testROI2.ROISetColor( 0, 0, 1 )
    ImageDisplay disp = img.ImageGetImageDisplay( 0 )
    disp.ImageDisplayAddROI( testROI1 )
    disp.ImageDisplayAddROI( testROI2 ) 

    // Connect the ROI of specific ID to the "DoStuff" method of listener on "changed" message.
    // The signature of the "DoStuff" method has to be of form ( object self , ROI thisROI )
    // The method returns a unique ID for this connection.

    object listener = Alloc(myRListen)          
    Number listenerID = ImageDisplayAddEventListener( disp, listener, "roi_changed:DoROIStuff" )
    if ( TwoButtonDialog( "Immediately disconnect?", "Yes", "No" ) )
        ImageDisplayRemoveEventListener( disp, listenerID )
}

Unless you have to monitor a specific ROI over multiple imageDisplays, the second option is the more versatile one. The method you register the roi_changed event with not only gives you a handle on the ROI, but also on the display it sits on. The number variables contain the event-flags telling you what has changed.

In GMS 2.3.1 there are currently the following ROI messages available:

roi_added, 
roi_removed, 
roi_begin_track,
roi_end_track, 
roi_property_changed,
roi_display_changed, 
roi_changed

and they need to be connected to methods of signature

void RAction( object self, Number e_fl, ImageDisplay idisp, Number r_fl, Number r_fl2, ROI r )

---

Examples

You can find listerner-type script examples on the FELIM script database, i.e.:

• Interactive Rotational Profile
• 3D Line Profile for SI