The ds9 Array (Developer Reference) The ds9 Array (Developer Reference)DS9's Tcl library (ds9/library/*.tcl) keeps most of the application's live state in one global array, ds9. A script running via the -tcl command line option, a ~/.ds9.ini (or ~/ds9.ini) startup file, or the tcl XPA access point runs in the global namespace and can read (and, for the elements marked below, usefully write) this array directly, e.g.:
global ds9
puts "there are [llength $ds9(frames)] frames, current display mode is $ds9(display)"This page documents every element of ds9 as of this checkout, derived from its initialization in ds9/library/ds9.tcl and its use across the rest of the library. Elements are grouped by what they track rather than listed alphabetically. See also The current Array, a smaller companion array tracking which frame/channel/mode is presently selected.
A note on pds9: user-facing preferences (background color, fonts, precision digits, confirm dialogs, SAMP/XPA startup, themes, and so on) live in a separate global array, pds9, which is what gets written to and read back from the preferences file. pds9 is out of scope for this page. A handful of legacy element names that look like ds9(bg), ds9(nan), ds9(confirm), ds9(dialog), ds9(language), ds9(font), ds9(font,size), ds9(font,style), ds9(samp)/ds9(samp,auto), ds9(xpa), ds9(automarker), ds9(backup), ds9(display,user), and ds9(analysis,user)/user2/user3/user4 only ever exist transiently, while restoring a backup/session file saved by a very old DS9 version; FixVar/FixVarRm in ds9/library/prefs.tcl immediately migrate them into pds9 (or current/panalysis) and delete them. They are not part of the live ds9 array and are omitted below.
Application identity, version, and startup
- ds9(app)
- String. The running executable's base name (normally ds9), derived from argv0. Also used to build the ~/.ds9.ini init-file name and the preferences file name. Read-only.
- ds9(version)
- String, e.g. 8.8. The major.minor release version. Read-only.
- ds9(version,display)
- String, e.g. 8.8. The full version string shown in the About box and title bar; may include a beta suffix. Read-only.
- ds9(wm)
- String: x11, aqua, or win32 — the result of tk windowingsystem. Used throughout the library to branch on platform. Read-only.
- ds9(root)
- String, a directory path. The DS9 installation root, used to locate bundled resources such as icons (see ds9(icons,*) below). Read-only.
- ds9(top)
- Widget path, always .. The main top-level window. Read-only.
- ds9(main)
- Widget path. The main ttk::frame that fills the top-level window and contains every other widget. Internal; read-only.
- ds9(mb)
- Widget path, always .mb. The menu bar's window path. Internal; read-only.
- ds9(visual)
- String, e.g. truecolor. The X/Tk visual class in use, from winfo visual. Read-only.
- ds9(depth)
- Integer, e.g. 24. The display color depth in bits, from winfo depth (normalized to 16/24 on odd depths like 15/32). Read-only.
- ds9(scaling)
- Real number, e.g. 1.0. The Tk display-scaling factor used for HiDPI adjustment (computed specially per platform because tk scaling alone isn't trustworthy). Read-only.
- ds9(threads)
- Integer. The default number of render threads, initialized from the detected core count (GetNumCores); can be overridden per-frame with the frame threads command. Safe to read; not normally written after startup.
- ds9(FTY_MAXAXES)
- Integer constant, 9. The maximum number of FITS axes DS9's IRAF/funtools (fty) support code will handle. Read-only.
- ds9(prefs)
- Boolean (0/1), default 1. Whether the preferences file was loaded/should be honored this session; can be turned off via a command line option. Effectively read-only after startup.
- ds9(init)
- Boolean (0/1). 1 only while DS9 is still starting up (before the main window is fully built); used to defer handling of early macOS Open/Print document events. Not useful to a script running after startup, since it will always read 0 by then. Read-only.
- ds9(themes)
- List of strings. The available ttk theme names (x11/win32 only), with alt and classic filtered out. Read-only; see pds9(theme) to change the active theme.
Fonts
- ds9(helvetica)
- String, a font family name. The sans-serif UI font family for this platform (with platform-specific fallbacks, e.g. .AppleSystemUIFont on macOS). Read-only; see pds9(font)/pds9(font,size)/pds9(font,style) to change the active UI font.
- ds9(courier)
- String, always courier. The monospace UI font family. Read-only.
- ds9(times)
- String, a font family name (serif on X11, times elsewhere). The serif UI font family. Read-only.
Frames and display mode
- ds9(frames)
- List of frame command names, e.g. {Frame1 Frame2}. Every frame currently in existence, in creation order. Read-only — create/delete frames via the normal frame-management commands, not by editing this list.
- ds9(active)
- List of frame command names. The frames considered "active" for the current display/lock mode (e.g. the frames a blink or tile-lock cycles through); order matters. Read-only.
- ds9(seq)
- Integer counter, starts at 1. The next sequence number to use when auto-naming a new frame (Frame<seq>); incremented on each new frame. Read-only in practice.
- ds9(last)
- Frame command name or {}. The previously-current frame, cached to short-circuit redundant "frame changed" work; scripts operating on current(frame) generally have no need to touch this. Internal; read-only.
- ds9(lock)
- Boolean (0/1). A general re-entrancy guard used while frame/crosshair/etc. lock updates are being propagated to other frames, to avoid recursive callbacks. Internal; do not set from a script.
- ds9(display)
- String: single, tile, blink, reveal, or fade. Mirrors current(display) — the frame display/layout mode. Read-only; change display mode via the normal current(display)-setting commands (e.g. the View/Frame menu equivalents) rather than writing this directly.
- ds9(row)
- Integer, -1 when unset. The currently highlighted row in the FITS bin-table row-selection UI. Internal; read-only.
- ds9(freeze)
- Boolean (0/1). When set, suppresses frame-list/menu rebuilds that would otherwise happen while frames are being added or removed in bulk (e.g. during a mosaic load), as an optimization. Internal; do not set from a script.
Mouse button and keyboard modifier state
- ds9(b1), ds9(b2), ds9(b3)
- Boolean (0/1) each. Whether mouse buttons 1/2/3 are currently held down over the main canvas. Read-only, maintained by button bindings.
- ds9(sb1), ds9(sb2), ds9(sb3)
- Boolean (0/1) each. Same, but for the current button state while holding Shift.
- ds9(cb1), ds9(cb2), ds9(cb3)
- Boolean (0/1) each. Same, but for the current button state while holding Control (or Command on macOS).
- ds9(csb1), ds9(csb2), ds9(csb3)
- Boolean (0/1) each. Same, but for the current button state while holding Control+Shift (or Command+Shift on macOS).
- ds9(modifier)
- Boolean (0/1). Whether a modifier key relevant to the current pointer mode is currently held. Internal; read-only.
- ds9(ctrl)
- String, either Control- or Command-. The platform-appropriate Tk event modifier prefix, used when building keyboard-shortcut event names (e.g. <${ds9(ctrl)}o>). Read-only.
- ds9(shiftctrl)
- String, either Shift-Control- or Shift-Command-. Same idea, for Shift+Control/Command shortcuts. Read-only.
Status/error messages
- ds9(msg)
- String. The most recently posted status/error message text, shown by the message timer. Setting it directly is unusual; use the library's Error/message-posting procs instead.
- ds9(msg,level)
- String, default info. The severity of ds9(msg) (e.g. info, error), used to pick how it's displayed.
- ds9(msg,src)
- String, default tcl. Where the pending message originated from.
- ds9(msg,timeout)
- Integer milliseconds, default 1000. How long the message timer waits between checks (an after interval), set up once at startup. Read-only after startup.
Raw data array load defaults
These hold the last-used (and default) parameters for the raw-array loader (mirrors the -array command line option and the frame load array command's implicit dimensions dialog); they are safe to set before invoking a raw array load to change its defaults.
- ds9(array,x), ds9(array,y)
- Integer, default 512 each. Default array width/height in pixels.
- ds9(array,bitpix)
- Integer, default -32 (IEEE 32-bit float, FITS BITPIX convention). Default array pixel data type.
- ds9(array,skip)
- Integer, default 0. Default number of leading bytes to skip (header size) before pixel data begins.
- ds9(array,arch)
- String, default bigendian. Default byte order of the raw array data.
Menu layout
These record fixed indices into the Frame and Analysis menus so the library can insert/remove the dynamic per-frame and per-task menu entries at the right position. They depend on platform (menus start at index 0 on macOS, 1 elsewhere) and on the static menu items defined above them; not meaningful to change from a script.
- ds9(menu,start)
- Integer, 0 (aqua) or 1 (x11/win32). Base menu index offset.
- ds9(menu,size,frame,goto)
- Integer. Menu index where the per-frame "goto" entries begin in the Frame menu.
- ds9(menu,size,frame,active)
- Integer. Menu index where the per-frame "active" checkbutton entries begin in the Frame menu.
- ds9(menu,size,analysis)
- Integer. Menu index where dynamically-loaded analysis-task entries begin in the Analysis menu.
- ds9(menu,size,wrap)
- Integer, 20. How many dynamic entries are placed before wrapping into a new menu column/submenu.
UI widget handles
These hold the Tk widget paths (and, for the icon directories, filesystem paths) of major pieces of the DS9 window, set once by the corresponding Create* procedure at startup. They're useful to read (e.g. to bind an event on $ds9(canvas), or to size a dialog relative to $ds9(top)) but should not be reassigned.
- ds9(canvas)
- Widget path. The main image display canvas — the Tk canvas that hosts every frame's canvas item, the panner, magnifier, colorbar, and markers. This is the single most useful handle for scripts doing custom canvas work, e.g. $ds9(canvas) itemcget $::current(frame) -width to get a frame's on-screen size.
- ds9(canvas,bottom)
- Widget path or {}. An optional frame packed below the canvas (layout-dependent).
- ds9(image)
- Widget path. The frame that directly contains the canvas.
- ds9(header)
- Widget path. The header bar frame (contains the info panel, panner, and magnifier).
- ds9(header,sep)
- Widget path. The separator below the header bar.
- ds9(info)
- Widget path. The info panel frame (coordinate/value readout).
- ds9(info,row,image), ds9(info,row,physical), ds9(info,row,amplifier), ds9(info,row,detector)
- Integer grid row numbers within $ds9(info) for each coordinate-system readout line, recorded so rows can be shown/hidden as the user toggles which coordinate systems are displayed.
- ds9(info,row,value), ds9(info,row,value,1), ds9(info,row,value,2), ds9(info,row,value,3)
- Integer grid row numbers within $ds9(info) for the pixel-value readout line(s) (single value, or up to three for RGB/multicolor frames).
- ds9(magnifier)
- Widget path. The magnifier panel frame.
- ds9(magnifier,canvas)
- Widget path. The magnifier's own small canvas widget.
- ds9(magnifier,minus), ds9(magnifier,plus)
- Widget paths. The magnifier's zoom-out/zoom-in buttons.
- ds9(panner)
- Widget path. The panner panel frame.
- ds9(panner,canvas)
- Widget path. The panner's own small canvas widget.
- ds9(panner,align)
- Widget path. The panner's WCS-alignment toggle button.
- ds9(panner,center)
- Widget path. The panner's "recenter" button.
- ds9(buttons)
- Widget path. The main button-bar frame.
- ds9(buttons,frame)
- Widget path. The outer frame holding the button bar (shown/hidden as a unit).
- ds9(buttons,aux)
- Widget path. The auxiliary (analysis-task) button bar frame; per-task sub-frames are stored as ds9(buttons,aux,<n>), not listed individually here.
- ds9(buttons,sep)
- Widget path. The separator above the button bar.
- ds9(icons,top), ds9(icons,bottom), ds9(icons,left)
- Widget paths. The icon toolbars docked at the top/bottom/left of the main window.
- ds9(icons,top,sep), ds9(icons,bottom,sep), ds9(icons,left,sep)
- Widget paths. The separators next to the corresponding icon toolbar.
- ds9(icons,ui), ds9(icons,lut), ds9(icons,colors)
- Filesystem directory paths (under $ds9(root)/icons/...) holding the toolbar-icon, colormap-preview, and named-color-swatch PNG files, respectively. Read-only.
Tile drag-and-drop
- ds9(tile,drag)
- Frame command name or unset. The frame currently being dragged in tile-mode drag-and-drop reordering.
- ds9(tile,drop)
- Frame command name or {}. The frame currently under the drag as a drop target.
- ds9(tile,drop,color)
- String, a saved color name. The drop target's original highlite color, saved so it can be restored after the drop-target highlight is removed.
Temporary files and OS document events
- ds9(tmpdir)
- Directory path, set by InitTempDir at startup. Where DS9 creates its own temporary files. Read-only.
- ds9(cacert,temp)
- File path or {}. A temporary extracted CA-certificate bundle path used for HTTPS connections, cleaned up on exit. Internal; read-only.
- ds9(event,opendoc)
- List, macOS only. Arguments from a macOS "open document" Apple Event received before startup finished, replayed once initialization completes. Internal; read-only.
- ds9(event,printdoc)
- List, macOS only. Same, for a "print document" Apple Event. Internal; read-only.