skycat - Frequently Asked Questions

## SKYCAT FAQ
FREQUENTLY ASKED QUESTIONS

Return to skycat Main Page

FEATURES

1. What command-line options does skycat support?
2. Where can I get the source code for skycat?
3. Where can I get a binary release of skycat?
4. How can I add my own catalogs to skycat?
5. What are the special MORE and PREVIEW catalog columns?
6. What remote interfaces are there to access skycat?
7. What commands can I send to skycat with Tk send?
8. How does the remote socket interface to skycat work?
9. How can I access skycat images in shared memory?

PROBLEMS

1. Why do I sometimes get color flashing when using skycat?
2. skycat uses up all of the colors in my colormap. How do I make it stop?
3. What does the catalog window take so long to pop up?

What command-line options does skycat support?

  In general, the syntax is:

  > skycat fileName -option value ...

  An argument not starting with "-" is taken to be a FITS image file to load. A "-" by itself means: read the FITS file from the standard input. A file with the suffix ".hfits" is taken to be an H-compressed FITS file and is decompressed automatically. A ".gfits" or ".gzfits" suffix indicates that the FITS file is GZIP compressed and a suffix of ".cfits" is assumed to be UNIX compressed. Image formats other than FITS are not currently supported, but will be in a future release.

  The following options are supported:

  -file FITSfile | Specify a FITS file to load. The '-file' part is optional, so you can also simply specify a file name, as described above.

  -cat bool | If bool is 1, include 'Data-Servers' menu in the menubar (This is the default). The 'Data-Servers' menu gives you access to the ESO/Archive extensions for browsing astronomical catalogs, plotting objects in the image window and getting images over the network from the image servers, such as the Digitized Sky server.

  -rtd bool | If bool is 1, include the Real-Time menu in the menubar (default is 0). The Real-Time menu gives you access to the VLT Real-Time Display features, such as camera control and rapid frames. To use these features, the rtdServer daemon must be running on the local host. A client application, linked with the Rtd image event library can then send images via shared memory to be displayed in rapid succession.

  -port portnum | Specify a port number to ue for the remote socket interface. The default is 0, which means choose an unused port. See the RTD User's Guide for a description of the remote socket interface.

  -disp_image_icon bool | If bool is 1 (default), display a miniature version of the image in the tool's icon window.

  -default_cmap cmap | Specify the default colormap. This should be one of the names listed in the 'Colors' popup window (default is 'real').

  -default_itt itt | Specify the default intensity transfer table. This should be one of the names listed in the 'Colors' popup window (default is 'ramp').

  -colorramp_height pixels | This option can be used to change the height of color bar (the widget at the bottom of the screen displaying the image colors).

  -with_colorramp bool | If bool is true, display the color bar (default).

  -with_zoom_window bool | If bool is true, display the zoom window (default).

  -with_pan_window bool | If bool is true, display the pan window (default).

  -dozoom bool | If bool is true, turn the zoom window on automatically (default).

  -debug bool | If bool is true (default: false) turn on debugging features. This also enables the real-time simulation (when the -rtd option was specified).

  -verbose bool | If bool is true (default: false) display debugging messages at run-time (for debugging).

  -display dpy | Specify the X server to use.

  Arguments which are not switches are interpreted as image files.

Where can I get the source code for skycat?
  The software is available as source code for research and other non-profit organizations. If you are interested to obtain the package send us a note.

Where can I get a binary release of skycat?
  Single binary versions of skycat are available for Solaris, HP-UX and SunOS. These binaries were built using code borrowed from GNU emacs (unexec) that makes it possible to include interpreted sources and other files in an executable.

How can I add my own catalogs to skycat?
  First of all, you should have a look at the skycat config file This file lists the catalogs available by default. You can use a different list by setting the environment variable `SKYCAT_CONFIG` to a valid URL on an http server. If you want us to add your catalog to the default list, send us an email.
  More about catalog servers can be found in the note written by Clive Davenhall (Starlink).

  To include your own catalog in skycat, you have to implement a catalog server, and add an entry to the skycat config file for it.

  Note that there has been some discussion about standards for catalog servers and the URL syntax used to access them. Please see Astronomical Server URL for more information on that.

  A catalog server is called via HTTP as a cgi-bin application. The syntax for the URL is taken from the skycat config file. The URL contains the query parameters, such as RA, DEC, RADIUS, etc. The format of the return value is a tab separated table with column headings separated from data by a dashed line "---".

      TableTitle

      # comments, text, etc...
      ...

      ID      RA      DEC     OtherCols
      ----    ----    ----    ---------
      someId1 42.331  43.233  etc...
      ...

  skycat expects the first three columns to always be: ID, RA and DEC. The following columns can be anything. RA and DEC should be in degrees, J2000. In the the query arguments, RA and DEC are specified in HH:MM:SS.sss format and the radius in arcmin.

