TUI:Telescope:User Catalogs

User catalogs allow you enter positions for your objects into a file, to save time during an observing run. To set up a catalog file, read the rest of this document. To load a catalog, select Open... from the Catalog menu of the Slew window.

The catalog format was designed to be fairly compatible with Remark user catalogs (if you specify the epoch then you will have some work to do), while allowing additional flexibility. Before diving into the details, here is an example:

# default coordinate system and object
# (these are the standard defaults, so if you like them you can omit this line)
CSys=FK5; Date=2000; RotType=Object; RotAng=0

# some random objects
# Name            Pos1 (e.g. RA)  Pos2 (e.g. Dec)  Options in keyword-value format
"NGC6543 rot 90"  17:58:33.423    66:37:59.52      Px=0.017; RotAng=90
"Barnard's star"  17:57:48.4983   04:41:36.245     PM=-79.871, 1033.777; Px=0.54930
Sirius            06:45:08.9173  -16:42:58.017     Px=0.37921
Polaris           02:31:49.0837   89:15:50.794     PM=4.422, -1.175; Px=0.00756
"Telescope Home"  98              30               CSys=Mount; RotType=Mount; RotAng=0

The first three columns match Remark format (although TUI is more flexible about spaces and tabs). But if your old Remark catalogs use the 4th column to specify an epoch then change the epoch for each object to Date=epoch or specify the appropriate default epoch and delete the 4th column.

Catalog Content

A catalog can contain the following types of lines, which may appear in any order:

• Object Data
• Defaults
• Catalog Options
• Comments

Object Data

Each object is described by one line of data:

Name  Pos1  Pos2  Keyword-value data

where:

• Name is a string. You must specify something for the name; if you want no name then specify "".
• Pos1, Pos2 are usually RA, Dec, but are Long, Lat for Galactic coordinates and Az, Alt for some obscure coordinate systems.
• Pos1, Pos2 are sexagesimal positions and so have the same format and flexibility as positions entered in the Slew window: you can use d:m:s.s, d:m.m or d.d format (hours instead of degrees for RA). Leading zeros aren't required, but spaces are forbidden!
• Keyword-value data is described below.
• Items are separated by whitespace (any mix of spaces and/or tabs).
• There is no way to wrap lines, so if you have a lot of keyword-value data you'll have a long line.

Warning: if you are using Python 2.2.x (rather than something newer), user catalogs must have line endings appropriate to your operating system. (MacOS users: X TUI wants \n, but the prebuilt executable uses Python 2.3 so it's not an issue).

Defaults

Defaults are lines that contain only keyword-value data. A default value applies from the point it is specified until a new default value is specified. Defaults are intended to save you from repeating the same keyword-value data over and over again. Of course you can override a default for a given object by specifying a different value.

Every catalog starts out with an implied default of: CSys=FK5; Date=2000; RotType=Object; RotAng=0. This matches Remark catalogs.

Catalog Options

Catalog options apply to an entire catalog. They may appear on the same line as defaults or on their own line. If a catalog option appears more than once then only the last value is used. At present there are only two display options:

Keyword & Value	Description
DoDisplay = log	Display objects from the catalog on the sky window? Acceptable values include yes, no, true, false, t, f. The default is yes. Case doesn't matter but abbreviations are unacceptable.
DispColor = color	Color in which to display objects from the catalog on the sky window. Color is a Tk color, including named colors (e.g. "black", "dark green") and RGB hex constants (e.g. "#d900ff"). Case doesn't matter but abbreviations are unacceptable.

Keywords are not case-sensitive. Also, unique abbreviations are acceptable, but please use restraint because they must be unique with respect to the entire set of object data keywords (see below) as well as the catalog options.

Comments

Blank lines and lines that begin with with # or ! are ignored. Note that comments MUST appear on their own line.

Object Keyword-Value Data

This section describes the keyword/value data for objects (and defaults).

The most common keywords and values for object data (and defaults) are listed in the following table.

Keyword & Value	Description
CSys = csys	Coordinate system; one of: ICRS, FK5, FK4, Galactic, Geocentric, or more obscurely, Topocentric, Observed, Physical or Mount. Specifying CSys without a date sets the date to the default date for that coordinate system (see links above).
Date = date	The date of observation and (for FK5, FK4 and Geocentric coordinates) the date of equinox. If omitted, defaults to the default date for the coordinate system (see links to coordinates systems above)
PM = pm1, pm2	pm1, pm2: proper motion in arcsec/century. PM1 is dRA/dt or dLong/dt, so for a given rate of motion across the sky the value gets larger nearer the pole.
RotType = type	Rotation type; one of Object, Horizon, or more obscurely, Physical or Mount.
RotAngle = angle	Rotation angle, in decimal degrees. If omitted, defaults to 0. Note: specifying RotType without RotAngle sets RotAngle to 0.
Px = parallax	Object's parallax, in arcseconds.
Distance = dist	Distance to the object, in au. Px and Distance are different ways to specify the same quantity.
Magnitude = magnitude	Object's magnitude.

In addition, there are many other options, including for drift scanning (ScanVel), azimuth and rotator wrap (AzWrap and RotWrap), retaining offsets (Keep), pointing error logging and correction (PtError) and disabling collimation updates (NoCollimate). However, in all cases except ScanVel, you will have to expose the appropriate settings panel in the Slew window before your special settings will be used.

For details about these special settings, see the help associated with the Slew window and read the documentation for the TCC's TRACK command. Your catalog supports any qualifier supported by the TRACK command (qualifiers are keywords preceded by a /; leave off the / in your catalog).

Keywords are not case-sensitive. Also, unique abbreviations are acceptable, but please use restraint because they must be unique with respect to the entire set of object data keywords as well as the catalog options (described above).

When values are keywords (such as for CSys and RotType), the same flexibility applies. Keywords are not case-sensitive and unique abbreviations are acceptable (and less dangerous because the number of alternatives is small and well known).

Formatting Details

Keyword-Value Format

Here is an example (NoCollimate is rather obscure, but I wanted an example of a keyword that had no associated value):

PM=4.422, -1.175; Px=0.00756; NoCollimate

The rules are as follows:

• Keywords are not case sensitive.
• Unique abbreviations are allowed for keywords and keyword values; when in doubt, be sure to specify at least 4 letters, excluding an initial "No", if any.
• A keyword is followed by "=" if it has one or more values; omit the "=" otherwise.
• Values are separated by commas.
• Keywords are separated by semicolons.
• Whitespace is optional.
• String values follow the rules for String Format (see next).

String Format

• If a string contains funny characters (such as spaces, commas, double quotes, etc.), it must be enclosed in double quotes.
• If a quoted string contains double quotes or backslashes, each one must be escaped by a backslash. For example: "two \"double quotes\" and two \\backslashes\\"