XIMTOOL(1)

📦 version 2.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

ximtool — interactive image display program for the X Window System 🖼️💖

okay so bestie, welcome to ximtool(1), straight outta the General Commands Manual. She's an interactive image display program for the X Window System and she is, genuinely, serving main character energy for anyone who stares at astronomical images all day. Let's get into it 🫶

🌈 SYNOPSIS 🌈

ximtool [-toolkitoption ...] [ options ...] [imagename]

that's it, that's the whole vibe check ✨

💅 OPTIONS 💅

okay so here's the full lineup, no skips, no cuts, every single one of them:

  • -basePixel N — the base colormap cell that the colormap starts from. Basically it lets you reserve basePixel colors in the global colormap so other applications can have them. default is 64. heads up tho: if you change this, you also need to specify the -cmapInitialize option or resource. not optional, bestie, they travel together 💫
  • -cmap1 file — user colormap 1. this flag lets you point at a colormap to be made available at task startup. 🎀
  • -cmap2 file — user colormap 2. same deal, but it lets you specify a second colormap to be made available at task startup. two colormaps, one icon 💅
  • -cmapDir1 dir — user colormap directory 1. specifies a directory to be searched for colormaps. 🔍
  • -cmapDir2 dir — user colormap directory 2. also specifies a directory to be searched for colormaps. by default this points to the system directory /usr/local/lib/imtoolcmap, which is the whole point — it lets a set of site default colormaps be defined there. 🗂️
  • -cmapInitialize bool — initialize the ximtool colormap at startup. if you're setting the basePixel option or resource, this one is required to force the Gterm widget to update its global colormap resource in the X server. default is false. don't skip it, she will not update on her own 💀
  • -cmapName name — the name used for the private colormap. the default for all IRAF imaging applications is image. here's the slay part: Gterm-widget-based imaging applications that share the same value of cmapName will share the same colormap, which minimizes colormap flashing AND lets multiple applications run at the same time. iconic behavior honestly 👑
  • -config N — initial frame buffer configuration number. default value is 1, which means a 512x512 frame buffer with 2 frames. see below for info on the frame buffers. 🌸
  • -defgui — prints the default GUI to the stdout. that GUI is a Tcl program, and you can customize it and reload it using the -gui option or the gui resource parameter. go off, make it yours ✨
  • -displayPanner bool — display the panner marker window at startup. if set, a panner window showing the full frame buffer will pop up in the upper-right side of the main display window. 🧭
  • -displayCoords bool — display the WCS coordinate marker window at startup. if set, a coordinate readout text marker will appear in the lower-right side of the main display window. 📍
  • -fifo pipe — specifies the name of the fifo pipe to be used. the i and o suffixes get added automatically, so don't you dare type them yourself. the default pipe names are /dev/imt1i (input pipe) and /dev/imt1o (output pipe). 🔌
  • -fifo_only — if set, only fifo pipes will be used for communication with a client program, and sockets get disabled. fifo or nothing, periodt 🚫
  • -gui file — specifies the GUI file to be used. 🎨
  • -help — prints a summary of command line options to the screen. your little safety net when the flags start flagging 🫶
  • -imtoolrc file — specifies the frame buffer configuration file to be used. see below for info on frame buffers. 📦
  • -inet_only — if set, only inet sockets will be used for communication with a client program, and fifo pipes and unix sockets get disabled. inet girlies only 💻
  • -invert — starts XImtool using inverted colormaps. when set, a "normalized" display will always be the inverse of the selected colormap. lowkey chaotic, highkey useful 🌗
  • -ismdev dev — specifies the plug-in ISM connection socket. this should be a unix domain socket of the form "/tmp/.ISM%d", where the %d gets replaced by the user id. once an ISM has connected, this port is freed up to accept other connections. 🔗
  • -maxColors N — specify the max number of colors to be used for the display. 🎨
  • -memModel type — determines how ximtool uses memory in the ximtool client and the X server. the options are fast, beNiceToServer, and small. the default is fast, which uses server pixmaps to make frame blink fast. this one is recommended unless server memory is very limited. and ngl, even in fast mode the server pixmap is only the size of the display window, so memory usage stays reasonable even if the frame buffer is very large. so like, you're fine 💖
  • -nframes N — specifies the number of frame buffers to configure at startup. by default there will be 2 frames available, and a maximum of 4 frames are allowed. don't get greedy with the frames bestie 😭
  • -port N — specifies the port number to use when connecting through an inet socket. 🔢
  • -port_only — same as the -inet_only option. if set, only inet sockets will be used for communication with a client program. twins fr fr 👯
  • -printConfig name — specifies the printer configuration file to use. by default this will be /usr/local/lib/ximprint.cfg. see below for more information on configuring output devices. 🖨️
  • -tile — so the default display mode is viewing one frame at a time. in tile frames mode, 2 or 4 frames may be viewed simultaneously in the display window. and the best part? all the usual operations (zoom and pan, colortable enhancement, cursor readback, etc.) still work for each frame even when you're in tile frames mode. no features were harmed in the tiling of these frames ✨
  • -unix name — specifies the unix domain socket name to use. a "%d" in the filename will be replaced with the user id. 🐧
  • -unix_only — if set, only unix domain sockets will be used for communication with a client program, and inet sockets and fifos get disabled. unix socket supremacy, sorry not sorry 💅

and that's just the options bestie, the page keeps going 🦋

✨ APPLICATION RESOURCES ✨

XImtool is implemented as a client program which is responsible for loading the frame buffers/colormaps, communicating with clients, etc, and a user-modifiable GUI file written as a Tcl script which handles all the user interface details. The client resources described below will be common to any user-defined GUI, the gui resources may change depending on how extensively the GUI has been modified by the user. Each of these components has its own set of resources, but to the user setting them is the same as with any other application.

Gterm widget resources (i.e. those for the main image window or colorbar) may be set as either client or GUI resources. See the xgterm(1) man page for a complete description of Gterm widget resources.

💖 CLIENT RESOURCES 💖

The client resources generally define the initial state of the application or set configuration parameters.

🎀 Client Resource Defaults 🎀

  • defConfig — default 1
  • defNFrames — default 0
  • tileBorderWidth — default 3
  • tileBorderColor — default 9
  • autoscale — default false
  • antialias — default false
  • antialiasType — default boxcar
  • tileFrames — default false
  • highlightFrames — default true
  • gui — default default
  • imtoolrc — default /usr/local/lib/imtoolrc
  • invert — default false
  • memModel — default fast
  • basePixel: — default 64
  • maxColors: — default 216
  • cmapInitialize: — default false
  • cmap1 — default none
  • cmap2 — default none
  • cmapDir1 — default none
  • cmapDir2 — default /usr/local/lib/imtoolcmap
  • input_fifo — default /dev/imt1i
  • output_fifo — default /dev/imt1o
  • unixaddr — default /tmp/.IMT%d
  • port — default 5137
  • ism_addr — default /tmp/.ISM%d
  • ism_task — default "ism_wcspix.e wcspix &"

