GRIM

General-purpose GRaphical Interface for oMinas.

CATEGORY: NV/GR

CALLING SEQUENCE:

ARGUMENTS:

INPUT:

arg1, arg2:

GRIM accepts up to two arguments, which can appear in either order. Possible arguments are:

data descriptors [object array] file specifications [string array] grn (GRIM window number) [scalar] plot [1d array] image [2d array] cube [3d array]

Plots are displayed as graphs whose abscissa are the array index, unless an abscissa is present in the data descriptor. Many functions are not available in this mode.

Cubes are handled as multiple image planes unless /rgb is used (see below). All GRIM planes will contain the same data array, but display only data ranges corresponding to one channel of the cube. For /rgb (assuming the cube has three channels), the data are placed on a single image plane with each cube channel assigned the R, G, or B color channel.

OUTPUT:

None

KEYWORDS:

INPUT:

Descriptor Keywords

The following inputs replace objects already maintained by GRIM. They must be given as either a single element, which is applied to the current plane, or as an array with one element for each plane.

cd: Replaces the current camera descriptor. This may also be a map descriptor, in which case some of GRIM's functions will not be available. When using a map descriptor instead of a camera descriptor, you can specify a camera descriptor as the observer descriptor (see the 'od' keyword below) and some additional geometry functions will be available.

od: Replaces the current observer descriptor. The observer descriptor is used to allow some geometry objects (limb, terminator) to be computed when using a map descriptor instead of a camera descriptor.

The following inputs replace or augment objects already maintained by GRIM. They are sorted into their respective planes by comparing their internal generic descriptors with the data descriptor or observer descriptor (in the case of a map) for each plane. Objects whose names match those already maintained by GRIM replace them.

ltd: Replaces the current light descriptor.

pd: Adds/replaces planet descriptors.

rd: Adds/replaces ring descriptors.

sd: Adds/replaces star descriptors.

std: Adds/replaces station descriptors

ard: Adds/replaces array descriptors

gd: Generic descriptor containing some or all of the above descriptors.

assoc_xd: If given, use these descriptors to sort descriptors into planes instead of matching the data descriptors or observer descriptors in their internal generic descriptors.

Descriptor Select Keywords

Descriptor select keywords (see pg_get_*) are specified using the standard prefix corresponding to the descriptor type. For example, the fov keyword to pg_get_planets would be given to GRIM as plt_fov. Note that these keywords do not appear in the transator arguments in GRIM's overlay settings tool.

Initial Colormap Keywords

The colormap structure (see colormap_descriptor__define) can be be initialized via keywords prefied with 'cmd_', e.g., 'cmd_shade'. In addition, the following keywords apply to the initial color map:

*auto_stretch: If set, the color table for each plane is automatically stretched. This is identical to using the 'Auto' button on on the GRIM color tool.

Translator Keywords

The following keywords are passed directly to the translators, which are responsible for interpreting their meanings.

*cam_trs: String giving translator keywords for the camera descriptors.

*lgt_trs: String giving translator keywords for the light descriptors.

*plt_trs: String giving translator keywords for the planet descriptors.

*rng_trs: String giving translator keywords for the ring descriptors.

*str_trs: String giving translator keywords for the star descriptors.

*stn_trs: String giving translator keywords for the station descriptors.

*arr_trs: String giving translator keywords for the array descriptors.

TVIM Keywords

The following keywords set the initial viewing parameters and are simply passed to TVIM.

*xsize: Size of the graphics window in the x direction.

*ysize: Size of the graphics window in the y direction.

*zoom: Initial zoom to be applied to the image. If not given, GRIM computes an initial zoom such that the entire image fits on the screen.

*integer_zoom: If set, zoom levels will be rounded to the nearst integer or 1/integer.

*rotate: Initial rotate value to be applied to the image (as in the IDL ROTATE routine). If not given, 0 is assumed.

