Equation viewer

The Equation Viewing tool, EQV2, makes it easy to study an equation and see what each parameter in it does. Equation parameters may be varied by moving a slider bar allowing the effects of hundreds of values to be examined in seconds. The equation itself may be modified with the result being instantly displayed. Equation changes and the current parameter settings may be saved in a new equation file and the current plot may be sent to the printer.

In IDL the equation viewer routine, eqv2, may be called with an equation file as an argument:
eqv2,'parabola'
One other keyword argument is allowed: color=clr which sets the curve burn in color (defaults to top color).

The equation file is a simple text file with entries the give the equation to plot, the plot range, and describe the adjustable parameters. The file format is given below. If eqv2 is called with no arguments one option is that it will guide you through the set up of an equation file.

Example: plotting a parabola

Here is a simple example that plots a parabola in the current plot window. Here the last plot was an image with labeled axes (made using the JHU/APL IDL library routine IZOOM). The example image has a parabola embedded in it and is shown with the parabola drawn on it. A simple XY plot covering the desired parabola range would also allow viewing the parabola but the image is a more interesting case.

Below is the EQV2 control widget. A simple function of X, a parabola, is shown in the equation window. The plotted parabola may be moved around on the image by adjusting the equation coeffications using the slider bars.

The control widget consists of several sections.

Equation display and entry area

The current equation is shown in the top text area of the EQV2 widget. The equation may be modified just by deleting or typing text in this area. Press RETURN (ENTER) to see the results of the change.

The Equation File format The equation viewer, EQV2, may be given an initialization file called an equation file. The calling syntax is: eqv2, name where the default extension is .eqv, like gaussian.eqv. So eqv2,'gaussian' is ok. Equation files set up an equation, parameter values, independent variable range, and number of points. Equation files contain 3 types of lines: comment lines, null lines, and keyword/value lines. Comment lines have * in line 1. Null lines have no text. Keyword/value lines have a keyword starting in column 1. The keyword is followed by a colon (:). The value is on the rest of line. Only equation lines may be continued by adding a $ to the end of the each line to be continued. Example equation file: *--------- gaussian.equ = Gaussian curve ----------- * R. Sterner, 25 Oct, 1993 title: Gaussian Curve eq: y = amp*exp(-(x-mu)^2/sigma) xrange: -10, 10 n_points: 100 par: amp -10 10 8 par: mu -10 10 0 par: sigma 0 100 6 All the recognized keywords are listed below in example lines with a discussion on the next line(s). title: Polar Curve # 2. Optional. Used as the widget title. Useful as a reminder. eq: y = a*sin(x/b) The initial equation. It may be continued by ending lines with a $. xrange: 0 10 The independent variable range if x is used. Use only one of xrange or trange. trange: 0 150 The independent variable range if t is used. Intended for parametric equations. Use only one of xrange or trange. n_points: 1000 Number of points in the independent variable range. Defaults to 100. par: a 1.00000 10.0000 3.12625 par: b 1.00000 10.0000 3.68875 Adjustable parameter definition line. Must have 4 items: parameter name, slider bar min, slider bar max, starting value. May have an optional 5th item, the word int which forces the integer value to be returned. Int may be useful as a flag of some sort. There is one parameter line for each adjustable parameter in the equation. Extra parameter lines may be used to define potiential new parameters.

Adjustable parameters

Below the equation display area is the adjustable parameter control panel. Each adjustable parameter in the equation has a set of labeled text entry fields, three buttons, and a slider bar. These are discussed below.

Parameter name: The left-most text entry field for each parameter. It is possible to change the parameter names. To do so first change the name in the equation area but do not press RETURN. Then change the name of the parameter just above it's slider bar and then press RETURN.

Parameter value field: The text entry field to the right of the parameter name. It displays the current value of the parameter. It will be updated as the slider bar is moved. If a new value is entered, press RETURN.

Parameter range fields: these give the min and max values for the slider bar. These values may be changed by typing new values and pressing RETURN (ENTER).

Range Min and Max buttons: these set the range min or max to the current parameter value. They make it easy decrease the range for finer control. To increase the range new values must be typed in the fields.

Default value button: This is the button on the right for each parameter. It resets the value to the entry value which is the default set in the equation file.

Slider bar: the mouse is used to move the slider bar pointer to change the value of the corresponding adjustable parameter.

Note: there may be extra parameters unused in the equation. These may be used to add new adjustable parameters.

Command buttons

On the left of the bottom line are several command buttons:

File
- Quit --- On exit may erase curve, burn it in, or abort exit.
- List --- List the current equation and parameter values.
- Snap --- Save the current equation and parameter settings to a new equation file.
Off --- Toggle plotted curve on or off. Useful for viewing graphics or imagery beneath the plotted curve.
Display
- Bring window to front --- Useful if the window is hidden.
- Refresh plot window --- Not available for maps. Clears away any graphics added after starting EQV2.
- Optional process buttons: If the file xview.txt exists in your home directory it may contain added processing buttons. See the section "Adding functions and printers" for details.
Print --- May contain a list of PS printers. Obtained from the file xview.txt in your home directory. See the section "Adding functions and printers" for details.
Help Various help topics.