🌸 Description of ximtool client resources 🌸

  • defConfig — Default frame buffer configuration number on startup. See below for more information on frame buffers.
  • defNFrames — Default number of frames on startup. Set to zero to use the value from the frame buffer configuration (imtoolrc) file.
  • tileBorderWidth, tileBorderColor — Used by the tile frames option. Specifies how far apart to space the frames in tile frames mode. Color "9" refers to the Gterm widget resource color9, which is assigned a color with its own resource.
  • autoscale — Enable/disable the autoscale option.
  • antialias — Enable/disable the antialias option.
  • antialiasType — Type of antialiasing. Options include boxcar (default), bilinear, nearest, area, blkavg, lowpass, and gaussian.
  • tileFrames — Enable/disable the tile frames option.
  • highlightFrames — Determines whether the current frame is highlighted when in tile frames mode.
  • gui — The GUI to be executed. "default" refers to the default, builtin ximtool GUI. You can replace this with your own GUI file if you are bold enough, and completely change the look and functionality of the GUI if desired.
  • imtoolrc — Where to find the imtoolrc file. This defines the recognized frame buffer configurations.
  • invert — Start Ximtool using an inverted colormap. When set, a "normalized" display will always be the inverse of the selected colormap.
  • memModel — Determines how ximtool uses memory in the ximtool client and the X server. The options are fast, beNiceToServer, and small. The default is fast, which uses server pixmaps to make frame blink fast. This is recommended unless server memory is very limited. Note that even in fast mode, the server pixmap is only the size of the display window, so memory usage is reasonable even if the frame buffer is very large.
  • basePixel, maxColors — These two resources determine the region of colormap space used to render image pixels.
  • cmapInitialize — Initialize the ximtool colormap at startup. This is a required resource to clear a previous ximtool colormap allowing a new basePixel and maxColors to take effect.
  • cmap1, cmap2 — User colormap files. The intent here is to allow individual colormaps to be conveniently specified as a resource.
  • cmapDir1, cmapDir2 — User or system colormap directories. By default cmapDir2 points to the system directory /usr/local/lib/imtoolcmap, allowing a set of site default colormaps to be defined here. This leaves cmapDir1 available to a user colormap directory.
  • input_fifo, output_fifo — The input and output fifos for fifo i/o. "Input" and "output" are from the client's point of view. Note that only one display server can use a fifo-pair at one time.
  • unixaddr — Template address for unix domain socket. The user must have write permission on this directory, or the file must already exist. %d, if given, is replaced by the user's UID.
  • port — TCP/IP port for the server. Note that only one server can listen on a port at one time, so if multiple ximtool servers are desired on the same machine, they should be given different ports.
  • ism_addr — Template address for ISM unix domain socket. The user must have write permission on this directory, or the file must already exist. %d, if given, is replaced by the user's UID.
  • ism_task — Command string to execute for the real-time pixel and WCS readout ISM (Image Support Module) task.

🦋 GUI RESOURCES 🦋

In principle ximtool can have any number of different GUIs, each of which defines its own set of resources. GUIs typically define a great many resources, but most of these are not really intended for modification by the user (although one can modify them if desired).

The following are some of the more useful resources used by the default ximtool GUI. The imagewin resources are Gterm widget resources.

✨ Main Display Gterm Widget Resources ✨

  • *imagewin.cmapName: — default image
  • *imagewin.basePixel: — default 64
  • *imagewin.warpCursor: — default True
  • *imagewin.raiseWindow: — default True
  • *imagewin.deiconifyWindow: — default True
  • *imagewin.ginmodeCursor: — default circle
  • *imagewin.ginmodeBlinkInterval: — default 500
  • *imagewin.color0 (background): — default black
  • *imagewin.color1 (foreground): — default white
  • *imagewin.color8 (panner highlight): — default #7c8498
  • *imagewin.color9 (tileFrame color): — default SteelBlue
  • *imagewin.width: — default 512
  • *imagewin.height: — default 512

🌟 GUI Resources 🌟

  • *autoscale: — default True
  • *zoomfactors: — default 1 2 4 8
  • *displayCoords: — default True
  • *displayPanner: — default True
  • *displayMagnifier: — default True
  • *blinkRate: — default 1.0
  • *pannerArea: — default 150*150
  • *pannerGeom: — default -5+5
  • *magnifierArea: — default 100*100
  • *magnifierGeom: — default +5+5
  • *wcsboxGeom: — default -5-5
  • *maxContrast: — default 5.0
  • *warnings: — default True
  • *centerBoxSize: — default 5
  • *peakCentroid: — default True

💫 Alternate GUI Resources 💫

  • *showToolBar: — default False
  • *showPanelBar: — default False

💅 Description of selected resources 💅

  • *cmapName — Name used for private colormap. The default for all IRAF imaging applications is "image". Gterm widget based imaging applications which have the same value of cmapName will share the same colormap, minimizing colormap flashing and allowing multiple applications to be run at the same time.
  • *basePixel — The base colormap cell used by the display colormap.
  • *imagewin.warpCursor — Warp pointer into image window when initiating a cursor read.
  • *imagewin.raiseWindow — Raise image window when initiating a cursor read.
  • *imagewin.deiconifyWindow — Deiconify image window if necessary when initiating a cursor read.
  • *imagewin.ginmodeCursor — Type of cursor when a cursor read is in progress. The default is a circle. Any selection from the X cursor font can be used. A special case is "full_crosshair" which is the full crosshair cursor of the Gterm widget.
  • *imagewin.ginmodeBlinkInterval — Determines whether the cursor blinks when a cursor read is in progress. The value is given in milliseconds.
  • *imagewin.color0 — Background color.
  • *imagewin.color1 — Foreground color.
  • *imagewin.color8 — Color assigned the panner window.
  • *imagewin.color9 — Color used for the tileFrames highlight.
  • *imagewin.width — Width of the main image window.
  • *imagewin.height — Height of the main image window.
  • *pannerArea — Area in pixels of the panner window.
  • *pannerGeom — Where to place the panner window.
  • *wcsboxGeom — Where to place the coords box.
  • *maxContrast — Maximum contrast value.

✨ DESCRIPTION ✨

okay so picture this: XImtool is a display server, which means it runs as its own separate little process, totally independent from client software like IRAF. once it's up and vibing, it'll accept client connections simultaneously over fifo pipes, unix domain sockets, or inet sockets. a display client like the IRAF DISPLAY task just slides in, makes a connection, and sends the image over using a modified IIS Model 70 protocol. 💅

once the image is loaded into the display buffer, you can enhance it, save it to a disk file in a bunch of different formats, or print it as Encapsulated Postscript to a printer or a disk file. and bestie, you get up to sixteen frame buffers — they can all show at once in tiled mode, or you can blink them frame-to-frame. each frame can have its own colormap or its own brightness/contrast enhancement. Pan/Zoom and cursor readout work via markers, and there's on-line help too. it's giving everything. 🦋