*order: Initial display order to be applied to the image.

*offset: Initial offset (dx,dy) to be applied to the image.

doffset: Change the offset viewing parameter by this amount.

default: If set, use default tvim properties (zoom=[1,1], offset=[0,0] order=0 [bottom-up])

previous: If set, restore last-used tvim viewing parameters.

restore: If set, use saved tvim viewing paramters.

Customization Keywords

*menu_extensions: Array of strings giving the names of functions that return menu definitions, as defined by cw_pdmenu. These menus are added to the built-in GRIM menus between the Overlays menu and the Help menu. The default is 'grim_default_menus'. If the first character in the first menu function is '+', then grim_default_menus is retained an the new menu are appended after that menu. Otherwise, 'grim_default_menus' is replaced.

*button_extensions: Array of strings giving the names of definition functions for custom cursor modes to be added after the built-in cursor modes. The definition function takes one argument (see arg_extensions below) and returns a grim_user_mode_struct.

*arg_extensions: Argument to be provided to the button extension definition function above.

*menu_fname: Name of a file containing additional menus to add to the GRIM widget. The file syntax follows that for cw_pdmenu.

*arg_menus: Argument to be provided to the menu extension definition function above.

Other Keywords

*extensions: String array giving extensions to try for each input file. see dat_read.

*new: If set, a new GRIM instance is created and all keywords apply to that instance.

erase: If set, erase the current image before doing anything else.

*mode_init: Initial cursor mode. See below.

*mode_args: Array giving arguments for the cursor modes initialization functions. If a string, then syntax is NAME:ARG, where NAME is the name of the cursor mode, and ARG is the argument for that mode. For example:

would cause the function 'myreadout_fn' to be added to the list of functions called by pg_cursor and pg_measure via the readout cursor mode. If not a string, the argument is passed to the initialization function with no processing.

*retain: Retain settings for backing store (see "backing store" in the IDL reference guide). Defaults to 2.

*clip: Controls the number of fields of view in which overlays are computed.

*fov: Controls the number of fields of view in which to request planet, ring and star descriptors. Values are as follows:

0 : get all descriptors <0 : relative to viewport >0 : relative to image / optic axis

Note that fov > 0 is the same as setting the fov descriptor select keywords (see above). Default is 0, but stars operate best when fov > 0.

*hide: If set, overlays are hidden w.r.t shadows and obstructions. Default is on.

no_erase: If set, GRIM does not erase the draw windoww.

no_refresh: If set, GRIM does not refresh.

*rgb: If set, GRIM interprets a 3-plane cube as a 3-channel color image to be displayed on a single plane.

*channel: Array of bitmasks specifying the color channel in which to display each given image: 1b, 2b, or 4b.

*visibility: Initial visibility setting for planes:

0: Only the current plane is drawn. 1: All planes are drawn.

Default is 0.

*max: Maximum data value to scale to when displaying images. Values larger than this are set to the maximum color table index. If not set, the maximum value in the data set is used. In cases where the data array is being subsampled, this value may not be known, resulting in varying image scaling as more and more data values are sampled. That problem may be eliminated via this keyword.

exit: If set, GRIM immediately exits. This can be used to kill an existing GRIM window.

modal: If set, GRIM is run as a modal widget, i.e., there is no command prompt.

*frame:If set, the initial view is set such that all members of the named overlay types are are visible. If /frame, then all overlays are framed. Note that object types that rely on the view to determine which objects to compute (e.g., stars) cannot be framed in this way.

refresh_callbacks: Array of strings giving the names of procedures to be called after each refresh. See CALLBACK PROCEDURES below. Refresh callbacks receive only the data argument.

refresh_callback_data_ps: Array of pointers (one per callback) to data for the refresh callback procedures specified using the refresh_callbacks keyword. See CALLBACK PROCEDURES below.

plane_callbacks: Array of strings giving the names of procedures to be called after each plane change. See CALLBACK PROCEDURES below. Plane callbacks receive only the data argument.

