VERY LARGE TELESCOPE

The ESO SkyCat Tool - Issue 2.22.3VLT-MAN-ESO-19400-155211Single Binary Versions of SkycatSkycat can also be compiled as a single binary that includes all of the necessary bitmaps, colormapsand Tcl source files.For Tcl7.6/Tk4.2, this is done using a slightly modified version of ET1 (Embedded Tk), a public domain package designed for this purpose. This works by creating a single Tcl script out of all of theTcl sources (including all dependent packages). The generated Tcl script is then “compiled” by ET ,creating a C source file, in which the Tcl code is declared as a string. ET defines the necessary environment so that Tcl scripts are found in the string at run time. The bitmaps and colormap files arecompiled in, in all cases, so that there is no problem there.For Tcl8.0/Tk8.0, the Scriptics TclPro prowrap2 application is used, if available. The ET version doesnot currently work with Tcl8.0.1. The ET code had to be extended to support Itcl and Itk.2. See http://www.scriptics.com/tclpro/ for information about TclPro and prowrap.

12The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-1552

The ESO SkyCat Tool - Issue 2.23VLT-MAN-ESO-19400-155213User’s GuideThis section first describes the skycat Itcl widget classes and then describes a number of ways to extend skycat and add new features by using plugins, Tcl send, a remote socket interface, and subclassing.3.1The Skycat ApplicationThe skycat application comes in two basic versions: An interpreted version A single binary versionActually both versions are interpreting Tcl source code. The difference is in the external environment required.The single binary version has all of the Tcl source files included as strings in the binary, and so doesnot require any local Tcl installation or special environment to run. This version is easier to distribute over the net.The interpreted version, on the other hand, requires a complete Tcl environment, with all of thenecessary extensions. This version is practical to use during development or when you want to dynamically load Tcl packages at run-time. This version is started using a symbolic link to a shellscript skycat.sh that sets the necessary environment variables and starts skycat wish, passing it themain skycat.tcl source file. The shell script is generated by the skycat configure script and includesthe package path names found at the time configure was run.In both versions, the application is started by calling SkyCat::startSkyCat (a class procedure).This proc sets up the necessary Tcl environment and creates an instance of the top level SkyCatclass. The command line arguments are passed unchanged to the class as options. See Rtd(n) andSkyCat(n) for a detailed description of the options.Usage:skycat fitsFile -option value .Skycat Command Line OptionsOptionValueDescription-catboolean(1 or 0)Include ESO/Archive catalog extensions (default: 1).-colorramp heightheight in pixlesHeight of colorramp window (default: 12).-debugbooleanDebug flag: If true, run background processes in the foreground toease debugging.-default cmapbasename ofcolormap fileSpecify a different default colormap (default: “real”). See the RTD LIBRARY/colormap directory for a list of the availablecolormaps. The option value if the basename of the file.-default ittbasename of ittfile.Set the default intensity transfer table. (default: “ramp”). See the RTD LIBRARY/colormap directory for a list of the availablefiles.

14The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-1552Skycat Command Line OptionsOptionValueDescription-filefile nameSpecify a FITS file to load (‘-’ for stdin). This is the defaultoption, so you can leave off the “-file” part and just specify a fileto load.-float panelbooleanIf the option value is 1, the skycat info panel is put in a separatepopup window, leaving more space for the image window (Thedefault is off).-min scale-max scalenumberSpecify the min and max scale values for the Magnification(2 zoom 2xMenu. Negative values shrink the image, positive values zoom in-2 zoom 1/2x) closer. The default values are -10 and 20.-panel layoutlayoutWith this option, you can change the order of the zoom and panwindows in the layout. The default layout is: zoom window on theleft, info panel in the center and pan window right. If the layout isspecified as saoimage, a layout similar to saoimage is used (infopanel, pan window, zoom window). If reverse is specified, theorder of the windows is the reverse of the y the orientation of the “Pick Object” window. The defaultis horizontal (panel left, image right). vertical puts the image attop and panel underneath.-portport numberListen for remote commands on the given port (default: 0, whichmeans to choose a port).-remotebooleanIf -remote 1 is specified and a skycat process is already running,the existing skycat process is sent a message and asked to open anew window and the new skycat process exits immediately. Thishas the advantage of sharing the image colormap and using fewersystem resources, however it depends on being able to use the Tclsend mechanism. For security reasons, Tcl send will not work ifyou are using xhost based X security. You need to use Xauth security. See the Tcl/Tk Tools book from O’Reilly for more on thistopic.-rtdbooleanIf true, include ESO/VLT Real-Time Features in the Skycat menubar (default: not included).-scrollbarsbooleanIf true, Display horizontal and vertical scrollbars for the image(not displayed by default).-shm databooleanIf true, put image data in sysV shared memory. By default imagefiles are mapped with mmap, not with sysV shared memory.-shm headerbooleanIf true, put the image header in sysV shared memory (default: 0).-usexshmbooleanIf true (default), use X shared memory, if available.-use zoom viewbooleanIf true (default), use a “view” of the image for the zoom window.-verbosebooleanIf true, print diagnostic messages for debugging (default: 0).-with colorrampbooleanIf true (default), display the color bar.