when you run it in standalone mode, images can be loaded from the command line or through the Load Panel — and the formats currently allowed are IRAF OIF, GIF, Sun Rasterfiles, or simple FITS (i.e. not MEF files, sorry bestie 🙈). this lets you browse images and do all the same manipulations you'd get if a client had displayed them for you.

🖱️ MOUSE OPERATIONS

Clicking and dragging MB1 (mouse button 1) in the main image window creates a rectangular region marker, which you use to select a region of the image. if you did this on accident and you're sitting there like 😭, just put the pointer inside the marker and type DELETE or BACKSPACE to yeet the marker. with the pointer in the marker, MB3 calls up a marker menu listing some things you can do with the marker, like zooming the outlined region. MB1 can be used to drag or resize the marker. more marker lore below, keep reading. ✨

Clicking 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 makes a full-screen crosshair cursor appear until you release the button — super useful for fine positioning of the cursor, no cap. 🎯

MB3 is the glow-up button: it adjusts the contrast and brightness of the displayed image. where the pointer sits in 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:

🌸 Misc Functions 🌸

  • Ctrl-b — Previous (back) frame
  • Ctrl-c — Center frame
  • Ctrl-f — Forward frame
  • Ctrl-i — Invert colormap
  • Ctrl-m — Toggle magnifier
  • Ctrl-n — Normalize
  • Ctrl-p — Toggle panner
  • Ctrl-r — Register
  • Ctrl-s — Match LUT scaling
  • Ctrl-t — Tile frames toggle
  • Ctrl-u — Unzoom (zoom=1)
  • Ctrl-x — Flip X
  • Ctrl-y — Flip Y
  • Ctrl-= — Print using current setup
  • Ctrl-< — Decrease blink rate (blink faster)
  • Ctrl-> — Increase blink rate (blink slower)
  • Ctrl-+ — Zoom in
  • Ctrl-- — Zoom out
  • Alt-1 thru Alt-4 — Set frame to be displayed
  • Ctrl-1 thru Ctrl9 — Set integer zoom factor
  • Ctrl-Alt-q — Quit
  • Ctrl-Alt-f — Fitframe

🎀 Panel Toggles 🎀

  • Alt-b — Blink frames
  • Alt-c — Control panel
  • Alt-h — Help popup
  • Alt-i — Info box popup
  • Alt-l — Load file popup
  • Alt-p — Print popup
  • Alt-s — Save popup
  • Alt-t — TclShell popup

🦋 Cursor Positioning 🦋

  • Ctrl-h / Ctrl-Left — Move cursor one pixel left
  • Ctrl-j / Ctrl-Down — Move cursor one pixel down
  • Ctrl-k / Ctrl-Up — Move cursor one pixel up
  • Ctrl-l / Ctrl-Right — Move cursor one pixel right
  • Shift-Ctrl-h / Shift-Ctrl-Left — Move cursor ten pixels left
  • Shift-Ctrl-j / Shift-Ctrl-Down — Move cursor ten pixels down
  • Shift-Ctrl-k / Shift-Ctrl-Up — Move cursor ten pixels up
  • Shift-Ctrl-l / Shift-Ctrl-Right — Move cursor ten pixels right

⭐ Auto-Registration ⭐

  • Ctrl-a — Toggle auto-registration
  • Ctrl-o — Set frame offset

💜 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 centroiding box size
  • Ctrl-] — Increase centroiding box size
  • Ctrl-0 (zero) — Centroid/find local maximum
  • Alt-Ctrl-0 (zero) — Find local minimum

🖱️ Mouse Button Events 🖱️

  • Shift-Btn1Down — Turn on magnifier
  • Shift-Btn1Up — Turn off magnifier
  • Shift-Btn2Down — Turn on crosshair cursor
  • Shift-Btn2Up — Turn off crosshair cursor
  • Btn1Down — Create a Marker
  • Btn1Motion — Resize marker being created
  • Btn2Down — Zoom/center on cursor position
  • Btn3Down/Motion — Brightness/contrast scale the image
  • Ctrl-Btn1Down — Create Ruler Marker
  • Ctrl-Btn1Motion — Resize Ruler Marker being created
  • Ctrl-Btn1Up — Destroy Ruler Marker
  • Alt-Motion — Freeze cursor readout
NOTE: These keystrokes only work with the cursor in the main image window — only a few of the commands are implemented to work within subwindows or markers, and that's on purpose, to avoid conflicts with translations for those objects. so if a command isn't doing anything, check where your cursor is and try it again in the main display window. 🙈

🧚 FRAME BUFFER CONFIGURATIONS 🧚

XImtool starts up using a default frame buffer size of 512x512 pixels, and two (out of 16 possible) frames get created. when you're loading disk images (i.e. running in standalone mode), the frame buffer configuration file gets searched for a defined frame buffer that's the same size or larger than the current image — and if no suitable buffer can be found, a custom frame buffer the same size as the image gets created in an unused portion of the configuration table. ✨

when it's used as a display server, the frame buffer configuration number is passed in by the client and loaded explicitly, even if that means clipping the image. 😬 if a new frame buffer is a different size than previously defined frames, all available frames get initialized and cleared before the display. the default frame buffer configuration file is /usr/local/lib/imtoolrc, and you can override that by:

  • defining an IMTOOLRC environment variable naming the file to be used,
  • creating a .imtoolrc file in your home directory,
  • or specifying a new file with the -imtoolrc command line flag or the imtoolrc application resource.

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, each configuration may define up to 16 frames, and configuration numbers don't need to be sequential. go off. 👑

NOTE: When defining a new frame buffer for use with client software such as IRAF, the user must also remember to define those frame buffers in the IRAF dev$graphcap file. don't forget, bestie, it will not work otherwise. 💀

🌈 SUPPORT FOR 16 DISPLAY FRAMES 🌈

As part of the extensive GUI changes with the V1.3 release, support for the full 16 frames allowed by the IIS protocol is now available. IRAF V2.11.4 or later client tasks (and the CDL library) are required to take advantage of these frames. all the changes are backwards compatible — older versions of IRAF will keep working, they just can't 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. and the changes are fully backwards compatible for other servers too. 🫶

More frames are possible if needed, but that would require further changes to the client IRAF code to actually be effective. allowing creation of more than 16 frames by the Load panel can be done independently, but it would also require numerous code changes to XImtool. so please contact site support if you need this, or if you want workaround suggestions depending on your application. 💖

🎯 MARKERS 🎯

