From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001 From: Joe Hunkeler Date: Tue, 11 Aug 2015 16:51:37 -0400 Subject: Repatch (from linux) of OSX IRAF --- vendor/x11iraf/guidemo/ximtool.html | 674 ++++++++++++++++++++++++++++++++++++ 1 file changed, 674 insertions(+) create mode 100644 vendor/x11iraf/guidemo/ximtool.html (limited to 'vendor/x11iraf/guidemo/ximtool.html') diff --git a/vendor/x11iraf/guidemo/ximtool.html b/vendor/x11iraf/guidemo/ximtool.html new file mode 100644 index 00000000..434edcc7 --- /dev/null +++ b/vendor/x11iraf/guidemo/ximtool.html @@ -0,0 +1,674 @@ + +XImtool On-Line Help Summary + +

Welcome to XImtool V1.1

+ +XImtool is an image display server developed by the IRAF Project at the +National Optical Astronomy Observatories. To view images you need +client software (such as IRAF) to load images into the display, or it can +load images directly when run as a standalone task. XImtool is +interchangeable with older display servers such as SAOimage / +IMTOOL and with newer servers like SAOtng, but offers many new +features not available elsewhere. +

+More detailed help is available on the following topics: +

+
Basic Usage:
+
+
+
Advanced Features:
+
+

+Please contact iraf@noao.edu with comments, bugs, or suggestions. +

+

+ +

Table of Contents:

 +
+        Getting Started
+        GUI Overview
+        Mouse Operations
+        Keystroke Accelerators
+        Command-line Options
+        Client Connections
+	Frame Buffers
+        Markers
+            Panner Marker
+            Coords Box Marker
+            General Markers
+                Menu Options
+        Control Panel
+            View Controls
+            Enhancement Controls
+            Blink Controls
+            Options:
+                Autoscale
+                Antialiasing
+                Tile Frames
+                Warnings
+	Colormap Selection
+                Builtin Colormaps
+                User-defined Colormaps
+        Load Panel
+            Directory browsing
+            File Patterns
+            Direct File Load
+            Frame Selections
+        Save Panel
+            File Name
+            Format
+            Color
+        Print Panel
+            Postscript Options
+            Color Options
+            Processing Options
+            Printer selection
+        Info Panel
+        TclShell
+
+

+

+

Getting Started

+As a display server, XImtool is started as a separate process from client +software such as IRAF. Once it is running it will accept +client connections simultaneously on fifo pipes, unix +domain sockets, or inet sockets. A display client like the IRAF DISPLAY +task makes a connection and sends the image across using an IIS protocol +(other/different protocols may be supported in the future). Once the image +is loaded in the display buffer it may be enhanced, +saved to a disk file in a number of different formats, or +printed as Encapsulated Postscript to a printer or disk file. +

+When run in standalone mode, images may be loaded on the +command line or by using the Load Panel. +This allows you to browse images and perform the same manipulations as if +they had been displayed by a client. +

+ +

GUI Overview

+

+The GUI consists of a large image display window and a number of smaller +pannels that control various specific functions such as image +Load, Save and Print +as well as a general purpose Control Panel. The main +window menubar has several menu buttons to the left: the Files menu +is used to load/save/print an image as well as quit the task. The View +menu let's you select the image orientation, zoom, colormap or frame. The +Options menu allows you to call up control panels, toggle markers +or blinking etc. Some of this functionality is duplicated elsewhere in +the GUI. The right side of the menubar contains command buttons to flip the +image as well as buttons for frame selection and the help button. +

+For more detailed information on the operation of the control panels please +see the on-line help (i.e. use the '?' button or Alt-h keystroke in the +main image window). + +

Mouse Operations

+Clicking and dragging MB1 (mouse button 1) in the main image +window creates a rectangular region marker, used +to select a region of the image. If you do this accidentally and don't +want the marker, put the pointer in the marker and type DELETE or +BACKSPACE to delete the marker. With the pointer in the marker, +MB3 will call up a marker menu listing some things + you can do with the marker, like zoom the outlined region. MB1 can be used +to drag or resize the marker. See below for more +information on markers. +

