From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- vendor/x11iraf/Notes-V1.3.html | 1841 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1841 insertions(+) create mode 100644 vendor/x11iraf/Notes-V1.3.html (limited to 'vendor/x11iraf/Notes-V1.3.html') 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 @@ + + + + + + + + +

+
+

X11IRAF V1.3 REVISIONS NOTES

+Last Modified: Mon Feb 4 16:33:02 MST 2002 + +
+ +

+
+
Table of Contents:
+
+ + + + +


+ +
+1. INSTALLATION CHANGES +
+ +

+ 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. + +

+To install from an unpacked source distribution: + +

+     % xmkmf              build the package Makefile
+     % make World         build binaries from sources
+     % su                 become the root user
+     # ./install          install the files (interactive)
+
+ +

+Only the last two commands are required to install from an unpacked binary +distribution. + + +


+ +

+2. XIMTOOL REVISIONS +
+ +

+ 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: + +

+ +

+ 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. + +

+ 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. + +

+ Users should feel free to contact IRAF site support (iraf@noao.edu) +with any questions. + + +


+ +

+ +2.1 Real-Time WCS/pixel Readout + + +

+ XImtool 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. +

+ WCS readout is enabled by default but can be toggled or reset +using the 'WCS/Pix' button on the Coords tab +in the control panel or the "ISM" toggle on the alt-gui +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 ISM (ISM is Image +Support Module) 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. +

+ By default, the logical and world image coordinates are displayed +to both the Coords 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 +"Options" toggle on the Coords panel. +Available coordinate systems are chosen using the "Type" +menu on the panel, the readout format (sexigesimal, degrees, etc) using +the "Format" 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. + +

+ By selecting the "BPM Data" toggle from the +Coords.Options 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 "BPM" keyword by convention. If the +cursor passes over a bad pixel in the mask, the Coords bpm +display as well as the main window wcsbox will change to a red background +color. Only the Coords display will show the value, any +non-zero value will be flagged with the color change. + +

+ With the ISM enabled the Compass 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 ISM off the pixel table +displays the scaled image values from the frame buffer. + + +


+ +

+ 2.2 "Peak-up" Cursor Centroid Positioning + +

+ 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 'centerBoxSize' +GUI resource (defaults to 5 pixels) but can be adjusted interactively +using the Ctrl-[ and Ctrl-] commands to +descrease andincrease the box size respectively. A marker will flash briefly +to indicate the new box size. +

+ The Ctrl-0 (zero) key finds either a centroid or +the local maximum pixel value within this box region, Alt-Ctrl-0 +(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 "Centroid Peaks" option from +the main Display control panel or by resetting the +"peakCentroid" GUI resource (defaults to True). + +

+ 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. + +

+ +
+2.2.1 Command Summary: + +

+        Ctrl-0 (zero)           Reposition to centroid/max-pixel
+    Alt-Ctrl-0 (zero)           Reposition to min-pixel
+        Ctrl-[                  Decrease centering box size (min of 5)
+        Ctrl-]                  Increase centering box size
+
+

+ +
+2.2.2 Resource Summary: + +

+        peakCentroid    True    Compute the box centroid position, a
+                                'False' value force the max value to be used
+        centerBoxSize   5       Size of the centroid box, used as cursor
+                                position +/- this value
+
+ + + +


+ +
+ 2.3 Auto-Registration of Images + + +

+ The auto-register 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 Display panel. + +

+For example, to use this feature do the following: + +

    +
  1. Enable Auto-Register (either on the + Display panel or the toolbar on the alt-gui) + and pan/zoom to some star of interest. +
  2. Use Mouse-Button-2 to center the star in the frame. +
  3. 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 Ctrl-o to offset it to the center. + Repeat as necessary. Small corrections will be cumulatively added + so you can use the Ctrl-0 peak-up command to + centroid each object in the frame before the Ctrl-o + offset. +
  4. 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. +
  5. A Ctrl-a command will toggle the feature, offsets are + only allowed when Auto-Register is enabled. +
+ +

+ Hitting "Register" 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. + +

+ The register display list is shared with the blink list and can +be set using the Display control panel. By default all +frames are included in the list. For accessing more than four frames, use +the box icon in the Blink/Register box of the +Display control panel to bring up a new window with access +to all 16 available frames. + +


+2.3.1 Command Summary: + +

+        Ctrl-o         set the offset from center
+        Ctrl-a         toggle the Auto-register feature
+
+ + + +


+ +
+2.4 Integrated Control Panel + +

+ 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 Tab 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). + +