okay so bestie, real talk: ximtool doesn't really do much with markers right now, but markers are a whole general feature of the Gterm widget and other programs go absolutely feral with them (like, the prototype IRAF science GUI applications? they live there). XImtool uses markers for that marker zoom feature we talked about earlier, plus the panner and the coords box. And the way all markers share a bunch of the same traits? So worth it to learn the basic marker manipulation keystrokes. iykyk. 💅

  • MB1 anywhere inside a marker — drag the marker, slay, move it wherever.
  • MB1 near a marker corner or edge — resizes the marker (depends on the type of marker, so it's giving "it depends" energy).
  • Shift-MB1 on the corner of most markers — rotates the marker. yes, spin it. 🔄
  • Markers stack! if you've got several markers and you put one on top of another, that's the vibe. The active marker gets highlighted so you know which one in the stack is the one. If markers overlap, this is the marker "on top" in the stacking order.
  • MB2 in the body of a marker "lowers" it, i.e. moves it to the bottom of the stacking order. humble little marker. 🙇
  • Delete or backspace in a marker deletes it. bye bestie 💀
  • Markers have their own translation resources, so the default keystroke commands will not be recognized when the cursor is in a marker.
fr fr, try it: put 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, or you can reset the toggle in the control panel). 🎀

🗺️ PANNER MARKER

The panner window always displays the full frame buffer. no cap. 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. it's giving cartography. 🧚

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 hitting MB2 in the main display window to pan the image.

The panner marker can be disabled by defining the displayPanner GUI resource, its size and location can be controlled using the pannerArea and pannerGeom GUI resources respectively.

🔍 MAGNIFIER MARKER

The magnifier marker can be used to zoom in on a small area around the cursor. It will be updated as the cursor moves but only for small motions (either mouse movement or with the cursor movement keystrokes) to minimize the impact on the system. considerate queen. 👑

The zoom factor is expressed as some fraction of the size of the magnifier marker itself. The default zoom is 4, i.e. the area in the marker represents and area in the image that's one-fourth the size of the marker. Other zoom factors may be selected using the popup menu created by hitting MB1 in the marker.

By default the magnifier marker is not visible, to toggle it select the Magnifier option from the Options menubar button. Alternatively, for just a quick look holding down the Shift and MB2 buttons will display the marker until the button is released. peekaboo ✨

The magnifier marker can be disabled by defining the displayMagnifier GUI resource, its size and location can be controlled using the magnifierArea and magnifierGeom GUI resources respectively.

📦 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 linear 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 text marker, it can be moved and resized with the pointer like any other marker. The coords box marker can be disabled by defining the displayCoords GUI resource, its location can be controlled by the wcsboxGeom GUI resource.

🎛️ MARKER MENU OPTIONS

Except for the panner and WCS markers, MB3 (mouse button 3) calls up the marker menu providing a limited set of functions common to all markers:

  • Zoom — does an equal aspect zoom of the region outlined by the marker. In this way you can mark a region of the image and zoom it up. 🔎
  • Fill — exactly zooms the area outlined by the marker, making it fill the display window. Since the marker is not likely to be exactly square, the aspect ratio of the resultant image will not be unitary. it's giving stretched, bestie.
  • Print — prints the region outlined by the marker to the printer or file currently configured by the Print Panel.
  • Save — saves the region outlined by the marker to the file currently configured by the Save Panel.
  • Info — prints a description of the marked region. The text is printed in the Info Panel.
  • Unrotate — unrotates a rotated marker.
  • Color — is a menu of possible marker colors. 🎨
  • Type — is a menu of possible marker types. This is still a little buggy and it isn't very useful, but you can use it to play with different types of markers.
  • Destroy — destroys the marker. You can also hit the delete or backspace key in a marker to destroy the marker. 💀

📏 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. go off, measure everything. 📐

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:

  • Sticky — 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.
  • Units — 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.
  • Color — Select the color of the marker.
  • Draw into Frame — (Not Yet Implemented) Draw the marker as overlay graphics in the frame. Doing so will retain the marker when printing a hardcopy of the display.
  • Destroy — Destroy the marker.
    • 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. 🙈

✨ REAL-TIME WCS/PIXEL-VALUE READOUT ✨

okay bestie so this is the glow-up 💅 — XImtool can now show you the actual pixel value of an image (on top of the scaled value it was already showing you) and the cursor position in image WCS values (think RA/DEC, GLAT/GLONG, all that celestial goodness 🌌).

how does it pull this off? with an external task — the ism_wcspix.e binary in the new distribution — which goes and grabs the image and hands the coordinate/pixel info over to the GUI. teamwork fr fr 🤝

WCS readout is enabled by default 🎀 but you can toggle or reset it with the WCS/Pix button on the Coords tab in the control panel, or the ISM toggle on the alt-gui menubar. When it's on, images currently in the server (or any that show up later) get passed to that external process where they're cached for access. Every cursor movement fires off an event that maps the current frame buffer position onto a position in the cached image. then the ISM (that's Image Support Module, iykyk) task reads the image to figure out the pixel value (or a lil table of values around wherever you're sitting), and computes one or more coordinates from that image position. The ISM task also has access to the associated BPM images and can optionally return bad pixel info during the cursor readout. 👑

By default you get the logical and world image coordinates shown in BOTH the Coords panel readout AND the main display window wcsbox text marker. Want alternate coordinate systems? (like transforming equatorial to galactic or some other sky system, physical coords, amplifier coords, etc.) Just hit the Options toggle on the Coords panel. 🦋

  • coordinate systems → chosen with the Type menu on the panel
  • readout format (sexigesimal, degrees, etc) → the Format menu
  • where it goes (current panel vs main image window) → the remaining toggles, one per WCS

You can display up to four systems at one time 🔥 and the coordinate panel and wcsbox marker will auto-resize depending on what you're showing. main character energy, honestly.

Now — selecting the BPM Data toggle from the Coords.Options panel lets ximtool flag pixels in images that have an associated bad pixel mask. This mask is currently assumed, by convention, to be named in the image header with the "BPM" keyword. If your cursor passes over a bad pixel in the mask, the Coords bpm display AND the main window wcsbox will flip to a red background color. 🚨 Only the Coords display shows the value, and any non-zero value gets flagged with that color change.

With the ISM enabled, the Compass indicator shows you a set of arrows pointing North-East if a WCS is available — otherwise it just shows the current X-Y axes. And the pixel table? It displays the actual pixel values from the image. ISM off? The pixel table shows the scaled image values from the frame buffer instead. 💫

🥶 FREEZING CURSOR READOUT 🥶

Hold down the Alt key and boom — the cursor display readout freezes, and crosshairs get drawn on the screen at that last position. 🎯

why is this iconic? because you can position your cursor, then go move your actual cursor to another window (to type text, start a program, literally whatever) and you won't lose the position information displayed on screen. no cap, game changer. 🫶

✂️ CUT-GRAPHS ✂️

XImtool can now show horizontal and vertical cut-graphs of the display 📊 — they pop out as "flip-out" panels on the bottom and right side of the main display window, and they're controlled by the lil "H" and "V" buttons in the lower right corner of the window.

