DISPLAY routine

By Pavel A. Romashkin, Ph.D., NOAA-CMDL, created 08-2000, updated 08-2001, 2002

DISPLAY has been updated to version 3.0. Overall size of the code was reduced, methods generalized, some features added, zooming optimized. See the procedure header for new features, or contact me if you have any questions or with bug reports. Version 2.0 requires normalize.pro (by D. Fanning) and get_range.pro. Also, ticks1k.pro is used in the IDLgrPlot::zoom.pro procedure, but can be disabled if so desired.

Old version is available also. Old version requires IDLgrPlot::zoom.pro, normalize.pro (by D. Fanning) and get_range.pro. Optional ticks1k.pro is enabled but can be easily disabled in the code.

DISPLAY is a 2D (X-Y coordinate space) plotting routine capable of linking plots in several windows using Region Of Interest (ROI) feature. ROI at this time assumes that data in the linked windows are related because they have the SAME number of data points.

Technical details can be found in the header and code of Display routine. On this page, the use of it is covered more thoroughly.

Display is an alternative for IDL's built-in PLOT routine. It is similar to great programs Wplot and Woplot by Paul van Delst, but allows some extra functionality. Display is recommended for faster machines in P-III and PowerPC G4 class, as it may appear slow on older machines.

The most obvious use of Display is interactive use from IDL command line. To create a new Display window, use:
Display, X, Y, color=[200,0,0], linestyle=6, psym=5, xtitle='My X axis', ytitle='My Y axis', $
    name='My_first_plot', title='My beautiful data', wtitle='First Display'

There are no limitations on the string used as plot name.

To append a plot, use:
Display, X1, Y1, color=[0,0,200], name='My_second_plot', /OVER
To alter an existing plot, use its name:
Display, name='My_second_plot', color=[0,200,0], psym=4, linestyle=6, $
    background=[255,255,200], title='Not so beautiful data', /OVER
The fact that DISPLAY allows fast changes to existing NAMED plots allows to visualize data change (simulate animation). Try:
; Get colors for nice view.
LoadCT, 39
tvlct, /get, r, g, b
c = transpose([[r],[g],[b]])
; Now, create a DISPLAY:
for i=0,10 do Display, sin(findgen(200)*0.1)*findgen(200)*0.01*(i+1), $
    name='a'+strtrim(i,2), psym=4, oref=oref, over=(i ne 0), color=c[*,i*25]
; Change the coefficient to alter the data in all of the plots and watch:
for i=0,10 do Display, sin(findgen(200)*0.1)*findgen(200)*0.1*(i+1), $
    name='a'+strtrim(i,2), over=1

A couple of things are worth mentioning here. Notice that OREF keyword has to be used in the first loop because DISPLAY will not become self-aware at the main IDL level until the statement that creates it (the FOR loop in this case) exits. OREF, in contrast, identifies a DISPLAY window immediately. For the second loop, there is already a DISPLAY on the main IDL level, so OREF is not necessary and OVER is set to 1. Color of each plot remains the same.

To print a plot, use:
Display, /OVER, /print[out]

Notice that, if used without /OVER, the /PRINT keyword will send the newly created blank plot to the printer. However, /PRINT causes the printer dialog to appear, so an erroneous print job can be cancelled by the user.
Printouts are attempted to be scaled like the original Display window. However, hard copies tend to have slightly different aspect ratio than the screen version of Display.

Main features of Display are as follows.

In order to ... Use unique names for plots and text labels. If the same name is used, an error may occur.

Notice that TITLE keyword alone sets the main title of the window. When used with the LEGEND keyword, TITLE sets the title of the legend.

Multiple Display windows are allowed. Any existing Display window can be modified from the command line, plots appended, removed, etc. by bringing the desired window to the foreground. The topmost Display window has "focus" and any command line call of "Display, /OVER" will apply to that window.

Display can be expanded through the use of left, middle and right mouse buttons. Display code provides distinction for the buttons already but a user can reassign the actions to add custom actions, for example, to delete points from plots, zoom along a given axis, etc.

To use the ROI feature:

Create linked DISPLAY windows containing related plots. Give those plots the same name. In order to maintain logical link between the plots, it is a good idea for the related plots to be the same length, because it is the order of points in the plot that defines ROI in this release of DISPLAY. No value analyses or interpolation is performed.
Once two (or more) windows are created, use middle mouse button to draw a region of interest in one of the windows. If the ROI you drew encloses any data points, a new plot(s) will appear on all linked DISPLAY windows. Name of each plot is prefixed with "Linked ...". It is a good idea to use a LEGEND to see which plots were linked.
Linked plots can be modified using their name and DISPLAY, NAME='Linked xxx', /OVER. They can be removed by double-clicking on them. Color of the linked plots can be set using ROI_COLOR keyword (use RGB 3-element vector as a parameter). So one can create a red linked plot first, then switch color and make another linked plot in blue, then compare them.