+ All panels were updated as part of the integration, however some +changes of note to each panels include: + +

+ + +


+ +
+2.4.1 Load Panel Changes + + +

+ The Load 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. + +

+A new options group was added to the panel with the following features: + +

+ +

+ + +


+ +
+2.4.2 Info Panel Changes + +

+ 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: + +

+ + +


+ +
+2.4.3 Tile Panel (NEW) + +

+ With the additional frames in this release, the default tiling +scheme proved inadequate. A new control panel Tile 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). +

+Tile configuration will make use of all frames currently selected in the +"Tile Frame" group in the following manner: + +

+ + +


+ +
+2.4.4 Coords Panel (NEW) + +

+ 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: + +

+ + The "Readout Values" group controls the selection +of WCS type, location and format to be displayed. The "Type" +menu always provides a selection of the image Logical, Physical +or World systems, which may be identical depending on the image +header. If a World 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 ISM is running as well as WCS information +present in the image. The "Format" 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 +Panel (i.e. the Coords Panel window) or +the ImgWin (i.e. the text marker on the main image window). +

+ 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 +Coords Panel display. The "BPM Data" option +controls whether or not the ISM will try to map any bad-pixel mask +associated with the image. If enabled, a bad-pixel mask specified by the +image header BPM keyword (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 +Coords Panel readout as well as the main image window marker +to switch to a red background color to flag the value. +

+ The last box allows the user to specify a different ISM task +to be executed or to reinitialize the current one. In most cases this +won't need to be changed, however a custom ISM could be started when +using special data formats. This command string can also be controlled by +the application "ism_task" resource. + + + +


+ +

+2.5 Support for 16 Display Frames + +

+ 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 DISPLAY task will automatically sense +whether the display server being used supports 16 frames or the original +4 and adjust the 'frame' parameter maximum accordingly. The changes +are fully backwards compatible for other servers (e.g. SAOimage, +DS9, etc). +

+ 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 Load panel can be done independently but +would also require numerous code change to XImtool. Please contact +site support (iraf@noao.edu) if there is a need for this, or for workaround +suggestions depending on your application. + + + +


+ +

+2.6 Magnifier + +

+ 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. + + +


+ +

+2.7 Freezing Cursor Readout + +

+ Holding down the Alt 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. + + +


+ +

+2.8 Cut-Graphs + +

+ 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 "H" and "V" 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: + +

+ +

+ 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. + + + +


+ +

+2.9 Ruler Markers + +

+ Holding down the Ctrl key and the +Left-Mouse-Button while moving the mouse will drag out +a "ruler marker" measuring the distance from the initial point to +the current mouse position. Releasing the Ctrl 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. +

+ Distances are measured by default in image logical pixels however +the Right-Mouse-Button can be used inside the marker to +popup a menu of options: + +

+ +

+The marker can also be destroyed by hitting the Delete +or Backspace key while the cursor is in the marker. There +is presently no way to move the marker to a new position in the frame. + + +


+ +

+2.10 Summary of Cursor Commands + +
+    * - indicates a new/changed command
+
+ + +Misc Functions +
+    Ctrl-b              Backward frame
+    Ctrl-c              Center frame
+    Ctrl-f              Forward frame
+    Ctrl-i              Invert
+    Ctrl-n              Normalize
+*   Ctrl-m              Toggle Magnifier
+*   Ctrl-p              Toggle Panner
+    Ctrl-r              Register
+*   Ctrl-s              Match LUTs
+    Ctrl-t              Tile frames toggle
+    Ctrl-u              Unzoom (zoom=1)
+    Ctrl-x              Flip X
+    Ctrl-y              Flip Y
+    Ctrl-=              Print
+    Ctrl-<              Decrease blink rate
+    Ctrl->              Increase blink rate
+    Ctrl-+              Zoom in
+    Ctrl--              Zoom out
+
+    Alt-1 thru Alt-4    Set frame displayed
+    Ctrl-1 thru Ctrl-9  Set integer zoom factor
+
+    Ctrl-Alt-q          Quit
+    Ctrl-Alt-f          Fitframe
+
+ +Panels +
+    Alt-b               Blink frames toggle
+    Alt-c               Control panel
+    Alt-h               Help panel
+    Alt-i               Info box panel
+    Alt-l               Load file panel
+    Alt-p               Print panel
+    Alt-s               Save panel
+    Alt-t               Tcl Shell panel
+
+ +Auto-Registration +
+*   Ctrl-a              Toggle Auto-Reg
+*   Ctrl-o              Set offset
+
+ +Cursor Positioning +
+*   Ctrl-h/Left_Arrow   move cursor 1 pixel left
+*   Ctrl-j/Down_Arrow   move cursor 1 pixel down
+*   Ctrl-k/Up_Arrorw    move cursor 1 pixel up
+*   Ctrl-l/Right_Arrow  move cursor 1 pixel right
+
+*   Shift-Ctrl-h        move cursor 10 pixels left
+*   Shift-Left          move cursor 10 pixels left
+*   Shift-Ctrl-j        move cursor 10 pixels down
+*   Shift-Down          move cursor 10 pixels down
+*   Shift-Ctrl-k        move cursor 10 pixels up
+*   Shift-Up            move cursor 10 pixels up
+*   Shift-Ctrl-l        move cursor 10 pixels right
+*   Shift-Right         move cursor 10 pixels right
+
+ +Frame Positioning +
+    Ctrl-Left           shift one full frame left
+    Ctrl-Down           shift one full frame down
+    Ctrl-Up             shift one full frame up
+    Ctrl-Right          shift one full frame right
+
+    Ctrl-Alt-Left       shift one half frame left
+    Ctrl-Alt-Down       shift one half frame down
+    Ctrl-Alt-Up         shift one half frame up
+    Ctrl-Alt-Right      shift one half frame right
+
+ +Peak-Up Centroiding +
+*   Ctrl-[              decrease centering box size
+*   Ctrl-]              inrease centering box size
+*   Ctrl-0 (zero)       centroid/find local max
+*   Alt-Ctrl-0 (zero)   find local min
+
+ +Mouse Button Actions +
+    Shift-Btn1Down      turn on magnifier
+    Shift-Btn1Up        turn off magnifier
+    Shift-Btn2Down      turn on crosshair cursor
+    Shift-Btn2Up        turn off crosshair cursor
+    Btn1Down            create marker
+    Btn1Motion          resize marker being created
+    Btn2Down            zoom on cursor position
+    Btn3Down/Motion     brightness/contrast scaling
+
+*   Ctrl-Btn1Down       create ruler marker
+*   Ctrl-Btn1Motion     resize ruler marker
+*   Ctrl-Btn1Up         destroy ruler marker
+
+*   Alt-Motion          freeze cursor readout
+
+ + +


+ +
+2.11 Summary of Application Resources + +

+ 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. +

+ 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 +GUI. + + +Client Program Resources +

+    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)
+
+ +