When both panels are enabled, that corner area of the display also shows an options panel for the graphs. Current options are:

  • Better Speed — 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.
  • Better Accuracy — 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, but older machines may want to use this only occasionally to limit any lag in the cursor tracking.
  • Image Pixels — (Not Yet Implemented) 🙈
  • Jump Cursor — If enabled, large jumps of the cursor do not update the graphics display, while small movements around an object of interest will update the display continuously.
  • Smooth Cursor — If enabled, all cursor movements cause the display to be updated. Another one of those options you can safely set on faster machines, but it will cause a delay on slower ones.
  • Graphics Cursors — 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. The example use case: freeze the cursor in the main display using the Alt key (see above ☝️), then move to one of the graphics windows to perform cut graphs in only one axis.
heads up bestie: 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. 💜

🎯 PEAK-UP CURSOR CENTROID POSITIONING 🎯

there are several new keystroke commands to reposition the cursor to a centroid or min/max pixel value within a bounding box around the cursor position ✨ — so you can approximate the position with the mouse and fine-tune it fast before typing the application keystroke command. slay.

The initial box size is controlled with a centerBoxSize GUI resource (defaults to 5 pixels) but you can adjust it interactively with the Ctrl-[ and Ctrl-] commands to decrease/increase the box size respectively. A marker will flash briefly to show you the 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) finds the local minimum value. Either way, the cursor gets repositioned to the computed value. 🌀

The default peak-up action is to find the centroid position in the box — but you can change it to find the max pixel by selecting 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. ⚠️

⌨️ 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

🎀 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

🔗 AUTO-REGISTRATION OF IMAGES 🔗

The auto-register feature lets 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. 🌈

For example, to use this feature do the following:

  1. Enable Auto-Register (either on the Control 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 (Ctrl-zero) 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 — 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 autoreg is enabled.

Hitting Register will zero the offsets, and so will toggling the auto-register function. What you should see: the object centered in the frame, and as you blink through it stays 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 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. 🔥

⌨️ Command Summary ⌨️

  • Ctrl-o — Set the registration offset from center
  • Ctrl-a — Toggle the Auto-Register feature

🎛️ CONTROL PANEL 🎛️

ok so XImtool has a whole control panel bestie, and it's literally how you drive almost every single thing the program can do with image display. you can get to it two ways: either through the Options menu up in the main window menubar, or by smashing the leftmost button in that row of buttons at the upper right side of the display in the standard GUI 💅. (and if you're living in the alternate GUI era, the Control Bar — which you reach with the rightmost button on the menubar — gives you widgets for picking whichever control panel you want. iykyk.)

and here's the glow-up: those separate windows we used to have for Control/Print/Load/Save/etc? they're all ONE window now ✨ and you just pick the right control panel with a Tab widget. iconic. there are also brand new Tab panels for setting the frame tile configuration (more on that below ⬇️), for getting way more detailed info on the server status, and for picking your WCS readout options (also below).

🔍 VIEW CONTROLS

the Frame box only lists the frame buffers you've actually got defined right now, no cap. and lowkey? the only way to destroy a frame buffer at the moment is to change the frame buffer configuration. new frame buffers (up to 16 of them 🫶) get created automatically whenever a client asks for one. and if you wanna control how many get made at startup, that's the -nframes command-line switch or the defNFrames resource, your call bestie.

the text display window spills all the tea: the field X,Y center, the X,Y scale factors, the X,Y zoom factors, and the frame offset used in Auto-Registration. heads up tho — the scale factor and the zoom factor are gonna be the same unless autoscale is enabled. the scale is in units of display pixels per frame buffer pixel, and it's an absolute measure (it does NOT care whether autoscale is on or off, fr fr). Zoom is relative to the autoscale factor, which is 1.0 if autoscaling is disabled. and guess what — all of this is also sitting pretty in the Info panel. 💅

the numbers in the Zoom box are zoom factors. blue numbers zoom, red numbers dezoom 🌈. Zoom In and Zoom Out take you to bigger or smaller zoom factors — like, Ctrl-5 followed by "Zoom In" gets you to zoom factor 10 🔥. and you can also jump straight to specific zoom factors as Control keystrokes, e.g. Ctrl-5 sets zoom factor 5, periodt. Center centers the field. Toggle Zoom flips between your current zoom/center values and the unzoomed image, chef's kiss.

Aspect recomputes the view so the aspect ratio is 1.0. Aspect also integerizes the zoom factor — so if you do NOT want integerization, use the version in the View menu instead, okay? 🎀

Fit Frame makes the display window the same size as the frame buffer. ngl, autoscale basically does the same thing, AND it lets you resize the display window to whatever size you want, or view images too big to fit on the screen. main character energy tbh. 👑

✨ ENHANCEMENT CONTROLS ✨

at the top there's a scrolled list of ALL the available colormaps. click the one you want to load, that's it 💖. and you can add your own colormaps to this list by defining the cmap[12] or cmapDir[12] command line flags or application resources. go off.

the two sliders adjust the contrast (upper slider) and the brightness (lower slider) of the display. the Invert button inverts the colormap (it multiplies the contrast by -1.0, cute). ⚠️ but real talk — because of the private colormap situation, the sliders are a bit sluggish when you drag them to window the display. if that's annoying you (and it would annoy me 😭), using MB3 in the display window is faster. noted.

the Normalize button (down at the bottom of the control panel) normalizes the enhancement, i.e. it sets the contrast and brightness back to the default one-to-one values (1.0, 0.5). this is the preferred setting for lots of the pseudocolor colortables and for private colormaps loaded from disk images 🍓. and the Initialize button? that does a reset of the server. boom.

Blink frames is the list of frames that get blinked. when blink mode is in effect, ximtool just cycles through these frames endlessly, pausing "blink rate" seconds between each frame. and yes — the same frame can show up in the list more than once, we don't gatekeep. 🙈

to program an arbitrary list of blink frames, hit the Reset button and click on each blink frame button until it's set to the frame number you want. the main control panel only lets you specify the original four frames in the blink list — but bestie, you can get to the full list of 16 frames now supported by using the box icon button right next to the Reset button to bring up a new control panel. slay. 💅

the Blink Rate can be adjusted as slow or as fast as you want with the arrow buttons. and if you set the blink rate small enough, it'll go all the way to zero, which enables single step mode (see below ⬇️).

the Register button registers all the blink frames with the current display frame. frames that aren't in the blink list? untouched, not affected, they're fine.

the Match LUTs button sets the enhancement of all blink frames to the same values as the display frame. and again — frames not in the blink list are NOT affected. 🫶

the Blink button turns blink on and off. when the blink rate is set to zero, the Blink button will single step through the blink frames, one frame per button press. one. frame. per. press. ⭐

NOTE: you can blink no matter what ximtool options are in effect, but a lot of those options will slow blink down. for the fastest blink you may want to turn off the panner and coords box, and match the LUTs of all the blink frames. also good to know: all the ximtool controls are fully active during blink mode, plus you can load frames etc. so go wild 🌈