The inpendent variable

The independent variable is either X or T. X is normally used for a simple function of one variable, like Y = sin(X) for example. T is normally used for parametric equations, like X=R*cos(T) & Y=R*sin(T). It is not necessary to use the independent variable, you may generate your own using something like FINDGEN or MAKEX, but the independent variable is generated anyway so might as well be used.

The scale factor

A scale factor may be applied to the X values after the equation is executed but before it is plotted. This may in some cases be useful for displaying harmonics. It is normally 1.

Some operational notes

The slider bar range may be reduced quickly using the Min and Max buttons to set new limits. To expand the range the limit values must be typed into the entry area and RETURN pressed.
The current parameter settings are easily saved using the Snap option under the File menu.
Add the imgneg process as described under Adding functions and printers below. Then use it before making a printout to give a black plot on a white background.
A printout will also list the equation and current parameter settings.

Example: Exploring a complicated function

An IDL function may be written to compute a function more complicated than may be entered explicitely in the equation area. The adjustable parameters may be positional or keyword parameters. Here is an example plot.

The plot is made using eXclusive-OR mode (XOR) so if the function falls along the axes over part of the range the axis will disappear. The widget control panel shows how the function may be used inside an equation in the equation area. The function may be directly plotted by dropping the text "exp(-" at the front and ")" at the end and pressing RETURN. Both views are useful and it is easy enough to switch betwen them.

Example: Interactive tools on maps

Using EQV2 and other routines from the JHU/APL IDL library it is easy to build interactive map tools. An example is an adjustable circle on the earth.

This example shows a circle plotted to fit the west coast.

The circle may be moved around on the map by sliding it in latitude and longitude, the radius may be adjusted, and the earth may be reoriented using the sliders to adjust set the central latitude and longitude.

The equation area in this case consists of calls to two IDL routines. The first is a simple routine called globe_plot (shown below) written to plot the earth given the latitude and longitude of the map center. It is almost a call to map_set except it remembers the last map center given and simply returns without doing anything if the map center has not changed. This means it doesn't replot unless it needs too. The map center slider bars can be set by clicking the middle mouse button at about the right spot on the slider instead of dragging with the left button. The second routine called gives the latitude and longitude of a point or points on the earth when given a starting point and a range and bearing. The range is the adjustable parameter r. The bearing is the independent variable t which has been set to go from 0 to 360 in 180 steps. The returned values are called x and y which is what EQV2 wants to plot. An ordinary PLOTS call using longitude and latitude will plot on a map after map_set has set up the projection. This is what eqv2 does internally and explains why the map plot works. Other map projections could have been used just as well. The EQV2 file (shown below) gives the parameter ranges and default values.

*--- globe_plot.eqv = Equation file for Spherical Circle *--- Created on tesla by Sterner on Wed Apr 22 11:21:51 1998 eq: globe_plot, lat, lng & rb2ll,x0,y0,r,/deg,t,x,y title: Globe Plot trange: 0 360 n_points: 180 par: x0 -180 180 -90 par: y0 -90 90 40 par: r 0 180 5 par: lat -90 90 40 par: lng -180 180 -90

;--------------------------------------------------- ; globe_plot.pro = Globe plot routine ; Only plot if globe center point changed. ; R. Sterner, 1998 Apr 22 ;--------------------------------------------------- pro globe_plot, lat, lng common globe_plot_com, lng0, lat0 ; Remember last center. if n_elements(lng0) eq 0 then begin ; Make sure last center defined. lng0 = 0. lat0 = 0. endif if (lng eq lng0) and (lat eq lat0) then return ; No change. map_set,/cont,/iso,/hor,/ortho,lat,lng ; Draw new map. lng0 = lng ; Save new center point. lat0 = lat return end

Adding functions and printers

 The first step is to set up a PostScript printer description file
 so that the routine psinit may be used.  The details are found on
 the web page http://fermi.jhuapl.edu/s1r/idl/s1rlib/psinit/psinit.html

 The next step is to setup some user defined commands.
 The user may define options which are set up
 as buttons at run time.  These options are defined
 in a simple text file called xview.txt in the user's
 home directory.  Currently two types of options are supported,
 print and process.  The setup file has a simple format of one
 line per option:

    type: label text / comand or printer

 type is either the word print or process.
 label text is the text that will appear on the button so
   should not be too long.
 comand or printer can a printer number or substring of the
   printer description given by psinit,/list, or a command to
   be executed if type is process.

 Null lines and lines with * as the first character are ignored.
 An example setup file is


*------  xview.txt = user defined xview commands  ---------
*        R. Sterner, 1997 Oct 1
print: Phaser 340 paper / Paper Color
print: Phaser 340 trans / Transparency Color
process: Negative / imgneg


  The JHU/APL IDL library routines xview.pro and eqv2.pro both
  use the file xview.txt to set up user defined print buttons.
  Note: eqv2.pro adds process options to the dispay menu button.

  The imgneg function is very useful for reversing the
  plot colors before making a printout.  The standard white on black
  is ok for the screen but wastes too much printer toner.