+Clicking on MB2 in the main image window pans (one click) or zooms (two +clicks) the image. Further clicks cycle through the builtin zoom factors. +Moving the pointer to a new location and clicking moves the feature under +the pointer to the center of the display window. Holding down the Shift +key while clicking MB2 will cause a full-screen crosshair cursor to appear +until the button is released, this can be useful for fine positioning of the +cursor. +

+MB3 is used to adjust the contrast and brightness of the displayed image. +The position of the pointer within the display window determines the +contrast and brightness values. Click once to set the values corresponding +to the pointer location, or click and drag to continuously adjust the display. +

+ +

Keystroke Accelerators

+ The following keystrokes are currently defined in the GUI: +
+  
+Ctrl-b   Backward frame        Alt-b  Blink frames (toggle)
+Ctrl-c   Center frame?         Alt-c  Control panel
+Ctrl-f   Forward frame         Alt-h  Help
+Ctrl-i   Invert?               Alt-i  Info box popup
+Ctrl-m   Match LUTs            Alt-l  Load file popup
+Ctrl-n   Normalize             Alt-p  Print popup
+Ctrl-p   Print                 Alt-s  Save popup
+Ctrl-r   Register              Alt-t  TclShell popup
+Ctrl-t   Tile frames toggle
+Ctrl-u   Unzoom (zoom=1)
+Ctrl-x   Flip X       	       Ctrl-Alt-q  Quit
+Ctrl-y   Flip Y       	       Ctrl-Alt-f  Fitframe
+
+Ctrl-=   Print
+Ctrl-<   Decrease blink rate   Ctrl-+   Zoom in
+Ctrl->   Increase blink rate   Ctrl--   Zoom out
+   
+Alt-1 thru Alt-4      Set frame displayed
+Ctrl-1 thru Ctrl-9    Set integer zoom factor  
+
+NOTE: These keystrokes only work with the cursor in the main image window, +not on the subwindows or in markers. +
+ +

Client Connections

+Ximtool allows clients to connect in any of the following ways: + +
fifo pipes
+
The traditional approach. The default, global /dev/imt1[io] pipes may +be used, or a private set of fifos.
+
tcp/ip socket
+
Clients connect via a tcp/ip socket. There is a default port, or a +custom port may be specified. This permits connecting to the server over a +remote network connection anywhere on the Internet.
+
unix domain socket
+
Like a tcp/ip socket, but limited to a single host system. Usually +faster than a tcp/ip socket, and comparable to a fifo. By default each user +gets their own unix domain socket, so this option allows multiple users +to run ximtools on the same host without having to customize things.
+ +By default ximtool listens simultaneously for client connctions on all three +types of ports. Clients communicate with XImtool using the IIS protocol, +other protocols may be supported in the future. +
+ +

Frame Buffers

+XImtool starts up using default frame buffer of 512x512 pixels. When loading +disk images the frame buffer configuration file will be searched for a +defined frame buffer that is the same size or larger than the current image, +when used as a display server the frame buffer configuration number is passed +in by the client. The default file used is /usr/local/lib/imtoolrc, this can +be overridden by defining a IMTOOLRC environment variable naming the +file to be used, or by creating a .imtoolrc file in your home +directory. +

+The format of the frame buffer configuration file is +

+   configno nframes width height [extra fields]
+e.g.                   
+	1  2  512  512
+	2  2  800  800
+	3  1 1024 1024          # comment
+
+At most 128 frame buffer sizes may be defined. +
+ +

Command-line Options