The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-155215Skycat Command Line OptionsOptionValueDescription-with gridbooleanIf true, include a WCS grid button (default: 0).-with pan windowbooleanIf true (default), display the pan window.-with zoom window booleanIf true (default), display the zoom window.-zoom factorSet the zooming factor for the zoom window (default: 4 x).3.23.2.1numberSkycat Widget ClassesThe Main Skycat WindowSkycat defines subclasses of some rtd and cat classes and combines the image display features of thertd with the catalog features of the cat package. The main window of the skycat application is inherited from rtd and adds only the Data-Servers menu, which is generated automatically based on thelist of available catalogs. Skycat’s top level window is implemented by the SkyCat(n) widget class,which is a subclass of the Rtd class. The SkyCat class adds the Data-Servers menu and defines an

16The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-1552external proc interface, so that other Tcl applications can use the Tcl send command to send commands to skycat.The SkyCatCtrl(n) widget defines the inner frame, containing the image and the upper panel. This isa subclass of the RtdImageCtrl class and adds methods for drawing plot symbols.3.2.2The Catalog WindowWhen a catalog is selected from the Data-Servers menu, the window that is displayed is a subclass ofthe catalog class cat::AstroCat called SkySearch(n).The top level SkySearch widget class adds image and plotting support to the cat::AstroCatwidget. It adds the Plot button and redefines the plot method to draw symbols in the image for eachquery result object.Skycat redefines the internal widgets that make up the AstroCat widget here to deal with imagesand plotting.The top widget, SkyQuery(n), is a subclass of cat::AstroQuery and adds two buttons for settingthe area of the image to search: “Select Area”, to interactively select a region of the image to search, and “Set From Image” to set the range to include the entire image.The results of the query are displayed in a subclass of cat::QueryResult called SkyQueryResult(n). This class redefines the methods for adding an object to a local catalog to include automaticselection of object coordinates using the RtdImagePick (pick object) widget.3.3Extending SkycatThere is an almost endless list of features that you could add to an application like skycat. Some ofthe features are of general use, while many others are specific to a certain project or telescope. Thissection describes some of the ways you can add new features or modify existing features without