+ Notes: +

    +
  1. Options: nearest, bilinear, area, blkavg, boxcar, lowpass, gaussian +
  2. Either the string 'default' or the path to a valid GUI file +
  3. Options: fast, small, beNiceToServer +
  4. Name of a colormap file in the cmapDir[1|2] directory +
  5. Path to directory of valid colormaps +
  6. Path to FIFO pipe +
  7. Unix socket path, a '%d' is replaced with the uid +
  8. 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. +
  9. Command used to start the default WCS/Pixel readout ISM task. +
+ +

+GUI Resources +
+    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
+
+ +

+ Notes: +

    +
  1. Value represents blink rate in seconds +
+ + +

+Main Image Window (Gterm) Resources +
+    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
+
+ +

+ Notes: +

    +
  1. Any user-defined name is acceptable +
  2. Value represents blink rate in milliseconds +
+ + +


+ +
+2.12 Summary of Command-Line Options + +
+    -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
+
+ + + +


+ +
+3. OBM (WIDGET SERVER) REVISIONS +
+ + +


+3.1 New Widgets + +

+ As part of the OBM modifications two new widgets were added +to the toolkit. The widgets were also added to the LISTRES +application in the X11IRAF 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: + +

+        % cd /<path>/x11iraf/obm/listres        # go to the source directory
+        % xmkmf                                 # create the Makefile
+        % make listres                          # compile the task
+
+ +