+ The following command-line options are currently recognized: +
+  -basePixel < num >       Base colormap pixel number
+  -cmap1 < file >          User cmap 1 
+  -cmap2 < file >          User cmap 2 
+  -cmapDir1 < dir >        User cmapDir 1 
+  -cmapDir1 < dir >        User cmapDir 2 
+  -cmapInitialize < bool > Initialize colormap at startup
+  -cmapName < name >       Private colormap name 
+  -config < num >          Initial config number
+  -defgui                  Print default GUI to stdout
+  -displayPanner < bool >  Display panner box
+  -displayCoords < bool >  Display wcs coords box
+  -fifo < pipe >           Fifo pipe to use
+  -fifo_only               Use fifo pipes only 
+  -gui < file >            GUI file to use 
+  -help                    Print command-line summary 
+  -imtoolrc < file >       Frame buffer configuration file 
+  -inet_only               Use inet sockets only 
+  -invert                  Invert colormap on startup?
+  -maxColors < num >       Number of colors 
+  -memModel < type >       Memory model (fast,small,beNiceToServer)
+  -nframes < num >         Number of frames at startup
+  -port < num >            Inet port to use
+  -printConfig < file >    Printer configuration file 
+  -port_only               Use inet sockets only 
+  -tile                    Tile frames on startup?
+  -unix < name >           Unix socket to use
+  -unix_only               Use unix sockets only 
+  < file >                 File to load on startup
+
+
+

Markers

+

Panner Marker

+

+The panner window always displays the full frame buffer. Try setting the +frame buffer configuration to a nonsquare frame buffer (e.g. imtcryo) and +then displaying a square image (e.g. dev$pix) and the panner will show you +exactly where the image has been loaded into the frame. +

+The panner window uses two markers, one for the window border and one to +mark the displayed region of the frame. Most of the usual marker keystrokes +mentioned below apply to these markers as well, e.g. +you can use MB1 to reposition on the panner window within the main image +display window, or to drag the region marker within the panner (pan the +image). Resizing the region marker zooms the image; this is a non-aspect +constrained zoom. The panner window itself can be resized by dragging a +corner with MB1. Typing delete or backspace anywhere in the panner window +deletes the panner. +

+A special case is MB2. Hitting MB2 anywhere in the panner window pans the +image to that point. This is analogous to typing MB2 in the main display +window to pan the image. + +

Coords Box Marker

+

+Ximtool provides a limited notion of world coordinates, allowing frame +buffer pixel coordinates and pixel values to be converted to some arbitrary +client defined coordinate system. The coords box feature is used to display +these world coordinates as the pointer is moved about in the image window. +

+The quantities displayed in the coords box are X, Y, and Z: the X,Y world +coordinates of the pointer, and Z, the world equivalent of the pixel value +under the pointer. All coordinate systems are linear. The precision of a +displayed quantity is limited by the range of values of the associated raw +frame buffer value. For example, if the display window is 512x512 only 512 +coordinate values are possible in either axis (the positional precision can +be increased however by zooming the image). More seriously, at most about +200 pixel values can be displayed since this is the limit on the range of +pixel values loaded into the frame buffer. If a display pixel is saturated +a "+" will be displayed after the intensity value. +

+The coords box is a marker (text marker) and it can be moved and resized +with the pointer like any other marker. + +

General Markers

+Although ximtool doesn't do much with markers currently, they are a general +feature of the Gterm widget and are used more extensively in other programs +(e.g. the prototype IRAF science GUI applications). Ximtool uses markers +for the marker zoom feature discussed above, and also for the +panner and the coords box. All +markers share some of the same characteristics, so it is worthwhile learning +basic marker manipulation keystrokes. + +For example, try placing the pointer anywhere in the coords box, then press +MB1 and hold it down, and drag the coords box marker somewhere else on the +screen. You can also resize the coords box by dragging a corner, or delete +it with the delete or backspace key. (The Initialize button will get the +original coords box back if you delete it). +

+

Marker Menu Options

+ + +
+

Control Panel

+

View Controls

+

The Frame box will list only the frame buffers you currently have +defined. Currently, the only way to destroy a frame buffer is to change the +frame buffer configuration, new frame buffers (up to 4) will be created +automatically if requested by the client. +

