what is the difference between DeleteImage() and closeImage()? - dm-script

Question

If I use DeleteImage() within a thread versus CloseImage(), there seems to be a difference - but I can only guess. Does anyone have a clear definition?
More detail:
Within the thread, an image A has an ROI. If the user deletes the ROI, I also want to close the image A, but still use it again later in the thread.
It seems that when I use A.deleteImage(), I have to redefine that image, whereas if I use A.CloseImage() - I don't.
It looks like that is what is happening, but if anyone knows for sure, please let me know.
Thanks

Answer 1

In order to undestand the commands you need to understand how memory objects are managed.
Anything will remain a valid memory object as long as there is a valid reference to it.
In case of images, this tanslates to:
An image will stay in memory as long as at least one of the following
is true:
The image is displayed on the screen
A script variable points to the image
Any other DM routine has a variable that points to the image
A single image can have multiple of the above conditions fulfilled at the same time. The only way to remove an image from memory is, to ensure all references to it are removed.
For displayed images this means to "close" the display. As a user, you would click the "X" of the window. The same functionality is invoked by the script command CloseImage(). Note that using this command on an image which isn't displayed, doesn't do anything. Note further, that closing an image does not remove any variables or their references to this image.
For script variables this mean you somehow have to "unlink" the variable from the image. (The opposite from using := to assing it.). This is done with the DeleteImage() command. Alternatively, one could also direclty assign the variable to the NULL-pointer as in img := NULL
For held references from DM there is nothing you can do, and you shouldn't. If a certain routine requires an image to be there, it will remain. You may be able to close the Display, but you can never remove it. That's why you can often 'find' images, and even show them using their label. Camera refernece images are a good example for this, but there are others as well.
Visually:
With the explanation given above, you should be able to understand the different behavior in the following examples:
void CloseTest( number ShowItFirst )
{
image img := realImage( "Test", 4, 100, 100 )
Result( "\n Assignment: Image is valid:" + img.ImageIsValid() )
if ( ShowItFirst )
{
img.ShowImage()
Result( "\n Displaying: Image is valid:" + img.ImageIsValid() )
}
img.CloseImage()
Result( "\n Closing: Image is valid:" + img.ImageIsValid() )
img.ShowImage()
Result( "\n Displaying: Image is valid:" + img.ImageIsValid() )
}
void DeleteTest( number ShowItFirst )
{
image img := realImage( "Test", 4, 100, 100 )
Result( "\n Assignment: Image is valid:" + img.ImageIsValid() )
if ( ShowItFirst )
{
img.ShowImage()
Result( "\n Displaying: Image is valid:" + img.ImageIsValid() )
}
img.DeleteImage() // This is the same as: img := NULL
Result( "\n Deleting: Image is valid:" + img.ImageIsValid() )
// img.ShowImage() // This fails, because image is no longer valid!
}
It should now also be clear, why one can use CloseImage( A ) but not DeleteImage( A ) for a displayed image of label A:
The first command only wants to close the image display of the image which is referenced by the label. The second, however, wants to 'unlink' the script variable from the image. But the label 'A' is not a script-variable!