The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-155217having to make any changes in the skycat source code. This is important, since it saves a lot of workmerging source code after every new version comes out.3.3.1PluginsPlugins are defined here as Tcl procedures that are called to extend skycat and add new features.Skycat supports two types of plugins: one at the widget level, which is called for each instance of atop level widget, after it has been constructed, and one at the application level, called once for the application, before any widgets are created. The Tcl plugin procedure can do something simple, suchas add a new menu item with a new feature, or something quite complex, including replacing themain application class with a derived class and dynamically loading Tcl packages from shared library files.3.3.1.1 Widget Level PluginsNearly all of the top level widgets used in skycat support plugins. This is a simple feature inheritedfrom the TopLevelWidget base class. For any given widget class Foo that is a subclass of TopLevelWidget, a Tcl proc named Foo plugin many be defined. The plugin proc is called for each instance of that class, after the class construction is complete (after calling the init method), with thename of the class instance as an argument.The plugin source files are located as follows: If the environment variable FOO PLUGIN is defined(replace FOO with the Itcl class or application name in upper case), it is assumed to be a colon separated list of plugin source file names, or the names of directories containing plugin files, or containing subdirectories with plugin files (see the example source tree below).In the case of skycat, you could define the environment variable SKYCAT PLUGIN, since skycat isthe name of the application and also the name of the main class. You could also define other environment variables, such as SKYSEARCH PLUGIN, for other toplevel Itcl classes, if you want to havea Tcl proc be called for each instance.Example:setenv SKYCAT PLUGIN “ dir1/myplugin1.tcl: dir2/myplugin2.tcl: dir3”In the above example, the two source files ( dir1/myplugin1.tcl and dir2/myplugin2.tcl) will be loaded as plugins, as well as any file named dir3/ {classname} plugin.tcl or dir3/*/ {classname} plugin.tcl. Probably the simplest way to organize the plugins is to define a single top levelplugin directory and create a subdirectory for each plugin. SKYCAT PLUGINplugin 1/plugin 2/SkyCat plugin.tclSkySearch plugin.tcl.SkyCat plugin.tclplugin n/SkyCat plugin.tclRtdImagePickObject plugin.tclTypical Skycat plugin directory structure.You can put plugin procedures for more than one class in a single plugin file, or define environment variables and create files for each one separately. If the plugin procedure is defined, it will becalled once for each instance of the class. The directory containing the plugin file is automatically

18The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-1552appended the tcl auto path variable, so that you can easily split the plugin into different source filesin that directory, as long as it contains a tclIndex file.The plugin proc can be used to add features to widgets, such as additional menus or buttons. Onceyou have the handle for the top level widget, it is usually easy to access other internal widgets, ifnecessary, to make any changes or additions you want. The Tcl language is also very flexible andwill allow you to redefine procedures and methods at run time.3.3.1.2 Example Widget Level PluginBelow is an example plugin file for the SkyCat class. To use this plugin, you have to define the environment variable SKYCAT PLUGIN first, for example:setenv SKYCAT PLUGIN your-pathname/SkyCat plugin.tclThe source code for SkyCat plugin.tcl is shown below:proc SkyCat plugin {this} {set w [info namespace tail this]add graphics features w}This plugin is used to add some menu items to the Graphics menu for saving line graphics to a file inworld or image coordinates so that they can be reloaded again later. The proc has to be calledSkyCat plugin, since the main Itcl class name is SkyCat. The argument this is the name of aninstance of the SkyCat class and is needed in order to be able to call methods. The variable w is setto the name of the top level window, which is the same string, but without the Itcl namespace information. You can usually use w in place of this, since the namespaces we are using (skycat,cat, rtd, etc.) are imported by default. w has the advantage that it can be used to refer to both theTk widget and the Itcl class instance.The code for the add graphics features proc is shown below:proc add graphics features {w} {set m [ w get menu Graphics] m add separator w add menuitem m command “Save graphics.” \{Save line graphics to a file} \-command [code save graphics w] w add menuitem m command “Load graphics.” \{Load line graphics from a file} \-command [code load graphics w]}The methods used here to add menu items are described in the man page for TopLevelWidget in thetclutil package documentation. We first get the handle for the Graphics menu, and then add the twoitems to it, including a short help text and a Tcl command to be called to do the work.We might have wanted to create a new menubutton, “Annotations”, rather than adding items to theexisting one. The code to do that would look something like this:proc add graphics features {w} {set m [ w add menubutton Annotations] w add menuitem m command “Save annotations.” \{Save line graphics to a file} \-command [code save annotations w] w add menuitem m command “Load annotations.” \

The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-155219{Load line graphics from a file} \-command [code load annotations w]}When the user selects the “Save graphics” (or “Save Annotations”) menu item, a tcl proc save graphicsis called and that is where the real work begins.We could also have put this code in an Itcl class, however this plugin does not have its own window (it only adds the menu items), so it makes sense to use plain Tcl procs here. It is usually easiestto define one Itcl class per widget (frame or toplevel).The save graphics proc is a bit long, so we’ll take it a step at a time as an example. The first thingwe have to do is find out the name of the file in which to save the graphics:set filename [filename dialog]if {“ filename” ““} {return}The Tcl proc filename dialog is one of a collection of simple dialog procedures provided by thetclutil package. It pops up a file browser and returns the user’s selection, or an empty string if no filewas selected. So now we know the file. We can check if it exists already, and ask if we should overwrite it:if {[file exists filename]} {if {! [confirm dialog “File filename’ exists. Overwrite it?”]} {return}}confirm dialog is another tclutil dialog that displays a message and gets a yes or no answer (OK,Cancel) from the user. Before we go any further, here is a short overview of the simple dialogs thatare available in this environment:Dialogs defined in the Tclutil Packagefilename dialogChoose a file with a file browser.confirm dialogAsk for confirmation before doing something.error dialogReport an error message.info dialogDisplay a message.choice dialogAsk the user to make a choice form a number of items.input dialogAsk the user to type something in.When we save the graphics, we have to ask whether to save the coordinates as world coordinates orimage pixel coordinates.set choice [choice dialog \“Please select the type of coordinates to save the graphics in:” \{{World Coordinates} {Image Coordinates} Cancel} \{World Coordinates} w]if { choice “Cancel”} {returnelseif { choice “World Coordinates”} {set units {deg J2000}} else {set units image}

20The ESO SkyCat Tool - Issue 2.2VLT-MAN-ESO-19400-1552Here we set units to either “deg J2000” for world coordinate degrees in J2000 or “image” for image pixel coordinates. This is the syntax that is supported by the rtd, along with other types, such as“canvas” and “screen”. We will use units below to convert the coordinates of the graphic itemsfrom canvas to units coordinates. But first, we need to open the output file and write the firstline of output indicating the units of the coordinates.if {[catch {set fd [open filename w]} msg]} {error dialog msgreturn}puts fd “set units \” units\””Now we are almost ready to do some work. We still need access to the canvas widget holding theimage and graphics, the rtdimage object that displays the image in the canvas, and the graphics editor object, draw, of class CanvasDraw, that is normally used to create graphic items and setupbindings for moving and resizing the objects.set canvas [ w component image component canvas]set image [ w component image get image]set draw [ w component image component draw] draw deselect objectsHere we used the Itk component method to access the canvas component of the SkyCat imagewindow. Actually we are going two levels down here, that is why there are two “component” references in the first line. The above example could also be cod

tend skycat and add new features by using plugins, Tcl send, a remote socket interface, and subclass-ing. 3.1 The Skycat Application The skycat application comes in two basic versions: An interpreted version A single binary version Actually both versions are interpreting Tcl source