+It may then be used as e.g. "listres <widget>" to print a full list of +resources for the named widget. + + +


+ +

+3.1.1 Tabs Widget + +

+ The Tabs 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 XImtool +Control Panel. 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. +

+ 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 + +

+        send <tab> setTop <name>
+
+ +

+where <tab> is the name of the Tab widget, +and <name> 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. +

+ 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 +'opPanels' with several child widgets containing layouts of other +widgets, the following resource settings will hide the parent Tabs widget: +

+

+    *opPanels.tabLabel:
+    *opPanels.font:                             nil2
+    *opPanels.height:                           0
+    *opPanels.width:                            0
+    *opPanels.borderWidth:                      65535
+    *opPanels.internalWidth:                    32765
+    *opPanels.internalHeight:                   32765
+
+ +

+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. +

+ An example GUI for this widget is in x11iraf$guidemo/tabs.gui + + +


+ +

+3.1.2 ListTree Widget + +

+ The ListTree 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. + +

+ A new Widget class command was added to allow GUI control of the +list contents. This command is of the form +

+

+        send <listree> setListTree <nested list>
+
+ +

+where <listree> is the name of the widget, +and <nested list> 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 +ListTree 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 +

+

+  send list setListTree {a1 {b1 { {a2 {a3 b3 c3 d3}} { b2 {z1 z2}} } } c1}
+
+

+would produce a nested list such as + +

+               a1
+               b1
+                 a2
+                   a3
+                   b3
+                 b2
+               c1
+
+ +

+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. + +

+ An example GUI for this widget is in x11iraf$guidemo/ltree.gui + + +


+ +

+3.2 Dynamic Widget Creation + +

+ In the original implementation of the OBM, the GUI is created or +defined using the 'appInitialize' and +'createObjects' server commands. appInitialize +initializes the X display but the 'resources' argument just sets the +fallback resources for the application. A 'createObjects' 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. +

+ The initial example GUIs all defined an "objects" resource +as the way to define the widgets and all the subsequent GUI tasks followed +that form, however appInitialize requires only a string of resource +definitions ('object' resources or otherwise), and createObjects +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. +

+ The solution then was implement a new 'appExtend' +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 createObjects 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 appExtend server method essentially works by + +

    +
  1. getting the fallback resource database +
  2. convert resource string arg to a new resource database +
  3. combine the two resource databases +
  4. write the combined database back as the new fallback database +
+ +

+For example, the plug-in code for a "Hello, World" GUI panel would look +something like + +

+     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
+
+ +

+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). +

+ 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. + + +

+ +


+ +
+4. CLIENT DISPLAY LIBRARY (CDL) REVISIONS +
+ + +


+4.1 Display Protocol Changes + +

+ 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 section 5.1 below. +

+ 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. + +

+ Changes remain completely backwards compatible so client tasks need +to be modified only to support the new XImtool features. + + +


+ +

+4.2 New Procedures + +

+ Three new public interface procedures were added in addition to the +internal changes made to support image mappings: + +

+ + +


+ +
+4.2.1 C Calling Sequence + +

+

+ 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)
+
+ +

+Where the arguments are defined as + +

+    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
+
+ + + +


+ +
+4.2.2 F77 Calling Sequence + +
+           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)
+
+ +

+Where the arguments are defined as above +and 'ier' is an error status code. + + +


+ +

+4.2.3 SPP Calling Sequence + +
+         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)
+
+ +

+Where the arguments are defined as above +and 'ier' is an error status code. + + +


+ +

+4.3 Demo Task Updates + + + + +
+


+ +
+5. TECHNICAL NOTES +
+ +


+5.1 IIS Protocol Changes + +

+ 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 'x' register be set to indicate +the new behavior was desired, e.g. the wcs text containing the extra mapping +data. +

+ 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). +

+ 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 'x' register has been set. +

+ Support for the full 16 frames allowed by the bit-flag 'z' +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. +

+ A complete summary of the XImtool IIS protocol implementation follows. + + +


+ +

+5.1.1 IIS Protocol Summary + +

+

+                                   IIS Header Packet Summary
+
+                      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   |
+              +------------------+-------------+-----+---+---+----+---+--------+
+
+ + +

+Where +