What are the special MORE and PREVIEW catalog columns?
  There are two special (optional) catalog column names: `MORE` and `PREVIEW`. They are expected to contain a URL in the format `M=http://...` for MORE and `P=http://...` for `PREVIEW`.

  The `MORE` URL should point to an HTML page with more information on the object. skycat passes the URL to netscape for display.

  The `PREVIEW` URL should point to either a FITS image (possibly compressed) of the selected object or a tab table with data to plot as an X,Y graph. The Content-type of the HTTP result is used to determine whether the data is a FITS image or a tab table and whether or not it is compressed. The Astronomical Server URL document mentioned above describes the allowed Mime-type/Content-type values. These have been implemented in skycat.

  If the Content-type of the PREVIEW data returned from an HTTP server is recognized as a tab table (text/x-starbase, etc., or even text/plain), it it should be an ASCII tab table with 2 columns. The first column is plotted as X and the second as Y and the column headings are displayed as the X and Y graph labels.

What remote interfaces are there to access skycat?
  There are a number of ways to access skycat data or commands from an external process:

  - Tk send, plus a collection of simple Tcl procs defined by Skycat
    (see below and also the comments at end of `skycat/interp/library/Skycat.tcl`)

  - Remote socket interface
    (see `rtd/rtdrmt` module for examples)

  - SysV shared memory for image header and data
    (see rtdimage "`shm`" subcommand)

  - MMAP shared file/memory for image header and data
    (mmap is used by default to read the image files)

  - Rtd real-time interface (rtdServer)

What commands can I send to skycat with Tk send?
  If Skycat is compiled with Tk send enabled (you have to edit the Tk Makefile to do this if you compile yourself) there are some simple Tcl procedures defined that can easily be called from another Tk based application:

  - `get_catalog_info` {}
    - return contents of catalog listing in the format {{selected_row} {{row1} {row2} ...}}

  - `display_image` {`ra dec width height {equinox 2000}`}
    - display image from DSS

  - `mark_image` {`ra dec width height`}
    - draw a rectangle on the image, return id

  - `unmark_image` {`id`}
    - remove the rectangle given by id

  - `load_image` {`filename`}
    - load and display an image file

  - `pick_object` {`{cmd ""}`}
    - display the "PickObject" dialog window to allow the user to select an object/star and return the info for it in the form: {$x $y $ra $dec $equinox $fwhmX $fwhmY $angle $object $background}

  See also the comments at end of source file: cat/tclcat/library/SkyCat.tcl. The PickObject interface is (or will be) described in the man page RtdImagePick(n).

How does the remote socket interface to skycat work?
  The remote socket interface is an RTD feature described in the RTD User's Guide, which can be found in the doc directory of the skycat ftp dir.

  Basically, what you can do is open a socket connection and send ASCII strings to Skycat (since it is based on the RTD). The port number can be specified on the Skycat command line with the `-port` num option.

  The strings are interpreted as RTD subcommands. The command method is called with the given arguments and the result is returned via socket again. It is similar to Tk send, except that it is more secure (you can only access RTD subcommands) and can easily be used by a C application (or any other language).

  The format to send a command is:

      command\n

  (command followed by newline) where `command` is one of the RTD subcommands (without an instance name). The result read from the socket has the format:

      status length \n result[length]

  That is, 2 lines: the first line contains 2 numbers: the command status (0 is OK) and the length of the result. The next line contains the result, which has the given length.

  Check out RTD User's Guide and the rtd/rtdrmt directory in the Skycat source tree for examples of how to use the remote interface.

How can I access skycat images in shared memory?
  Skycat doesn't put images in sysV shared memory by default, since some systems have a very low default limit on the number of available sysV shared memory areas. However, there are commands (rtdimage subcommands) to tell skycat to use shared memory for the internal FITS image header or data or both. (Note: by default skycat maps the image files using mmap(2).)

  - You can use the `-shm_header 1` and `-shm_data 1` options when starting skycat, so that shared memory is used automatically.

  - Use the rtdimage subcommand "`shm`" (also available via the remote socket interface) to tell skycat to use shared memory and to get the shared memory ids.

  See the RTD User's Guide for a description of the rtdimage subcommands.

Why do I sometimes get color flashing when using skycat?
  If you are running other applications, such as netscape, that use many colors, you may have this problem. Try running netscape with the "-ncols 60" option, to limit the number of colors it uses to 60. You can limit the number of colors skycat uses via the View menu (Colors item).

skycat uses up all of the colors in my colormap. How do I make it stop?
  Select Colors... from the skycat View menu. There you can adjust the number of colors skycat uses by moving the slider and pressing the Allocate button.

What does the catalog window take so long to pop up?
  When you display the catalog (Data-Server or Image-Server) window for the first time, it reads the skycat configuration file over HTTP for the list of catalogs. You can specify a local configuration file by setting the environment variable `SKYCAT_CONFIG` to a valid URL (http://... or file:/... for a local file). The default URL is: http://archive.eso.org/skycat/skycat2.0.cfg

Please send questions or comments to abrighto@eso.org.
Copyright © 1996 ESO - European Southern Observatory

Last modified: Thu Aug 6 20:37:07 MEST 1998