Example code:

; Create FIRST Display window with two plots in it.
display, findgen(200), sin(findgen(200)*0.1)*findgen(200)*0.01, psym=4, linestyle=6, name='Variable 1', link=1
display, findgen(200), cos(findgen(200)*0.1)*findgen(200)*0.01, psym=2, linestyle=3, name='Variable 2', /over, color=[200,100,0]
display, /over, /legend, legend_title='Legend 1'
display, /over, title='First DISPLAY', wtitle='FIRST', xtitle='Seconds', ytitle='Variable value'

; Create SECOND Display window, using the same LINK=1 as FIRST.
display, findgen(200), sin(findgen(200)*0.07)*findgen(200)*0.01, psym=4, linestyle=6, name='Variable 1', link=1
display, findgen(200), cos(findgen(200)*0.11)*findgen(200)*0.02, psym=2, linestyle=3, name='Variable 2', /over, color=[200,100,0]
display, /over, /legend, legend_title='Legend 2'
display, /over, title='Second DISPLAY', wtitle='SECOND', xtitle='Seconds', ytitle='Variable value'

; Create THIRD Display window, with a cross-plot of the variables.
display, sin(findgen(200)*0.1)*findgen(200)*0.01, sin(findgen(200)*0.07)*findgen(200)*0.01, $
    psym=4, linestyle=6, name='Variable 1', link=1
display, cos(findgen(200)*0.1)*findgen(200)*0.01, cos(findgen(200)*0.11)*findgen(200)*0.02, $
    psym=2, name='Variable 2', linestyle=3, /over, color=[200,100,0]
display, /over, /legend, legend_title='Legend 3'
display, /over, title='Third DISPLAY', wtitle='THIRD', xtitle='Window 1', ytitle='Window 2'

; Draw a ROI in the THIRD window as shown, to enclose some plonts from the middle part of the plot.

; Now, all three windows contain additional plots corresponding to selected ROI.
; Change color and shape of selected regions. Bring all windows in turn to foreground and type:
display, /over, name='Linked Variable 1', color=[0,0,255], psym=5

Less obvious use of Display is in programs.

Display can be called from inside a widget program as follows:
Display, parent=tlb_ID, oref=display_oref, [OPTIONAL_DATA_AND KEYWORDS]

This establishes a Display panel without resize functionality within the given widget tree. Parent does not have to be a TLB but it must be a base widget. Display_oref returned through the OREF keyword need to be stored in the widget tree State structure. To access Display panel later, use

Display, oref=Display_oref, /OVER, [OPTIONAL_DATA_AND KEYWORDS]

Notice that the programmatic use of Display does not interfere with interactive use of it, i.e. a widget program that accesses its own Display panel through OREF keyword is fully independent from any number of Display windows coexisting in the same IDL session. A DISPLAY that is a child of a base widget will not receive input from the command line, even if clicked on.

DISPLAY can be used effectively to show plots with related labels because TEXT items are positioned in the data space. This way, say, a label marking a feature on the plot will stay with the plot when zooming. It is easy to label plot features programmatically by positioning text using LOCATION keyword.

Some information about how DISPLAY knows about itself. Short answer: use OREF keyword if in doubt!
DISPLAY keeps track of its window by using a PARgrDisplay_top_window common block. This block gets updated in this version at the time when DISPLAY window is created.
To explicitly specify which DISPLAY will receive data, use OREF keyword. This will pass the address of the desired DISPLAY window to any subsequent overplotting operation. Therefore, it is a good idea to always use OREF=OREF keyword if you are including DISPLAY in you code. There is no need to keep track of the OREF variables because DISPLAY is self-contained and on destruction will clean up any object references it creates.

For debugging purposes, OREF keyword can also be used to retrieve the object reference from the window as it is created from the command line. If a window is then destroyed, variable created through OREF will become a null reference. Another way to access the reference(s) is to look in the common block PARgrDisplay_top_window where they are stored in a single variable. References to linked windows are always stored in the common block in the form of object reference array as long as the windows are alive. Reference to the topmost window will always be located in the first element of the reference array. However, a reference to non-linked window will only be in the common block variable if that window is on the top. Once it loses focus to another Display window, its reference is deleted from the common block.

Display uses object graphics, which may be somewhat slower to render than direct graphics applications such as Wplot and Woplot. Speed difference is not noticeable on faster machines of PIII or PowerPC G4 class, especially using OpenGL hardware rendering. Some claim that software rendering is faster on Windows machines, so you may want to try both to find the better performer.

Please send comments to Pavel Romashkin.
April 17, 2014