# E.S.O. - VLT project 
#
# "@(#) $Id: rtdimage.mann,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  20 Jul 95  Created
# Allan Brighton  10 Apr 96  updated for recent changes
# Allan Brighton  24 Oct 96  updated for recent changes
# Allan Brighton  22 Jan 98  updated for recent changes

NAME
rtdimage - Real-Time Display Image, a Tk Image Type

SYNOPSIS
image create rtdimage ?option value ...?

DESCRIPTION
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)).

CREATING RTDIMAGES
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.

OPTIONS
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)).

COORDINATES
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 WIN1 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.
    
IMAGE FORMATS
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.

COLOR ALLOCATION
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.

MOTION EVENTS
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).

IMAGE COMMANDS
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.


ENVIRONMENT VARIABLES 
RTD_LIBRARY - If set, this should point to the directory
              containing the rtdimage Tcl library files.
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
SEE ALSO
RtdImage(n), rtdServer(1), rtdImageEvt(3), BLT(n), canvas(n)
----------------------------------------------------------------------