plane_callback_data_ps: Array of pointers (one per callback) to data for the plane callback procedures specified using the plane_callbacks keyword. See CALLBACK PROCEDURES below.

*nhist:History setting to be applied to data decriptor (see ominas_data__define). GRIM uses data descriptor history to undo changes to the data array. If nhist is not set, or is equal to 1, the undo menu option will not function.

*maintain: If given, this maintainance setting is applied to the data descriptor (see ominas_data__define).

*compress: Compression setting to be applied to data decriptor (see ominas_data__define).

*filter: Initial filter to use when loading or browsing files.

*load_path: Initial path for the file loading dialog.

*save_path: Initial path for the file saving dialog.

*path: Sets both load_path and save_path to this value.

*workdir: Default directory for saving user points, masks, tie points, curves

user_psym: Default plotting symbol for user overlays.

grn: Identifies a specific GRIM window by number. GRIM numbers are displayed in the status bar, e.g.: grim <grn>.

tag: Identifies a specific GRIM window by string. GRIM tags are displayed in the status bar in quotes. If no GRIM window exists with this tag, then one is created.

pn: Directs GRIM to change to the plane corresponding to this plane number.

*cursor_swap: If set, cursor bitmaps are byte-order swapped.

*loadct: Index of color table to load.

*beta: If set beta features are enabled.

*npoints: Number of point to compute for various overlays. Default is 1000.

*plane_syncing: Turns plane syncing on (1) or off (0). Default is 0.

*tiepoint_syncing: Turns tiepoint syncing on (1) or off (0). Default is 0.

*curve_syncing: Turns curve syncing on (1) or off (0). Default is 0.

*activation_syncing: Turns activation syncing on (1) or off (0). Default is 0.

*action_syncing: Turns action syncing on (1) or off (0). Default is 0.

position: Sets the plot position; see the POSITION grahics keyword.

color: Sets the line color index for plots. One element per plane.

xrange:Sets the X-axis range for plots.

yrange:Sets the Y-axis range for plots.

thick: Sets the line thickness for plots. One element per plane.

title: For plots, sets the plot title for plots; one element per plane. For images, sets the base default title.

xtitle:Sets the X-axis label for plots. One element per plane.

ytitle:Sets the Y-axis label for plots. One element per plane.

psym: Sets the plotting symbol for plots. One element per plane.

nsum: See OPLOT. One element per plane.

*lights: List of bodies to use as light sources. Default is 'SUN'.

*overlays: List of initial overlays to compute on startup. Each element is of the form:

where 'type' is one of {limb, terminator, center, star, ring, planet_grid, array, station, shadow, reflection} and the names identify the name of the desired object. The keys and vals correspond to fields in the overlay structure and may be used to override the defaults. Note that GRIM will load more objects than named if required by another startup overlay. For example: will cause only one ring descriptor to load, whereas: will cause all of Saturn's rings to load because they are required in computing the limb points (for hiding).

Different results may be obtained using translator keywords, because those keywords are evaluated at the translator level. For example:

may result in no ring, while: would be more likely to yield a ring. In the former example, the specified name is compared against whatever default ring descriptors are returned by the tranlators, while in the latter case, the 'name' translator keyword is compared against all rings available to the translator.

Also note that the ordering is significant. For example:

overlays=['planet_grid:EARTH,MOON', $ 'terminator:MOON', $ 'shadow:MOON']

produces a different result than:

overlays=['terminator:MOON', $ 'shadow:MOON' 'planet_grid:EARTH,MOON']

To override an overlay parameters, use:

overlays=['limb:color=white'] overlays=['limb:jupiter/color=white/psym=1'] etc.

