Tk4.0 introduced a new "image" command and a C interface for adding new image types. A Tk image is much like a Tk widget in that it is both an object and a Tcl command. "rtdimage" is an extended Tk image type designed for real-time image display. Images can be loaded from shared memory or FITS format files, over sockets or HTTP. For real-time usage, a background daemon process rtdServer(1) communicates with the rtdimage software over a socket interface to display and update images rapidly from shared memory. A more general purpose remote control interface is also available (see rtdRemote(3)).
An "rtdimage" is created with the "image create" Tk command. After this, you can use the image in a Tk canvas by specifying it with the "-image" option. For example: set image [image create rtdimage ...] $canvas create image 0 0 -image $image ... Most Tk image types may be used in any Tk widget, however, for our purposes, it was necessary to restrict the use to canvas widgets only. This was necessary in order to handle scrolling efficiently.
The following options may be specified when creating or configuring an rtdimage: -displaymode mode The rtdimage supports two different display modes: 0 and 1. In display mode 0, space is allocated in the X server for the entire image. This makes scrolling faster, but uses enormous amounts of memory when the image is very large or is scaled to a large size. Still, this mode is useful in cases where the entire image is always displayed, such as in a panning window. In displaymode 1 (default), space is only allocated for the visible part of the image. This makes scrolling somewhat slower, but uses much less memory. -file name "name" specifies a FITS format file to load and display. -fitwidth winwidth -fitheight winheight These two options specify the size of the window into which the image must fit. The image will be scaled (shrunk) equally in the X and Y directions to fit as closely as possible inside the window. -newimagecmd command The given tcl command is evaluated every time a new image is loaded. This command is not called for real-time image updates, unless the image dimensions or data type changed. See the "camera" subcommand for getting notification of real-time image updates. -subsample bool If bool is true, subsampling is used when shrinking the image, i.e.: if the image is shrunk by 1/3, only every third pixel is displayed. Otherwise, the maximum value is taken from the group of pixels. -usexshm bool If bool is true (default), attempt to use X shared memory for the image display, if available. This improves performance considerably, but is only available when working on the system console. -verbose bool If bool is true, diagnostic messages are printed out to show what is going on internally (for debugging use). shm_header bool shm_data bool If bool is true, the image FITS header (or data) is kept in shared memory so that it can be accessed from a remote process (see rtdRemote(3)).
The rtdimage subcommands support the following types of coordinates: canvas - canvas coordinates (canvas scroll area) screen - canvas window coordinates (visible area) image - basic image pixel coords (at mag 1, no transformations) chip - detector chip/CCD coordinates wcs - world coordinates in H:M:S D:M:S deg - world coordinates in degrees For image coordinates, the origin of the image is at (1,1) (or .5,.5 if the image is zoomed). Detector chip coordinates may be the same as image coordinates, but can also have an additional offset and/or binning factor. The FITS keywords "HIERARCH ESO DET WIN STRX" and "...STRY" are used for the offset, if present. The rtdimage "convert" subcommand can be used to convert between any two coordinate systems. In addition, most rtdimage subcommands accept coordinates using the following syntax: $x $y coord_type For example: set val [$image get $x $y canvas] set val [$image get $ra $dec "wcs 1950"] set val [$image get 42.1 38.3 "deg 2000"] For world coordinates, the equinox may be optionally specified as part of the coordinate type. The default is 2000.
An rtdimage can load and display FITS format images or images written to shared memory via rtdServer(1). The following FITS image data types are supported: float, long, short, ushort, byte or XImage. Except for XImage, The order of lines is the same as for FITS files, with the origin at lower left. XImage is a special image type, which is taken to be already in a format that can be displayed with no color scaling. Support for other image types is planned, however the internal image type will remain FITS. New image types can be added by deriving a new subclass from the ImageIO(3) class.
All rtdimages in an application share the same default colormap. On startup, the rtdimage attempts to allocate as many color cells as possible, leaving about 10 free for other applications. The number of color cells allocated can be changed with the "alloccolors" subcommand. If another application (netscape, for example) has already grabbed all of the colors, a private colormap will be used. An attempt is made to keep most of the window manager colors intact, to avoid color flashing, at least in the GUI elements.
Since handling pointer motion events in Tcl code is fairly slow, the rtdimage code does some of the common work internally by setting values in a global array called "RtdImage". These values can be best accessed by specifying the "-textvariable" option to a Tk label or entry widget. The global "RtdImage" array contains the following values, which are updated on motion events: RtdImage(X) X image coordinate RtdImage(Y) Y image coordinate RtdImage(VALUE) pixel value at X,Y RtdImage(RA) world coordinate RA value RtdImage(DEC) world coordinate DEC value RtdImage(EQUINOX) world coordinate equinox The world coordinate values are set to empty strings if the image header does not support world coordinates. The same motion handler that sets the above variables also contains support for zoom windows (zoom and zoomview commands) and pixel tables (pixtab command).
The return value from the "image create rtdimage" command is the name of the image and also the name of a new Tcl command that can be used to operate on the image. The Tcl command has the following subcommands: <imageName> alloccolors ?numColors? With no arguments, this command returns a Tcl list containing the number of allocated and the number of free colors. With one argument, the command attempts to reallocate numColors colors. The number of colors actually allocated depends on what other applications are running (see COLOR ALLOCATION). <imageName> autocut ?-percent number? This command automatically sets the cut levels (the lowest and highest image pixel values considered in colormap scaling). Two different algorithms are supported. The default (and fastest version) is median filtering. If -percent is specified, the argument is a number between 0 and 100, such as 90 for 90%, where that percent of the image pixels should be within the cut values. i.e.: if you look at the graph (see graphdist command) of the pixel value distribution, you would take the top 90% of the graph and set the cut levels to left and right ends of the graph. Note: if this command is called, it is assumed that cut levels can be set automatically when a new image is loaded. See also the "cut" command. <imageName> camera start cameraName ?tclCommand? <imageName> camera stop <imageName> camera pause <imageName> camera continue The "camera start" command sends a message to the rtdServer daemon process telling it to start sending images from the given camera. Actually the server sends only image events, short messages over a socket interface, while the images are written to and read from shared memory. Camera is the name of a camera that must be known to the rtdServer (see rtdServer(1) for more information). The optional ?tclCommand? argument to "start" should be a string containing a Tcl command to be evaluated whenever a new image event is received and displayed. The "camera stop" command tells the rtdServer to stop sending image events. The "pause" and "continue" subcommands can be used to temporarily stop the image events and restart them, without having to know the name of the camera. <imageName> clear <imageName> clear ximage <imageName> clear ?-reuse $reuse -ra $ra -dec $dec -equinox $equinox -radius $radius -width $width -height $height? This command is used to blank out the display by generating and loading a blank image. With no arguments a small blank image is generated with a default header. If "-ximage" is specified, the image is only cleared temporarily, until the next image update. In the last case, the optional arguments are used to generate a dummy image that supports world coordinates, so that you can plot objects on a blank background. Any missing values are set to a default value. Optional arguments: reuse - flag: if true, reuse previous image, if it is the same ra, dec - center point for WCS coords (in decimal degrees) radius - used to initialize WCS coords (CDELT1 and 2) equinox - equinox for WCS coords width - width of generated image in pixels height - height of generated image in pixels <imageName> cmap file ?<colormapFile>? <imageName> cmap rotate <amount> <imageName> cmap shift <amount> <imageName> cmap pixels <imageName> cmap reset <imageName> cmap list <imageName> cmap private <imageName> cmap isprivate This command performs operations and queries on the colormap. If a colormap file is specified, it should contain 256 lines of red, green and blue values between 0.0 and 1.0 (MIDAS colormaps are saved in this format). The values will be distributed among the available colors and installed as a new colormap. For rotate and shift, the amount can be any integer. The colormap will be rotated (or shifted) by that amount. "pixels" returns a Tcl list of the colormap pixel values (for use by external applications using the RTI library, class ImageData). To get the number of colors in the colormap, you can use the "alloccolors" subcommand with no arguments or "llength" on the result of the pixels subcommand. "reset" resets the colormap to its original state. The RTD release includes a large number of MIDAS colormap files in the colormap directory. For "cmap file", if the filename is not specified, the current colormap file name is returned. "cmap list" returns a list of all of the colormap files currently loaded. "cmap private" says to start using a private colormap. "cmap isprivate" returns true if the colormap is private. <imageName> colorramp This command generates an rtdimage displaying the colors in the colormap as a ramp or colorbar. This image will have the same size as the window containing it. This command should be called again from Tcl if the window is resized. <imageName> colorscale ?scale_type? This command sets or queries the algorithm to be used for assigning the limited number of available colors to image pixels. If scale_type is specified, it should be one of: linear, log, sqrt or histeq, indicating the color scaling algorithm: linear scaling, logarithmic, square root or histogram equalization, resp. With no arguments, the current color scale type is returned. <imageName> convert coords inx iny in_coord_type outx outy out_coord_type <imageName> convert dist inx iny in_coord_type outx outy out_coord_type This command is used to convert between different coordinate representations. inx and iny and the input coords (or distance) in the given input coordinate system. "convert coords" treats x,y as a point, while "convert dist" treats it as a distance. outx and outy, if not empty, are the names of variables that will hold the resulting coordinates. If outx and outy are empty strings, the values are returned as a tcl list "x y". The available coordinate systems are: canvas - canvas coordinates (canvas scroll area) screen - canvas window coords (visible area) image - basic image pixel coords (at mag 1, no transformations) wcs - world coordinates in H:M:S deg - world coordinates in degrees The world coordinate types: "wcs" and "deg" may also include the epoch: Example: $image convert coords $ra $dec "wcs 1950" x y canvas Note: the coordinate types may be abbrieviated, since only the first char is actually checked. <imageName> cut <imageName> cut low high <imageName> cut low high fromUser This command sets or queries the cut levels. If low and high are specified, then the cut levels are set so that pixels below the low value will all have the lowest color while those above high will all have the highest color value. The optional fromUser argument indicates whether or not this is a result of a user action and defaults to 1 (true). Once a user has set the cut levels, automatic cut level setting is disabled. If the fromUser argument is 1, it is assumed that they should not be changed automatically when a new image is loaded. Calling the autocut subcommand resets this again (see the autocut subcommand). If no arguments are given, the current cut values are returned in a Tcl list {min max}. <imageName> dispwidth <imageName> dispheight These commands return the logical width and height of the image after transformations (scaling and rotating). This is the size of the displayed image, assuming the window is large enough. This command also takes the image's "requested width" into account (set by by "view update" subcommand). <imageName> dump <filename> This command dumps the current image to the given file in FITS format. If a FITS header is present, it is used, otherwise FITS keywords are inserted indicating the image type, width and height along with the date and a number of numbered "blank cards" or FITS keyword fields that can be modified by other applications as needed. The fields have names starting with BLANK followed by 2 digits (from BLANK00 to BLANK28). <imageName> flip <direction> ?bool? With two arguments, flip (or stop flipping) the image in the given direction, where direction is one of x, y, xy or "none" for flipping in the x, y, or x and y directions or neither. The boolean value turns flipping on (1) or off (0) in the given direction(s). With one argument, the command returns the current value for the given argument. <imageName> frameid This command returns the frame Id of this image. The frame Id is a unique number used to identify the image to the rtdServer for use with rapid frames. <imageName> get x y coord_type ?nrows ncols? Returns a Tcl list of image values at the given X,Y coordinates. X and Y are interpreted in the given coordinate system (see COORDINATES above). The return value is a tcl list where each item consists of a list of {X Y Value}, where X and Y are the adjusted coordinates in the raw image and Value is the raw data value at that point or "-" if out of range. If nrows and ncols are greater than 1, the command returns a Tcl list of nrows x ncols values, each a list of rows, centered at the given point. <imageName> graphdist bltGraph bltElem numValues This command displays the distribution of pixel values in the image in the given BLT graph widget. The data for the given BLT graph element will be set directly to the graph without going through tcl (see blt_graph(n)). The number of points to plot is given by the numValues argument. <imageName> itt file <ITTFile> <imageName> itt scale <scaleFactor> This command operates on MIDAS style intensity transfer tables or ITTs. If an ITT file is specified, it should contain 256 intensity values in the range 0.0 to 1.0, one per line. The colormap will be modified by applying the intensities to it. The colormap can also be stretched or squeezed by applying an integer scale factor to the ITT. The RTD release contains a number of ITTs in the colormaps directory. <imageName> max Returns the highest pixel value in the image. <imageName> mband x0 y0 x1 y1 cord_type show_angle Draw a measure band on the canvas to show the distance in world coordinates (diagonal, vertical and horizontal). This method was originaly implemented in Tcl/[incr Tk], but was redone here for better performance. x0 and y0 are the starting coordinates of the drag, x1 and y1 are the coordinates from the motion events and show_angle is a flag: if true, show the horizontal and vertical distance, otherwise only the diagonal. The coordinates are accepted in the given coordinate system "coord_type", see COORDINATES above. <imageName> min Returns the lowest pixel value in the image. <imageName> mmap set $data_filename $data_offset $data_owner ?$header_filename $header_offset $header_owner? <imageName> mmap get data <imageName> mmap get header <imageName> mmap create $filename $size <imageName> mmap delete $filename <imageName> mmap update This subcommand provides access to the mmap shared memory in which the FITS image data and header are stored. Image files are always mapped with mmap by default (since it is faster than reading the file). Applications can take advantage of this to modify the image data and then notify the application to update the image. This command makes it posible to put the image data and header in separate files, so that they can be more easily updated by other applications. If you want to put both header and data in the same file in the normal way, just use "<imageName> config -file". Otherwise you can use this command to quickly update the image data in a separate file. The "set" command allow you to set the files to use to for the image data and header. The data and header in the specified files should be in FITS format (i.e.:, a FITS file split in 2 parts). If the header is not specified, the previous header is reused, if there was one. The offset arguments indicate an offset in the file where the header or data start. If the file contains only the data or only the header, the offset argument should be set to 0. A flag indicating who "owns" the file may be specified (if true, then the file will be deleted when no longer needed). Example: <imageName> mmap set datafile1 0 0 headerfile1 0 0 <imageName> mmap set datafile2 0 0 ... The "get" command returns mmap information about the data or header. If the data or header is not currently mapped, an error is returned. The return value is a list of the form {filename offset owner}, the same as the arguments to the "<imageName> mmap set" command. The "create" command creates a new mmapped file with the given name and the given size. The mmaped file/memory should be released with the "delete" subcommand when no longer needed. The "delete" command unmaps the given file and deletes it, if it was created with the "mmap create" subcommand. The "update" command causes the display to be updated to reflect any changes in the image memory. <imageName> pan start <tclCommand> <shrinkFactor> pan stop This command supports a panning image, which is, in this case, a second rtdimage image or "view" of the main image, scaled to a small size with a rectangle indicating the visible portion of the image. If "start" is specified, the given tcl command will be evaluated whenever the image size changes, due to scaling or loading a new image, or whenever the image position has changed due to scrolling. The tcl command will be called with 5 arguments: x1 y1 x2 y2, which are the coordinates of the visible part of the image, scaled by the given "shrinkFactor", and a flag indicating whether the image is new (1) or an update of the existing image (0). This can be used to draw the panning rectangle on the panning image. To stop the command from being called, use the "pan stop" subcommand. <imageName> pixtab start <nrows> <ncols> <imageName> pixtab stop This command supports displaying a table of pixel values around a point. All this commmand does is set a flag causing Tcl array variables to be updated on motion events, which can cause the display to be updated via the "-textvariable" widget option on the table items. The array name is fixed as: RtdPixTab and the elements are indexed as $RtdPixTab(i,j), where the left and top sides of the table (array) are the X and Y image coordinates, resp. and the rest are image pixel values. <imageName> preview <bool> If bool is true and real-time images are being displayed, the viewing mode is set to "preview mode", otherwise, it is set back to "real-time mode". In preview mode, the camera is stopped (if it was running) and a local copy of the shared memory image is made, so that it can be freed or modified without affecting the image. <imageName> radecbox <ra> <dec> <radius> ra and dec are the world coords (h:m:s or decimal deg) and radius is expected in arcmin. The return value in Tcl is a list of 4 values {ra0 dec0 ra1 dec1} that form a ra,dec box with the given center point and radius. <imageName> remote ?$port? This command implements a remote control of the RTD image. If a port number argument is specified The widget will start listening for commands on the given port. If port is 0, a port number will be chosen. If no port number is specified, the current port number is returned, or "" if there is none. This is a way to determine the port number at the Tcl level. <imageName> remotetcl ?$command? Evaluate a Tcl command in the RTD Tcl interpreter. <imageName> rotate ?bool? Rotate (or stop rotating) the image. Currently, rotation is only done by swapping the x and y axis. If bool is specified, rotation is turned on(1) or off(0). Otherwise, the current setting is returned. <imageName> scale ?sx sy? With 2 arguments, the image is scaled (magnified) by the given X and Y amount. With no arguments, the current scaling factors are returned (as a tcl list of 2 integers). The scaling factors are positive or negative integers (default 1). Positive integers are used to zoom in on the image (2 means twice the original size). Negative integers are used to zoom out (-2 means 1/2 the original size). The software imposes an arbitrary limit on the minimum and maximum scaling factor allowed. <imageName> shm set $data_size $data_id $data_owner ?$header_size $header_id $header_owner? <imageName> shm get data <imageName> shm get header <imageName> shm create $size <imageName> shm delete $Id <imageName> shm update This subcommand provides access to the shared memory in which the FITS raw image data and header are stored. The raw image is stored in shared memory if the -shm_data option was specified when creating the image and the header is stored in shared memory if the -shm_header option was specified. The "set" command allow you to set the shared memory Ids to use to access the image data and header. The data and header in the area specified should be in FITS format. If the header is not specified, the previous header is reused. For both data and header, the size of the area (in bytes) and the shared memory Id must be specified. In addition a flag indicating who "owns" the shared memory is specified (if true, then the area will be deleted when no longer needed). The "get" command returns the shared memory Id of the data or header. If the data or header is not currently in shared memory, it is copied to a new shared memory area and the Id for this area is returned. The "create" command creates a new shared memory area with the given size and returns the Id. The memory should be deleted with the "delete" subcommand when no longer needed. The "delete" command deletes the shared memory with the given Id (which should have been returned from the "create" subcommand). The "update" command causes the display to be updated to reflect any changes in the image memory. <imageName> spectrum <bltGraph> <bltElem> x0 y0 x1 y1 coord_type This command is used to display a graph of a "cut" of the image along a given line. x0, y0, x1 and y1 are the end points of a line in the image (in the given coordinate system, see COORDINATES above). <bltGraph> is the path name of a BLT graph widget to display the plot of the pixel intensities along the line. <bltElem> is the name of the element in the graph that should receive the data. The data is sent directly to the graph for display. The return value in Tcl is the number of points to plot. <imageName> statistics statistics subcommand: calculate statistics on the section of the image being displayed. The return value in Tcl is a list of the following values: {x y ra dec equinox fwhmX fwhmY angle objectPeak meanBackground} where: x = adjusted X image coordinate y = adjusted Y image coordinate ra = RA position (calculated from mean X pos within array) dec = DEC position (calculated from mean Y position within array) equinox = equinox of RA and DEC fwhmX = FWHM in X fwhmY = FWHM in Y angle = angle of major axis, degrees, along X = 0 objectPeak = peak value of object above background meanBackground = mean background level <imageName> type Returns the data type of the raw image as a string: one of: float, long, short, ushort, byte or XImage. The last type, XImage is a special pseudo type, the same as a byte image, except that the Y axis is reversed and it is assumed to not need color scaling. <imageName> update This command makes sure that the image is up to date with the raw data (which may have changed via shared memory, mmap, etc). <imageName> view add <path> ?propagateScale? <imageName> view remove <path> <imageName> view update <path> x y width height viewx viewy coord_type <imageName> view enter <path> <imageName> view leave <path> The view command is used to specify a viewing image to view the same image, possibly at a different size. The new view will share data with the original and be updated when the original is updated. This can be used, for example, to build a panning window or a rapid frame. <path> must be the name of a second rtdimage image. The two images will communicate internally to always display the same image, possibly scaled to different sizes. The subcommands are: add Adds a new view to this image. remove Removes the view. update Updates the view from this image with the given image x,y offset, width and height and the position of the image view origin in the given coordinate type. This command can be used to implement a zoom window or rapid frame, since it controls which portion of the image is displayed. enter If 2 images are in the same canvas, make <path> the current one (receives motion events, ...). leave Undo the enter command. If the optional "add" argument "propagateScale" is true, changes in the scale factors in the master image will propagate to the view (this is the default behavior). <imageName> warp <x> <y> Warp (move) the mouse pointer by the given x and y amounts (pixels). <imageName> wcscenter ?-format <format>? This command returns the world coordinates of the center of the image. The optional format option determines the format of the result: -format 0 ==> H:M:S [+-]D:M:S (default) -format 1 ==> RA DEC (in degrees) The return value is a tcl list, formatted according to the format option, or an empty string if the coordinates are out of range or WCS is not supported. <imageName> wcsdist x0 y0 x1 y1 This command returns the world coordinate distance between 2 points after transformations. The arguments are expected in canvas coords (canvasx, canvasy, doubles). The return value in Tcl is the WCS distance between the given points after transformations. <imageName> wcsheight This command returns the height of the image in arcmin or the empty string if WCS is not supported. <imageName> wcswidth This command returns the width of the image in arcmin or the empty string if WCS is not supported. <imageName> wcsradius This command returns the radius (distance from center to corner) of the image in arcmin or the empty string if WCS is not supported. <imageName> wcsset <ra> <dec> <secpix> <xrefpix> <yrefpix> <nxpix> <nypix> <rotate> <equinox> <epoch> <projection> <imageName> wcsset If arguments are specified, this subcommand sets up the WCS structure from the given information about the image: Arguments: ra = Center right ascension in H:M:S dec = Center declination in D:M:S secpix = Number of arcseconds per pixel xrefpix = Reference pixel X coordinate yrefpix = Reference pixel Y coordinate nxpix = Number of pixels along x-axis nypix = Number of pixels along y-axis rotate = Rotation angle (clockwise positive) in degrees equinox = Equinox of coordinates, 1950 and 2000 supported epoch = Epoch of coordinates, used for FK4/FK5 conversion no effect if 0 proj = Projection With no arguments, the command returns a list of the basic WCS parameter values: {ra dec secpix nxpix nypix rotate equinox epoch}. <imageName> wcsshift <ra> <dec> <coorsys> This command resets the center of the WCS structure. Arguments: ra = New center right ascension in degrees dec = New center declination in degrees equinox = must be 2000 or 1950 <imageName> width <imageName> height These commands return the width and height of the raw image in pixels. <imageName> zoom start <frame> <zoomFactor> <imageName> zoom stop (Note: This command is no longer supported: please use zoomview (below) instead.) This command is used to implement a zoom window, a window displaying a magnified section of the image at the location of the mouse pointer. There are currently two versions of this command (see the zoomview subcommand below). In this version, a Tk frame is specified to hold the zoomed image, which is copied directly from the XImage whenever the mouse pointer moves over the image. This version is faster, but when the main image is shrunk, the zoom will not be very accurate. If "start" is specified, zooming begins in the given window, and can be stopped with the "zoom stop" subcommand. <imageName> zoomview start <view> <zoomFactor> <imageName> zoomview stop This command can be used as an alternative to the zoom command above. It uses a "view" of the main rtdimage, so the zoom image is always accurate, even when main image is shrunk. The "view" argument to "zoomview start" should be the name of a second rtdimage, which is a "view" of the main image, added with the rtdimage "view" subcommand. The zoomFactor is the magnification relative to the main image. For example, if the zoomFactor is 5 and the main image is scaled to 1/2, the zoom window scale factor would be 4. Once started, the main image will automatically track mouse movements and update the zoom window's x and y offsets as needed to display the relevant magnified section of the image.
RTD_LIBRARY - If set, this should point to the directory containing the rtdimage Tcl library files.
$RTD_LIBRARY/ - Tcl/Itcl library files $RTD_LIBRARY/colormaps - MIDAS colormap/ITT files $RTD_LIBRARY/images - sample FITS images $RTD_LIBRARY/bitmaps - X bitmaps used at runtime $RTD_LIBRARY/demos - rtdimage demo application
RtdImage(n), rtdServer(1), rtdImageEvt(3), BLT(n), canvas(n)
- - - - - - Last change: 07 May 99
Please send questions or comments to abrighto@eso.org.
Copyright © 1998 ESO - European Southern Observatory