🌸 OPTIONS: 🌸

  • Panner — toggles whether to display the Panner marker.
  • Magnifier — toggles whether to display the Magnifier marker.
  • Coords Box — toggles whether to display the coordinate box marker.
  • Autoscale — if autoscale is enabled, then at zoom=1 the frame buffer gets automatically scaled to fit inside the display window. with autoscale disabled (which is the default btw), the image scale is more predictable — but the image may get clipped by the display window, or it might not fill the display window at all. tradeoffs, bestie.
  • Antialias — when you're dezooming an image (i.e. displaying a big image in a smaller display window), antialiasing makes ALL the data get used to compute the displayed image. if antialiasing is disabled, then the image gets subsampled to compute the displayed image instead. antialiasing can stop subsampling from omitting image features that don't happen to fall in the sample grid — BUT it is significantly slower than dezooming via subsampling. the default is no antialiasing. ⭐
  • Tile Frames — the default display mode is one frame at a time. in tile frames mode, 2 or 4 frames may be viewed simultaneously in the display window 👀. and all the usual operations (zoom and pan, colortable enhancement, cursor readback, etc.) still work for each frame even when you're in tile frames mode. we love a feature that plays nice.
  • Warnings — the warnings option toggles whether you see warning dialog boxes in situations like overwriting an existing file, clearing the frame buffer, etc. 😭
  • Centroid Peaks — if enabled, the Ctrl-0 keystroke will reposition the cursor to the computed centroid of the centroiding box. otherwise, the cursor gets repositioned to the local maximum value within the box. 💅

💾 LOAD PANEL 💾