*exclude_overlays: Specifies overlays to exclude. Syntax is the same for the , overlays keyword except keyword=value pairs are ignored. If only a name or names are specified (i.e., no overlay type), then all overlays with that name are excluded. Note that the exclusions are not implemented until after the overlays have been computed, so exclusions do not reduce processing. The, specified exclusions apply for the entire GRIM session.

*delay_overlays: If set, initial overlays (see 'overlays' above) are not computed until the first time they are accessed. This option can greatly improve performance in cases where a large number of image planes are loaded with initial overlays, particularly if it is not expected that all planes will necesarily be viewed or otherwise accessed. Typically this option will cause overlays to be computed only for the initially visible planes, with other planes loading overlays only as they are made visible. However, there may be other cirumstances that can cause initial overlays to be loaded without actually viewing a plane.

*settings_overlays: Structure giving initial overlay settings. Fields are as follows:

name : Name of overlay type. If not present, all types are affected. color : String giving overlay color. shade : Float giving color shade. psym : Plotting symbol. symsize : Symbol size. tlab : Label toggle. tshade : Shading toggle.

*activate: If set, inital overlay are activated.

*ndd: Sets the global ndd value in the OMINAS state structure, which controls the maximum number of data descriptors with maintain == 1 to keep in memory at any given time

*render_sampling: Over-sampling value for rendering.

*render_numbra: Number of random rays to trace to light sources when rendering.

*render_minimum: Minimum value (percent) to assign to photometric output in renderings.

*render_rgb: If set, renderings are done in color if the source has color color planes. Default is off.

*render_current: If set, the rendering source is the image on this plane rather a map. Default is off.

*render_spawn: If set, renderings from an image (as opposed to a rendering) are placed on a new plane. Default is on, except for rendering planes.

*render_sky: If set, the sky is included in the rendering. Default is off.

*render_auto: If set, automatically render whenever there is an object event. Default is off, though note that rendering planes always automatically re-render.

*rendering: If set, perform a rendering on the initial descriptor set.

*guideline: If set, the guideline is turned on at startup.

OUTPUT:

None

GRIM Resource File

The keywords marked above with an asterisk may be overridden using the file $HOME/.ominas/grimrc. Keyword=value pairs may be entered, one per line, using the same syntax as if the keyword were entered on the IDL command line to invoke GRIM. Lines beginning with '#' are ignored. Keywords entered in the resource file override the default values, and are themselves overridden by keywords entered on the command line.

Shell Interface

The grim alias may be used to start GRIM from the shell prompt. The shell interface accepts all keywords marked with an asterisk above. See grim.bat.

Example:

GRIM currently defines no environment variables..

Environment Variables

Common Blocks

grim_block: Keeps track of most recent GRIM instance and which ones are selected.

Side Effects

GRIM operates directly on the memory images of the descriptors that it is given. Therefore, those descriptors are modified during a session. This architecture allows data to be operated on concurrently through GRIM and from the command line; see grift.pro for details.

Layout

The philosphy that drives GRIM's layout is that the maximum possible screen space should be devoted to displaying the data. This policy allows for many GRIM windows to be used simultaneously without being obscured by crazy control panels full of buttons, gadgets, widgets, doodads, whirly-gigs, and what-nots. The GRIM layout consists of the following items:

Title bar

The title bar displays the GRIM window number (grn), the tag (if any), the current plane number (pn), the total number of planes, the core name field of the data descriptor for the current plane, the default title (if given; see the title keyword above), and a string indicating which RGB channels are associated with the current plane.

Menu bar

Most of GRIM's functionality is accessed through the system of pulldown menus at the top. Individual menu items are described in their own sections.

Shortcut buttons

Some commonly used menu options are duplicated as shortcut buttons arranged horizontally just beneath the menu bar. The function of each button is displayed in the status bar (see below) when the mouse cursor is hovered over the button.

Cursor mode buttons

Cursor mode shortcut buttons are arranged vertically along the left side of the GRIM window, and are provided as shortcuts for the corresponding options in the Mode menu. The following modes are available:

