Custom Image Object Annotations

Many images are annotated to explain certain features or highlight specific details. Color annotations are more noticeable than plain black or white annotations. This section includes the following examples:

Annotating Indexed Image Objects

Annotating RGB Image Objects

Annotating Indexed Image Objects

When using Object Graphics, the original color table does not need to be modified. The color table (palette) pertains only to the image object not the window, view, model, polygon, or text objects. Color annotations are usually applied to label each color level within the image or to allow color comparisons. This section shows how to label each color level on an indexed image in Object Graphics. As an example, an image of average world temperature is imported from the worldtmp.png file. This file does not contain a color table associated with this image, so a pre-defined color table will be applied. This table provides the colors for the polygons and text used to make a colorbar for this image. Each polygon uses the color of each level in the table. The text represents the average temperature (in Celsius) of each level. Complete the following steps for a detailed description of the process.

Determine the path to the worldtmp.png file:

worldtmpFile = FILEPATH('worldtmp.png', $  
   SUBDIRECTORY = ['examples', 'demo', 'demodata'])

Import the image from the worldtmp.png file into IDL:

worldtmpImage = READ_PNG(worldtmpFile)

Determine the size of the imported image:

worldtmpSize = SIZE(worldtmpImage, /DIMENSIONS)

Initialize the display objects necessary for an Object Graphics display:

oWindow = OBJ_NEW('IDLgrWindow', RETAIN = 2, $  
   DIMENSIONS = [worldtmpSize[0], worldtmpSize[1]], $  
   TITLE = 'Average World Temperature (in Celsius)')  
oView = OBJ_NEW('IDLgrView', $  
   VIEWPLANE_RECT = [0, 0, worldtmpSize[0], $  
   worldtmpSize[1]])  
oModel = OBJ_NEW('IDLgrModel')

Initialize the palette object, load the Rainbow18 color table into the palette, and then apply the palette to an image object:

oPalette = OBJ_NEW('IDLgrPalette')  
oPalette -> LoadCT, 38  
oImage = OBJ_NEW('IDLgrImage', worldtmpImage, $  
   PALETTE = oPalette)

Add the image to the model, then add the model to the view, and finally draw the view in the window:

oModel -> Add, oImage  
oView -> Add, oModel  
oWindow -> Draw, oView

The following figure is displayed.

Figure 9-5: Temperature Image and Rainbow18 Color Table (Object Graphics)

Figure 9-5: Temperature Image and Rainbow18 Color Table (Object Graphics)

Before applying the color polygons and text of each level, you must first initialize their color values and their locations. The Rainbow18 color table has only 18 different color levels, but still has 256 elements. You can use the INDGEN routine to make an array of 18 elements ranging from 0 to 17 in value, where each element contains the index of that element. Then you can use the BYTSCL routine to scale these values to range from 0 to 255. The resulting array contains the initial color value (from 0 to 255) of the associated range (from 0 to 17, equalling 18 elements).

Initialize the color level parameter:

fillColor = BYTSCL(INDGEN(18))

Initialize the average temperature of each level, which directly depends on the initial color value of each range. Temperature is linearly scaled to range from -60 to 40 Celsius. You can convert the resulting temperature value to a string variable to be used as text:

temperature = STRTRIM(FIX(((20.*fillColor)/51.) - 60), 2)

Note
When the fillColor variable in the previous statement is multiplied by the floating-point value of 20 (denoted by the decimal after the number), the elements of the array are converted from byte values to floating-point values. These elements are then converted to integer values with the FIX routine so the decimal part will not be displayed. The STRTRIM routine converts the integer values to string values to be displayed as text. The second argument to STRTRIM is set to 2 to note the leading and trailing black values should be trimmed away when the integer values are converted to string values.

With the polygon color and text now defined, you can determine their locations. You can use a polygon object to draw each polygon and text objects to display each element of text. The process is repetitive from level to level, so a FOR/DO loop is used to display the entire colorbar. Since each polygon and text is drawn individually within the loop, you only need to determine the location of a single polygon and an array of offsets for each step in the loop. The following two steps describe this process.

Initialize the polygon and the text location parameters. Each polygon is 35 pixels in width and 18 pixels in height. The offset will move the y-location 18 pixels every time a new polygon is displayed:

x = [5., 40., 40., 5., 5.]  
y = [5., 5., 23., 23., 5.] + 5.  
offset = 18.*FINDGEN(19) + 5.

Initialize the polygon and text objects:

oPolygon = OBJARR(18)  
oText = OBJARR(18)  
FOR i = 0, (N_ELEMENTS(oPolygon) - 1) DO BEGIN & $  
   oPolygon[i] = OBJ_NEW('IDLgrPolygon', x, $  
   y + offset[i], COLOR = fillColor[i], $  
   PALETTE = oPalette) & $  
   oText[i] = OBJ_NEW('IDLgrText', temperature[i], $  
   LOCATIONS = [x[0] + 3., y[0] + offset[i] + 3.], $  
   COLOR = 255*(fillColor[i] LT 255), $  
   PALETTE = oPalette) & $  
ENDFOR

Note
The & after BEGIN and the $ allow you to use the FOR/DO loop at the IDL command line. These & and $ symbols are not required when the FOR/DO loop in placed in an IDL program as shown in ApplyColorbar_Indexed_Object.pro in the examples/doc/objects subdirectory of the IDL installation.

Add the polygons and text to the model, then add the model to the view, and finally redraw the view in the window:

oModel -> Add, oPolygon  
oModel -> Add, oText  
oWindow -> Draw, oView

The following figure displays the colorbar annotation applied to the image.