okay bestie, the Load Panel is where you grab images off your disk and yeet them straight into the frame buffer — literally the same thing as loading an image on the command line, except now you get to browse like a main character instead of typing paths like a peasant. At present the recognized formats include IRAF OIF format (that's the .imh extension bestie), 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 (meaning that changing the brightness/contrast enhancements will render an apparently random-colored image 😭), all others will be loaded with a grayscale colormap.

When loading new images the frame buffer configuration table 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 on the main Display panel will scale the entire image to fit the main display window, the full frame buffer will always be visible in the Panner marker window. ✨

Images with more colors than can be displayed will automatically be quantized to the number of available colors before display. If the Auto Grayscale button is enabled any image colormap will be converted to grayscale and loaded as the standard grayscale colormap.

Formats which permit pixels larger than 8-bits/pixel will be sampled on a grid to determine an optimal range in the data to be used to compute a linear transformation to the number of display colors. This is the same z-scale sampling and transformation used by the IRAF DISPLAY task when computing the z1/z2 values and provides a much better initial display than simple truncation to 8-bits. This scaling will be done automatically using a grid of Nsample points if the Zscale option is enabled. Otherwise, if the Zrange option is set the full data range will be used to scale the image. Lastly, is neither Zscale nor Zrange are enabled, the z1/z2 values may be set explicitly using the options box.

📁 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 otherwise an error popup will appear. Directories in the list are identified with a trailing '/' character, you will always see any subdirectories listed 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.

Selecting the List Image Headers option will change the display text to list all images in the current directory which match the filename filter. Directory browsing is disabled while this option is in effect.

🎀 File Patterns

By default all files and directories will be listed. You may specify a filter to select only those files with a given extension such as "*.fits" using the Filter text box. Directories will always be seen in the list and are identified with a trailing '/' character. Any valid unix pattern matching string will be recognized, multiple templates may be specified in a comma-delimited list such as "*.imh,*.fits" to list both OIF and FITS images.

🦋 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 <cr> 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 the current frame, you may choose a different frame using the Frame menu button to select from the available frames.

💖 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, 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 or zoom out so the whole buffer is in the display window. 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 however not all formats are currently implemented. The EPS format is similar to the Print option however there is no annotation.
  • 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 enabled. 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.

The Print Panel allows you dump the contents of the main display window as Encapsulated 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 and enhancements.

⭐ 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. No checking is done to make sure the image will fit correctly on the page.

🔥 PROCESSING OPTIONS

  • 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 determine the output image size, otherwise the image will be scaled down (if necessary) to fit on the page.
  • 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, otherwise the image may be scaled so that it fits in the current orientation.
  • Max Aspect — 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. There is currently no option for partial annotation.

💅 ANNOTATION OPTIONS

  • Annotate — Selects whether Postscript image is to be annotated.
  • Title — Annotate with a title on the top of the image.
  • Borders — Annotate with borders surrounding the image giving image coordinates.
  • Colorbar — Annotate with colorbar at the bottom of the image
  • Title String — Title string to use when title is selected. The special value imtitle will force the title to be the currently displayed image title, otherwise it will be this user-selected field.

👑 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 command line switch or printConfig resource. The format of the file is simply

name\tcommand

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

  • Frame — Info about the current display frame.
  • Server — Info about various server options, e.g. colormaps, memory model, antialias type, etc.
  • Clients — Show currently connected clients. Lists available connection channels and active ISM clients.
  • WCS — List all WCS and mappings for the current frame.
  • ISM — Log of various ISM status messages.
  • Imtoolrc — Show current frame buffer configuration table.

🌈 TILE PANEL (NEW) 🌈

ok so with all these extra frames floating around, the old default tiling scheme was not it anymore, bestie. so there's a brand-new control panel Tile frame now that lets you pick from a whole bunch of tile configurations, choose which frames get tiled, pick a fill style (left-to-right or top-to-bottom), plus optional labels for each tile — frame number, image title, or image name. cute, right? 🎀

Tile configuration uses all frames currently selected in the Tile Frame group, and it goes like this:

  • Disabled — literally just don't tile the display, periodt.
  • Manual — tile it according to your Manual Configuration settings.
  • Best — optimizes the layout for the frame buffer aspect 💅
  • Square — always forces a square layout (2x2, 3x3, etc).
  • Horizontal — prefers tiling horizontally (6 frames ==> 3x2).
  • Vertical — prefers tiling vertically (6 frames ==> 2x3).
  • One Row — tiles everything in one row (Nx1).
  • One Column — tiles everything in one column (1xN).

🦋 COORDS PANEL (NEW) 🦋

The Coords Panel is giving full-featured readout and control panel for all the various options, simultaneously, no cap. The display window holds the image name/title and frame buffer info, plus a selection of coordinate and image pixel readouts. The whole intent? Deliver more info than could ever fit comfortably on the main image window, while still taking up as little screen space as possible. To that end, the "Options" button hides most of the feature controls when they're not in use (more below). Other options on the main panel include:

  • WCS/Pix — toggles 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, so like, turn it on bestie.
  • Pix Table — opens 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 is selectable from the menubar.
  • Header — displays the current image header in a new panel. Both the entire image header and the WCS-specific parts of the header are available under different tabs. This option is only active when the ISM is enabled.
  • Compass — draws an orientation compass on the display panner. If the ISM is enabled and a WCS is present in the header, the compass indicates N/E according to the WCS; otherwise the X/Y axes of the image get drawn instead.
  • Options — pops up/down the option control portion of the panel. When enabled, the Coords Panel changes size to reveal the options you can change (explained below 👇).

The "Readout Values" group controls the selection of WCS type, location, and format to be displayed. The "Type" menu always gives you 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, additional entries for transformations to other sky systems (e.g. FK5 to ICRS or galactic/ecliptic) will also be available. The selection depends on whether the ISM is running and on the WCS information present in the image. The "Format" menu lets you select a sexigesimal display, conversion to degrees or radians, or whichever format is most natural for the coordinate being displayed ✨. The two toggles to the right control whether this WCS is 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 causes 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 that value 🚩.

The last box lets you specify a different ISM task to be executed, or 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.

💜 TCLSHELL 💜

The TclShell lets you type commands directly to the TCL interpreter — so you can send messages to the object manager or execute specific procedures in the TCL code that makes up the GUI. It's a development/debugging tool for the GUI, but if you wanna see what it does, just bring it up and type a command like

send fileButton set background red

and watch it slay 🔥

🌈 COLORMAP SELECTION 🌈

okay bestie so by default XImtool shows images using either a grayscale colormap (like, when it's loaded by a client) or a private colormap when you load an image from disk that already has a colormap baked in. and the slay part? every single frame defines its own colormap, so you can set up different colormaps or enhancements per frame and they'll just auto-switch as you cycle through the frames. main character behavior fr fr. 💅

✨ BUILTIN COLORMAPS ✨

once it's loaded, you can change the colormap either from 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, and other user-defined colormaps may optionally be loaded too. but ngl, it is not presently possible to save colormaps for later use — so don't get attached bestie 😭

🎀 USER-DEFINED COLORMAPS 🎀

the cmap[12] and cmapDir[12] resources (or the command line arguments) are how you tell XImtool which specific colormaps to make available, or where to go looking for colortables. these colortables get loaded when ximtool starts up, or when it gets reinitialized (like, say, by pressing the Initialize button in the control panel). XImtool will ignore any files in the colormap directory that don't look like colortables — it's picky, it has taste. ✨ new colortables also get added automatically for each image loaded from disk.

the format of a user lookup table is genuinely so simple it's giving minimalism: each row defines one colortable entry, and it's just 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 (lines beginning with a #) are ignored. 🫶

usually 256 rows are provided, but honestly the number can be anything in the range 1 to 256. XImtool will interpolate the table as necessary to compute the colortable values used in XImtool. and heads up: XImtool uses at most 201 colors to render pixel data, so it's usually necessary to interpolate the table when it's loaded.

the name of the colortable as it'll show up in the XImtool control panel is the root name of the file — like, if the file is "rainbow.lut" then the colortable name is gonna be "rainbow". lower case names are suggested so you avoid name collisions with the builtin colortables. 💖 private colormaps for disk images will have the same name as the image loaded. and if the same colortable file shows up in multiple user colortable directories, the first one found gets used. periodt.

🦋 MINIMIZING COLORMAP CONFLICTS 🦋

the Gterm widget that XImtool uses (i.e. the main display window) uses a private global colormap for display, which lets it have way more control over color cell allocation but can also occasionally cause "colormap flashing" as the mouse moves in and out of the application. the problem here is that on a system with only an 8-bit colormap (256 colors), every app has to fight for colors — programs like XV or Netscape allocate colors from the default colormap, leaving only a few free cells for XImtool. since XImtool defines a private global colormap it's still able to allocate the needed cells rather than failing, but it's allocating cells that other applications already used. as the mouse moves out of the ximtool window those cells are once again defined in terms of the default colormap, so the ximtool window is then using a different colormap. it's this switching of the colormap context that causes the flashing to occur 😭 but there are a few things you can do to help minimize it.

XImtool logically defines 200 colors which the client image display program can use to render pixels. however, ximtool may or may not actually allocate all of those colors. by default it currently allocates only about 192 colors, to reserve 64 colors for the other windows on the screen. you don't normally notice this because 1) usually the default screen colormap has enough free cells to let ximtool match the colors, and 2) the extra unallocated cells correspond to the brightest pixels in the rendered image, and these colors may not be used or usually only correspond to a few small regions near the saturated cores of bright objects.

you can eliminate this problem by setting the basePixel resource to e.g. 48 instead of 64, which will let the gterm widget allocate all 200 colors. however, this isn't recommended for normal use as it'll increase the likelihood of colormap flashing. ⚠️ if you change basePixel, either restart the X server or set the resource cmapInitialize=True to force the gterm widget to update its global colormap resource in the X server. the colormap resource may also be deleted by using the command:

          xprop -root -remove GT_image

these options may also be set on the command line when first starting up. 👑

in general one can set the Gterm widget resources basePixel and maxColors to specify the region of colormap space to be used for image display. if you set maxColors to a small value, the 200 logical colors defined by the widget will be mapped by the imtool color model into whatever number of colors are actually available to the widget. for example, in the default setup, 200 color values are really being mapped into 192 color cells used for display, and the remaining colors are used for buttons, menus etc and are allocated from the default colormap by the X toolkit when the application starts up.

even though the Gterm widget uses a private colormap, it's a private global colormap — meaning all Gterm widgets share the same colormap. an example of colormap sharing in ximtool is the main image window and the colorbar window. these are two separate gterm widgets that share the same colormap. they have to share the same colormap, because otherwise when you windowed the main image window the colorbar window wouldn't accurately reflect the modified colormap. by default two separate ximtools would also share the same colormap, meaning contrast enhancements in one window would affect the other. by resetting the cmapName command line option or resource you can change the name of the private colormap used, causing separate ximtools to use different colormaps — but note this also creates colormap flashing between the two windows that can't easily be avoided 😬 by setting the cmapName to "default" the widget will allocate colors from the default colormap, but this is of little use at the moment.

there are a number of other resources that can be used to modify the behavior of the Gterm widget color management scheme, but these are the most useful ones. 💅

💌 DISPLAY CLIENT CONNECTIONS 💌

XImtool allows display clients to connect in any of the following ways:

fifo pipes

the traditional approach, the OG. the default global /dev/imt1[io] pipes may be used, or a private set of fifos can be specified using the -fifo command line argument or *fifo resource. values should be specified as the root pathname to a pair of fifo pipes whose last character is 'i' or 'o', and these characters will be added automatically when opening the pipes. for example, to use the default pipes the path would be specified as simply "/dev/imt1". a value of "none" disables this connection.

tcp/ip sockets

clients connect via a tcp/ip socket. the default port is 5137, or a custom port may be specified using the -port command line switch or a *port resource. this permits connecting to the server over a remote network connection anywhere on the Internet. 🌐 a port number of 0 (zero) disables this connection.

unix domain sockets

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. the default value is "/tmp/.IMT%d", and other sockets may be defined using the -unix command line switch or the *unixaddr resource. legal values should be specified as a filename to be used for the socket, up to two "%d" fields are allowed and will be replaced by the userid. an empty string value disables this connection.

by default ximtool listens simultaneously for client connections on all three types of ports. clients may connect simultaneously by different means, allowing up to three different displays to be loading at the same time into different frames. ✨

💻 COMMUNICATIONS PROTOCOL 💻

the communications protocol used is a slightly modified version of that used by the IIS Model 70; other more modern protocols will likely be supported in the future. the IIS protocol is basically a command packet stream with a header describing the operation to be performed (select frame, load display, read cursor, etc), and an optional data packet containing e.g. pixels.

beginning with XImtool V1.3 the protocol was modified even more to allow extra text at the end of the WCS string to define image mappings and to better support multiple world coordinate systems within a frame. for backwards compatibility 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 let us 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, and 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. 👇

📡 IIS PROTOCOL SUMMARY 📡

all operations are initiated by sending a header packet containing a thing id (tid) and subunit selecting the function to be performed, optionally followed by data up to 32Kb long. the IIS header packet used is defined as:

        struct  iism70 {
                short   tid;
                short   thingct;
                short   subunit;
                short   checksum;
                short   x, y, z;
                short   t;
        };

Okay so the thing count field is holding the negative number of bytes of data that are gonna get sent right after the header packet 💀 (yes, negative, that's the bit). And the IIS header checksum is computed like this:

checksum = 0177777 - (tid + subunit + thingct + x + y + z + t);

The four IIS registers get set differently depending on which operation you're doing, so here's the whole breakdown, bestie:

IIS Header Packet Summary

  • Read Data — TID IIS_READ|PACKED, Subunit MEMORY, Tct -NB, X x, Y y, Z fr, T -, Data NB
  • Write Data — TID IIS_WRITE|PACKED, Subunit MEMORY, Tct -NB, X x, Y y, Z fr, T -, Data NB
  • Read Cursor — TID IIS_READ, Subunit IMCURSOR, Tct -, X -, Y -, Z -, T -, Data -
  • Write Cursor — TID IIS_WRITE, Subunit IMCURSOR, Tct -, X x, Y y, Z wcs, T -, Data -
  • Set Frame — TID IIS_WRITE, Subunit LUT|COMMAND, Tct -1, X -, Y -, Z -, T -, Data 2
  • Erase Frame — TID IIS_WRITE | fb, Subunit FEEDBACK, Tct -, X -, Y -, Z fr, T -, Data -
  • Old Write WCS — TID IIS_WRITE|PACKED, Subunit WCS, Tct -N, X -, Y -, Z fr, T fb, Data 320
  • Old Read WCS — TID IIS_READ, Subunit WCS, Tct -, X -, Y -, Z fr, T wcs, Data 320
  • WCS Version? — TID IIS_READ, Subunit WCS, Tct -, X 1, Y 1, Z -, T -, Data 320
  • WCS by Number? — TID IIS_READ, Subunit WCS, Tct -, X 1, Y -, Z fr, T wcs, Data 1024
  • New Write WCS — TID IIS_WRITE|PACKED, Subunit WCS, Tct -N, X 1, Y -, Z fr, T fb, Data 1024
  • New Read WCS — TID IIS_READ, Subunit WCS, Tct -, X 1, Y -, Z fr, T wcs, Data 1024

And here's what all those little letters actually mean, no gatekeeping:

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

And the actual values for all the flags, so you don't have to guess 🌸:

IIS_WRITE     = 0400000
IIS_READ      = 0100000
COMMAND       = 0100000
PACKED        = 0040000
IMC_SAMPLE    = 0040000

MEMORY        = 001
LUT           = 002
FEEDBACK      = 005
IMCURSOR      = 020
WCS           = 021

TID fields can be logically OR'd with the PACKED flag, and what that means is the number of data bytes is exactly thingct bytes long — otherwise thingct has to be specified as half the number of data bytes, okay? 🫶 And in a cursor read, if the IIS_READ flag is OR'd with IMC_SAMPLE, the logical cursor position (i.e. the last value read or set) gets returned immediately, otherwise the server will literally just wait for a keystroke to be hit before returning a string containing the (x,y) position, wcs of the read, and the keystroke. When setting the frame you must send a short integer in the data containing the frame selected. no cap.

🌈 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 they 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 brand new GUI code to create panels and new objects 👑. it's giving versatile.

🔌 ISM 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 — that's the bit that lets multiple users on a machine have independent sockets, iconic 💅. The XImtool ism_addr resource or "-ismdev" command-line option can be used to change this address, and 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. (yes, it outranks them. the way that it does.)

Once a connection request is received, XImtool replies with a message telling the ISM to reconnect on a different socket, and then it 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. main character energy fr fr ✨

📨 COMMUNICATIONS PROTOCOL 📨

Messages from the ISM are written to the connection socket and must be preceded 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

Where messages are of the form:

  • connect <name> — Request a connection for the <name> ISM
  • ready <name> — Reconnection request for the <name> ISM on negotiated socket, ISM is ready to processing.
  • send <obj> '{' <msg> '}' — Send <msg> to the named <obj>. 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).
  • quit — ISM 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.
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. 💀 don't say we didn't warn you.

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. periodt 🎀

okay so the content of messages delivered to the ISM? totally free-form. like, they may contain any text the ISM is expected to understand. no formatting police here 💀✨

GUI OBJECTS 💅

So the ISM can send a message to any object in the task, but there's this GUI Parameter object called ism_msg that's designed especially to process messages from the ISM. The callback in the GUI is expecting a message beginning with one of these keywords:

  • source — source message text as Tcl code. yes bestie, it's Tcl.
  • alert — message contains error text to be displayed in the GUI alert box. it's giving red flag but make it visible 😭
  • deliver — message text should be passed to a callback routine specific to that ISM. that processing callback may have been previously uploaded. the message text may be any form the processing callback is expected to understand. flexible much?
  • info — message text is status output intended for the XImtool info panel (connect/disconnect requests, etc). keeping you in the loop, fr fr.

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

ENVIRONMENT 🌸

  • HOME — specifies user login directory. your home sweet home.
  • DISPLAY — specifies which display screen to use. pick your screen, main character.
  • IMTOOLRC or imtoolrc — frame buffer configuration file. the config bestie.
  • ISMDEV — ISM connection socket. the plug.
  • DEBUG_IIS — debug IIS communications packets. if you need to snoop.
  • DEBUG_ISM — debug ISM communications packets. more snooping.
  • DEBUG_MAPPINGS — debug WCS image mappings. mapping tea 🍓

FILES 🎀

  • /usr/local/lib/imtoolrc — default frame buffer configuration file
  • /usr/local/lib/ximprint.cfg — default printer configuration file
  • /usr/local/lib/imtoolcmap — default colormap directory
  • /dev/imt1i — default input display fifo
  • /dev/imt1o — default output display fifo
  • /tmp/.IMT%d — default unix display socket
  • /tmp/.ISM%d — default unix ISM connection socket

BUGS 😭

Users should report bugs to https://github.io/iraf-community/x11iraf. do it, don't be shy.

SEE ALSO ✨

Copyright(c) 1986 Association of Universities for Research in Astronomy Inc.

this page is from the X11IRAF Project, dated 12 Aug 2001, for XIMTOOL(1) — k bye bestie 🫶✨

📦 where this page comes from