The text display window gives the field X,Y center, X,Y scale +factors, and the X,Y zoom factors. The scale factor and the zoom factor +will be the same unless autoscale is enabled. The scale is in units of +display pixels per frame buffer pixel, and is an absolute measure (it doesn't +matter whether or not autoscale is enabled). Zoom is +relative to the autoscale factor, which is 1.0 if autoscaling is disabled. +This information is also presented in the Info panel. +

The numbers in the Zoom box are zoom factors. Blue numbers zoom, +red numbers dezoom. Zoom In and Zoom Out may be used to go to +larger or smaller zoom factors, e.g. "Ctrl-5" followed by "Zoom In" will get you +to zoom factor 10. Specific zoom factors may also be accessed directly as +Control keystrokes, e.g. Ctrl-5 will set zoom factor 5. +Center centers the field. Toggle Zoom toggles between the +current zoom/center values, and the unzoomed image. +

Aspect recomputes the view so that the aspect ratio is 1.0. +Aspect also integerizes the zoom factor (use the version in the View menu +if you don't want integerization). +

Fit Frame makes the display window the same size as the frame +buffer. Note that autoscale has much the same effect, +and allows you to resize the display window to any size you want, or view +images to large to fit on the screen. + +

Enhancement Controls

+ +

At the top is a scrolled list of all the available +colormaps. Click on the one you want to load it. You can add your own +colormaps to this list. +

The two sliders adjust the contrast (upper slider) and +brightness (lower slider) of the display. The Invert button +inverts the colormap (multiples the contrast by -1.0). Note that due to the +use of the private colormap the sliders are a bit sluggish when dragged to +window the display. If this is annoying, using MB3 in the display window is +faster. +

The Normalize button (on the bottom of the control panel) will +normalize the enhancement, i.e. set the contrast and brightness to the default +one-to-one values (1.0, 0.5). This is the preferred setting for many of the +pseudocolor colortables and for private colormaps loaded from disk images. + +

Blink Controls

+ +

+NOTE: you can blink no matter what ximtool options are in effect, but many +of these will slow blink down. To get the fastest blink you may want to +turn off the panner and coords box, and match the LUTs of all the blink +frames. All the ximtool controls are fully active during blink mode, plus +you can load frames etc. + + +

Options:

+
+
Autoscale
+
If autoscale is enabled then at zoom=1, the frame buffer will be +automatically scaled to fit within the display window. With autoscale +disabled (the default), the image scale is more predictable, but the image +may be clipped by the display window, or may not fill the display window.
+ +
Antialiasing
+
When dezooming an image, i.e., displaying a large image in a smaller +display window, antialiasing causes all the data to be used to compute the +displayed image. If antialiasing is disabled then image is subsampled to +compute the displayed image. Antialiasing can prevent subsampling from +omitting image features that don't fall in the sample grid, but it is +significantly slower than dezooming via subsampling. The default is no +antialising.
+ +
Tile Frames
+
The default display mode is to view one frame at a time. In tile frames +mode, 2 or 4 frames may be viewed simultaneously in the display window. All +the usual operations (zoom and pan, colortable enhancement, cursor readback, +etc.) still work for each frame even when in tile frames mode.
+ +
Warnings
+
The warnings options toggles whether you see warning dialog boxes in +situations like overwriting an existing file, clearing the frame buffer, etc. +
+
+ +

Colormap Selection

+By default XImtool will display images using either a grayscale colormap +if loaded by a client, or a private colormap when loading an image from +disk that contains a colormap. Each frame defines its own colormap so +you can define different colormaps or enhancements for each frame, they +will change automatically as you cycle through the frames. + +

Builtin Colormaps

+Once loaded, the colormap may either be changed using the builtin colormap +menu under the View menu button on the main window, or from the +Enhancement box on the control panel. Ximtool has about a dozen colormap +options builtin, other user-defined colormaps may +optionally be loaded. + +

User-defined Colormaps

+The cmap[12] and cmapDir[12] resources (or command line +arguments are used to tell ximtool which specific colormaps to make +available or where to look for colortables respectively. The colortables +are loaded when ximtool starts up, or when it is reinitialized (e.g. by +pressing the Initialize button in the control +panel). Ximtool will ignore any files in the colormap directory +which do not look like colortables. New colortables will also be added +for each images loaded from disk. +

+The format of a user lookup table is very simple: each row defines one +colortable entry, and consists of three columns defining the red, green, +and blue values scaled to the range 0.0 (off) to 1.0 (full intensity). +

+        R G B
+        R G B
+        (etc.)
+
+Blank lines and comment lines (# ...) are ignored. +

+Usually 256 rows are provided, but the number may actually be anything in +the range 1 to 256. Ximtool will interpolate the table as necessary to +compute the colortable values used in Ximtool. Ximtool uses at most 201 +colors to render pixel data, so it is usually necessary to interpolate the +table when it is loaded. +

+The name of the colortable as it will appear in the Ximtool control panel +is the root name of the file, e.g., if the file is "rainbow.lut" the +colortable name will be "rainbow". Lower case names are suggested to avoid +name collisions with the builtin colortables. Private colormaps for disk +images will be have the same name as the image loaded. If the same colortable +file appears in multiple user colortable directories, the first one will be +used. +

+The directory "luts" in the ximtool source directory contains a sample set +of colortable files. This can be installed as /usr/local/lib/imtoolcmap +when ximtool is installed. +

+ +

Load Panel

+The Load Panel allows you load images from disk directly to the frame buffer, +this is analogous to loading an image on the command line except that +browsing is possible. At present recognized formats include IRAF OIF format +(i.e. .imh extension), simple FITS files, GIF, and Sun rasterfiles. The +task will automatically sense the format of the image and load it +appropriately. Images with private colormaps (such as GIF) will be loaded +using the private colormap by default (meaning that changing the +brightness/contrast enhancements will render a random-colored image). If +the Grayscale button is enabled the image will be converted to +grayscale and loaded with the standard grayscale colormap. +

+When loading new images the frame buffer configuration table +(imtoolrc) will be searched for a frame buffer that is the same size +or larger than the new image size, if no frame buffer can be found a custom +buffer exactly the size of the image will be created. This means that the +image may not fill the display window when loaded, or you may see a subsection +of the image in the main display window. Setting the +autoscale option will scale the entire image to fit +the main display window. +

+Images with more colors than can be displayed will automatically be quantized +to the number of available colors before display. Formats which allow more +than 8-bit pixels will be sampled to determine an optimal range in the data +to be used to compute the transformation to the number of display colors. +This is the same transformation used by the IRAF DISPLAY task. + +

+
Directory browsing
+
+The load panel contains a list of files in the current directory that may +be selected for loading by selecting with left mouse button. If the file +is a directory the contents of the new directory will be loaded, if it's +a plain file an attempt will be made to load it as an image. Directories +in the list are identified with a trailing '/' character, you will always +see any directories available even if a filter is +specified. +

+The Root button will reset the current directory to the system root +directory. The Home button will reset the current directory to the +user's login directory, the Up button moves up one directory level, +and Rescan reloads the file list by rescanning the directory. The +current working directory is given below the file selection window.

+ +
File Patterns
+
By default all files and directories will be listed. You may specify a +filter to e.g. select only those files with a given extension like "*.fits" +to list only files with a ".fits" extension. Directories will always be seen +in the list and are identified with a trailing '/' character. Any valid +unix pattern matching string will be recognized.
+
Direct File Load
+
If you know exactly which file you wish to load, you may enter its name +in the Load File text box and either hit or the Load button to +load it. An absolute or relative path name may be given, if a simple filename +is specified it will be searched for in the current working directory.
+
Frame Selections
+
By default images will be loaded into frame number 1, you may select a +different frame using the Frame menu button.
+
+
+ +

Save Panel

+The Save Panel lets you save the current contents of the main display window +to a disk file (including the Panner/Coords markers, any general graphics +markers, or overlay graphics displayed by the client program). Presently, +only the contents of the main display window may be saved, there is no +facility for saving the undisplayed contents of the entire frame buffer +other than to enable the autoscale feature. A limited +number of formats are currently available, others will be added in future +versions. +
+
File Name
+
The File Name text box allows you to enter the file name of the +saved file. A "%d" anywhere in the name will be replaced by a sequence number +allowing multiple frames to be saved with unique names.
+
Format
+
The Format box allows you to choose the format of the image to be +created. Not all formats are currently implemented.
+
Color
+
The Color box lets you choose the color type of the image to be +created. The options will change depending on the format, e.g. FITS doesn't +allow color so no color options will be allowed. Formats which allow 24-bit +images will be written using the current colormap after converting to a 24-bit +image, pseudocolor images will be written with the current colormap.
+
+
+ +

Print Panel

+The Print Panel allows you dump the contents of the main display window as +Enacpsulated Postscript to either a named printer device or to a disk file. +The Print To selects the type of output, the Print Command +box will adjust accordingly, either as a Unix printer command or as a file +name. A "%d" anywhere in the name for disk output will be replaced by a +sequence number allowing multiple frames to be saved with unique names. +Selecting printers from the installed list will +automatically change the command to be used to generate the output. This +command does not necessarily need to be a printer command, the +printer configuration file lets you define any command +string to process the image. +

Color Options

+The Color box lets you choose the color type of the image to be created. +PseudoColor or 24-bit postscript will be created using the current colormap. +

Postscript Options

+
+
Orientation
+
Set the page orientation. +
Paper Size
+
Select the paper size to be used. +
Image Scale
+
Set the scale factor used to compute the final image size. +
+

Processing Options

+
+
Auto Scale
+
The auto scale toggles whether or not the image is automatically scaled +to fit the page. If not enabled, the image scale will be used to +dtermine the output image size. +
Auto Rotate
+
Auto rotate determines whether or not the image will be rotated to fit +on the page. When set, an image larger than the current orientation will be +rotated and possibly scaled to fit the page. +
Max Aspect
+
Max Aspect takes images smaller than the page and automatically increases +the scale so the image fills the page in the current orientation. +
Annotate
+
The annotate option toggles whether or not the final file includes +annotation such as the image title, a colorbar, and axis labels. +
+

Printer selection

+The printer selection list lets choose the printer to be used. The printer +configuration file is /usr/local/lib/ximprint.cfg by default or may be reset +using the printConfig resource. The format of the file is simply +
+	name < tab > command
+
+The name value is what appears in the selection list and may be more +than a single word, the command can be any command that accepts EPS +input from a pipe, the two fields must be separated by a tab character. +Normally the command will be +a simple 'lpr -Pfoo' or some such, but can also include converters or +previewers. At most 128 printer commands may be used. +
+ +

Info Panel

+ The information panel is underused at present but is meant to provide +basic information about the frame being displayed. It is updated to be +current while changing enhancements, pan/zoom regions, or frame selection. +In cases where the image title string is truncated in the main display window, +the user can always pop up the info window to see the full title. +
+ +

TclShell

+ The TclShell is mostly used as a development or debugging +tool for the GUI. It allows the user to type commands directly to the +TCL interpreter letting you send messages to the object manager or execute +specific procedures in the TCL code that makes up the GUI. Most users will +never need this, but for an example of what it does, bring it up and type a +command such as +
+    send helpButton set background red
+
+Cool, huh. +
+ +

Acknowledgements

+ XImtool was developed by the IRAF Group at the National Optical +Astronomy Observatories in Tucson, AZ. For further information or to report +problems please contact iraf@noao.edu +
+This document was last updated 11/6/96. + + + -- cgit