Activate: In activate mode, overlay objects may be activated or deactivated by clicking and/or dragging using the left or right mouse buttons respectively. This activation mechanism allows the user to select which among a certain type of objects should be used in a given menu selection. A left click on an overlay activates that overlay and a right click deactivates it. A double click activates or deactivates all overlays associated with a given descriptor, or all stars. Active overlays appear in the colors selected in the 'Overlay Settings' menu selection. Inactive overlays appear in gray. A descriptor is active whenever any of its overlays are active.

Zoom:The zoom button puts GRIM in a zoom cursor mode, wherein the image zoom and offset are controlled by selecting a box in the image. When the box is created using the left mouse button, zoom and offset are changed so that the contents of the box best fill the current graphics window. When the right button is used, the contents of the current graphics window are shrunken so as to best fill the box. In other words, the left button zooms in and the right button zooms out.

Pan: The pan button puts GRIM in a pan cursor mode, wherein the image offset is controlled by selecting an offset vector using the left mouse button. The middle button may be used to center the image on a selected point.

Pixel Readout: In pixel readout mode, a text window appears and displays data about the pixel selected using the left mouse button.

Tiepoint: In tiepoint mode, tiepoints are added using the left mouse button and deleted using the right button. Tiepoints appear as crosses identified by numbers. The use of tiepoints is determined by the particular option selected by the user.

Curve: In curve mode, curves are added using the left mouse button and deleted using the right button. Curves appear as red lines identified by numbers at each end. The use of curves is determined by the particular option selected by the user.

Mask: GRIM maintains a mask for each plane whose use is appication-dependent. Mask mode allows pixels in the mask to be toggled on and off.

Magnify: In magnify mode, image pixels in the graphics window may be magnifed using either the right or left mouse buttons. The left button magnifies the displayed pixels, directly from the graphics window. The right button magnifies the data itself, without the overlays.

XY Zoom: Same as 'zoom' above, except the aspect ratio is set by the proportions of the selected box.

Remove overlays: Allows the user to remove overlay arrays.

Trim overlays: Allows the user to trim points from overlay arrays.

Select within overlays: Allows the user to select points within overlay arrays.

Define Region: Allows the user to define GRIM's region of interest.

Smooth: Allows the user to select a smoothing box to be applied to the data array.

Select Plane: Allows the user to change planes using the pointer. This option is only useful in cases where multiple planes are displayed.

Drag Image: Allows the user to reposition the current plane by clicking and dragging.

Target: Allows the user to re-target the camera by clicking.

Navigate: Allows the user to modify the camera position and orientation using the mouse.

Graphics window

The graphics window displays the data associated with the given data descriptor using the current zoom, offset, and display order. The edges of the data are indicated by a dotted line. The camera optic axis is indicated by a large red cross.

Pixel readout

The cursor position and corresponding data value are are displayed beneath the graphics window, next to the message line.

Message line

The message line displays short messages pertaining GRIM's current state or button functions.

Callback Procedures

GRIM callback procedures are called with one or two arguments: the first argument is a pointer to data that was provided when the callback was added. The second argument, if present, depends on the applicatation.

X Resource Names

The following X-windows resource names apply to GRIM's widgets:

