diff options
| author | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
|---|---|---|
| committer | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
| commit | fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 (patch) | |
| tree | bdda434976bc09c864f2e4fa6f16ba1952b1e555 /vendor/x11iraf/Notes-V1.3.html | |
| download | iraf-linux-fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4.tar.gz | |
Initial commit
Diffstat (limited to 'vendor/x11iraf/Notes-V1.3.html')
| -rw-r--r-- | vendor/x11iraf/Notes-V1.3.html | 1841 |
1 files changed, 1841 insertions, 0 deletions
diff --git a/vendor/x11iraf/Notes-V1.3.html b/vendor/x11iraf/Notes-V1.3.html new file mode 100644 index 00000000..810a1efe --- /dev/null +++ b/vendor/x11iraf/Notes-V1.3.html @@ -0,0 +1,1841 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE></TITLE> +<META NAME="generator" CONTENT="txt2html v1.28"> +</HEAD> +<BODY BGCOLOR=#FFFFFF> + +<br><br> +<center> +<H1><A NAME="section-1">X11IRAF V1.3 REVISIONS NOTES</A></H1> +<i><font size=-1>Last Modified: Mon Feb 4 16:33:02 MST 2002 +</i></font> +</center> + +<br><br> +<HR NOSHADE=3> +<center><b><font size=+1>Table of Contents:</b></font></center> +<HR NOSHADE=3> + +<ul> +<PRE> + 1. <a href="#sec-1">Installation Changes</a> + + 2. <a href="#sec-2">XImtool Revisions</a> + 2.1 <a href="#sec-2.1">Real-Time WCS/pixel Readout</a> + 2.2 <a href="#sec-2.2">"Peak-up" Cursor Centroid Positioning</a> + 2.2.1 <a href="#sec-2.2.1">Command Summary</a> + 2.2.2 <a href="#sec-2.2.2">Resource Summary</a> + 2.3 <a href="#sec-2.3">Auto-Registration of Images</a> + 2.3.1 <a href="#sec-2.3.1">Command Summary</a> + 2.4 <a href="#sec-2.4">Integrated Control Panel</a> + 2.4.1 <a href="#sec-2.4.1">Load Panel Changes</a> + 2.4.2 <a href="#sec-2.4.2">Info Panel Changes</a> + 2.4.3 <a href="#sec-2.4.3">Tile Panel (NEW)</a> + 2.4.4 <a href="#sec-2.4.4">Coords Panel (NEW)</a> + 2.5 <a href="#sec-2.5">Support for 16 Display Frames</a> + 2.6 <a href="#sec-2.6">Magnifier</a> + 2.7 <a href="#sec-2.7">Freezing Cursor Readout</a> + 2.8 <a href="#sec-2.8">Cut-Graphs</a> + 2.9 <a href="#sec-2.9">Ruler Markers</a> + 2.10 <a href="#sec-2.10">Summary of Cursor Commands</a> + 2.11 <a href="#sec-2.11">Summary of Application Resources</a> + 2.12 <a href="#sec-2.12">Summary of Command-Line Options</a> + + 3. <a href="#sec-3">OBM (Widget Server) Revisions</a> + 3.1 <a href="#sec-3.1">New Toolkit Widgets</a> + 3.1.1 <a href="#sec-3.1.1">Tabs Widget</a> + 3.1.2 <a href="#sec-3.1.2">ListTree Widget</a> + 3.2 <a href="#sec-3.2">Dynamic Widget Creation</a> + + 4. <a href="#sec-4">Client Display Library (CDL) Revisions</a> + 4.1 <a href="#sec-4.1">Display Protocol Changes</a> + 4.2 <a href="#sec-4.2">New Procedures</a> + 4.2.1 <a href="#sec-4.2.1">C Calling Sequence</a> + 4.2.2 <a href="#sec-4.2.2">F77 Calling Sequence</a> + 4.2.3 <a href="#sec-4.2.3">SPP Calling Sequence</a> + 4.3 <a href="#sec-4.3">Demo Task Updates</a> + + 5. <a href="#sec-5">Technical Notes</a> + 5.1 <a href="#sec-5.1">IIS Protocol Changes</a> + 5.1.1 <a href="#sec-5.1.1">IIS Protocol Summary</a> + 5.2 <a href="#sec-5.2">IRAF 'imd' Interface Changes</a> + 5.2.1 <a href="#sec-5.2.1">Program Initialization</a> + 5.2.2 <a href="#sec-5.2.2">WCS Text Changes</a> + 5.2.3 <a href="#sec-5.2.3">Cursor Reads</a> + 5.3 <a href="#sec-5.3">ISM Communications</a> + 5.3.1 <a href="#sec-5.3.1">Socket Connection</a> + 5.3.2 <a href="#sec-5.3.2">Communications Protocol</a> + 5.3.3 <a href="#sec-5.3.3">GUI Objects</a> +</PRE> +</ul> + + +<br><br><br> +<A NAME="sec-1"></a> +<HR NOSHADE=3> +<font size=+2><b>1. INSTALLATION CHANGES</b></font> +<HR NOSHADE=3> + +<P> + A new script automatically unpacks the distribution and installs +files in the system (or user's directories for a private install), provides +error checking and user interaction to skip parts of the process or change +defaults. The 'install' script is packaged with both source and binary +distribution files. To install for general use in the system directories +the script must be run as root user, it may be run by any user to install +to private directories. + +<P> +To install from an unpacked source distribution: + +<PRE> + % <tt><b>xmkmf</tt></b> <i>build the package Makefile</i> + % <tt><b>make World</tt></b> <i>build binaries from sources</i> + % <tt><b>su</tt></b> <i>become the root user</i> + # <tt><b>./install</tt></b> <i>install the files (interactive)</i> +</PRE> + +<P> +Only the last two commands are required to install from an unpacked binary +distribution. + + +<br><br><br> +<A NAME="sec-2"></a> +<HR NOSHADE=3> +<font size=+2><b>2. XIMTOOL REVISIONS</b></font> +<HR NOSHADE=3> + +<P> + Aside from general bug fixes most of the changes in this release +are all new features for XImtool. Details on individual features are +explained below, but in summary: + +<UL><UL> + <LI>real-time cursor image WCS and actual pixel readout + <LI>new cursor centroiding function + <LI>ability to "auto-register" frames + <LI>integrated/enhanced control panel + <LI>support for up to 16 display frames + <LI>improved support for image tiling + <LI>a "compass" indicator for the display orientation + <LI>pixel table readout + <LI>image header display (keyword selection, WCS display) + <LI>horizontal/vertical cut-graphs of the display + <LI>ruler markers on the display + <LI>control port for external process communications +</UL></UL> + +<P> + The most significant change in this version is the ability to +access the displayed image pixels or header data to produce the real-pixel +and WCS readouts. This is done using an external process called an ISM +(Image Support Module) which communicates with ximtool as a "plug-in" +module to enhance the features of the core program. In this case the ISM +is written as an IRAF task (although any application that can send text +over a socket can be used as an ISM regardless of the language/environment) +run at the host level with the ability to access any supported image format. +Any number of such ISM plug-ins can be developed to provide e.g. catalog +overlay, animation, and so on. + +<P> + For the WCS/pixel ISM to operate properly changes to the display +protocol were required to pass the needed information. These changes are all +backwards compatible with "older" display servers however for the ISM to +work at all you will need to be running at least IRAF V2.12. Updates to +external packages using image display (notably MSCRED) have already been +completed. Details of the changes required are found in the technical notes +at the end of this document. + +<P> + Users should feel free to contact IRAF site support (iraf@noao.edu) +with any questions. + + +<br><br><br> +<A NAME="sec-2.1"></a> +<HR NOSHADE=3> +<font size=+1><b><A NAME="sec-2.1"> +2.1 Real-Time WCS/pixel Readout +</A></font></b> + +<P> + <b>XImtool</b> now has the ability to display the actual pixel value +of an image (as well as the scaled value previously shown) and the cursor +position in image WCS values (e.g. RA/DEC, GLAT/GLONG, etc). This is done +using an external task (the 'ism_wcspix.e' binary in the new distribution) +to access the image and pass the coordinate/pixel information to the GUI. +<P> + WCS readout is enabled by default but can be toggled or reset +using the '<tt><b>WCS/Pix</tt></b>' button on the <tt><b>Coords</b></tt> tab +in the control panel or the "<tt><b>ISM</b></tt>" toggle on the <i>alt-gui</i> +menubar. When enabled, images currently in the server or subsequently +displayed will be passed to the external process where they are cached for +access. Cursor movements generate an event that maps the current frame buffer +position to a position in the cached image. The <b>ISM</b> (ISM is <i>Image +Support Module</i>) task then reads the image to determine the pixel value +(or a small table of values around the current position), and computes one +or more coordinates from the image position. The ISM task also has access +to the associated BPM images and can optionally return bad pixel information +during the cursor readout. +<P> + By default, the logical and world image coordinates are displayed +to both the <tt><b>Coords</b></tt> panel readout as well as the main display +window wcsbox text marker. Alternate coordinate systems (e.g. transformation +of equatorial to galactic coordinates or some other sky system, physical +coords, amplifier coords, etc) can be selected for display by hitting the +"<tt><b>Options</b></tt>" toggle on the <tt><b>Coords</b></tt> panel. +Available coordinate systems are chosen using the "<tt><b>Type</b></tt>" +menu on the panel, the readout format (sexigesimal, degrees, etc) using +the "<tt><b>Format</b></tt>" menu, and the display to the current panel or +main image window using the remaining toggles for each WCS. Up to four +systems may be displayed at one time, the coordinate panel and wcsbox marker +will adjust size automatically depending on the display. + +<P> + By selecting the "<tt><b>BPM Data</b></tt>" toggle from the +<tt><b>Coords.Options</b></tt> panel ximtool is able to flag pixels in images +with an associated bad pixel mask. This bad pixel mask is currently assumed +to be named in the image header "<i>BPM</i>" keyword by convention. If the +cursor passes over a bad pixel in the mask, the <tt><b>Coords</b></tt> bpm +display as well as the main window wcsbox will change to a red background +color. Only the <tt><b>Coords</b></tt> display will show the value, any +non-zero value will be flagged with the color change. + +<P> + With the <b>ISM</b> enabled the <tt><b>Compass</b></tt> indicator +will display a set of arrows showing North-East if a WCS is available, +otherwise just the current X-Y axes are shown. The pixel table will display +actual pixel values from the image, with the <b>ISM</b> off the pixel table +displays the scaled image values from the frame buffer. + + +<br><br><br> +<A NAME="sec-2.2"></a> +<HR NOSHADE=3> +<font size=+2><b> 2.2 "Peak-up" Cursor Centroid Positioning </A></font></b> + +<P> + Several new keystroke commands are available to reposition the +cursor to a centroid or min/max pixel value within a bounding box of the +cursor position, allowing you to approximate the position with the mouse +and fine tune it quickly before typing an application keystroke command. +The initial box size is controlled with a '<tt><b>centerBoxSize</b></tt>' +GUI resource (<i>defaults to 5 pixels</i>) but can be adjusted interactively +using the <tt><b>Ctrl-[</b></tt> and <tt><b>Ctrl-]</b></tt> commands to +descrease andincrease the box size respectively. A marker will flash briefly +to indicate the new box size. +<P> + The <tt><b>Ctrl-0</b></tt> (zero) key finds either a centroid or +the local maximum pixel value within this box region, <tt><b>Alt-Ctrl-0</b></tt> +(zero) will find the local minimum value. In either case the cursor is +reposition to the computed value. The default peak-up action is to find +the centroid position in the box however this can be changed to find the +max pixel by selection the "<tt><b>Centroid Peaks</b></tt>" option from +the main <tt><b>Display</b></tt> control panel or by resetting the +"<tt><b>peakCentroid</b></tt>" GUI resource (defaults to <i>True</i>). + +<P> + Centroiding is done using only the scaled screen pixel values and +only pixels above the mean value within the box are used. It works best +if the box size is set appropriately, the centroid position may appear to +drift if the box is too large and includes too many background pixels. + +<p> + +<br> +<font size=+1><b><A NAME="sec-2.2.1">2.2.1 Command Summary:</A></b></font> + +<PRE> + <tt><b>Ctrl-0</b></tt> (zero) <i>Reposition to centroid/max-pixel</i> + <tt><b>Alt-Ctrl-0</b></tt> (zero) <i>Reposition to min-pixel</i> + <tt><b>Ctrl-[</b></tt> <i>Decrease centering box size (min of 5)</i> + <tt><b>Ctrl-]</b></tt> <i>Increase centering box size</i> +</PRE> +<p> + +<br> +<font size=+1><b><A NAME="sec-2.2.2">2.2.2 Resource Summary:</A></b></font> + +<PRE> + <tt><b>peakCentroid</b></tt> True <i>Compute the box centroid position, a + 'False' value force the max value to be used</i> + <tt><b>centerBoxSize</b></tt> 5 <i>Size of the centroid box, used as cursor + position +/- this value</i> +</PRE> + + + +<br><br><br> +<A NAME="sec-2.3"></a> +<HR NOSHADE=3> +<font size=+2><b> 2.3 Auto-Registration of Images </A></font></b> + + +<P> + The <b>auto-register</b> feature allows you specify a registration of +two or more display frames with an offset. When enabled, this registration +is maintained for all frames in the list if any one of them is panned or +zoomed to a new location in the frame buffer. The list of frames to be +registered is maintained in the <tt><b>Display</b></tt> panel. + +<P> +For example, to use this feature do the following: + +<OL> + <LI>Enable <tt><b>Auto-Register</b></tt> (either on the + <tt><b>Display</b></tt> panel or the toolbar on the <i>alt-gui</i>) + and pan/zoom to some star of interest. + <LI>Use <tt><b>Mouse-Button-2</b></tt> to center the star in the frame. + <LI>Cycle through the frames and you may see a small shift + of the star. For each frame, position the cursor on the + star and type <tt><b>Ctrl-o</b></tt> to offset it to the center. + Repeat as necessary. Small corrections will be cumulatively added + so you can use the <tt><b>Ctrl-0</b></tt> peak-up command to + centroid each object in the frame before the <tt><b>Ctrl-o</b></tt> + offset. + <LI>Pan around the image in one display frame, then switch frames + and the new frame should also be panned to the new image with + the proper offset. + <LI>A <tt><b>Ctrl-a</b></tt> command will toggle the feature, offsets are + only allowed when <i>Auto-Register</i> is enabled. +</OL> + +<P> + Hitting "<tt><b>Register</b></tt>" will zero the offsets, as will +toggling the auto-register function. What you should see is the object +centered in the frame and as you blink through it remains registered but +the panner box marker is moving around. Drag the panner around and all +frames still remain registered with the given offset. The control/info +panels also now display what the offset is for each frame. + +<P> + The register display list is shared with the blink list and can +be set using the <tt><b>Display</b></tt> control panel. By default all +frames are included in the list. For accessing more than four frames, use +the box icon in the <tt><b>Blink/Register</b></tt> box of the +<tt><b>Display</b></tt> control panel to bring up a new window with access +to all 16 available frames. + +<br><br><br> +<b><font size=+1><A NAME="sec-2.3.1">2.3.1 Command Summary:</A></b></font> + +<PRE> + <tt><b>Ctrl-o</b></tt> <i>set the offset from center</i> + <tt><b>Ctrl-a</b></tt> <i>toggle the Auto-register feature</i> +</PRE> + + + +<br><br><br> +<A NAME="sec-2.4"></a> +<HR NOSHADE=3> +<font size=+1><b>2.4 Integrated Control Panel</A></font></b> + +<P> + The separate windows previous used for Control/Print/Load/Save/etc +have now been integrated into a single window with the appropriate control +panel selectable with a <tt><b>Tab</b></tt> widget. There are also new Tab +panels for setting the frame tile configuration (see below), more detailed +information on the server status, and selecting the WCS readout options +(see above). + +<P> + All panels were updated as part of the integration, however some +changes of note to each panels include: + +<UL> + <LI>Display + <UL> + <LI> View box + <UL> + <LI> supports 16 frames + <LI> Frame offset added to readout + </UL> + <LI> Blink/Register + <UL> + <LI> new box icon button brings up independent control panel w/ + access to all 16 frames + </UL> + <LI> Options + <UL> + <LI> addition of "Magnifier" and "Centroid Peaks" options + </UL> + </UL> + <LI>Print + <UL> + <LI> Postscript Options + <UL> + <LI> added B5 paper size as option + </UL> + </UL> + <LI>Load + <UL> + <LI> Complete redesign of panel (see below) + <LI> New options group (see below) + <LI> Filename filter accepts a comma-delimited list of templates + </UL> + <LI>Save + <UL> + <LI> EPS added a save format, saves image w/ no annotation + </UL> + <LI>Info + <UL> + <LI> Complete redesign of panel (see below) + </UL> + <LI>Tile + <UL> + <LI> New panel allowing configuration of tile frame layout (see below) + </UL> + <LI>Coords + <UL> + <LI> New panel allowing selection of WCS readout options (see below) + </UL> +</UL> + + +<br><br><br> +<A NAME="sec-2.4.1"></a> +<HR NOSHADE=3> +<font size=+1><b>2.4.1 Load Panel Changes </A></font></b> + + +<P> + The <tt><b>Load</b></tt> panel was redesigned to make directory +navigation easier as well as to provide new features. The file list box +is now larger and implemented using a more natural directory listing format. +The filename filter box can now accept a comma-delimited list of templates +providing multiple matches to e.g. "*.fits" and "*.imh" images in the same +listing. Sub-directories are always listed in the output. + +<P> +A new options group was added to the panel with the following features: + +<P> + +<UL> +<DL> + <DT><b>Auto Load</b> + <dd> + If enabled, selecting an image name from the list will force it + to the display automatically. Otherwise the Load button at the + bottom of the panel must be used to load the image. Specifying + a filename in the "Load File" text box will load that image either + with a CR or using the panel Load button. +<P> + <DT><b>Auto Grayscale</b> + <dd> + If enabled, color images (e.g. GIF) are converted to grayscale + automatically, otherwise a private colormap is loaded for the image. +<P> + <DT><b>List Image Headers</b> + <dd> + If enabled the file list will change to display only the matching + image names along with the pixel size, image size, and optional + title string. Directory navigation is disabled until this option + is turned off. MEF FITS files will be listed with the number + of extensions they contain but cannot be loaded. +<P> + <DT><b>Frame</b> + <dd> + Select the frame in which to display the image. The special + value "Current" is used to display to whichever is the current + display frame, otherwise any of 16 available frames may be selected. +<P> + <DT><b>Zscale Options</b> + <dd> + The remaining options can be used to specify the z-scale parameters + used when loading the image. The algorithm works as follows: + <PRE> + if (zscale enabled) + determine optiminal z1/z2 given 'Nsample' points + else if (zrange enabled) + use image min/max as z1/z2 + else + use panel z1/z2 values + </PRE> + <p> + To load 8-bit data directly the 'zscale' option should be disabled. +</DL> +</UL> + + +<br><br><br> +<A NAME="sec-2.4.2"></a> +<HR NOSHADE=3> +<font size=+1><b>2.4.2 Info Panel Changes </A></font></b> + +<P> + The Info panel was revised to provide a greater variety of status +information. The type of output is controlled by the toggle buttons on +the bottom of the frame, however all output is kept current as the program +runs. Current info options include: + +<UL><DL> + <DT><b>Frame</b> + <dd>Info about the current display frame + <DT><b>Server</b> + <dd>Info about various server options, e.g. colormaps, + memory model, antialias type, etc. + <DT><b>Clients</b> + <dd>Show currently connected clients. Lists available + connection channels and active ISM clients. + <DT><b>WCS</b> + <dd>List all WCS and mappings for the current frame + <DT><b>ISM</b> + <dd>Log of various ISM status messages + <DT><b>Imtoolrc</b> + <dd>Show current frame buffer configuration table +</DL></UL> + + +<br><br><br> +<A NAME="sec-2.4.3"></a> +<HR NOSHADE=3> +<font size=+1><b>2.4.3 Tile Panel (NEW) </A></font></b> + +<P> + With the additional frames in this release, the default tiling +scheme proved inadequate. A new control panel <tt><b>Tile</b></tt> frame +now allows you to select from a number of tile configurations, the list of +frames to be tiled, a "fill style" (left-to-right or top-to-bottom), as +well as optional labels for each of the tiles (frame number, image title +or image name). +<P> +Tile configuration will make use of all frames currently selected in the +"Tile Frame" group in the following manner: + +<UL><DL> + <DT><b>Disabled</b> + <dd>Do not tile the display + <DT><b>Manual</b> + <dd>Tile according to "Manual Configuration" settings + <DT><b>Best</b> + <dd>Optimize layout for frame buffer aspect + <DT><b>Square</b> + <dd>Always force a square layout (2x2, 3x3, etc) + <DT><b>Horizontal</b> + <dd>Preferentially tile horizontally (6 frames ==> 3x2) + <DT><b>Vertical</b> + <dd>Preferentially tile vertically (6 frames ==> 2x3) + <DT><b>One Row</b> + <dd>Tile all in one row (Nx1) + <DT><b>One Column</b> + <dd>Tile all in one column (1xN) +</DL></UL> + + +<br><br><br> +<A NAME="sec-2.4.4"></a> +<HR NOSHADE=3> +<font size=+1><b>2.4.4 Coords Panel (NEW) </A></font></b> + +<P> + The Coords Panel is meant to provide a full-featured readout as +well as serve as a control panel for the various options. The display +window contains the image name/title and frame buffer info, and a selection +of coordinate and image pixel readouts. The intent is provide more information +than can fit comfortably on the main image window while still +taking up as little screen space as possible. To this end the "Options" +button is used to hide most of the feature controls when not in use (see +below). Other options on the main panel include: + +<UL><DL> + <DT><b>WCS/Pix</b> + <dd>Toggle the real-time WCS/pixel readout capability + (i.e. the ISM used to access the disk image). This + must be enabled for certain other options to work. + + <DT><b>Pix Table</b> + <dd>Open a panel showing an image pixel table. The panel + shows an array of pixels surrounding the cursor position, + either the actual pixel values if the ISM is enabled, or + scaled display values otherwise. The size of the table + may be selected from the menubar. + + <DT><b>Header</b> + <dd>Display the current image header in a new panel. Both + the entire image header as well as WCS-specific parts of + the header are available under different tabs. This + option is only active when the ISM is enabled. + + <DT><b>Compass</b> + <dd>Draw an orientation compass on the display panner. If + the ISM is enabled and a WCS is present in the header, + the compass will indicate N/E according to the WCS, other- + wise the X/Y axes of the image are drawn. + + <DT><b>Options</b> + <dd>Pop-up/down the option control portion of the panel. When + enabled, the Coords Panel will change size to reveal the + options which can be changed (explained below). +</DL></UL> + + The "<tt><b>Readout Values</b></tt>" group controls the selection +of WCS type, location and format to be displayed. The "<tt><b>Type</b></tt>" +menu always provides a selection of the image <i>Logical</i>, <i>Physical</i> +or <i>World</i> systems, which may be identical depending on the image +header. If a <b>World</b> system is supplied in the image addition entries +for transformations to other sky systems, (e.g. FK5 to ICRS or +galactic/ecliptic) will also be available. The selection is dependent on +whether the <tt><b>ISM</b></tt> is running as well as WCS information +present in the image. The "<tt><b>Format</b></tt>" menu allows the use to +select a sexigeimal display, conversion to degrees or radians, or whichever +format is most natural for the coordinate being display. The two toggles +to the right control whether this WCS is to be displayed on the +<tt><b>Panel</b></tt> (i.e. the <tt><b>Coords Panel</b></tt> window) or +the <tt><b>ImgWin</b></tt> (i.e. the text marker on the main image window). +<P> + Other options below this group control whether or not to display the +WCS labels, the image name/title, and frame buffer information in the main +<tt><b>Coords Panel</b></tt> display. The "<tt><b>BPM Data</b></tt>" option +controls whether or not the <b>ISM</b> will try to map any bad-pixel mask +associated with the image. If enabled, a bad-pixel mask specified by the +image header <i>BPM keyword</i> (currently fixed by convention but this may +be selectable later) will be mapped along with the image. Aside from +wcs/pixel readouts at each cursor position, any BPM data values found will +also be displayed. A non-zero value will cause the BPM field of the +<tt><b>Coords Panel</b></tt> readout as well as the main image window marker +to switch to a red background color to flag the value. +<P> + The last box allows the user to specify a different <b>ISM</b> task +to be executed or to reinitialize the current one. In most cases this +won't need to be changed, however a custom <b>ISM</b> could be started when +using special data formats. This command string can also be controlled by +the application "<tt><b>ism_task</b></tt>" resource. + + + +<br><br><br> +<A NAME="sec-2.5"></a> +<HR NOSHADE=3> +<font size=+1><b>2.5 Support for 16 Display Frames </A></font></b> + +<P> + As part of the extensive GUI changes, support for the full 16 +frames allowed by the current IIS protocol is now available. IRAF V2.12 or +later client tasks (and CDL library) are required to take advantage of +these frames. All changes are backwards compatible, older versions of IRAF +will continue to work but cannot access more than the original four +frames. The new <tt><b>DISPLAY</b></tt> task will automatically sense +whether the display server being used supports 16 frames or the original +4 and adjust the '<i>frame</i>' parameter maximum accordingly. The changes +are fully backwards compatible for other servers (e.g. <i>SAOimage</i>, +<i>DS9</i>, etc). +<P> + More frames are possible if needed but will require further changes +to the client IRAF code to be effective. Allowing creation of more than +16 frames by the <tt><b>Load</b></tt> panel can be done independently but +would also require numerous code change to <b>XImtool</b>. Please contact +site support (iraf@noao.edu) if there is a need for this, or for workaround +suggestions depending on your application. + + + +<br><br><br> +<A NAME="sec-2.6"></a> +<HR NOSHADE=3> +<font size=+1><b>2.6 Magnifier</A></font></b> + +<P> + The magnifier marker appears to be stable and was moved into the +default ximtool GUI and is now enabled by default. The ximtool-mag command +has been removed. + + +<br><br><br> +<A NAME="sec-2.7"></a> +<HR NOSHADE=3> +<font size=+1><b>2.7 Freezing Cursor Readout</A></font></b> + +<P> + Holding down the <tt><b>Alt</b></tt> key will now freeze the cursor +display readout and draw crosshairs on the screen at the last position. +This can be used for example to position the cursor but then allow the cursor +to be moved to another window (to enter text, start a program, whatever) +without losing the position information displayed on the screen. + + +<br><br><br> +<A NAME="sec-2.8"></a> +<HR NOSHADE=3> +<font size=+1><b>2.8 Cut-Graphs</A></font></b> + +<P> + XImtool now has the ability to display horizontal and vertical +cut-graphs of the display, these appear as "flip-out" panels that appear +on the bottom and right side of the main display window and are controlled +by the small "<tt><b>H</b></tt>" and "<tt><b>V</b></tt>" buttons in the lower +right corner of the window. When both panels are enabled the corner area +of the display also shows an options panel for the graphs. +Current options include: + +<UL><DL> + <dt><b>Better Speed</b> + <dd>Draw the graphics so they update at the fastest + possible rate. This is done by subsampling pixels + to produce a smoother graph but without sacrificing + too much accuracy. + + <dt><b>Better Accuracy</b> + <dd>Draw the graphics using all screen pixels to produce + the most accurate display. On fast modern machines + this can be enabled with no apparent loss of speed, + however older machines may wish to use this only + occassionally to limit any lag in the cursor tracking. + + <dt><b>Image Pixels</b> + <dd><i>(Not Yet Implemented)</i> + + + <dt><b>Jump Cursor</b> + <dd>If enabled, large jumps of the cursor do not update + the graphics display, small movements around an object + of interest will update the display continuously. + + <dt><b>Smooth Cursor</b> + <dd>If enabled, all cursor movements cause the display to + be updated. This is another option that can be set + safely on faster machines but will cause a delay on + slower ones. + + <dt><b>Graphics Cursors</b> + <dd>If enabled, the graphics cursors in either of the + plots are active and can be used to update the cursor + readout on the main image window and the complementary + cut-graph. This can be used for example to freeze + the cursor in the main display using the Alt key (see + above), then moving to one of the graphics windows + to perform cut graphs in only one axis. +</DL></UL> + +<P> + Graphs are (currently) drawn using only the scaled display values +to avoid complications of accessing multiple images in a mosaic display. Both +plots are labeled using the frame z1/z2 values and contain cursor indicators +which update contuously. + + + +<br><br><br> +<A NAME="sec-2.9"></a> +<HR NOSHADE=3> +<font size=+1><b>2.9 Ruler Markers</A></font></b> + +<P> + Holding down the <tt><b>Ctrl</b></tt> key and the +<tt><b>Left-Mouse-Button</b></tt> while moving the mouse will drag out +a "<i>ruler marker</i>" measuring the distance from the initial point to +the current mouse position. Releasing the <tt><b>Ctrl</b></tt> key before +lifting the mouse button will leave the marker on the display, otherwise +it will be erased automatically once the mouse button is released. Any +number of ruler markers can be created in the frame. +<P> + Distances are measured by default in image logical pixels however +the <tt><b>Right-Mouse-Button</b></tt> can be used inside the marker to +popup a menu of options: + +<UL><DL> + <dt><b>Sticky</b> + <dd>By default rulers are destroyed whenever the display + changes due to a pan, zoom, flip, or frame change. + This option will make the ruler "sticky" so it will + not be erased, subsequent use of the menu to shows + this option to be "UnSticky" to remove this feature. + + <dt><b>Units</b> + <dd>Sub-menu to select the units of the display. If the + ISM is enabled and a WCS is present in the image and + selected as one of the readout options, distances may + also be read out in units of arcseconds, arcminutes, + or degrees instead of the default logical pixels. All + markers created after the unit change will readout in + the new units as their default. + + <dt><b>Color</b> + <dd>Select the color of the marker. + + <dt><b>Draw into Frame</b> + <dd><i>(Not Yet Implemented)</i> Draw the marker as overlay + graphics in the frame. Doing so will retain the + marker when printing a hardcopy of the display. + + <dt><b>Destroy</b> + <dd>Destroy the marker. +</DL></UL> + +<P> +The marker can also be destroyed by hitting the <tt><b>Delete</b></tt> +or <tt><b>Backspace</b></tt> key while the cursor is in the marker. There +is presently no way to move the marker to a new position in the frame. + + +<br><br><br> +<A NAME="sec-2.10"></a> +<HR NOSHADE=3> +<font size=+1><b>2.10 Summary of Cursor Commands </A></font></b> + +<PRE> + <b>*</b> - <i>indicates a new/changed command</i> +</PRE> + +</UL> +<b><font size=+1><A NAME="sec-2.10.1"><u>Misc Functions</u></A></b></font> +<PRE> + <b>Ctrl-b</b> <i>Backward frame</i> + <b>Ctrl-c</b> <i>Center frame</i> + <b>Ctrl-f</b> <i>Forward frame</i> + <b>Ctrl-i</b> <i>Invert</i> + <b>Ctrl-n</b> <i>Normalize</i> +* <b>Ctrl-m</b> <i>Toggle Magnifier</i> +* <b>Ctrl-p</b> <i>Toggle Panner</i> + <b>Ctrl-r</b> <i>Register</i> +* <b>Ctrl-s</b> <i>Match LUTs</i> + <b>Ctrl-t</b> <i>Tile frames toggle</i> + <b>Ctrl-u</b> <i>Unzoom (zoom=1)</i> + <b>Ctrl-x</b> <i>Flip X</i> + <b>Ctrl-y</b> <i>Flip Y</i> + <b>Ctrl-=</b> <i>Print</i> + <b>Ctrl-<</b> <i>Decrease blink rate</i> + <b>Ctrl-></b> <i>Increase blink rate</i> + <b>Ctrl-+</b> <i>Zoom in</i> + <b>Ctrl--</b> <i>Zoom out</i> + + <b>Alt-1</b> thru <b>Alt-4</b> <i>Set frame displayed</i> + <b>Ctrl-1</b> thru <b>Ctrl-9</b> <i>Set integer zoom factor</i> + + <b>Ctrl-Alt-q</b> <i>Quit</i> + <b>Ctrl-Alt-f</b> <i>Fitframe</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.2"><u>Panels</u></A></b></font> +<PRE> + <b>Alt-b</b> <i>Blink frames toggle</i> + <b>Alt-c</b> <i>Control panel</i> + <b>Alt-h</b> <i>Help panel</i> + <b>Alt-i</b> <i>Info box panel</i> + <b>Alt-l</b> <i>Load file panel</i> + <b>Alt-p</b> <i>Print panel</i> + <b>Alt-s</b> <i>Save panel</i> + <b>Alt-t</b> <i>Tcl Shell panel</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.3"><u>Auto-Registration</u></A></b></font> +<PRE> +* <b>Ctrl-a</b> <i>Toggle Auto-Reg</i> +* <b>Ctrl-o</b> <i>Set offset</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.4"><u>Cursor Positioning</u></A></b></font> +<PRE> +* <b>Ctrl-h/Left_Arrow</b> <i>move cursor 1 pixel left</i> +* <b>Ctrl-j/Down_Arrow</b> <i>move cursor 1 pixel down</i> +* <b>Ctrl-k/Up_Arrorw</b> <i>move cursor 1 pixel up</i> +* <b>Ctrl-l/Right_Arrow</b> <i>move cursor 1 pixel right</i> + +* <b>Shift-Ctrl-h</b> <i>move cursor 10 pixels left</i> +* <b>Shift-Left</b> <i>move cursor 10 pixels left</i> +* <b>Shift-Ctrl-j</b> <i>move cursor 10 pixels down</i> +* <b>Shift-Down</b> <i>move cursor 10 pixels down</i> +* <b>Shift-Ctrl-k</b> <i>move cursor 10 pixels up</i> +* <b>Shift-Up</b> <i>move cursor 10 pixels up</i> +* <b>Shift-Ctrl-l</b> <i>move cursor 10 pixels right</i> +* <b>Shift-Right</b> <i>move cursor 10 pixels right</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.5"><u>Frame Positioning</u></A></b></font> +<PRE> + <b>Ctrl-Left</b> <i>shift one full frame left</i> + <b>Ctrl-Down</b> <i>shift one full frame down</i> + <b>Ctrl-Up</b> <i>shift one full frame up</i> + <b>Ctrl-Right</b> <i>shift one full frame right</i> + + <b>Ctrl-Alt-Left</b> <i>shift one half frame left</i> + <b>Ctrl-Alt-Down</b> <i>shift one half frame down</i> + <b>Ctrl-Alt-Up</b> <i>shift one half frame up</i> + <b>Ctrl-Alt-Right</b> <i>shift one half frame right</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.6"><u>Peak-Up Centroiding</u></A></b></font> +<PRE> +* <b>Ctrl-[</b> <i>decrease centering box size</i> +* <b>Ctrl-]</b> <i>inrease centering box size</i> +* <b>Ctrl-0</b> (zero) <i>centroid/find local max</i> +* <b>Alt-Ctrl-0</b> (zero) <i>find local min</i> +</PRE> + +<b><font size=+1><A NAME="sec-2.10.7"><u>Mouse Button Actions</u></A></b></font> +<PRE> + <b>Shift-Btn1Down</b> <i>turn on magnifier</i> + <b>Shift-Btn1Up</b> <i>turn off magnifier</i> + <b>Shift-Btn2Down</b> <i>turn on crosshair cursor</i> + <b>Shift-Btn2Up</b> <i>turn off crosshair cursor</i> + <b>Btn1Down</b> <i>create marker</i> + <b>Btn1Motion</b> <i>resize marker being created</i> + <b>Btn2Down</b> <i>zoom on cursor position</i> + <b>Btn3Down/Motion</b> <i>brightness/contrast scaling</i> + +* <b>Ctrl-Btn1Down</b> <i>create ruler marker</i> +* <b>Ctrl-Btn1Motion</b> <i>resize ruler marker</i> +* <b>Ctrl-Btn1Up</b> <i>destroy ruler marker</i> + +* <b>Alt-Motion</b> <i>freeze cursor readout</i> +</PRE> + + +<br><br><br> +<A NAME="sec-2.11"></a> +<HR NOSHADE=3> +<font size=+1><b>2.11 Summary of Application Resources </A></font></b> + +<P> + Following is a summary of the task client and GUI resources, along +with select resources defined for the main image display Gterm widget. All +GUI elements can be controlled to some exten with resource definitions +although not all resources are useful. Feel free to contact site-support +(iraf@noao.edu) with questions about how to change the appearance of the GUI. +Future versions of XImtool should feature a control panel to allow some of +these more critical resources to be redefined at runtime. +<P> + Format for the listing is resource-name, default-value, and type, +with an optional note appended. See the man page or online help for a full +description of all resources. A '*' in the leftmost column indicates a new +resource added with this release, some resource apply only to the alternative +<STRONG>GUI.</STRONG> + + +<b><font size=+1><A NAME="sec-2.11.1"><u>Client Program Resources</u></A></b></font> +<PRE> + defConfig 1 Int + defNFrames 0 Int + tileBorderWidth 3 Int + tileBorderColor 9 Int + autoscale False Boolean + antialias False Boolean + antialiasType boxcar String (1) + tileFrames False Boolean + highlightFrames True Boolean + gui default String (2) + imtoolrc /usr/local/lib/imtoolrc String + invert False Boolean + memModel Fast String (3) + basePixel 64 Int + maxColors 216 Int + cmapInitialize False Boolean + cmap1 none String (4) + cmap2 none String (4) + cmapDir1 none String (5) + cmapDir2 /usr/local/lib/imtoolcmap String (5) + input_fifo /dev/imt1i String (6) + output_fifo /dev/imt1o String (6) + unixaddr /tmp/.IMT%d String (7) +* ism_addr /tmp/.ISM%d String (8) +* ism_task "ism_wcspix.e wcspix &" String (9) +</PRE> + +<P> + <b>Notes:</b> +<OL> + <LI>Options: nearest, bilinear, area, blkavg, boxcar, lowpass, gaussian + <LI>Either the string 'default' or the path to a valid GUI file + <LI>Options: fast, small, beNiceToServer + <LI>Name of a colormap file in the cmapDir[1|2] directory + <LI>Path to directory of valid colormaps + <LI>Path to FIFO pipe + <LI>Unix socket path, a '%d' is replaced with the uid + <LI>Unix socket path, a '%d' is replaced with the uid. This is the + socket used by plug-ins to negotiate a socket, once connected the + actual communications use a different socket. + <LI>Command used to start the default WCS/Pixel readout ISM task. +</OL> + +<br><br> +<b><font size=+1><A NAME="sec-2.12.2"><u>GUI Resources</u></A></b></font> +<PRE> + autoscale True Boolean + zoomfactors 1 2 4 8 String + displayCoords True Boolean + displayPanner True Boolean + displayMagnifier False Boolean + blinkRate 1.0 Real (1) + pannerArea 150*150 Geometry + pannerGeom -5+5 Geometry +* magnifierArea 100*100 Geometry +* magnifierGeom +5+5 Geometry + wcsboxGeom -5-5 Geometry + maxContrast 5.0 Real +* showToolBar False Boolean +* showPanelBar False Boolean + warnings True Boolean +* centerBoxSize 5 Int +* peakCentroid True Boolean +</PRE> + +<P> + <b>Notes:</b> +<OL> + <LI>Value represents blink rate in seconds +</OL> + + +<br><br> +<b><font size=+1><A NAME="sec-2.12.3"><u>Main Image Window (Gterm) Resources</u></A></b></font> +<PRE> + cmapName image String (1) + basePixel 64 Int + warpCursor True Boolean + raiseWindow True Boolean + deiconifyWindow True Boolean + ginmodeCursor circle Cursor + ginmodeBlinkInterval 500 Int (2) + color0 Black Pixel + color1 White Pixel + background Black Pixel + foreground White Pixel + width 512 Int + height 512 Int +</PRE> + +<P> + <b>Notes:</b> +<OL> + <LI>Any user-defined name is acceptable + <LI>Value represents blink rate in milliseconds +</OL> + + +<br><br><br> +<A NAME="sec-2.1"></a> +<HR NOSHADE=3> +<font size=+1><b>2.12 Summary of Command-Line Options </font></b> + +<PRE> + -basePixel <num> Base colormap pixel + -cmap1 <file> User colormap 1 + -cmap2 <file> User colormap 2 + -cmapDir1 <dir> User colormap directory + -cmapDir2 <dir> Default colormap directory + -cmapInitialize <bool> initialize colormap + -cmapName <name> Set Colormap name + -config <num> Set initial config number + -defgui Print default GUI and exit + -displayPanner <bool> Display Panner box + -displayMagnifier <bool> Display Magnifier box + -displayCoords <bool> Display WCS Coords box + -fifo <pipe> Fifo pipe to use for connection + -fifo_only Use fifo only for display + -gui <file> GUI file + -help Print help + -imtoolrc <file> Set frame buffer configuration file + -inet_only | -port_only Use inet only for display + -invert Start with inverted colormap + -ismdev <dev> ISM device (socket) template + -maxColors <num> Max number of image colors to allocate + -memModel <type> Memory model (fast|small|beNiceToServer) + -nframes <num> Number of frames to create at startup + -port <num> Set inet port to use for connection + -printConfig <name> Set printer config file + -tile Start in tile-frames mode + -unix <name> Set unix socket to use for connection + -unix_only Use only unix socket for display + <file> File to load at startup +</PRE> + + + +<br><br><br> +<A NAME="sec-3"></a> +<HR NOSHADE=3> +<font size=+2><b>3. OBM (WIDGET SERVER) REVISIONS</font></b> +<HR NOSHADE=3> + + +<br><br><br> +<b><font size=+1><A NAME="sec-3.1.1">3.1 New Widgets</A></b></font> + +<P> + As part of the <b>OBM</b> modifications two new widgets were added +to the toolkit. The widgets were also added to the <b>LISTRES</b> +application in the <b>X11IRAF</b> sources which can be consulted for a +complete list of resources. LISTRES is not normally built with the system +but is installed locally on the NOAO/IRAF development machines. To build +it yourself: + +<PRE> + % <b><tt>cd /<path>/x11iraf/obm/listres</tt></b> <i># go to the source directory</i> + % <b><tt>xmkmf</tt></b> <i># create the Makefile</i> + % <b><tt>make listres</tt></b> <i># compile the task</i> +</PRE> + +<P> +It may then be used as e.g. "<tt><b>listres</b></tt> <<i>widget</i>>" to print a full list of +resources for the named widget. + + +<br><br><br> +<A NAME="sec-3.1.1"></a> +<HR NOSHADE=3> +<font size=+1><b>3.1.1 Tabs Widget</font></b> + +<P> + The <tt><b>Tabs</b></tt> widget is a composite widget providing an +"index tab" appearance to it's child widgets. The children will normally +be layouts of more complex panels such as is done for the <b>XImtool +Control Panel</b>. Only the children of the active Tab are visible, the +contents of other Tabs are not displayed until that Tab is raised by +selecting it with the mouse and the left mouse button. +<P> + A new Widget class command was added to allow GUI control of the +active Tab (e.g. to programmatically raise a Tab). This command is of +the form + +<PRE> + <tt><b>send</b></tt> <<i>tab</i>> <tt><b>setTop</b></tt> <<i>name</i>> +</PRE> + +<P> +where <<i>tab</i>> is the name of the Tab widget, +and <<i>name</i>> is the name of the child widget to be raised. +Only one Tab widget is required to handle child widgets, the Tabs will be +created automatically. +<P> + The widget code was also modified slightly to allow specific +resource values to hide the appearance of the widget from the display, e.g. +to completely change the appearance of a panel's layout by invisibly raising +a different Tab. For instance, assuming we have a Tab widget called +'<i>opPanels</i>' with several child widgets containing layouts of other +widgets, the following resource settings will hide the parent Tabs widget: +<P> +<PRE> + *opPanels.tabLabel: + *opPanels.font: nil2 + *opPanels.height: 0 + *opPanels.width: 0 + *opPanels.borderWidth: 65535 + *opPanels.internalWidth: 32765 + *opPanels.internalHeight: 32765 +</PRE> + +<P> +Essentially we set NULL labels and sizes and values for the borderWidth +and internalHeight/Width that have the same bit pattern as a negative value +which internally means the borders are not drawn. The GUI callback code +can then use the setTop Widget method to raise the desired Tab meaning the +entire panel will change layouts automatically. This has advantages over +simply unmapping/mapping the layouts as it doesn't create a window resize +event which may cause the panel to "flash" during the change. +<P> + An example GUI for this widget is in <b>x11iraf$guidemo/tabs.gui</b> + + +<br><br><br> +<A NAME="sec-3.1.2"></a> +<HR NOSHADE=3> +<font size=+1><b>3.1.2 ListTree Widget</font></b> + +<P> + The <tt><b>ListTree</b></tt> widget provides a nested list of items, +where each item is either a terminal item in a list, or another list. Lists +may be "open" meaning their contents are displayed, or "closed" meaning +they are shown as an individual item. This widget can best be used to +represent e.g. contents of a directory or sections/subsections of a document. + +<P> + A new Widget class command was added to allow GUI control of the +list contents. This command is of the form +<P> +<PRE> + <tt><b>send</b></tt> <<i>listree</i>> <tt><b>setListTree</b></tt> <<i>nested list</i>> +</PRE> + +<P> +where <<i>listree</i>> is the name of the widget, +and <<i>nested list</i>> is a list of +items to be displayed. This list should be a valid Tcl list, where items +in the list may be lists themselves to produce the nested format. All +<b>ListTree</b> widget are initially presented with the embedded lists +"closed". There is presently no way to append the contents of the list, +the entire list must be redefined with the above command. For example, +the command +<P> +<PRE> + <tt><b>send list setListTree {a1 {b1 { {a2 {a3 b3 c3 d3}} { b2 {z1 z2}} } } c1}</b></tt> +</PRE> +<P> +would produce a nested list such as + +<PRE> + a1 + b1 + a2 + a3 + b3 + b2 + c1 +</PRE> + +<P> +Specifying the lists is a bit complex, but this widget is a nice way to +handle something like a table of contents in online documentation. + +<P> + An example GUI for this widget is in <b>x11iraf$guidemo/ltree.gui</b> + + +<br><br><br> +<A NAME="sec-3.2"></a> +<HR NOSHADE=3> +<font size=+1><b>3.2 Dynamic Widget Creation</font></b> + +<P> + In the original implementation of the OBM, the GUI is created or +defined using the '<b><i>appInitialize</i></b>' and +'<b><i>createObjects</i></b>' server commands. <b><i>appInitialize</i></b> +initializes the X display but the '<i>resources</i>' argument just sets the +fallback resources for the application. A '<b><i>createObjects</i></b>' call +then queries the fallback resource database (either by a named resource o +the 'objects' resource by default) to get the widget tree and then parses +that as a string to actually create the widgets in the OBM. +<P> + The initial example GUIs all defined an "<i>objects</i>" resource +as the way to define the widgets and all the subsequent GUI tasks followed +that form, however <i>appInitialize</i> requires only a string of resource +definitions ('object' resources or otherwise), and <i>createObjects</i> +can take an argument as to which resource value specifies the widgets to +create. For dynamic widget creation all that's really required is that we +have a way to append the fallback resource database with a new list of widgets. +<P> + The solution then was implement a new '<tt><b>appExtend</b></tt>' +server command that simply sends a new resource string to the OBM to be +merged into the fallback resource database. A plug-in would call this to +load the widgets, then call <tt><b>createObjects</b></tt> naming the resource +to realize the widgets. The new widgets are created as though they were +specified from the start and can receive messages, be destroyed, etc. +The <tt><b>appExtend</b></tt> server method essentially works by + +<OL> + <LI>getting the fallback resource database + <LI>convert resource string arg to a new resource database + <LI>combine the two resource databases + <LI>write the combined database back as the new fallback database +</OL> + +<P> +For example, the plug-in code for a "Hello, World" GUI panel would look +something like + +<PRE> + appExtend { + *test_objects:\ + toplevel TopLevelShell testPanel\ + testPanel Form testForm\ + testForm Label testLabel\ + testForm Command testQuit + + *testLabel.label: Hello, world! + *testQuit.fromHoriz: testLabel + *testQuit.label: Quit + } + createObjects test_objects + send testPanel map +</PRE> + +<P> +This code could be uploaded by an ISM plug-in and sourced as Tcl code +in a callback. It's also possible to define objects w/ existing parents +meaning a plug-in can add buttons to menubars or panels when they first +connect (e.g. a plug-in can add a new activation button for it to an +existing menubar on the GUI). +<P> + The ability to dynamically create widgets means that plug-in modules +can create their own GUI components, but it also means that meta-widgets such +as Help panels, Image Display panels, etc can be recycled from a library of +code. To use this effectively, however, some rules need to be established +for an object naming convention, protocols for adding/deleting callbacks and +event handlers, and some method of object orientation is desired in the Tcl +code to make having multiple instances of a meta-widget in a GUI easier to +handle. These details are still largely TBD, the basic functionality now +exists in this version but may change as we take advantage of it and +implement new plug-in tasks or meta-widgets. + + +<HR> + +<br><br><br> +<A NAME="sec-4"></a> +<HR NOSHADE=3> +<font size=+2><b>4. CLIENT DISPLAY LIBRARY (CDL) REVISIONS </font></b> +<HR NOSHADE=3> + + +<br><br><br> +<b><font size=+1><A NAME="sec-4.1">4.1 Display Protocol Changes</b></font> + +<P> + The IIS display protocol used was modified to conform to the XImtool +and IRAF changes implemented for the support of WCS mapping information. +These are detailed in <a href="#sec-5.1">section 5.1</a> below. +<P> + Unlike the IRAF IMD interface changes though, the WCS version can +be determined when the CDL is first opened so no explicit call to query +this is required by CDL applications. Tasks may still set/retrieve mapping +information and assume this is handled automatically by the interface. +The hi-level routines for displaying FITS or IRAF images will also send the +mapping information automatically, it's only when using the low-level +cdl_displayPix() routine or setting the WCS explicitly where the mappings +need to be set by the application. + +<P> + Changes remain completely backwards compatible so client tasks need +to be modified only to support the new XImtool features. + + +<br><br><br> +<A NAME="sec-4.2"></a> +<HR NOSHADE=3> +<font size=+1><b>4.2 New Procedures</font></b> + +<P> + Three new public interface procedures were added in addition to the +internal changes made to support image mappings: + +<UL><DL> + <dt><b>cdl_setMapping()</b></dt> + <dd>Set mapping data to be sent with next <b>cdl_setWCS</b>() call.<br> + Returns a non-zero status if mapping was set.</dd> +<P> + <dt><b>cdl_getMapping()</b></dt> + <dd>Get mapping data returned with last <b>cdl_getWCS</b>() call.<br> + Returns a non-zero status if valid mapping available</dd> +<P> + <dt><b>cdl_queryMap()</b></dt> + <dd>Given a WCS number return the mapping data for that WCS.<br> + Returns a non-zero status if valid mapping available.</dd> +<P> +</DL></UL> + + +<br><br><br> +<A NAME="sec-4.2.1"></a> +<HR NOSHADE=3> +<font size=+1><b>4.2.1 C Calling Sequence</font></b> + +<P> +<PRE> + valid = cdl_setMapping (cdl, region, sx,sy,snx,sny, dx,dy,dnx,dny, ref) + stat = cdl_getMapping (cdl, region, sx,sy,snx,sny, dx,dy,dnx,dny, ref) +stat = cdl_queryMapping (cdl, wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref) +</PRE> + +<P> +Where the arguments are defined as + +<PRE> + cdl - CDL package pointer returned by cdl_open() + region - user-defined name for the region (e.g. 'image', + 'subras1', 'ccd3', etc). + sx, sy, snx, sny - source rect in the object + dx, dy, dnx, dny - destinaton rect in the display frame buffer + ref - full node!/path/image[sec] image name, same as + was immap'd when the image was displayed. Used + for access after the display + wcs - WCS number for a specified mapping +</PRE> + + + +<br><br><br> +<A NAME="sec-4.2.2"></a> +<HR NOSHADE=3> +<font size=+1><b>4.2.2 F77 Calling Sequence</font></b> + +<PRE> + cfsetmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cfgetmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cfquerymapping (wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref, ier) +</PRE> + +<P> +Where the arguments are defined <a href="#sec-4.2.1">as above</a> +and 'ier' is an error status code. + + +<br><br><br> +<A NAME="sec-4.2.3"></a> +<HR NOSHADE=3> +<font size=+1><b>4.2.3 SPP Calling Sequence</font></b> + +<PRE> + cdl_setMapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cdl_getMapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, ref, ier) + cdl_queryMapping (wcs, region, sx,sy,snx,sny, dx,dy,dnx,dny, objref, ier) +</PRE> + +<P> +Where the arguments are defined <a href="#sec-4.2.1">as above</a> +and 'ier' is an error status code. + + +<br><br><br> +<A NAME="sec-4.3"></a> +<HR NOSHADE=3> +<font size=+1><b>4.3 Demo Task Updates</font></b> + +<UL> + <LI>The DISPLAY demo task in the 'examples' subdirectory was modified + to show how the <b>cdl_setMappings()</b> call is to be used when + displaying the image using the low-level procedures. + + <LI>The CDLTEST test task in the 'test' subdirectory has a new 'Q' + command to test the <b>cdl_queryMap()</b> procedure. +</UL> + + +<HR> +<br><br><br> +<A NAME="sec-5"></a> +<HR NOSHADE=3> +<font size=+1><b>5. TECHNICAL NOTES</A></font></b> +<HR NOSHADE=3> + +<br><br><br> +<b><font size=+1><A NAME="sec-5.1">5.1 IIS Protocol Changes</A></b></font> + +<P> + For backwards compatability none of the existing IIS protocols were +modified completely, however we take advantage of unused registers to flag +the new features in existing functions (like read/write WCS). The WCS mapping +changes required only that the unused '<b>x</b>' register be set to indicate +the new behavior was desired, e.g. the wcs text containing the extra mapping +data. +<P> + We also added two new WCS calls that allow us to query the WCS version, +or query a WCS by a specific number corresponding to a mapping. The WCS +version query will return a string such as "version=10" which can be parsed +by the client to get a version number '10' (corresponding to version 1.0). +<P> + Because of the added mapping text the WCS string length was increased +from 320 to 1024 bytes, the string length used internally depends on whether +the '<b>x</b>' register has been set. +<P> + Support for the full 16 frames allowed by the bit-flag '<b>z</b>' +register in the IIS header packet required the masking values be changed at +various places in the code. This was more a limitation of the initial +implementation than a required change to the protocol. +<P> + A complete summary of the XImtool IIS protocol implementation follows. + + +<br><br><br> +<A NAME="sec-5.1.1"></a> +<HR NOSHADE=3> +<font size=+1><b>5.1.1 IIS Protocol Summary</font></b> + +<P> +<PRE> + <b>IIS Header Packet Summary</b> + + TID Subunit Tct X Y Z T Data + +------------------+-------------+-----+---+---+----+---+--------+ +Read Data | IIS_READ|PACKED | MEMORY | -NB | x | y | fr | - | nbytes | +Write Data | IIS_WRITE|PACKED | MEMORY | -NB | x | y | fr | - | nbytes | +Read Cursor | IIS_READ | IMCURSOR | - | - | - | wcs| - | - | +Write Cursor | IIS_WRITE | IMCURSOR | - | x | y | wcs| - | - | +Set Frame | IIS_WRITE | LUT|COMMAND | -1 | - | - | - | - | 2 | +Erase Frame | IIS_WRITE | fb | FEEDBACK | - | - | - | fr | - | - | + | | | | | | | | | +Old Read WCS | IIS_READ | WCS | - | - | - | fr | - | 320 | +Old Write WCS | IIS_WRITE|PACKED | WCS | -N | - | - | fr |fb | 320 | + | | | | | | | | | +WCS Version? | IIS_READ | WCS | - | 1 | 1 | - | - | 320 | +WCS by Num.? | IIS_READ | WCS | - | 1 | - | fr |wcs| 1024 | +New Read WCS | IIS_READ | WCS | - | 1 | - | fr | - | 1024 | +New Write WCS | IIS_WRITE|PACKED | WCS | -N | 1 | - | fr |fb | 1024 | + +------------------+-------------+-----+---+---+----+---+--------+ +</PRE> + + +<P> +Where +<PRE> + nbytes | NB = number of bytes expected or written + x = x position of operation in frame buffer coords + y = y position of operation in frame buffer coords + fr = frame number (passed as bitflag (i.e. 1, 2 ,4 8, etc) + fb = frame buffer config number (zero indexed) + N = length of WCS string + wcs = WCS number (usually zero) + Data = the number of bytes of data to be read or written + following the header packet. + + IIS_WRITE = 0400000 + IIS_READ = 0100000 + COMMAND = 0100000 + PACKED = 0040000 + IMC_SAMPLE = 0040000 + + MEMORY = 001 + LUT = 002 + FEEDBACK = 005 + IMCURSOR = 020 + WCS = 021 +</PRE> + + + +<br><br><br> +<A NAME="sec-5.2"></a> +<HR NOSHADE=3> +<font size=+1><b>5.2 IRAF 'imd' Interface Changes.</font></b> + +<P> + In order for the XImtool ISM task map exactly the same image that +was passed into the task displaying the image (i.e. the fully qualified +node!path prefix including any image section or kernel args). It was +necessary to modify the IIS <b>SetWCS</b> command to contain extra information +at the end of the normal WCS text. This is passed from XImtool to the ISM +at the time of the display if an ISM is already running, or when the ISM +first connects thereafter. + +<P> + To maintain complete backwards compatability it is not possible to +bury this change in the internals of the interface, therefore it will be +necessary for all tasks using the IMD interface to display images to make +revisions to use the new features. Tasks which are not changed will continue +to work, XImtool will simply disable the ISM when the display client connects +without indicating it is able to pass mapping information. Client tasks, +modified or not, will also continue to work when connecting to "mapping +unaware" display servers since the interface only send the extra mapping +information to servers which are expecting it. + +<P> + To modify a task to make use these changes, there are just a few +routines you need to be aware of: + +<P> +<PRE> + <b>imd_wcsver()</b> - Query the server for new capabilities. Returns a + non-zero version if the server can use the new + mapping functionality. + +<b>imd_setmapping()</b> - Set mapping data to be sent with next imd_putwcs() call + +<b>imd_getmapping()</b> - Get mapping data returned with last imd_getwcs() call. + returns a non-zero status if valid mapping available + + <b>imd_query_map()</b> - Given a WCS number return the mapping data. Returns a + non-zero status if valid mapping available +</PRE> + +<P> +where the calling sequence is + +<pre> + <b>imd_setmapping</b><tt> (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)</tt> + valid = <b>md_getmapping</b><tt> (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)</tt> + status = <b>md_query_map</b><tt> (wcs, reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)</tt> + version = <b>md_wcsver</b><tt> ()</tt> +</pre> + +<P> +In order to maintain compatability with existing servers as well as take +advantage of the new ximtool features, the idea is that all interfaces will +remain the same and any program wishing to use these features will need a +slight modification to 1) determine whether mappings are supported via a +call to imd_wcsver(), and 2) use the new <b>imd_[sg]etmapping</b>() +procedures to set and retrieve the mapping information. <b>imd_query_map</b>() +can be used to query for the mapping using the wcs number returned from +e.g. a cursor read. Details and examples of these modifications are +included below. + + +<br><br><br> +<A NAME="sec-5.2.1"></a> +<HR NOSHADE=3> +<font size=+1><b>5.2.1 Program Initialization</b></font> + +<P> + For a program to use mappings it must first query the server to see +if this is supported, the reply also serves to initialize the imd interface. +This is done using the <b>imd_wcsver</b>() call. For example, in the DISPLAY +task during startup one would do something like + +<PRE> + # Query server to get the WCS version, this also tells us whether + # we can use the all 16 supported frames. + if (imd_wcsver() == 0) + call clputi ("display.frame.p_max", 4) + else + call clputi ("display.frame.p_max", 16) +</PRE> + +<P> +The call to <b>imd_wcsver</b>() in this case is used to reset the number of +allowed frames depending on the server capabilities. + +<P> + This call is <b>REQUIRED</b> before mappings can be used by the +interface. Internally, the interface defaults to a "version" of zero +meaning the server does not support mappings, once the procedure is called +the server reply value is stored in the interface common and returned as +the function value. The return value is always an integer, zero means the +server does not support mappings and a non-zero value is the WCS version +number of the display change (e.g. a value of 10 is version 1.0, 11 is 1.1, +etc). +<P> + A '<tt><b>disable_wcs_maps</b></tt>' boolean environment variable +can be set by the user to force this procedure to always return zero and +disable mappings in case a problem is found after release or the old behavior +is desired. + + +<br><br><br> +<A NAME="sec-5.2.2"></a> +<HR NOSHADE=3> +<font size=+1><b>5.2.2 WCS Text Changes</b></font> + +<P> + Without getting into the details, if a server is found to be capable +of using mappings in the <b>imd_wcsver</b>() call, the WCS string sent/read +will have two additional lines of information to define the mapping. +Specifically, +<PRE> + <i>name - title\n + a b c d tx ty z1 z2 zt\n + region_name sx sy snx sny dx dy dnx dny\n + object_ref</i> +</PRE> + +<P> +where the new parameters are defined as + +<PRE> + region_name - user-defined name for the region (e.g. 'image', + 'subras1', 'ccd3', etc). + sx, sy, snx, sny - source rect in the object + dx, dy, dnx, dny - dest rect in the display frame buffer + object_ref - full node!/path/image[sec] image name, same as + was immap'd when the image was displayed. Used + for access after the display +</PRE> +<P> + Since the interfaces remain the same a separate imd_setmapping() +or imd_getmapping() call is required to set/get the additional mapping data. +For example, to set the WCS: +<P> +<PRE> + # Set the mapping info to be written with the WCS. + call imd_setmapping (region, sx,sy,snx,sny, dx,dy,dnx,dny, objref) + + # Write the WCS and mapping info to the data. + call imd_putwcs (ds, frame, Memc[imname], Memc[title], + a, b, c, d, tx, ty, W_ZS(wdwin), W_ZE(wdwin), W_ZT(wdwin)) +</PRE> + + +<P> +To read the frame WCS: + +<PRE> + # Query the server for a wcs.<BR> + if (imd_getwcs (frame, server, image, sz_image, title, sz_title, + a,b,c,d, tx,ty) == OK) { + + # If we got that okay, get the mapping information returned. + if (imd_getmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, obj) > 0) { + : + } + } +</PRE> + +<P> +In all cases if the <b>imd_wcsver</b>() initialization says the server can't +do mappings these calls will be no-ops. + +<P> + For multiple-image displays to a single frame it's important to +remember that the default WCS for the frame will be the *<b><i>last</i></b>* +WCS set by the client. For example, a mosaic display can set a wcs and mapping +for each of the subrasters, but a final SetWCS call is required to define +an overall WCS for the frame defining the "detector coords". Note that the +'objref' string should include the MEF extension number so it's mapped +properly by the ISM. + + +<br><br><br> +<A NAME="sec-5.2.3"></a> +<HR NOSHADE=3> +<font size=+1><b>5.2.3 Cursor Reads</b></font> + +<P> + The <b>imd_query_map</b>() procedure is used to return the mapping +for a particular WCS number, such as that returned by a cursor read. It +will do a new WCS query for this regardless of a previous <b>imd_getwcs</b>() +call. Typical usage would be something like the following in <b>IMEXAMINE</b>: + +<PRE> +procedure t_imexamine () + : +begin + : + wcsver = imd_wcsver() + : + : + while (ie_gcur (ie, curtype, x,y,wcs, key, cmd, SZ_LINE) != EOF) { + if (imd_query_map (wcs,reg,sx,sy,snx,sny,dx,dy,dnx,dny,imname) > 0) { + .... add image name to list + } + } + : +end +</PRE> + +<P> +<b>[NOTE: in this example the ie_gcur() procedure was modified to return the + wcs from the cursor read.]</b> +<P> + +<P> +The WCS number returned by a cursor read now corresponds to the object id +used in the server. It still contains the frame number as before, but the +wcs number itself is used to identify the mapping. + + +<br><br><br> +<A NAME="sec-5.3"></a> +<HR NOSHADE=3> +<font size=+1><b>5.3 ISM Communications</b></font> + +<P> + The <b>ISM</b> (Image Support Module) can be any external task which +connects to XImtool over a socket. Communications are limited to simple +null-terminated text strings. In most cases these strings are just the +standard OBM messages sent to XImtool objects but can also include Tcl +callback code (either ISM-specific callbacks, procedures which can be +added to the callback list for existing XImtool objects, or even new GUI +code to create panels and new objects). + + +<br><br><br> +<A NAME="sec-5.3.1"></a> +<HR NOSHADE=3> +<font size=+1><b>5.3.1 Socket Connection</b></font> + +<P> + The ISM first requests a connection to XImtool on a dedicated +socket whose default value is "<i>/tmp/.ISM%d</i>", where the '<i>%d</i>' +is replaced by the userid allowing multiple users on a machine to have +independent sockets. The XImtool '<tt><b>ism_addr</b></tt>' resource or +"<tt><b>-ismdev</b></tt>" command-line option can be used to change this +address, a value of '<i>none</i>' will disable ISM communications. The +socket may also be set with an ISMDEV environment variable which will +override the resource or command-line options. +<P> + Once a connection request is received, XImtool replies with +a message telling the ISM to reconnect on a different socket, it then +frees the initial connection allowing multiple other ISMs to request +their own connection. The communications between XImtool and the ISM +are carried out entirely over this second negotiated socket. Once connected, +the ISM appears as just another named object which can receive OBM messages. + + +<br><br><br> +<A NAME="sec-5.3.1"></a> +<HR NOSHADE=3> +<font size=+1><b>5.3.1 Communications Protocol</b></font> + +<P> + Messages from the ISM are written to the connection socket and must +be preceeded by one of the following keywords: + +<PRE> + <b>callback</b> <i>Negotiate a connection on another socket</i> + <b>ready</b> <i>Client is ready to begin processing</i> + <b>quit</b> <i>Client is shutting down and disconnecting</i> + <b>send</b> <i>Send a message to another object</i> +</PRE> + + +<P> +Messages are of the form: + +<UL><DL> + <dt><b>connect <name></b> + <DD>Request a connection for the <name> ISM + + <dt><b>ready <name></b> + <DD>Reconnection request for the <name> ISM on + negotiated socket, ISM is ready to processing. + + + <dt><b>send</b> <i><obj></i> <b>'{'</b> <i><msg></i> <b>'}'</b> + <dd>Send <i><msg></i> to the named <i><obj></i>. + The message may be any valid string that will be understood + by the recipient. The object may be any object in the GUI + or OBM (see below). + + <dt><b>quit</b> + <dd><b>ISM</b> is shutting down. The named is determined + from the communications channel, ISM is + responsible for any cleanup of it's callbacks + before issuing the shutdown. +</DL></UL> + +<P> +All messages must be null-terminated. XImtool will buffer the text until +a complete message is received. Once an ISM client has delivered a +<b>QUIT</b> message no further messages will be sent the that ISM. +<P> + In OBM terminology the ISM is a named Client class object, where +the name is set in the connection request. Messages sent to the ISM should +use this name, messages sent to "client" are still interpreted to mean the +XImtool client. +<P> + The content of messages delivered to the ISM are totally free-form +and may contain any text the ISM is expected to understand. + + +<br><br><br> +<A NAME="sec-5.3.3"></a> +<HR NOSHADE=3> +<font size=+1><b>5.3.3 GUI Objects</b></font> + +<P> + While the ISM can send a message to any object in the task, there +is a GUI Parameter object called 'ism_msg' designed especially to process +messages from the ISM. The callback in the GUI is expecting a message +beginning with one of the following keywords: + +<PRE> + <b>source</b> Source message text as Tcl code + <b>alert</b> Message contains error text to be displayed in the + GUI 'alert' box + <b>deliver</b> Message text should be passed to a callback routine + specific to that ISM. This processing callback may + have been previously uploaded. The message text + may be any form the processing callback is expected + to understand. + <b>info</b> Message text is status output intended for the + XImtool 'info' panel (connect/disconnect requests, etc) +</PRE> + + +<P> +In all cases the message is expected to be of the form + +<PRE> + <cmd> <ism_name> [ <arg1> <arg2> <...> ] +</PRE> + +<P> +where <cmd> is one of the above keywords, <ism_name> is the name of the +ISM sending the message. The remainder of the message is passed as an 'argv' +list to the processing callback uploaded for the ISM. The ISM is responsible +for formatting these messages. + + + +</BODY> +</HTML> |