+        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
+
+ + + +


+ +
+5.2 IRAF 'imd' Interface Changes. + +

+ 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 SetWCS 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. + +

+ 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. + +

+ To modify a task to make use these changes, there are just a few +routines you need to be aware of: + +

+

+    imd_wcsver()  - Query the server for new capabilities.  Returns a
+                    non-zero version if the server can use the new
+                    mapping functionality.
+
+imd_setmapping()  - Set mapping data to be sent with next imd_putwcs() call
+
+imd_getmapping()  - Get mapping data returned with last imd_getwcs() call.
+                    returns a non-zero status if valid mapping available
+
+ imd_query_map()  - Given a WCS number return the mapping data.  Returns a
+                    non-zero status if valid mapping available
+
+ +

+where the calling sequence is + +

+         imd_setmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)
+ valid = md_getmapping (reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)
+ status = md_query_map (wcs, reg, sx,sy,snx,sny, dx,dy,dnx,dny, objref)
+   version = md_wcsver ()
+
+ +

+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 imd_[sg]etmapping() +procedures to set and retrieve the mapping information. imd_query_map() +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. + + +


+ +

+5.2.1 Program Initialization + +

+ 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 imd_wcsver() call. For example, in the DISPLAY +task during startup one would do something like + +

+        # 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)
+
+ +

+The call to imd_wcsver() in this case is used to reset the number of +allowed frames depending on the server capabilities. + +

+ This call is REQUIRED 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). +

+ A 'disable_wcs_maps' 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. + + +


+ +

+5.2.2 WCS Text Changes + +

+ Without getting into the details, if a server is found to be capable +of using mappings in the imd_wcsver() call, the WCS string sent/read +will have two additional lines of information to define the mapping. +Specifically, +

+        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
+
+ +

+where the new parameters are defined as + +

+    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
+
+

+ 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: +

+

+    # 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))
+
+ + +

+To read the frame WCS: + +

+    # Query the server for a wcs.

+    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) {
+              :
+        }
+    }
+
+ +

+In all cases if the imd_wcsver() initialization says the server can't +do mappings these calls will be no-ops. + +

+ For multiple-image displays to a single frame it's important to +remember that the default WCS for the frame will be the *last* +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. + + +


+ +

+5.2.3 Cursor Reads + +

+ The imd_query_map() 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 imd_getwcs() +call. Typical usage would be something like the following in IMEXAMINE: + +

+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
+
+ +

+[NOTE: in this example the ie_gcur() procedure was modified to return the + wcs from the cursor read.] +

+ +

+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. + + +


+ +

+5.3 ISM Communications + +

+ The ISM (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). + + +


+ +

+5.3.1 Socket Connection + +

+ The ISM first requests a connection to XImtool on a dedicated +socket whose default value is "/tmp/.ISM%d", where the '%d' +is replaced by the userid allowing multiple users on a machine to have +independent sockets. The XImtool 'ism_addr' resource or +"-ismdev" command-line option can be used to change this +address, a value of 'none' will disable ISM communications. The +socket may also be set with an ISMDEV environment variable which will +override the resource or command-line options. +

+ 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. + + +


+ +

+5.3.1 Communications Protocol + +

+ Messages from the ISM are written to the connection socket and must +be preceeded by one of the following keywords: + +

+    callback            Negotiate a connection on another socket
+    ready               Client is ready to begin processing
+    quit                Client is shutting down and disconnecting
+    send                Send a message to another object
+
+ + +

+Messages are of the form: + +

+ +

+All messages must be null-terminated. XImtool will buffer the text until +a complete message is received. Once an ISM client has delivered a +QUIT message no further messages will be sent the that ISM. +

+ 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. +

+ The content of messages delivered to the ISM are totally free-form +and may contain any text the ISM is expected to understand. + + +


+ +

+5.3.3 GUI Objects + +

+ 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: + +

+    source        Source message text as Tcl code
+    alert         Message contains error text to be displayed in the
+                  GUI 'alert' box
+    deliver       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.
+    info          Message text is status output intended for the
+                  XImtool 'info' panel (connect/disconnect requests, etc)
+
+ + +

+In all cases the message is expected to be of the form + +

+      <cmd> <ism_name> [ <arg1> <arg2> <...> ]
+
+ +

+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. + + + + + -- cgit