To turn off the confusing higlight box around the modes buttons, put the following line in your ~/.Xdefaults file: Shortcut buttons also have resource names that may be used to define keyboard shortcuts (search grim.pro file for "resource_name=" to find the names for each button.

Each menu option has a corresponding resource name given by its event procedure name; see grim_menu_desc in grim.pro and grim_default_menus in grim_default_menus.pro.

Default definitios may be found in .ominas/Xdefaults-grim.

Operation

GRIM displays 1-, 2-, and 3-dimensional data sets. 1-dimensional data arrays are displayed as plots. In that case, the abscissa is the sample number unless the data descriptor contains an abscissa. Some functionality is not available when working with plots. 2- and 3-dimensional arrays are displaye as image planes. The only difference between images and cubes in GRIM is that images planes each have their own data descriptor, while cubes are represented by multiple image planes that share a common data descriptor; each plane in a cube corresponds to a unique offset in the data array stored in the common data descriptor.

GRIM requests only the data samples needed for the current viewing parameters. Therefore, GRIM can display data sets of arbitrary size when used with a file reader that supports subsampling. However, note that specific menu options may request the entire data array, depending on the application.

Each GRIM instance may contain any number of planes as well as associated geometric data (i.e. object descriptors) and overlay arrays for displaying various geometric objects -- limbs, rings, stars, etc. An array of user overlay points is maintained to be used for application- specific purposes. Generally, a set of overlay points or a descriptor must be activated in order to be used as input to a menu item; see activate mode above.

There are exclusive and non-exclusive mechanisms for selecting GRIM windows. GRIM windows may be non-exclusively selected using the select mode button mentioned above (upper-left corner). The exclusive selection mechanism consists of a "primary" GRIM window, indicated by a red outline in the graphics window. The primary selection is changed by pressing any mode or shortcut button, or by clicking in the graphics area of the desired GRIM window. The meaning of the various selections depends on the application.

The functions of the left and right mouse buttons are determined by the cursor mode; some cursor modes define modifier keys to broaden the number of functions available in that mode. The middle mouse button toggles the activation state of overlay arrays, or allows the image to be panned if no overlay appears beneath the cursor. The mouse wheel cycles among cursor modes, or zooms about the cursor position if the control key is held down.

Objects maintained by GRIM are accessible via the GRIFT interface, for example:

returns the data desciptor, camera descriptor, planet descriptors, and limb points associated with the current plane.

GRIM registers event handlers for all of its objects, so the window is updated any time an object is modifed, whether by GRIM or by some other program, or from the command line.

(1) To create a new GRIM instance with no data:

(2) To create a new GRIM instance with data from a file of name "filename": IDL> grim, filename

(3) To give an existing GRIM instance a new camera descriptor:

Window resizing is not precise. GRIM tries to resize to the selected size, but typically overshoots. This is probably platform-dependent.

Known bugs

Objects inherited by rendering planes do not respond to events.

Image shifting: - Descriptors not updated if shift performed form another window because the there's no way for the irst window to know to update its descriptors - fix wrap-around; clip instead

Plane->Coregister does not update descriptors

Navigate mode gets weird when you do certain modifer key presses --> maybe a conflict with <ctrl> wheel zoom action

Crashes occur with File->Close

/no_erase is not enabled for images, just plots. Probably should fix that.

Initial visibility setting does not seem to work until applied using plane settings window.

/frame causes a crash if there are no initial overlays.

It's not clear whether the symsize keyword is actually used.

pn keyword does not function.

Crash when tiepoint syncing is on and tiepoint selected with multiple planes.

Title keyword does not properly map multiple elements to multiple planes.

Nsum keyword does not properly map multiple elements to multiple planes.

Plane syncing appears to be incomplete and I don't remember what it was supposed to be. I'm sure it was awesome, though.

Not sure what slave_overlays keyword does, or was supposed to do.

Overlays on rendered planes do not respond to events

Menu toggles don't update propoerly in some circumsumstances.

grim_message sometimes pops up messages from nv_message, which can be pretty obnxious. This probably has to do with the calls to grim_message in grim_compute.include

Overlay point selections are not retained after recomputing

Undo does not seem to be working reliably

Events on overlays copied to rendering planes do not function

The help menu is currently not working because it relied on the old documentation system.

Navigation mode control is poor for the Shift-Right motion.

Target mode flips the camera orientation in the X direction.

File-> Save Postscript doesn't work right: the image order is sometimes wrong, and the overlays don't line up.

Stars are not always correctly computed for wider fields of view.

SEE ALSO

GRIFT, GRAFT