Figure 9-6: Temperature Image and Colorbar (Object Graphics

Figure 9-6: Temperature Image and Colorbar (Object Graphics

Clean up object references. When working with objects always remember to clean up any object references with the OBJ_DESTROY routine. Since the view contains all the other objects, except for the window (which is destroyed by the user), you only need to use OBJ_DESTROY on the view and the palette objects:

OBJ_DESTROY, [oView, oPalette]

Annotating RGB Image Objects

When using Object Graphics, colors can be defined just by the values of their red, green, and blue components. In this example, a color spectrum of additive and subtractive primary colors will be drawn on an RGB image for comparison with the colors in that image. The glowing_gas.jpg file (which is provided by the Hubble Heritage Team, made up of AURA, STScI, and NASA) contains an RGB image of an expanding shell of glowing gas surrounding a hot, massive star in our Milky Way Galaxy. This image contains all the colors of this spectrum. Complete the following steps for a detailed description of the process.

Determine the path to the glowing_gas.jpg file:

cosmicFile = FILEPATH('glowing_gas.jpg', $  
   SUBDIRECTORY = ['examples', 'data'])

Import the image from the glowing_gas.jpg file into IDL:

READ_JPEG, cosmicFile, cosmicImage

Determine the size of the imported image. The image contained within this file is pixel-interleaved (the color information is contained within the first dimension). You can use the SIZE routine to determine the other dimensions of this image:

cosmicSize = SIZE(cosmicImage, /DIMENSIONS)

Initialize the display objects required for an Object Graphics display:

oWindow = OBJ_NEW('IDLgrWindow', RETAIN = 2, $  
   DIMENSIONS = [cosmicSize[1], cosmicSize[2]], $  
   TITLE = 'glowing_gas.jpeg')  
oView = OBJ_NEW('IDLgrView', $  
   VIEWPLANE_RECT = [0., 0., cosmicSize[1], $  
   cosmicSize[2]])  
oModel = OBJ_NEW('IDLgrModel')

Initialize the image object. The INTERLEAVE keyword is set to 0 because the RGB image is pixel-interleaved:

oImage = OBJ_NEW('IDLgrImage', cosmicImage, $  
   INTERLEAVE = 0, DIMENSIONS = [cosmicSize[1], $  
   cosmicSize[2]])

Add the image to the model, then add the model to the view, and finally draw the view in the window:

oModel -> Add, oImage  
oView -> Add, oModel  
oWindow -> Draw, oView

The following image contains all of the colors of the additive and subtractive primary spectrum. A colorbar annotation can be added to compare the colors of that spectrum and the colors within the image. The color of each box is defined in the following array.

Figure 9-7: Cosmic RGB Image (Object Graphics)

Figure 9-7: Cosmic RGB Image (Object Graphics)

You can use the following to determine the color and location parameters for each polygon.

Initialize the color parameters:

fillColor = [[0, 0, 0], $ ; black  
   [255, 0, 0], $ ; red  
   [255, 255, 0], $ ; yellow  
   [0, 255, 0], $ ; green  
   [0, 255, 255], $ ; cyan  
   [0, 0, 255], $ ; blue  
   [255, 0, 255], $ ; magenta  
   [255, 255, 255]] ; white

After defining the polygon colors, you can determine their locations. Initialize polygon location parameters:

x = [5., 25., 25., 5., 5.]  
y = [5., 5., 25., 25., 5.] + 5.  
offset = 20.*FINDGEN(9) + 5.

The x and y variables pertain to the x and y locations (in pixel units) of each box of color. The offset maintains the spacing (in pixel units) of each box. Since the image is made up of mostly a black background, the x border of the colorbar is also determined to draw a white border around the polygons.

Initialize location of colorbar border:

x_border = [x[0] + offset[0], x[1] + offset[7], $  
   x[2] + offset[7], x[3] + offset[0], x[4] + offset[0]]

The y border is already defined by the y variable.

These parameters are used when initializing the polygon and polyline objects These objects will be used draw the boxes of the color spectrum and the colorbar border. Each polygon is 20 pixels wide and 20 pixels high. The offset will move the y-location 20 pixels every time a new polygon is displayed.

Initialize the polygon objects. The process is repetitive from level to level, so a FOR/DO loop will be used to display the entire colorbar. Since each polygon is drawn individually within the loop, you only need to determine the location of a single polygon and an array of offsets for each step in the loop:

oPolygon = OBJARR(8)  
FOR i = 0, (N_ELEMENTS(oPolygon) - 1) DO oPolygon[i] = $  
   OBJ_NEW('IDLgrPolygon', x + offset[i], y, $  
   COLOR = fillColor[*, i])

The colorbar border is produced with a polyline object. This polyline object requires a z variable to define it slightly above the polygons and image. The z variable is required to place the polyline in front of the polygons. Initialize the polyline (border) object:

z = [0.001, 0.001, 0.001, 0.001, 0.001]  
oPolyline = OBJ_NEW('IDLgrPolyline', x_border, y, z, $  
   COLOR = [255, 255, 255])

The polygon and polyline objects can now be added to the model and then displayed (re-drawn) in the window. Add the polygons and polyline to the model, then add the model to the view, and finally redraw the view in the window:

oModel -> Add, oPolygon  
oModel -> Add, oPolyline  
oWindow -> Draw, oView

The following figure shows the colorbar annotation applied to the image.

Figure 9-8: Specified Colors on an RGB Image (Object Graphics)

Figure 9-8: Specified Colors on an RGB Image (Object Graphics)

OBJ_DESTROY, oView