Frame Commands (Developer Reference)

Every DS9 frame is itself a Tcl canvas item with its own command name (e.g. Frame1, Frame2, ...; $::current(frame) always holds the name of the currently selected one — see The current Array). This page documents every command that name accepts — the frame-level grammar implemented by a bison/flex parser in tksao/frame/parser.Y and tksao/frame/lex.L in the DS9 source tree. It is one level below the Tcl library in ds9/library/*.tcl: most menu actions and XPA access points are themselves thin wrappers that eventually call one of these frame commands.

This is developer-level documentation aimed at scripting DS9 from the -tcl command line option, from a ~/.ds9.ini (or ~/ds9.ini) startup file (any Tcl file of that name in your home directory is automatically sourced once DS9 has finished starting up — see SourceInitFileDir in ds9/library/util.tcl), or from the tcl XPA access point. A typical invocation looks like:
set d [$::current(frame) get zoom] $::current(frame) pan 100 100 $::current(frame) marker create circle 256 256 20
All keywords are matched case-insensitively by the lexer (%option caseless), but are written lowercase by convention, which this page follows. get ... and has ... forms compute a value and return it as the result of the Tcl command — use set x [$::current(frame) get ...] to capture it; every other command performs an action on the frame and its Tcl return value is not meaningful. A handful of commands accept no arguments at all (e.g. center, show) and simply perform their action.

Numbers written <value> below accept either an integer or a real number. Where a command's arguments depend on a coordinate system or sky frame given earlier in the same command, see Common Parameter Types for the full set of choices — that section is referenced throughout instead of being repeated for every command.
Common Parameter Types bg bin block center clear clip colorbar colormap colorscale contour crop crosshair cube datasec debug fade fitsy get grid has hide highlite hls hsv iis iraf layer load macosx magnifier marker mask match multicolor nan orient pan panner postscript precision query region reset reveal rgb rotate save show smooth threads threed unload update version warp wcs win32 zoom
Common Parameter Types

These placeholders are used throughout this page instead of being spelled out in every command's syntax.

<value>

A plain number, e.g. 10 or -3.5.

<yesno>

yes (also y, on, true, or a non-zero integer) or no (also n, off, false, or 0).

<angle>

A plain number in degrees, or a number suffixed with d for degrees or r for radians (e.g. 90, 90d, 1.5708r).

<coordSystem>

image | physical | amplifier | detector | <wcsSystem>

<wcsSystem>

wcs (the primary/current WCS) or one of the 26 alternate WCS systems wcsa through wcsz that a FITS header may define (WCSAXES-style alternate WCS letters), or wcs0 (reset/none). Used for coordSystem above, and directly by load ... mosaic, wcs, and match.

<internalSystem>

canvas (screen pixels of the Tk canvas) or panner (screen pixels of the panner widget). Used where a command needs raw widget pixel coordinates rather than an image-based coordSystem.

<skyFrame>

fk4 (or b1950) | fk5 (or j2000) | icrs (default) | galactic | ecliptic. Only meaningful when the preceding coordSystem is a WCS system; ignored otherwise. If omitted where the grammar allows it, defaults to icrs.

<skyFormat>

degrees (default) | sexagesimal — how a returned sky coordinate is formatted.

<skyDist>

degrees (default) | arcmin | arcsec — the unit of a returned or supplied angular size/distance.

<coord>

A coordinate pair appropriate to the coordSystem/skyFrame just given: two plain numbers (<x> <y>) for image/physical/amplifier/detector/wcs systems, or two sexagesimal strings DD:MM:SS.s DD:MM:SS.s, or an HMS/DMS pair HHhMMmSS.ss DDdMMmSS.ss, for a sky frame.

<endian>

native (default) | big (or bigendian) | little (or littleendian).

<fileNameType>

root base (default, e.g. foo) | root (e.g. foo.fits) | full base (e.g. foo with directory stripped only) | full (complete path).

<layerType>

image (default) | mask — whether data being loaded becomes the frame's image data or a pixel mask layer.

<shmType>

shmid (default, a System V shared memory id) | key (a System V shared memory key). Used by the shared/sshared forms of load/save.

<cutMethod>

average (default) | sum | median.

<scaleType>

linear | log | pow | sqrt | squared | asinh | sinh | histequ.

<minmaxMode>

auto | scan | sample | datamin | irafmin.

<maskType>

zero | nonzero (default) | nan | nonnan | range.

<maskBlend>

source (default) | multiply | screen | overlay | darken | lighten | color-dodge | color-burn | hard-light | soft-light | difference | exclusion | hue | saturation | color | luminosity. Also used by layer for image-layer blending.

<pointShape>

circle (default) | box | diamond | cross | x | arrow | boxcircle.

<analysisTask>

panda (also cpanda) | histogram | plot2d | plot3d | radial | stats.

<analysisMethod>

average (default) | sum | median.

<markerCallBack>

One of: select, unselect, highlite, unhighlite, begin move, move, end move, begin edit, edit, end edit, begin rotate, rotate, end rotate, delete, text, color, width, property, font, key, update — the marker lifecycle event a callback clause fires on. Used by marker's callback= property and callback/delete callback verbs.

<markerProperty>

none | select | highlite | dash | fixed | edit | move | rotate | delete | include | source | fill — one of a marker's boolean behavior flags, set with property <markerProperty> <yesno>.

<pscolorspace>

bw | gray | rgb | cmyk. Used by postscript.

<gridType>

analysis | publication. Used by grid.

<contourMethod>

smooth | block. Used by contour.

<contourClipMode>

minmax | zscale | zmax | user. Used by contour (a subset of clip modes, without auto/sample/datamin/irafmin).

<contourClipScope>

global | local. Used by contour and clip scope.

<renderMethod>

mip | aip | fip. Used by threed.

<renderBackground>

none | azimuth | elevation. Used by threed.

<smoothFunction>

boxcar | tophat | gaussian | elliptic. Used by smooth.

<markerFormat>

ds9 (default) | xml | ciao | saotng | saoimage | pros | xy (raw x/y). The region file dialect for marker load/save/list/command.

<markerLayer>

An optional word right after marker/region/get marker selecting which layer of markers to operate on: omitted (default), region, user, or pointer all mean the normal user-created region layer; catalog means catalog-overlay markers; footprint means footprint-overlay markers. See marker.

bg

Sets the frame's background color (shown outside the loaded image / behind transparent pixels).
Syntax: bg color <color> bg color <yesno> Example: $::current(frame) bg color white $::current(frame) bg color yes # enable using the configured bg color
bin

Controls binning of FITS bin-table (event list) data: bin factor, bin center, binning columns, buffer size, and the binning function.
Syntax: bin about center bin about <x> <y> bin buffer size <value> bin cols <xcol> <ycol> <zcol> bin depth <value> bin factor <value> [<value>] bin factor <value> [<value>] about <x> <y> bin factor to <value> [<value>] bin factor to <value> [<value>] about <x> <y> bin filter <string> bin function average|sum bin to fit bin to <fx> <fy> about center <xcol> <ycol> <zcol> bin to <fx> <fy> about <ax> <ay> <xcol> <ycol> <zcol> bin to <fx> <fy> <depth> <dx> <dy> about center <xcol> <ycol> <zcol> <tcol> bin to <fx> <fy> <depth> <dx> <dy> about <ax> <ay> <xcol> <ycol> <zcol> <tcol> Example: $::current(frame) bin about center $::current(frame) bin about 512 512 $::current(frame) bin buffer size 1024 $::current(frame) bin cols detx dety time $::current(frame) bin factor 4 $::current(frame) bin factor 4 2 about 512 512 $::current(frame) bin filter {pha > 5} $::current(frame) bin function sum $::current(frame) bin to fit $::current(frame) bin to 4 4 about center detx dety time
The bin to <fx> <fy> ... forms are a legacy one-shot combination of setting the bin factor, the about-point, and the binning columns (and, in the four-column forms, a bin buffer depth) in a single call; prefer the separate bin factor/bin about/bin cols/bin depth commands above in new scripts.

block

Sets the block (downsample) factor used when displaying oversized images.
Syntax: block <value> [<value>] block to fit block to <value> [<value>] Example: $::current(frame) block 2 $::current(frame) block 2 4 $::current(frame) block to fit
center

Recenters the frame's pan position on the image.
Syntax: center Example: $::current(frame) center
clear

Clears (unloads) the frame's current image data.
Syntax: clear Example: $::current(frame) clear
clip

Controls the scale limits (clip values) used to map data values to the colormap.
Syntax: clip scope global|local clip mode <value> clip mode minmax|zscale|zmax|user clip minmax <value> <minmaxMode> clip minmax mode <minmaxMode> clip minmax sample <n> clip minmax rescan clip user <low> <high> clip user nan nan clip zscale <contrast> <samples> <line> Example: $::current(frame) clip scope local $::current(frame) clip mode zscale $::current(frame) clip mode 99.5 $::current(frame) clip minmax 100 scan $::current(frame) clip minmax mode sample $::current(frame) clip minmax sample 1000 $::current(frame) clip minmax rescan $::current(frame) clip user 10 5000 $::current(frame) clip zscale 0.25 600 120
See <minmaxMode> for the clip minmax mode values.

colorbar

Tags the frame's colorbar (associates a name with it; used internally when multiple frames share/lock a colorbar). Most colorbar display options live on the colorbar widget itself, not this frame-level command — see Colorbar.
Syntax: colorbar tag <string> Example: $::current(frame) colorbar tag mytag
colormap

Low-level colormap-cell update, as used while interactively dragging contrast/bias with the pointer. Not typically needed from a script; prefer the cmap/contrast/bias Tcl-level commands for normal colormap control.
Syntax: colormap <index> <contrast> <bias> <width> <height> colormap rgb <r> <g> <b> <contrast> <bias> <gamma> <width> <height> colormap hsv <h> <s> <v> <contrast> <bias> <gamma> <width> <height> colormap hls <h> <l> <s> <contrast> <bias> <gamma> <width> <height> colormap multicolor <index> <width> <rfile> <gfile> <bfile> <height> colormap begin colormap motion ... # same forms as above, sent while dragging colormap end Example: $::current(frame) colormap begin $::current(frame) colormap motion 200 0.5 0.5 256 1 $::current(frame) colormap end
colorscale

Sets the scale (transfer) function applied to clipped data values before colormap lookup.
Syntax: colorscale <scaleType> colorscale log <exponent> Example: $::current(frame) colorscale log $::current(frame) colorscale sqrt $::current(frame) colorscale log 1000
See <scaleType>.

contour

Creates, loads, pastes, saves, or deletes the frame's contour overlay.
Syntax: contour create <colorname> <numlevel> <smooth> <contourMethod> <width> <dash> <scaleType> <log> <contourClipMode> <contourClipScope> <low> <high> <method> contour create polygon contour dashlist <len1> <len2> contour delete contour delete aux contour load <filename> contour load <filename> <colorname> <width> <yesno> contour paste <filename> contour paste <filename> <colorname> <width> <yesno> [<dash1> <dash2>] contour save <filename> <coordSystem> <skyFrame> contour save aux <filename> <coordSystem> <skyFrame> Example: $::current(frame) contour create green 5 1 smooth 1 0 linear 0 minmax global 10 5000 smooth $::current(frame) contour delete $::current(frame) contour load foo.con $::current(frame) contour save foo.con image icrs
See <contourMethod>, <scaleType>, <contourClipMode>, <contourClipScope>.

crop

Crops the displayed image to a sub-region, either interactively (begin/motion/end, as used while dragging the crop tool) or to an explicit box.
Syntax: crop crop <x1> <y1> <x2> <y2> <coordSystem> <skyFrame> crop center <coord> <coordSystem> <skyFrame> <width> <height> <coordSystem> <skyDist> crop begin <x> <y> crop motion <x> <y> crop end <x> <y> crop 3d crop 3d <low> <high> <coordSystem> <skyFrame> crop 3d begin <x> <y> <axis> crop 3d motion <x> <y> <axis> crop 3d end <x> <y> <axis> Example: $::current(frame) crop $::current(frame) crop 100 100 400 400 image icrs $::current(frame) crop center 512 512 image icrs 200 200 image arcmin
crosshair

Positions or toggles the frame's crosshair (used in crosshair mode to mark/sync a position across frames).
Syntax: crosshair <yesno> crosshair <internalSystem> <x> <y> crosshair <coordSystem> <skyFrame> <coord> crosshair warp <x> <y> crosshair begin motion <internalSystem> <x> <y> crosshair motion <internalSystem> <x> <y> crosshair begin motion <coordSystem> <coord> crosshair motion <coordSystem> <coord> Example: $::current(frame) crosshair yes $::current(frame) crosshair canvas 256 256 $::current(frame) crosshair image 512 512
cube

Sets which FITS axis is treated as the cube's "depth" (slice) axis.
Syntax: cube axes <axis> Example: $::current(frame) cube axes 3
datasec

Enables or disables honoring the FITS DATASEC keyword (restricting display/analysis to the header-declared valid data section).
Syntax: datasec <yesno> Example: $::current(frame) datasec no
debug

Internal developer flags — enables verbose bison/flex parser tracing or per-subsystem debug logging to stderr. Not useful outside of debugging DS9 itself.
Syntax: debug <yesno> debug parser <yesno> debug mosaic <yesno> debug perf <yesno> debug wcs <yesno> debug bin <yesno> debug block <yesno> debug compress <yesno> debug crop <yesno> debug gz <yesno> debug rgb <yesno> Example: $::current(frame) debug parser yes
fade

Sets the frame's fade level, used while blending between two frames in fade display mode.
Syntax: fade <value> fade clear Example: $::current(frame) fade 0.5 $::current(frame) fade clear
fitsy

Checks whether the loaded FITS file has a named extension.
Syntax: fitsy has ext <extname> Example: $::current(frame) fitsy has ext WCSDVARR
get

The general-purpose query command: get <path> ... computes something about the frame and returns it as the Tcl command's result, e.g. set z [$::current(frame) get zoom]. It mirrors most of the other frame commands (a plain get with no arguments returns a summary status line). Marker/region queries (get marker ...) are documented separately under marker.

Syntax Returns

get a one-line frame status summary

get type the frame type (base, 3d, rgb, ...)

get bg color the background color

get bin depth the bin table depth axis buffer size

get bin factor the current bin factor, as <x> <y>

get bin function average or sum

get bin buffer size the bin buffer size

get bin cursor the bin table cursor column mode

get bin filter the current bin filter expression

get bin cols the current bin columns, as <xcol> <ycol>

get bin cols minmax <col> min/max of the named bin-table column

get bin cols dim <col> the dimension/width of the named bin-table column

get bin list the list of columns available for binning

get block factor the current block factor, as <x> <y>

get clip the current low/high clip values

get clip <contourClipMode> <contourClipScope> low/high clip values for that mode/scope without changing the frame's current mode

get clip <value> <contourClipScope> low/high for a percentage clip at that scope

get clip scope global or local

get clip mode the current clip mode name

get clip minmax mode the current minmax mode (see <minmaxMode>)

get clip minmax sample the minmax sample size

get clip user level the current user-clip low/high values

get clip zscale contrast the zscale contrast setting

get clip zscale sample the zscale sample size

get clip zscale line the zscale line size

get colorbar whether the colorbar is shown

get colorbar tag the colorbar's tag name

get colormap level <n> the raw colormap value at cell <n>

get colormap level <n> <internalSystem> <x> <y> same, contrast/bias derived from a screen position

get colormap level <n> <low> <high> <scaleType> <exp> same, from explicit clip/scale parameters

get colorscale the current <scaleType>

get colorscale log the log-scale exponent

get colorscale level <n> <low> <high> <scaleType> <exp> the scaled color-scale value for cell <n>

get contour <coordSystem> <skyFrame> contour parameters in that system

get contour clip current contour clip low/high

get contour clip mode / scope the contour clip mode/scope

get contour color the contour color name

get contour dash whether the contour is dashed

get contour dashlist the contour dash pattern

get contour level the list of contour levels

get contour number level the number of contour levels

get contour method the current <contourMethod>

get contour colorscale / colorscale log the contour's own color-scale settings

get contour smooth the contour smoothing radius

get contour width the contour line width

get coordinates <x> <y> <coordSystem> <skyFrame> <skyFormat> convert image pixel <x> <y> into the requested system

get crop <coordSystem> <skyFrame> <skyFormat> the current crop box in that system

get crop center <coordSystem> <skyFrame> <skyFormat> <coordSystem> <skyDist> the crop box as center+size

get crop 3d <coordSystem> <skyFrame> the current cube-axis crop range

get crosshair <internalSystem> crosshair position in screen pixels

get crosshair <coordSystem> <skyFrame> <skyFormat> crosshair position in the requested system

get crosshair status whether the crosshair is active

get cube axes the axis currently used as the cube depth axis

get cursor <internalSystem> the pointer position in screen pixels

get cursor <coordSystem> <skyFrame> <skyFormat> the pointer position in the requested system

get data <coordSystem> <skyFrame> <coord> <width> <height> <format> a block of raw pixel values around a position

get data <n> <coordSystem> <skyFrame> <coord> <width> <height> <format> same, for cube slice <n>

get data <internalSystem> <x> <y> <width> <height> a block of raw pixel values, screen-pixel addressed

get datasec whether DATASEC is honored (see datasec)

get fits naxes the number of FITS axes

get fits center <coordSystem> <skyFrame> <skyFormat> the image center position

get fits count the number of loaded FITS images/extensions

get fits depth [<n>] the number of frame buffers/depth for image <n> (default 2)

get fits bitpix the FITS BITPIX value

get fits ext <n> the extension name/number for image <n>

get fits ext <internalSystem> <x> <y> the extension under a screen position (mosaics)

get fits file name <fileNameType> [<n>] the loaded file name

get fits file name <fileNameType> <internalSystem> <x> <y> the file name of the mosaic tile under a screen position

get fits header [<n>] the full FITS header text

get fits header keyword <key> a single header keyword's value

get fits header <n> keyword <key> same, from image <n>

get fits header wcs <n> the WCS-only header cards for alternate WCS <n>

get fits height / width the image dimensions in pixels

get fits object name the FITS OBJECT keyword

get fits size the image size as <width> <height>

get fits size <coordSystem> <skyFrame> <skyDist> the image size in sky units

get fits slice [<n>] the current cube slice number

get fits slice from image [<n>] <coordSystem> convert a cube axis value into a slice number

get fits slice to image <value> <coordSystem> convert a slice number into a cube axis value

get grid / grid option / grid var the coordinate-grid state/options/AST variables

get highlite color the highlite (selection) color

get histogram <xcol> <ycol> <bins> a bin-table column histogram

get horizontal cut <chan1> <chan2> <x> <y> <internalSystem> <n> <cutMethod> a horizontal pixel-value cut through a screen position

get horizontal cut <chan1> <chan2> <x> <y> <coordSystem> <skyFrame> <n> <cutMethod> same, position addressed via coordSystem

get vertical cut ... same as horizontal cut, vertically

get hsv channel / hls channel the active HSV/HLS channel

get hsv system / hls system / rgb system / multicolor system the coordinate system used for the composite image's WCS

get hsv view / hls view / rgb view which channels are visible, as three <yesno>

get iis <x> <y> <w> <h> legacy IIS frame buffer contents (see iis)

get iis cursor the IIS cursor position

get iis file name [<n>] the IIS file name

get info <title> <fileNameType> a formatted info-panel line for the whole image

get info clip the clip values as shown in the info panel

get info <internalSystem> <x> <y> <title> <fileNameType> a formatted info-panel line for a screen position

get iraf align whether IRAF frame alignment is enabled

get minmax the data min/max

get layer count the number of image layers

get layer no the active layer number

get layer color [<n>] / blend [<n>] / transparency [<n>] / view [<n>] that image layer's property (layer 0/omitted = active layer)

get mask color / mark / range / system / transparency / count / blend the corresponding pixel-mask setting (see mask)

get nan color the NaN-pixel display color

get orient the current orientation (see orient)

get pan preserve whether pan position is preserved across new images

get pixel table <internalSystem> <x> <y> <dim> <dim> <fmt> a square of pixel values around a screen position, for the pixel table dialog

get rotate the current rotation angle

get smooth function / radius / radius minor / sigma / sigma minor / angle the corresponding smoothing parameter (see smooth)

get threads the number of render threads for this frame

get 3d view / view point / border [color] / compass [color] / highlite [color] / method / background / shade [ambient|strength|normal [strength]] / scale the corresponding 3D-frame parameter (see threed)

get value <internalSystem> <x> <y> the raw pixel value at a screen position

get wcs the frame's current coordSystem/skyFrame

get wcs align / align pointer WCS-alignment state (see wcs)

get wcs name <wcsSystem> the WCSNAME of that alternate WCS

get zoom the current zoom factor

Example:
set z [$::current(frame) get zoom] set minmax [$::current(frame) get minmax] set hdr [$::current(frame) get fits header]
grid

Creates or deletes the frame's coordinate grid overlay.
Syntax: grid create <coordSystem> <skyFrame> <skyFormat> <gridType> <grid-option-list> [<label-option-list>] grid delete Example: $::current(frame) grid create wcs fk5 degrees analysis {} {} $::current(frame) grid delete
See <gridType>. The option-list strings are AST grid-plotting attribute lists as produced by the Grid dialog; see Coordinate Grids.

has

Boolean capability/state queries; each form returns yes or no.
Syntax: has amplifier has bg color has bin column <colname> has contour has contour aux has crop has datamin has datasec has detector has fits has fits bin has fits cube has fits mosaic has grid has iis has irafmin has marker highlite has marker select has marker paste has marker undo has physical has image has smooth has system <coordSystem> has wcs <coordSystem> has wcs celestial <coordSystem> has wcs equatorial <coordSystem> has wcs linear <coordSystem> has wcs alt has wcs 3d <coordSystem> Example: set ok [$::current(frame) has fits] set ok [$::current(frame) has wcs wcs] set ok [$::current(frame) has marker select]
hide

Hides the frame (removes it from the tiled/single display without deleting it).
Syntax: hide Example: $::current(frame) hide
highlite

Shows/hides, or sets the color of, the frame's highlite border (drawn when the frame is the active one and highlite display is enabled).
Syntax: highlite <yesno> highlite color <color> Example: $::current(frame) highlite yes $::current(frame) highlite color yellow
hls

Controls an HLS (hue/lightness/saturation) composite frame's channel selection, coordinate system, and channel visibility.
Syntax: hls channel hue|saturation|<string> hls system <coordSystem> hls view <yesno> <yesno> <yesno> Example: $::current(frame) hls channel hue $::current(frame) hls system wcs $::current(frame) hls view yes yes no
hsv

Controls an HSV (hue/saturation/value) composite frame's channel selection, coordinate system, and channel visibility.
Syntax: hsv channel hue|saturation|value|<string> hsv system <coordSystem> hsv view <yesno> <yesno> <yesno> Example: $::current(frame) hsv channel value $::current(frame) hsv view yes yes yes
iis

Legacy IIS (Image Interchange System) frame-buffer protocol support, used by very old IRAF display clients. Not relevant to normal scripting.
Syntax: iis new <width> <height> iis erase iis message <string> iis cursor <x> <y> canvas|<coordSystem> iis cursor mode <yesno> iis set file name <string> [<n>] iis set <x> <y> <w> <h> iis update iis wcs <6 matrix values> <2 offset values> <n> Example: $::current(frame) iis new 512 512 $::current(frame) iis erase
iraf

Sets whether this frame participates in IRAF-style frame-buffer alignment.
Syntax: iraf align <n> Example: $::current(frame) iraf align 1
layer

Manages the frame's stack of image layers (the base image plus any additional loaded/mask layers), including their color, blend mode, transparency, visibility, and stacking order. Most forms take an optional leading <n> selecting which layer to affect (a layer number of 0, or the argument omitted, means "the active layer", and setting a layer's color/blend/transparency/view also makes it the active layer). up/down swap a layer with its neighbor above/below in the stack; top/bottom move it to the front/back; the last remaining layer cannot be deleted. Distinct from the marker/region <markerLayer> prefix used by marker/region.
Syntax: layer layer create layer <n> layer no <n> layer [<n>] color <color> layer [<n>] blend <maskBlend> layer [<n>] transparency <value> layer [<n>] view <yesno> layer [<n>] show layer [<n>] hide layer [<n>] delete layer [<n>] up layer [<n>] down layer [<n>] top layer [<n>] bottom Example: $::current(frame) layer create $::current(frame) layer 2 color red $::current(frame) layer 2 blend multiply $::current(frame) layer 2 transparency 0.5 $::current(frame) layer 2 top
See <maskBlend>.

load

Low-level data loading into the frame. This is the mechanism the -fits/-array/-mosaic/... command line options and File menu ultimately call; a script would normally use those higher-level forms (see Command Line Options) rather than load directly, except when it needs a data source load supports that those don't expose, such as a Tcl variable or shared memory segment.

Almost every load target accepts data from one of the same handful of sources, given after the filename/target:

Source Meaning

<filename> alloc <title> read the whole file into memory under a window titled <title>

<filename> allocgz <title> same, gzip-decompressing on the fly

<filename> channel <title> read from an already-open Tcl channel named <filename> (registered via fifo-style channel commands), window titled <title>

<filename> mmap [all|incr] memory-map the file directly (fast, no copy); the FITS-only forms additionally accept a load-completeness hint

<filename1> <filename2> smmap [all|incr] shared memory-map spanning two files (header + data)

<filename> mmapincr [all|incr] memory-map a file that is still being written to incrementally

<filename> shared <shmType> <id> [all|incr] read from a System V shared memory segment

<filename> sshared <shmType> <hdrid> <dataid> [all|incr] same, header and data in separate segments

<filename> socket <fd> read from an open socket file descriptor

<filename> socketgz <fd> same, gzip-decompressing on the fly

<filename> var <varname> read from the contents of Tcl variable <varname> (as set by, e.g., an XPA fits data callback), window titled <filename>

Every source form also accepts a trailing <layerType> unless noted. [all|incr] above is the incrLoad hint kept for backward compatibility and can normally be omitted.

These sources combine with the following load targets:

Target Sources accepted Notes

load array <source> all, minus smmap a raw 2D data array (like -array)

load array rgb|hls|hsv cube <source> all, minus smmap/mmapincr-with-incrLoad a raw 3-plane RGB/HLS/HSV data cube

load envi <hdrfile> <datafile> smmap smmap only an ENVI image (paired header + data file)

load fits <source> all, plus a two-file smmap form a FITS image (like -fits)

load fits slice <source> all, plus two-file smmap one slice of a FITS cube

load fits ext cube <source> all except smmap a FITS cube built from multiple extensions

load fits rgb|hls|hsv image <source> all except smmap/sshared a FITS RGB/HLS/HSV composite image

load fits rgb|hls|hsv cube <source> all, plus two-file smmap and sshared a FITS RGB/HLS/HSV composite cube

load fits mosaic [iraf|wcs] <source> all, plus two-file smmap and sshared; wcs/wfpc2 forms require a leading <wcsSystem> a single-image mosaic tile, aligned by IRAF ccdmap or by WCS

load fits mosaic image [iraf|wcs|wfpc2] <source> same as above same, but only the image (not a full mosaic-aware load)

load nrrd <source> all except smmap/sshared/mmapincr load hint an NRRD-format volume

load photo <filename> <format> a Tk photo image format name (e.g. gif, png) — no source suffix like -jpeg/-png/-tiff/-gif

load photo slice <filename> <format> same load a photo image as one cube slice

load incr data <x1> <y1> <x2> <y2> <n> — notify the frame that new data has arrived in a region of an incrementally-mapped file

load incr minmax <x1> <y1> <x2> <y2> <n> — same, also rescanning min/max over that region

load incr end — mark an incremental load as complete

Example:
$::current(frame) load fits foo.fits mmap image $::current(frame) load fits myvar var somevar image $::current(frame) load array foo.arr alloc "foo.arr" image $::current(frame) load fits mosaic wcs wcs foo.fits mmap {} image $::current(frame) load photo foo.png png
macosx

macOS-specific printing hook (no-op on other platforms).
Syntax: macosx print Example: $::current(frame) macosx print
magnifier

Controls the magnifier's linkage to this frame: on/off, whether it shows graphics (markers) or cursor-following, its background color, its own render size, and its zoom factor.
Syntax: magnifier <yesno> magnifier graphics <yesno> magnifier cursor <yesno> magnifier color <color> magnifier <name> <width> <height> magnifier update <x> <y> magnifier zoom <value> Example: $::current(frame) magnifier yes $::current(frame) magnifier zoom 4 $::current(frame) magnifier graphics no
marker

The region/marker system: creating, editing, querying, and managing the graphical shapes (circles, boxes, polygons, points, rulers, annuli, panda shapes, composites, etc.) drawn on a frame. This is what the Regions menu and dialogs drive under the hood.

The full command is marker <markerLayer> <verb> ... — see <markerLayer> for the optional layer word (normally omitted, meaning the ordinary user region layer). Coordinates given to marker create are always in canvas (on-screen) pixels, regardless of the frame's current coordinate system — convert with get coordinates first if you have image/WCS coordinates. Most other marker verbs identify an existing marker either by its integer id (as returned when it was created, or from get marker id) or by a tag name given as a string.

Creating markers — marker create <shape> ... [<property>=<yesno> ...] [color=<color>] [width=<n>] [font=<string>] [dashlist=<n> <n>] [text=<string>] [tag=<string> ...] [callback=<markerCallBack> <procname> <data> ...] — the bracketed clauses after each shape's own parameters are common to every shape and may appear in any order, any number of times (tags/callbacks accumulate).

Shape Syntax (after marker create)

circle circle <x> <y> <radius>

ellipse ellipse <x> <y> <rx> <ry> [<angle>]

box box <x> <y> <width> <height> [<angle>]

polygon polygon <x> <y> <x2> <y2> (a 2-vertex polygon; add vertices afterward with marker <id> polygon point ...)

segment segment <x> <y> <x2> <y2>

line line <x1> <y1> <x2> <y2>

vector vector <x> <y> <x2> <y2>

text text <x> <y> [<angle>] (set the label with text=<string>)

point <pointShape> point <x> <y> [<pointSize>] — e.g. circle point, box point, x point

ruler ruler <x1> <y1> <x2> <y2> <coordSystem> <skyFrame> <coordSystem> <skyDist> <label>

compass compass <x> <y> <radius> <coordSystem> <skyFrame>

projection projection <x1> <y1> <x2> <y2> <width>

annulus annulus <x> <y> <innerRadius> <outerRadius> <numAnnuli>

ellipse annulus ellipseannulus <x> <y> <rx> <ry> <outerRadius> <numAnnuli> [<angle>]

box annulus boxannulus <x> <y> <width> <height> <outerSize> <numAnnuli> [<angle>]

panda (circular) cpanda <x> <y> <angle1> <angle2> <numAngles> <innerRadius> <outerRadius> <numAnnuli>

panda (elliptical) epanda <x> <y> <angle1> <angle2> <numAngles> <rx> <ry> <outerRadius> <numAnnuli> [<angle>]

panda (box) bpanda <x> <y> <angle1> <angle2> <numAngles> <width> <height> <outerSize> <numAnnuli> [<angle>]

composite composite [0|1] (an empty group marker that other markers can be added to; 0=union, 1=intersection, for its composite area flag)

from template template <templateName> <x> <y> / template var <templateName> <x> <y> / template <templateName> <coordSystem> <skyFrame> <coord> — create a marker from a region template previously saved with marker save template

Example:
set id [$::current(frame) marker create circle 256 256 20 color=red] $::current(frame) marker create box 100 100 40 20 45 color=green tag={mybox} $::current(frame) marker create text 200 200 text={Hello} color=yellow $::current(frame) marker create annulus 256 256 10 40 4
Other marker verbs (<id> is a marker's integer id or a tag/name string; forms without a leading id apply to all selected markers):

Syntax Action

marker centroid [<id>] recompute centroid for one/all markers

marker centroid auto <yesno> / radius <value> / iteration <n> / option <n> <value> configure auto-centroiding

marker color <color> / <id> color <color> set marker color

marker copy / <id> copy copy selected marker(s) to the internal clipboard

marker cut / <id> cut cut (copy + delete) selected marker(s)

marker paste [<coordSystem>] paste previously copied/cut markers

marker undo undo the last marker edit

marker command <markerFormat> <string> / command <markerFormat> var <varname> create/edit markers from a region-format command string

marker composite delete delete a composite marker's grouping (ungroup)

marker <id> composite global <yesno> / area <yesno> / type <string> composite marker's global/area/operation-type flags

marker delete [select] / <id> delete delete all, all-selected, or one marker

marker edit begin <x> <y> <handle> / motion <x> <y> <handle> / end interactive handle-drag edit (as used while dragging a marker's resize handle)

marker epsilon <n> set the hit-test tolerance (pixels) for polygon/line vertex picking

marker font <string> / <id> font <string> set text font, e.g. {helvetica 10 normal roman}

marker highlite all / only <x> <y> / toggle <x> <y> / <id> highlite [only] / unhighlite all / <id> unhighlite highlite (pre-select) marker(s), by screen position or id

marker <id> analysis <analysisTask> <yesno> enable/disable an analysis task (histogram, plot, radial, stats, panda) for this marker

marker analysis stats callback [<proc>] set/clear the global region-stats callback

marker <id> angle <angle> [<internalSystem>|<coordSystem> <skyFrame>] set a shape's rotation angle

marker <id> annulus radius <inner> <outer> <n> <coordSystem> <skyDist> (also boxannulus, ellipseannulus, and a <string> radius-list form) set an annulus-family shape's radii

marker <id> box radius <w> <h> <coordSystem> <skyDist> / circle radius ... / ellipse radius ... resize a box/circle/ellipse

marker <id> bpanda edit ... / cpanda edit ... / epanda edit ... set a panda shape's angles and radii in one call (as used while dragging its handles)

marker <id> callback <markerCallBack> <procname> <data> / <id> delete callback <markerCallBack> <procname> attach/detach a Tcl callback on a marker lifecycle event

marker <id> compass arrow <yesno> <yesno> / label <n> <e> / radius <value> <coordSystem> <skyDist> / system <coordSystem> <skyFrame> configure a compass marker

marker create annulus|boxannulus|bpanda|epanda|cpanda|ellipseannulus radius|angle <dr> <da> append one more radius/angle ring to an existing (just-created) annulus-family shape

marker create polygon|segment vertex <n> <x> <y> / <id> delete polygon|segment vertex <n> / <id> polygon|segment reset <x> <y> <coordSystem> <skyDist> / <id> polygon point <coordSystem> <skyFrame> <skyFormat> <pointlist> add/remove/replace polygon or segment vertices

marker <id> delete annulus|boxannulus|bpanda|cpanda|epanda <n> remove one ring from an annulus-family shape

marker <id> delete tag [<name>|<n>] remove one (or the <n>th) tag from a marker

marker key / key <x> <y> simulate a key-triggered marker action at a position (used by the keyboard region-create shortcuts)

marker list [select] <markerFormat> <coordSystem> <skyFrame> <skyFormat> <yesno> [<markerProperty>=<yesno> ...] [tag=<name> ...] return all (or selected) markers as region-format text; the trailing property/tag clauses filter which markers are included

marker load <markerFormat> <filename|n> [<n> <color> <coordSystem> <skyFrame>] / load fits <filename> [<color>] load regions from a file/fd, or from a FITS region extension

marker <id> line arrow <yesno> <yesno> / <id> line point <coordSystem> <skyFrame> <coord> <coord> set a line's arrowheads / endpoints

marker move <x> <y> / <id> move <x> <y> / move front|back / <id> move front|back / move to <coordSystem> <skyFrame> <coord> / <id> move to ... move selected marker(s), or one marker, by offset or to an absolute position, or restack front/back

marker move begin <x> <y> / motion <x> <y> / end interactive drag-move (as used while dragging a marker)

marker point shape <pointShape> / <id> point shape <pointShape> / <id> point size <n> change a point marker's shape/size

marker <id> projection <coordSystem> <skyFrame> <coord> <coord> <width> <coordSystem> <skyDist> set a projection marker's endpoints and width

marker property <markerProperty> <yesno> / <id> property <markerProperty> <yesno> / property <markerProperty> <yesno> <x> <y> set a boolean property flag on selected marker(s), one marker, or the marker under a screen position

marker preserve <yesno> whether markers persist across a new image being loaded into the frame

marker <id> rotate begin / rotate begin <x> <y> / rotate motion <x> <y> <handle> / rotate end interactive rotate-drag

marker <id> ruler format <string> / ruler point ... / ruler system <coordSystem> <skyFrame> <coordSystem> <skyDist> configure a ruler marker's distance format, endpoints, and units

marker select all / only <x> <y> / toggle [<x> <y>] / first / last / <id> select [only] / unselect all / <id> unselect select/unselect marker(s)

marker show <yesno> / show text <yesno> show/hide all markers, or just their text labels

marker save <filename> [select] <markerFormat> <coordSystem> <skyFrame> <skyFormat> <yesno> / save template <filename> save all/selected markers to a region file, or save a marker as a reusable template

marker <id> tag <name> / tag <name> / tag edit <old> <new> / tag delete <name> / tag delete all / tag update <name> add/rename/remove tags

marker <id> text <string> / text rotate <yesno> set a text marker's label / whether it rotates with the shape

marker <id> vector arrow <yesno> / vector point <coordSystem> <skyFrame> <coord> <coordSystem> <skyDist> <magnitude> <angle> configure a vector marker's arrowhead / endpoint+magnitude+angle

marker <id> width <n> / width <n> / <id> dashlist <n> <n> / dashlist <n> <n> set line width / dash pattern on one marker or selected marker(s)

Querying markers — invoked as get marker <markerLayer> ..., not marker .... Most forms mirror a creation/edit form above but return the value instead of setting it.

Syntax Returns

get marker centroid auto / radius / iteration / option centroid auto-mode settings

get marker color / <id> color marker color

get marker font / <id> font marker font

get marker epsilon hit-test tolerance

get marker handle <x> <y> which resize handle (if any) is at a screen position

get marker id <x> <y> / <name> id the marker id at a screen position, or by tag/name

get marker id all ids of all markers

get marker <id> analysis <analysisTask> ... that marker's analysis-task configuration/results

get marker analysis stats all data <coordSystem> <skyFrame> / stats fields stats over all markers / the list of stats field names

get marker <id> angle [<internalSystem>|<coordSystem> <skyFrame>] rotation angle

get marker <id> annulus|boxannulus|ellipseannulus radius <coordSystem> <skyDist> / box|circle|ellipse radius ... the shape's radii/size

get marker <id> bpanda|cpanda|epanda angle [...] / radius <coordSystem> <skyDist> panda shape angles/radii

get marker <id> center <coordSystem> <skyFrame> <skyFormat> marker center position

get marker <id> compass arrow / label / radius ... / system compass marker settings

get marker <id> composite global / area / type composite marker flags

get marker <id> highlite / select whether a marker is highlited/selected

get marker highlite [<x> <y>] / highlite number the highlited marker(s) / count

get marker select [<x> <y>] / select number the selected marker(s) / count

get marker <id> line arrow / line length <coordSystem> <skyDist> / line point ... line marker properties

get marker <id> map length <value> <coordSystem> <skyDist> convert a canvas-pixel length to a sky/image length for that marker

get marker <id> point shape / point size point marker shape/size

get marker <id> polygon point ... / polygon segment <x> <y> polygon vertex list / which segment is at a position

get marker <id> projection point ... / length ... / thick ... projection marker geometry

get marker <id> property [<markerProperty>] / property <markerProperty> a marker's (or the under-cursor marker's) property flag(s)

get marker <id> ruler format / length ... / point ... / system ruler marker settings

get marker <id> tag [<n>] / <name> tag / <name> tag number / tag all / tag default name a marker's tag(s), or the default tag name for new markers

get marker <id> text / text rotate text marker label / rotate-with-shape flag

get marker <id> type the marker's shape type name

get marker <id> vector arrow / vector length ... / vector point ... vector marker properties

get marker <id> width / width / <id> dashlist / dashlist line width / dash pattern

get marker number the total number of markers

get marker preserve whether markers persist across new images (see marker preserve)

get marker show / show text marker/label visibility

mask

Controls how a loaded pixel-mask layer is interpreted and displayed.
Syntax: mask clear mask color <color> mask mark <maskType> mask mark <int> # backward compatibility, numeric <maskType> mask range <low> <high> mask system <coordSystem> mask transparency <value> mask blend <maskBlend> Example: $::current(frame) mask color red $::current(frame) mask mark nonzero $::current(frame) mask range 1 100 $::current(frame) mask transparency 0.5
See <maskType> and <maskBlend>.

match

Cross-matches two lists of sky positions by angular separation. <xvar1>/<yvar1> and <xvar2>/<yvar2> are the names of (already-populated) Tcl variables, each holding an equal-length list of X/Y coordinate values in the coordinate system/sky frame given right after it; every position in list 1 is compared against every position in list 2, converting between the two sky frames first if they differ. For every pair within <radius> of each other, a two-element list {<i> <j>} (1-based indices into list 1 and list 2) is appended to the result; the full result list is stored into the Tcl variable named <resultvar>.
Syntax: match <xvar1> <yvar1> <coordSystem> <skyFrame> <xvar2> <yvar2> <coordSystem> <skyFrame> <radius> <coordSystem> <skyDist> <resultvar> Example: set ra1 {10.1 10.2 10.3}; set dec1 {41.1 41.2 41.3} set ra2 {10.15 10.25 12.0}; set dec2 {41.15 41.25 43.0} $::current(frame) match ra1 dec1 wcs fk5 ra2 dec2 wcs fk5 5 wcs arcsec matches puts $matches # e.g. {1 1} {2 2}
multicolor

Sets the coordinate system used for a multicolor (arbitrary N-channel) composite frame's WCS.
Syntax: multicolor system <coordSystem> Example: $::current(frame) multicolor system wcs
nan

Sets the display color used for NaN (not-a-number) pixel values.
Syntax: nan color <color> Example: $::current(frame) nan color black
orient

Flips the image about the X axis, Y axis, both, or resets to normal.
Syntax: orient x orient y orient xy orient none Example: $::current(frame) orient x $::current(frame) orient none
pan

Pans (recenters) the frame's view, by a relative offset or to an absolute position, in image, screen, or sky coordinates.
Syntax: pan <dx> <dy> pan <dx1> <dy1> <dx2> <dy2> pan canvas|panner <x> <y> # backward compatibility, same as plain <dx> <dy> pan <coordSystem> <skyFrame> <coord> pan to <x> <y> pan to canvas|panner <x> <y> # backward compatibility pan to <coordSystem> <skyFrame> <coord> pan bbox <x> <y> pan motion begin <x> <y> pan motion <x> <y> pan motion end <x> <y> pan preserve <yesno> Example: $::current(frame) pan 10 -10 $::current(frame) pan to 512 512 $::current(frame) pan to wcs fk5 13:29:52.698 +47:11:42.93 $::current(frame) pan preserve yes
panner

Controls the panner's linkage to this frame: on/off, its own render size, and forcing a redraw.
Syntax: panner <yesno> panner wcs <wcsSystem> <skyFrame> # backward compatibility, no-op panner <name> <width> <height> panner update Example: $::current(frame) panner yes $::current(frame) panner update
postscript

Sets PostScript print/export parameters for the frame.
Syntax: postscript colorspace <pscolorspace> postscript level <1|2|3> postscript resolution <dpi> postscript scale <value> # backward compatibility, no-op Example: $::current(frame) postscript colorspace rgb $::current(frame) postscript level 2 $::current(frame) postscript resolution 150
See <pscolorspace>.

precision

Sets the number of decimal digits used when formatting coordinates/values for display: linear, degrees, HMS, DMS, angle, length-in-linear, length-in-degrees, length-in-arcmin, length-in-arcsec (in that order).
Syntax: precision <linear> <deg> <hms> <dms> <lenLinear> <lenDeg> <lenArcmin> <lenArcsec> <angle> precision <linear> <deg> <hms> <dms> <lenArcmin> <lenArcsec> # backward compatibility, leaves lenLinear/lenDeg/angle unchanged Example: $::current(frame) precision 8 7 4 3 8 7 5 3 8 $::current(frame) precision 8 7 4 3 5 3
This mirrors the pds9(prec,*) preference settings; see The ds9 Array.

query

Forces the frame to recompute/report the value under the current pointer position (used by the value/pixel-table displays after an external change, e.g. a colormap update).
Syntax: query cursor Example: $::current(frame) query cursor
region

Interactive rubber-band region-select/highlite box, as used while shift-dragging on the canvas to multi-select markers. To create/edit/query regions themselves, see marker (a region command with the same <markerLayer> prefix is simply a synonym for marker in most of the Tcl library, but the frame-level region command below only implements the rubber-band select box, not full marker creation).
Syntax: region highlite begin <x> <y> region highlite motion <x> <y> region highlite end region highlite shift end region select begin <x> <y> region select motion <x> <y> region select end region select shift end Example: $::current(frame) region select begin 100 100 $::current(frame) region select motion 200 200 $::current(frame) region select end
reset

Resets the frame to its default state.
Syntax: reset Example: $::current(frame) reset
reveal

Sets or clears the "reveal" wipe position used in reveal display mode, where one frame is revealed over another up to a moving boundary.
Syntax: reveal <value> reveal clear Example: $::current(frame) reveal 400 $::current(frame) reveal clear
rgb

Controls an RGB composite frame's channel selection, coordinate system, and channel visibility.
Syntax: rgb channel <string> rgb system <coordSystem> rgb view <yesno> <yesno> <yesno> Example: $::current(frame) rgb channel red $::current(frame) rgb view yes no yes
rotate

Rotates the frame's view.
Syntax: rotate <angle> [degrees] rotate to <angle> [degrees] rotate motion begin rotate motion <angle> rotate motion end Example: $::current(frame) rotate 90 $::current(frame) rotate to 0
save

Saves the frame's data. Mirrors the sources used by load, but as write destinations: file <filename>, channel <title> (an open Tcl channel), or socket <fd>; the array/NRRD/ENVI forms additionally take an <endian>.

Syntax Saves

save array <dest> <endian> the raw data array

save array rgb|hls|hsv cube <dest> <endian> a raw 3-plane composite data cube

save fits [image] <dest> the FITS image

save fits table <dest> the FITS bin table

save fits slice <dest> the current cube slice

save fits ext cube <dest> a FITS cube built from all extensions

save fits mosaic image <dest> / save fits mosaic <dest> <n> one mosaic tile / the full mosaic (n = tile count)

save fits rgb|hls|hsv image <dest> / rgb|hls|hsv cube <dest> a FITS composite image / cube

save fits resample <dest> the currently displayed (zoom/rotate-resampled) image

save pixmask file|channel <dest> / socket <fd> the pixel mask layer

save nrrd <dest> <endian> an NRRD-format volume

save envi file <hdrfile> <datafile> <endian> an ENVI image (paired header + data file)

save photo <filename> the displayed image as a Tk photo-format file

Example:
$::current(frame) save fits file foo.fits $::current(frame) save array file foo.arr native $::current(frame) save photo foo.png
show

Un-hides a frame previously hidden with hide.
Syntax: show Example: $::current(frame) show
smooth

Applies (or removes) a smoothing filter to the displayed image.
Syntax: smooth <smoothFunction> <radius> <radiusMinor> <sigma> <sigmaMinor> <angle> smooth delete Example: $::current(frame) smooth gaussian 3 3 1.5 1.5 0 $::current(frame) smooth delete
See <smoothFunction>.

threads

Sets the number of worker threads used to render this frame.
Syntax: threads <n> Example: $::current(frame) threads 4
threed

Controls 3D-frame rendering: viewpoint, shading, borders, compass, and render method/background. Only meaningful for a frame created as a 3D frame (see -3d in Command Line Options).
Syntax: threed view <az> <el> threed view point <x> <y> <z> <az> <el> threed border <yesno> threed border color <color> threed compass <yesno> threed compass color <color> threed highlite <yesno> threed highlite color <color> threed method <renderMethod> threed background <renderBackground> threed shade <yesno> threed shade ambient <value> threed shade strength <value> threed shade normal <yesno> threed shade normal strength <value> threed scale <value> threed sync <n> Example: $::current(frame) threed view 45 30 $::current(frame) threed method mip $::current(frame) threed shade yes $::current(frame) threed shade ambient 0.8
See <renderMethod> and <renderBackground>.

unload

Unloads the frame's FITS data (lower-level than clear; used internally before loading new data).
Syntax: unload Example: $::current(frame) unload
update

Forces the frame to redraw/refresh its displayed FITS data, optionally restricted to a bounding box (e.g. after data underneath has changed via a shared-memory or incremental load) and/or a specific cube slice.
Syntax: update update <n> <x1> <y1> <x2> <y2> update fits slice <n> update fits slice <n1> <n2> update fits slice <value> <coordSystem> Example: $::current(frame) update $::current(frame) update 0 0 0 512 512
version

Returns the frame command grammar's version string.
Syntax: version Example: set v [$::current(frame) version]
warp

Moves the mouse pointer to a screen position within the frame (or to an absolute position).
Syntax: warp <x> <y> warp to <x> <y> Example: $::current(frame) warp 256 256
wcs

Sets the frame's active WCS system/sky-frame/format, manages alignment to another frame's WCS, and appends/replaces alternate WCS solutions from FITS header text.
Syntax: wcs <wcsSystem> <skyFrame> <skyFormat> wcs align <n> wcs align <n> <wcsSystem> <skyFrame> wcs align to <n> <wcsSystem> <skyFrame> wcs align pointer clear wcs reset <n> wcs replace <n> <n2|string> wcs replace text <n> <string> wcs append <n> <n2|string> wcs append text <n> <string> Example: $::current(frame) wcs wcs fk5 sexagesimal $::current(frame) wcs align 1 $::current(frame) wcs append text 0 {CRVAL1 = 10.68}
See <wcsSystem>.

win32

Windows-specific printing hook (no-op on other platforms).
Syntax: win32 print Example: $::current(frame) win32 print
zoom

Sets the frame's zoom factor, by absolute value or by zooming about a specific position.
Syntax: zoom <x> <y> zoom <x> <y> about <ax> <ay> zoom <x> <y> about <coordSystem> <skyFrame> <coord> zoom to fit [<margin>] zoom to <x> <y> zoom to <x> <y> about <ax> <ay> zoom to <x> <y> about <coordSystem> <skyFrame> <coord> Example: $::current(frame) zoom 2 2 $::current(frame) zoom to fit $::current(frame) zoom 4 4 about 256 256

Syntax	Returns
`get`	a one-line frame status summary
`get type`	the frame type (`base`, `3d`, `rgb`, ...)
`get bg color`	the background color
`get bin depth`	the bin table depth axis buffer size
`get bin factor`	the current bin factor, as `<x> <y>`
`get bin function`	`average` or `sum`
`get bin buffer size`	the bin buffer size
`get bin cursor`	the bin table cursor column mode
`get bin filter`	the current bin filter expression
`get bin cols`	the current bin columns, as `<xcol> <ycol>`
`get bin cols minmax <col>`	min/max of the named bin-table column
`get bin cols dim <col>`	the dimension/width of the named bin-table column
`get bin list`	the list of columns available for binning
`get block factor`	the current block factor, as `<x> <y>`
`get clip`	the current low/high clip values
`get clip <contourClipMode> <contourClipScope>`	low/high clip values for that mode/scope without changing the frame's current mode
`get clip <value> <contourClipScope>`	low/high for a percentage clip at that scope
`get clip scope`	`global` or `local`
`get clip mode`	the current clip mode name
`get clip minmax mode`	the current minmax mode (see <minmaxMode>)
`get clip minmax sample`	the minmax sample size
`get clip user level`	the current user-clip low/high values
`get clip zscale contrast`	the zscale contrast setting
`get clip zscale sample`	the zscale sample size
`get clip zscale line`	the zscale line size
`get colorbar`	whether the colorbar is shown
`get colorbar tag`	the colorbar's tag name
`get colormap level <n>`	the raw colormap value at cell <n>
`get colormap level <n> <internalSystem> <x> <y>`	same, contrast/bias derived from a screen position
`get colormap level <n> <low> <high> <scaleType> <exp>`	same, from explicit clip/scale parameters
`get colorscale`	the current <scaleType>
`get colorscale log`	the log-scale exponent
`get colorscale level <n> <low> <high> <scaleType> <exp>`	the scaled color-scale value for cell <n>
`get contour <coordSystem> <skyFrame>`	contour parameters in that system
`get contour clip`	current contour clip low/high
`get contour clip mode` / `scope`	the contour clip mode/scope
`get contour color`	the contour color name
`get contour dash`	whether the contour is dashed
`get contour dashlist`	the contour dash pattern
`get contour level`	the list of contour levels
`get contour number level`	the number of contour levels
`get contour method`	the current <contourMethod>
`get contour colorscale` / `colorscale log`	the contour's own color-scale settings
`get contour smooth`	the contour smoothing radius
`get contour width`	the contour line width
`get coordinates <x> <y> <coordSystem> <skyFrame> <skyFormat>`	convert image pixel <x> <y> into the requested system
`get crop <coordSystem> <skyFrame> <skyFormat>`	the current crop box in that system
`get crop center <coordSystem> <skyFrame> <skyFormat> <coordSystem> <skyDist>`	the crop box as center+size
`get crop 3d <coordSystem> <skyFrame>`	the current cube-axis crop range
`get crosshair <internalSystem>`	crosshair position in screen pixels
`get crosshair <coordSystem> <skyFrame> <skyFormat>`	crosshair position in the requested system
`get crosshair status`	whether the crosshair is active
`get cube axes`	the axis currently used as the cube depth axis
`get cursor <internalSystem>`	the pointer position in screen pixels
`get cursor <coordSystem> <skyFrame> <skyFormat>`	the pointer position in the requested system
`get data <coordSystem> <skyFrame> <coord> <width> <height> <format>`	a block of raw pixel values around a position
`get data <n> <coordSystem> <skyFrame> <coord> <width> <height> <format>`	same, for cube slice <n>
`get data <internalSystem> <x> <y> <width> <height>`	a block of raw pixel values, screen-pixel addressed
`get datasec`	whether `DATASEC` is honored (see datasec)
`get fits naxes`	the number of FITS axes
`get fits center <coordSystem> <skyFrame> <skyFormat>`	the image center position
`get fits count`	the number of loaded FITS images/extensions
`get fits depth [<n>]`	the number of frame buffers/depth for image <n> (default 2)
`get fits bitpix`	the FITS `BITPIX` value
`get fits ext <n>`	the extension name/number for image <n>
`get fits ext <internalSystem> <x> <y>`	the extension under a screen position (mosaics)
`get fits file name <fileNameType> [<n>]`	the loaded file name
`get fits file name <fileNameType> <internalSystem> <x> <y>`	the file name of the mosaic tile under a screen position
`get fits header [<n>]`	the full FITS header text
`get fits header keyword <key>`	a single header keyword's value
`get fits header <n> keyword <key>`	same, from image <n>
`get fits header wcs <n>`	the WCS-only header cards for alternate WCS <n>
`get fits height` / `width`	the image dimensions in pixels
`get fits object name`	the FITS `OBJECT` keyword
`get fits size`	the image size as `<width> <height>`
`get fits size <coordSystem> <skyFrame> <skyDist>`	the image size in sky units
`get fits slice [<n>]`	the current cube slice number
`get fits slice from image [<n>] <coordSystem>`	convert a cube axis value into a slice number
`get fits slice to image <value> <coordSystem>`	convert a slice number into a cube axis value
`get grid` / `grid option` / `grid var`	the coordinate-grid state/options/AST variables
`get highlite color`	the highlite (selection) color
`get histogram <xcol> <ycol> <bins>`	a bin-table column histogram
`get horizontal cut <chan1> <chan2> <x> <y> <internalSystem> <n> <cutMethod>`	a horizontal pixel-value cut through a screen position
`get horizontal cut <chan1> <chan2> <x> <y> <coordSystem> <skyFrame> <n> <cutMethod>`	same, position addressed via coordSystem
`get vertical cut ...`	same as `horizontal cut`, vertically
`get hsv channel` / `hls channel`	the active HSV/HLS channel
`get hsv system` / `hls system` / `rgb system` / `multicolor system`	the coordinate system used for the composite image's WCS
`get hsv view` / `hls view` / `rgb view`	which channels are visible, as three `<yesno>`
`get iis <x> <y> <w> <h>`	legacy IIS frame buffer contents (see iis)
`get iis cursor`	the IIS cursor position
`get iis file name [<n>]`	the IIS file name
`get info <title> <fileNameType>`	a formatted info-panel line for the whole image
`get info clip`	the clip values as shown in the info panel
`get info <internalSystem> <x> <y> <title> <fileNameType>`	a formatted info-panel line for a screen position
`get iraf align`	whether IRAF frame alignment is enabled
`get minmax`	the data min/max
`get layer count`	the number of image layers
`get layer no`	the active layer number
`get layer color [<n>]` / `blend [<n>]` / `transparency [<n>]` / `view [<n>]`	that image layer's property (layer 0/omitted = active layer)
`get mask color` / `mark` / `range` / `system` / `transparency` / `count` / `blend`	the corresponding pixel-mask setting (see mask)
`get nan color`	the NaN-pixel display color
`get orient`	the current orientation (see orient)
`get pan preserve`	whether pan position is preserved across new images
`get pixel table <internalSystem> <x> <y> <dim> <dim> <fmt>`	a square of pixel values around a screen position, for the pixel table dialog
`get rotate`	the current rotation angle
`get smooth function` / `radius` / `radius minor` / `sigma` / `sigma minor` / `angle`	the corresponding smoothing parameter (see smooth)
`get threads`	the number of render threads for this frame
`get 3d view` / `view point` / `border` [`color`] / `compass` [`color`] / `highlite` [`color`] / `method` / `background` / `shade` [`ambient`\|`strength`\|`normal` [`strength`]] / `scale`	the corresponding 3D-frame parameter (see threed)
`get value <internalSystem> <x> <y>`	the raw pixel value at a screen position
`get wcs`	the frame's current coordSystem/skyFrame
`get wcs align` / `align pointer`	WCS-alignment state (see wcs)
`get wcs name <wcsSystem>`	the WCSNAME of that alternate WCS
`get zoom`	the current zoom factor

Source	Meaning
`<filename> alloc <title>`	read the whole file into memory under a window titled <title>
`<filename> allocgz <title>`	same, gzip-decompressing on the fly
`<filename> channel <title>`	read from an already-open Tcl channel named <filename> (registered via `fifo`-style channel commands), window titled <title>
`<filename> mmap [all\|incr]`	memory-map the file directly (fast, no copy); the FITS-only forms additionally accept a load-completeness hint
`<filename1> <filename2> smmap [all\|incr]`	shared memory-map spanning two files (header + data)
`<filename> mmapincr [all\|incr]`	memory-map a file that is still being written to incrementally
`<filename> shared <shmType> <id> [all\|incr]`	read from a System V shared memory segment
`<filename> sshared <shmType> <hdrid> <dataid> [all\|incr]`	same, header and data in separate segments
`<filename> socket <fd>`	read from an open socket file descriptor
`<filename> socketgz <fd>`	same, gzip-decompressing on the fly
`<filename> var <varname>`	read from the contents of Tcl variable <varname> (as set by, e.g., an XPA `fits` data callback), window titled <filename>

Target	Sources accepted	Notes
`load array <source>`	all, minus `smmap`	a raw 2D data array (like `-array`)
`load array rgb\|hls\|hsv cube <source>`	all, minus `smmap`/`mmapincr`-with-incrLoad	a raw 3-plane RGB/HLS/HSV data cube
`load envi <hdrfile> <datafile> smmap`	`smmap` only	an ENVI image (paired header + data file)
`load fits <source>`	all, plus a two-file `smmap` form	a FITS image (like `-fits`)
`load fits slice <source>`	all, plus two-file `smmap`	one slice of a FITS cube
`load fits ext cube <source>`	all except `smmap`	a FITS cube built from multiple extensions
`load fits rgb\|hls\|hsv image <source>`	all except `smmap`/`sshared`	a FITS RGB/HLS/HSV composite image
`load fits rgb\|hls\|hsv cube <source>`	all, plus two-file `smmap` and `sshared`	a FITS RGB/HLS/HSV composite cube
`load fits mosaic [iraf\|wcs] <source>`	all, plus two-file `smmap` and `sshared`; wcs/wfpc2 forms require a leading <wcsSystem>	a single-image mosaic tile, aligned by IRAF `ccdmap` or by WCS
`load fits mosaic image [iraf\|wcs\|wfpc2] <source>`	same as above	same, but only the image (not a full mosaic-aware load)
`load nrrd <source>`	all except `smmap`/`sshared`/`mmapincr` load hint	an NRRD-format volume
`load photo <filename> <format>`	a Tk photo image format name (e.g. `gif`, `png`) — no source suffix	like `-jpeg`/`-png`/`-tiff`/`-gif`
`load photo slice <filename> <format>`	same	load a photo image as one cube slice
`load incr data <x1> <y1> <x2> <y2> <n>`	—	notify the frame that new data has arrived in a region of an incrementally-mapped file
`load incr minmax <x1> <y1> <x2> <y2> <n>`	—	same, also rescanning min/max over that region
`load incr end`	—	mark an incremental load as complete

Shape	Syntax (after `marker create`)
circle	`circle <x> <y> <radius>`
ellipse	`ellipse <x> <y> <rx> <ry> [<angle>]`
box	`box <x> <y> <width> <height> [<angle>]`
polygon	`polygon <x> <y> <x2> <y2>` (a 2-vertex polygon; add vertices afterward with `marker <id> polygon point ...`)
segment	`segment <x> <y> <x2> <y2>`
line	`line <x1> <y1> <x2> <y2>`
vector	`vector <x> <y> <x2> <y2>`
text	`text <x> <y> [<angle>]` (set the label with `text=<string>`)
point	`<pointShape> point <x> <y> [<pointSize>]` — e.g. `circle point`, `box point`, `x point`
ruler	`ruler <x1> <y1> <x2> <y2> <coordSystem> <skyFrame> <coordSystem> <skyDist> <label>`
compass	`compass <x> <y> <radius> <coordSystem> <skyFrame>`
projection	`projection <x1> <y1> <x2> <y2> <width>`
annulus	`annulus <x> <y> <innerRadius> <outerRadius> <numAnnuli>`
ellipse annulus	`ellipseannulus <x> <y> <rx> <ry> <outerRadius> <numAnnuli> [<angle>]`
box annulus	`boxannulus <x> <y> <width> <height> <outerSize> <numAnnuli> [<angle>]`
panda (circular)	`cpanda <x> <y> <angle1> <angle2> <numAngles> <innerRadius> <outerRadius> <numAnnuli>`
panda (elliptical)	`epanda <x> <y> <angle1> <angle2> <numAngles> <rx> <ry> <outerRadius> <numAnnuli> [<angle>]`
panda (box)	`bpanda <x> <y> <angle1> <angle2> <numAngles> <width> <height> <outerSize> <numAnnuli> [<angle>]`
composite	`composite [0\|1]` (an empty group marker that other markers can be added to; `0`=union, `1`=intersection, for its `composite area` flag)
from template	`template <templateName> <x> <y>` / `template var <templateName> <x> <y>` / `template <templateName> <coordSystem> <skyFrame> <coord>` — create a marker from a region template previously saved with `marker save template`

Syntax	Action
`marker centroid [<id>]`	recompute centroid for one/all markers
`marker centroid auto <yesno>` / `radius <value>` / `iteration <n>` / `option <n> <value>`	configure auto-centroiding
`marker color <color>` / `<id> color <color>`	set marker color
`marker copy` / `<id> copy`	copy selected marker(s) to the internal clipboard
`marker cut` / `<id> cut`	cut (copy + delete) selected marker(s)
`marker paste [<coordSystem>]`	paste previously copied/cut markers
`marker undo`	undo the last marker edit
`marker command <markerFormat> <string>` / `command <markerFormat> var <varname>`	create/edit markers from a region-format command string
`marker composite delete`	delete a composite marker's grouping (ungroup)
`marker <id> composite global <yesno>` / `area <yesno>` / `type <string>`	composite marker's global/area/operation-type flags
`marker delete [select]` / `<id> delete`	delete all, all-selected, or one marker
`marker edit begin <x> <y> <handle>` / `motion <x> <y> <handle>` / `end`	interactive handle-drag edit (as used while dragging a marker's resize handle)
`marker epsilon <n>`	set the hit-test tolerance (pixels) for polygon/line vertex picking
`marker font <string>` / `<id> font <string>`	set text font, e.g. `{helvetica 10 normal roman}`
`marker highlite all` / `only <x> <y>` / `toggle <x> <y>` / `<id> highlite [only]` / `unhighlite all` / `<id> unhighlite`	highlite (pre-select) marker(s), by screen position or id
`marker <id> analysis <analysisTask> <yesno>`	enable/disable an analysis task (histogram, plot, radial, stats, panda) for this marker
`marker analysis stats callback [<proc>]`	set/clear the global region-stats callback
`marker <id> angle <angle> [<internalSystem>\|<coordSystem> <skyFrame>]`	set a shape's rotation angle
`marker <id> annulus radius <inner> <outer> <n> <coordSystem> <skyDist>` (also `boxannulus`, `ellipseannulus`, and a `<string>` radius-list form)	set an annulus-family shape's radii
`marker <id> box radius <w> <h> <coordSystem> <skyDist>` / `circle radius ...` / `ellipse radius ...`	resize a box/circle/ellipse
`marker <id> bpanda edit ...` / `cpanda edit ...` / `epanda edit ...`	set a panda shape's angles and radii in one call (as used while dragging its handles)
`marker <id> callback <markerCallBack> <procname> <data>` / `<id> delete callback <markerCallBack> <procname>`	attach/detach a Tcl callback on a marker lifecycle event
`marker <id> compass arrow <yesno> <yesno>` / `label <n> <e>` / `radius <value> <coordSystem> <skyDist>` / `system <coordSystem> <skyFrame>`	configure a compass marker
`marker create annulus\|boxannulus\|bpanda\|epanda\|cpanda\|ellipseannulus radius\|angle <dr> <da>`	append one more radius/angle ring to an existing (just-created) annulus-family shape
`marker create polygon\|segment vertex <n> <x> <y>` / `<id> delete polygon\|segment vertex <n>` / `<id> polygon\|segment reset <x> <y> <coordSystem> <skyDist>` / `<id> polygon point <coordSystem> <skyFrame> <skyFormat> <pointlist>`	add/remove/replace polygon or segment vertices
`marker <id> delete annulus\|boxannulus\|bpanda\|cpanda\|epanda <n>`	remove one ring from an annulus-family shape
`marker <id> delete tag [<name>\|<n>]`	remove one (or the <n>th) tag from a marker
`marker key` / `key <x> <y>`	simulate a key-triggered marker action at a position (used by the keyboard region-create shortcuts)
`marker list [select] <markerFormat> <coordSystem> <skyFrame> <skyFormat> <yesno> [<markerProperty>=<yesno> ...] [tag=<name> ...]`	return all (or selected) markers as region-format text; the trailing property/tag clauses filter which markers are included
`marker load <markerFormat> <filename\|n> [<n> <color> <coordSystem> <skyFrame>]` / `load fits <filename> [<color>]`	load regions from a file/fd, or from a FITS region extension
`marker <id> line arrow <yesno> <yesno>` / `<id> line point <coordSystem> <skyFrame> <coord> <coord>`	set a line's arrowheads / endpoints
`marker move <x> <y>` / `<id> move <x> <y>` / `move front\|back` / `<id> move front\|back` / `move to <coordSystem> <skyFrame> <coord>` / `<id> move to ...`	move selected marker(s), or one marker, by offset or to an absolute position, or restack front/back
`marker move begin <x> <y>` / `motion <x> <y>` / `end`	interactive drag-move (as used while dragging a marker)
`marker point shape <pointShape>` / `<id> point shape <pointShape>` / `<id> point size <n>`	change a point marker's shape/size
`marker <id> projection <coordSystem> <skyFrame> <coord> <coord> <width> <coordSystem> <skyDist>`	set a projection marker's endpoints and width
`marker property <markerProperty> <yesno>` / `<id> property <markerProperty> <yesno>` / `property <markerProperty> <yesno> <x> <y>`	set a boolean property flag on selected marker(s), one marker, or the marker under a screen position
`marker preserve <yesno>`	whether markers persist across a new image being loaded into the frame
`marker <id> rotate begin` / `rotate begin <x> <y>` / `rotate motion <x> <y> <handle>` / `rotate end`	interactive rotate-drag
`marker <id> ruler format <string>` / `ruler point ...` / `ruler system <coordSystem> <skyFrame> <coordSystem> <skyDist>`	configure a ruler marker's distance format, endpoints, and units
`marker select all` / `only <x> <y>` / `toggle [<x> <y>]` / `first` / `last` / `<id> select [only]` / `unselect all` / `<id> unselect`	select/unselect marker(s)
`marker show <yesno>` / `show text <yesno>`	show/hide all markers, or just their text labels
`marker save <filename> [select] <markerFormat> <coordSystem> <skyFrame> <skyFormat> <yesno>` / `save template <filename>`	save all/selected markers to a region file, or save a marker as a reusable template
`marker <id> tag <name>` / `tag <name>` / `tag edit <old> <new>` / `tag delete <name>` / `tag delete all` / `tag update <name>`	add/rename/remove tags
`marker <id> text <string>` / `text rotate <yesno>`	set a text marker's label / whether it rotates with the shape
`marker <id> vector arrow <yesno>` / `vector point <coordSystem> <skyFrame> <coord> <coordSystem> <skyDist> <magnitude> <angle>`	configure a vector marker's arrowhead / endpoint+magnitude+angle
`marker <id> width <n>` / `width <n>` / `<id> dashlist <n> <n>` / `dashlist <n> <n>`	set line width / dash pattern on one marker or selected marker(s)

Syntax	Returns
`get marker centroid auto` / `radius` / `iteration` / `option`	centroid auto-mode settings
`get marker color` / `<id> color`	marker color
`get marker font` / `<id> font`	marker font
`get marker epsilon`	hit-test tolerance
`get marker handle <x> <y>`	which resize handle (if any) is at a screen position
`get marker id <x> <y>` / `<name> id`	the marker id at a screen position, or by tag/name
`get marker id all`	ids of all markers
`get marker <id> analysis <analysisTask> ...`	that marker's analysis-task configuration/results
`get marker analysis stats all data <coordSystem> <skyFrame>` / `stats fields`	stats over all markers / the list of stats field names
`get marker <id> angle [<internalSystem>\|<coordSystem> <skyFrame>]`	rotation angle
`get marker <id> annulus\|boxannulus\|ellipseannulus radius <coordSystem> <skyDist>` / `box\|circle\|ellipse radius ...`	the shape's radii/size
`get marker <id> bpanda\|cpanda\|epanda angle [...]` / `radius <coordSystem> <skyDist>`	panda shape angles/radii
`get marker <id> center <coordSystem> <skyFrame> <skyFormat>`	marker center position
`get marker <id> compass arrow` / `label` / `radius ...` / `system`	compass marker settings
`get marker <id> composite global` / `area` / `type`	composite marker flags
`get marker <id> highlite` / `select`	whether a marker is highlited/selected
`get marker highlite [<x> <y>]` / `highlite number`	the highlited marker(s) / count
`get marker select [<x> <y>]` / `select number`	the selected marker(s) / count
`get marker <id> line arrow` / `line length <coordSystem> <skyDist>` / `line point ...`	line marker properties
`get marker <id> map length <value> <coordSystem> <skyDist>`	convert a canvas-pixel length to a sky/image length for that marker
`get marker <id> point shape` / `point size`	point marker shape/size
`get marker <id> polygon point ...` / `polygon segment <x> <y>`	polygon vertex list / which segment is at a position
`get marker <id> projection point ...` / `length ...` / `thick ...`	projection marker geometry
`get marker <id> property [<markerProperty>]` / `property <markerProperty>`	a marker's (or the under-cursor marker's) property flag(s)
`get marker <id> ruler format` / `length ...` / `point ...` / `system`	ruler marker settings
`get marker <id> tag [<n>]` / `<name> tag` / `<name> tag number` / `tag all` / `tag default name`	a marker's tag(s), or the default tag name for new markers
`get marker <id> text` / `text rotate`	text marker label / rotate-with-shape flag
`get marker <id> type`	the marker's shape type name
`get marker <id> vector arrow` / `vector length ...` / `vector point ...`	vector marker properties
`get marker <id> width` / `width` / `<id> dashlist` / `dashlist`	line width / dash pattern
`get marker number`	the total number of markers
`get marker preserve`	whether markers persist across new images (see `marker preserve`)
`get marker show` / `show text`	marker/label visibility

Syntax	Saves
`save array <dest> <endian>`	the raw data array
`save array rgb\|hls\|hsv cube <dest> <endian>`	a raw 3-plane composite data cube
`save fits [image] <dest>`	the FITS image
`save fits table <dest>`	the FITS bin table
`save fits slice <dest>`	the current cube slice
`save fits ext cube <dest>`	a FITS cube built from all extensions
`save fits mosaic image <dest>` / `save fits mosaic <dest> <n>`	one mosaic tile / the full mosaic (n = tile count)
`save fits rgb\|hls\|hsv image <dest>` / `rgb\|hls\|hsv cube <dest>`	a FITS composite image / cube
`save fits resample <dest>`	the currently displayed (zoom/rotate-resampled) image
`save pixmask file\|channel <dest>` / `socket <fd>`	the pixel mask layer
`save nrrd <dest> <endian>`	an NRRD-format volume
`save envi file <hdrfile> <datafile> <endian>`	an ENVI image (paired header + data file)
`save photo <filename>`	the displayed image as a Tk photo-format file