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. I cannot see the new catalogues in SkyCat, what should I do?
   How do I refresh my SkyCat configuration file?
6. What are the special MORE and PREVIEW catalog columns?
7. What remote interfaces are there to access SkyCat?
8. What commands can I send to SkyCat with Tk send?
9. How does the remote socket interface to SkyCat work?
10. How can I access SkyCat images in shared memory?

Problems

1. Why 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 supported.

The following options are supported:

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. All of the required packages are always included in the tarfile.

Where can I get a binary release of SkyCat?

Single binary versions of SkyCat are available for MacOS and several Linux distributions.

How can I add my own catalogs to SkyCat?

First of all, you should have a look at the SkyCat configuration 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 configuration 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 configuration 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.

I cannot see the new catalogues that are now supported by the ESO SkyCat configuration file, what should I do? How can I refresh my SkyCat configuration file?

The list of data servers (astronomical catalogues, image archives, or name servers in the Data-Servers pulldown menu) in your SkyCat installation is entirely controlled by the SkyCat configuration file. By default SkyCat reads the configuration directly from ESO. Once a local catalogue is loaded into SkyCat ( "Data-Servers -> Local Catalogs -> Load from file... [CTRL-O]"), SkyCat stores the information of your local catalog in a local configuration file, together with the ESO online configuration available at that time. From that moment on, SkyCat will use that local configuration file for all catalogues (local and remote) and no longer the ESO online configuration.

Therefore, if you use a local configuration file, you cannot see/use new catalogues that might have been added by ESO into its online configuration file.

As an example, in October 2015 both the 2MASS point-source catalogue and the UCAC4 catalogues have been added to the online configuration. If you cannot see those two catalogs in the Data-Servers -> Catalogues pulldown menu, then this means that you are using a local configuration file.

If you want to have the new catalogues/image servers/name resolvers offered by ESO and ignore local catalogues you have been using (they can always be reloaded on demand), close SkyCat, simply delete your local version of skycat.cfg (usually under ~/.skycat) and unset the SKYCAT_CONFIG environment variable if set. When reopening SkyCat it will read the ESO online configuration.

If instead you want to reflect into your local configuration file the new catalogues/image servers/name resolvers offered by ESO, while preserving the other local catalogues you have been using, the please follow these instructions:

• rename your skycat.cfg
• download the ESO online configuration file (http://archive.eso.org/skycat/skycat.cfg)
• copy the local catalogues from the old to the new skycat.cfg file (local catalogues are the ones with "serv_type: local")
• place the new file exactly in the same place and with the same name of the original local configuration file you were using before the merge.

At this point, to make effective the change you can either restart SkyCat, or simply use the Data-Servers -> Reload config file [CTRL-R] option of SkyCat.

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 a browser 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.

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 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/skycat.cfg⁽¹⁾

(1) Your SkyCat installation might report to be using http://archive.eso.org/skycat/skycat2.0.cfg, do not worry skycat2.0.cfg and skycat.cfg are identical.