RTML - Remote Telescope Markup Language

Editor Preface

This HTML document incorporates material from documents written by Shawn Gordon; it has merely been rearranged in order to to facilitate understanding and to serve as an introduction to RTML. Jon Aymon, 29 January 2000.

1999/06/23 Shawn Gordon

Purpose of RTML ("Remote Telescope Markup Language")

The Remote Telescope Markup Language is designed primarily to enable a remote observer to submit observing requests to any remote telescope which can understand this language. The observing requests can be submitted in two modes of operation: interactive, where the observer waits for the result of the observation request, and non-interactive or 'batch', where the observer submits an observing list and allows the telescope to carry out the observations in a scheduled mode.

The definition of observer is rather loose. The observer can be a human sitting at a terminal, or it can be a computer accessing a database. The main point is that it does not matter to the remote telescope who or what generates the request as long as the request is a valid RTML request file.

Control of a remote telescope consists primarily of two modes of communications - requests sent to a telescope and the response or data that is received from the telescope. This form of communication can either be interactive, in the case where an observer is controlling a telescope in real time, or it can be non-interactive, where an observing list is submitted to the remote telescope to be executed by an on-site telescope operator or by scheduling software. These two distinct formats are implicitly supported by the structure of this language. We refer to these two formats in the following as an observing list, when requests are sent to the telescope, and as an observing log, when data is retreived from the telescope.

The mode of operation of a telescope (interactive or batch) is telescope and software dependent. Therefore, the RTML language does not specify which of these modes is currently in use for a specific file. The current mode is context dependent. For example, if an observer was controling a telescope interactively, the style of RTML file would be different than if the observer was sending the file to a batch executed telescope. The mode can be determined from the tags in the RTML file.

RTML Requirements

List of requirements that this language should address:

It must be able to describe a complete observation request for a specific telescope.
It must be telescope hardware and software independent.
It must be network independent.
It must accommodate a wide degree of telescope automation yet be able to take advantage of it where it is available (particularly if there is scheduling software available).
It must be human readable. It must also be simple enough that an observer could generate an observing list in this language and a telescope operator could generate a valid observing log.
It should provide the means to execute observations interactively or in a scheduled mode.
It should be extensible. When new features are added to this language, it must be backward compatible.
Although the initial implementation of this language is intended to be for optical telescopes, the language should not inhibit further extension for other telescopes operating at different wavelengths.
Define a complete general set of scheduling keywords to enable a variety of telescope scheduling systems to use RTML.

Origins of RTML

Automated telescopes are becoming much more common. With the advent of the Internet, it is now possible to control telescopes from a remote location. Typically, though, the language and routines which control a telescope are unique to that telescope. There are efforts underway to develop a common instrument control language (AIML and ATIS are two such languages). However, these efforts do not address the need to communicate to a variety of telescopes using a common language. RTML is an attempt to separate the observing goals from the instrument. The goals of RMTL are to enable an observer to develop an observing list in a format common to all telescopes. Obviously, the goals of a research project will dictate on which instrument the observations should be carried out. Nevertheless, a typical observation can be described such that the telescope to which it is submitted can understand and fulfill the request.

Remote Telescope Markup language is a data description language whose goal is to completely describe an observation request and the observation result, independent of the telescope hardware. The premise behind this language is that each RTML literate telescope has a small server running on it which can accept RTML files and parse them into its own command language. In the same manner that the Java programming language enables any program to be executed on any machine, RTML enables any observing list to be executed on any telescope system.

The origins of RTML are from the Hands On Universe Project, and it need to access optical telescopes on a worldwide basis. There are several telescopes which are already available for the HOU project. However, for the most part there is no standardization in either the hardware or software which operates these telescopes. This language is an attempt to standardize the communications protocol between a remote telescope and a remote observer. Although its impetus is the HOU project, it is not designed specifically for the HOU project. Instead, this language is an attempt to provide a common language to control remote telescope in either an interactive or scheduled manner.

One application of RTML is with the Hands On Universe Global Telescope Network (HOU-GTN). This project allows teachers and students from around the world to submit observation requests to the HOU server. These requests are then distributed to each of the available telescopes in its network. There is a strong interest by many telescope operators to participate in the HOU program. However, each telescope has a different telescope control system and each telescope has a different set of capabilities. One telescope may be entirely automated including a scheduler for distributing observation requests throughout the night; another may be operated manually. These types of differences and capabilities make it difficult for a project such as the HOU-GTN to incorporate a large set of telescopes without requiring some kind of standardization. RTML is the standard language for delivering an observing list to a telescope in a manner that is independent of the underlying system. The telescope need only be provided with a routine or program to translate the incoming RTML observing list into its own internal format.

Definition of the RTML Language

RTML is an extension of the XML markup language in the same manner that HTML is an extension of the XML language. The model of HTML and the web is similar to the model proposed by this langauge. With the web, programs known as servers respond to HTTP requests from a client and typically serve up HTML pages. The HTML data is delivered to the browser (or client) where it is decoded and displayed in a graphically appealing manner for the user.

By extension, RTML could be used in the following manner. An automated telescope would submit a HTTP request to a server on which a list of observing requests is stored. The server would parse the request and return an RTML document containing the list of targets to observe. On the telescope side, the client software would recieve the RTML document, either decode it such that the target list could be executed by the telescope, or it could be used directly if the telescope is 'RTML literate'.

This is not the only possible implemenation of RTML. By design it is to be used in a variety of possible situations. For example, through the use of XML exstensible style sheets, the incoming RTML document could be decoded by a XML literate browser (e.g. Netscape and IE) and viewed in a format that could be understood by an observer at a telescope which is not automated.

RTML is written using XML (eXtensible Markup Language). The primary reason for this choice is that XML provides the framework for organizing structured data in a text file. The result of this is a data file that is human readable and is network neutral. The secondary reason is that there already exist libraries of code (in Java, C, and perl, among others), which can parse XML (and hence RTML) files. As a result, it becomes easier to develop tools to read and process RTML files.

The model of RTML is similar to that of HTML (HyperText Markup Language), and in fact HTML is described by XML as well. HTML is a hardware-independent document definition language, which enables web documents to be viewed from any computer regardless of the underlying hardware. Similarly, RTML delivers observing lists to telescopes and telescopes return observing logs to observers in a manner that is independent of the underlying telescope system.

RTML "Document Type Definition"

The RTML Document Type Definition (DTD) describes the language to be used to communicate with remote telescopes via the internet. The purpose of this language is to address the communication needs of remote telescopes. It is designed to enable interactive or batch control of remote telescopes from a remote location over the internet. Refer to the RTML DTD for a completely detailed definition of the RTML Document Type Definition.

An RTML document uses tags (words bracketed by a '<' and a '>') and attributes (modifiers of the form 'name=value' within a tag) to describe a complete observation request or the result of an observation.

In the first version of RTML, the language is being designed for use with optical telescopes (hence the tags <FILTER> and <FILTERSET>). Most of the following describes the application of this language to optical telescopes. Obviously, it is important for the success of this language to extend it to include telescopes operating at other wavelengths.

In the following sections, this document describes the language and how it Is to be used. In section "Implementation", we describe how the system is to be implemented under three different scenarios. In section "Example", we provide sample RTML files and describe what they are meant to accomplish. Finally, in section "Tag Descriptions" we describe each one of the tags and how they are to be used.

Implementation of RTML

Usage

RTML is designed to provide the protocol for delivering observation requests to telescopes and receiving the observing logs from the telescopes. To that end, RTML files come in two distinct formats: (1) the observing list format, and (2) the observing log format. The format of a particular RTML file is determined both from its context (where it is coming from - e.g. a telescope) and from the document structure and tags it uses. Here we discuss the format and tags used by each of these particular formats.

Observing List

The observing list format is prepared by the observer and submitted to the telescope for which he or she has observing time. It has the following tag hierarchy:

<RTML>

<MOON>

</SCHEDULE>

<COORD>

<TRACK>

</TARGET>

<CORR>

</REQUEST>

</RTML>

Discussion of Observing List

Each observing file begins with the <CONTACT> tag. This tag contains the contact information for the RTML file. The next tag is the <CONFIG> tag. This tag is optional and is used to define default values for a set of variables used by the RTML server. These default values are useful when the RTML file must be generated manually. The third tag, <REQUEST>, describes a single complete observing request. There can be more than one <REQUEST> per file.

An observing request as defined by the <REQUEST> tag is a set of logically connected targets as defined by the <TARGET> tag. Typically, a target describes all aspects necessary to take a set of exposures of an astronomical object. An exposure is not required, however, and may simply be used to move the telescope to a specified location. By 'logically connected', we mean that each target within a request is related to the other targets in some reasonable fashion. For example, one might want to take an exposure in each filter of a filter set for a single object. Alternatively, the targets may consist of a set of exposures with offsets between each exposure.

Each <TARGET> describes a single complete action to be carried out by the telescope. Typically, this includes - but does not required - some kind of exposure. A <TARGET> is identified by its attribute 'name'. The number of times a target is executed is defined by the 'numobs' attribute. The following tags are defined in the <TARGET> tag: <COORD>, <OFFSET>, <FILTER>, <TRACK>, and <EXPOSE>. The state of the telescope is maintained between targets of a single request. This means that values which are maintained throughout the execution of a request (e.g. <COORD>, <FILTER>), need not be included in later tags. The exception to this rule is the <EXPOSE> tag. This tag is required if an exposure is desir It can also be used to define the ephemerides of a transient object such as planets or asteroids. This is done by including a set of <COORD> tags within a <TARGET> tag and including the date and time for which the coordinate is valid (using the datetime attribute in the <COORD> tag). The <OFFSET> tag defines a set of offsets from a previously defined coordinate. The <FILTER> tag defines which filter is to be used for the current target, and must be a valid filter for the telescope. The <TRACK> tag controls the tracking rate for the telescope. Valid entries are 'sidereal' (the default value), 'off', 'lunar', 'manual'. If manual, then the observer sets the tracking rates via the RA and Dec attributes of the <TRACK> tag. Finally, the <EXPOSE> tag defines the length and type of exposure to be taken. If it is not defined, then the current target takes no exposure.

In addition to the targets, each request can also contain a single scheduling tag, as defined by the <SCHEDULE> tag, and a single <CORR> tag. The <SCHEDULE> tag will only be recognized by telescope which have some form of scheduling software running; on all other telescopes the RTML server should throw an error. It gives a complete description of how and when the REQUEST should be executed in order to fulfill the goals of the observation. Because of the potential complexity of the scheduling tag, we describe it in detail below.

The <SCHEDULE> currently defines the following set of scheduling criteria: <MOON>, <TIMERANGE>, <FREQUENCY>, <PRIORITY>. The <MOON> tag allows the user to set limits on where in its cycle the moon must be in order for the request to be executed. The <TIMERANGE> tag sets the date interval during which the request will be attempted by the telescope. The <FREQUENCY> tag sets the total number of times a request should be executed during the time range and the minimum interval between observations. The <PRIORITY> tag defines whether or not this target should be given a higher priority than other targets. It remains to be decided how the <PRIORITY> should be compared (i.e. compared to other targets within the same RTML file, in an entire night of observations, etc.).

The <CORR> tag is used to apply corrections (such as flat fielding, bias subtraction, etc.) to a given set of exposures taken in a request. This tag sets the reduction steps to be applied to the observation. Currently, the following steps are defined:

1. ZERO: correct an image for bias offset

2. DARK: correct an image for dark current

3. FIXPIX: remove bad pixels in an image

4. CRPIX: cosmic ray removal

5. SKYFLAT: correct an image using a SKYFLAT field

6. DOMEFLAT: correct an image using a dome flat

7. FRINGE: fringe correction

Observing Log

A telescope produces an RTML file summarizing the results of an observing list. This information lists all images taken, errors that occurred, and the location of the images. In this section, we define the structure of the observing log format, and detail each of the tags used by this format.

Hierarchy

<RTML>

<IMAGE>

<COORD>

<TRACK>

<CORR>

</IMAGE>

<ERROR>

<TELEM>

</RTML>

Discussion of Observing Log

The output from an RTML-aware telescope is an RTML file describing the results of the observations for a given observing list. Currently, there are five primary tags which describe an observing log. These are: <TELESCOPE>, <CONFIG>, <IMAGE>, <ERROR>, <TELEM>.

<TELESCOPE> tag

The <TELESCOPE> tag provides all information about the current telescope and instrument configuration. This information can either be contained inline (within the RTML file) or can be located via the 'src' attribute. The 'src' attribute is a URI to an RTML file containing this information. The telescope tag contains 5 tags of its own: <SPECS>, <LOCATION>, <LIMITS>, <DETECTOR>, <FILTERSET>.

The <SPECS> tag provides general information about the telescope itself. Specifically, it contains information about the scale, reflectivity, collecting area, and f ratio through the attributes: 'scale', 'reflect', 'area', and 'fratio'.

The <LOCATION> tag gives the latitude, longitude and elevation of the instrument. The format for the coordinates is contained in the <FORMAT> tag and the elevation units are contained in the <EUNITS> tag.

The physical observing limits of the telescope are described by the <LIMITS> tag. These limits are the NORTH, SOUTH, EAST, WEST and ALTITUDE tags and are given in units of degrees above horizon. The <DETECTOR> tag gives a complete description of each instrument available for the telescope. There can be more than one detector for a telescope, so each must be given a unique name. The actual detector that is used by the telescope is given either In the <CONFIG> tag or in the <IMAGE> tag.

The <FILTERSET> tag lists each of the filters available for the telescope system. The filterset contains a list of <FILTER> tags, which describe the individual filters available for the telescope. It is the responsibility of the observer to determine the names of the filter and use them in the generation of the observing list.

<IMAGE> Tag

The <IMAGE> tag describes all information about the image. It has four attributes, all of which are required: 'project', 'id', 'request', 'src'. The first three tie the image to the original request. The project name can be set as default in the <CONFIG> tag if all images in the RTML file belong to the same project. The 'src' attribute is the URI to the actual image data. This URI must be accessible via on the WWW in order for the data to be downloadable by the user.

Each of the following tags are allowed in the <IMAGE> tag and combine to completely describe an exposure:

* COORD: corresponds to the coordinate of the observation at the time that the exposure was taken. The datetime field in the coord tag is the actual time of observation at the start of the exposure.

* TRACK: describes tracking status of the telescope.

* CORR: indicates which corrections were applied to the Image.

* WEATHER: provides information about weather conditions at the time of exposure.

* EXPOSE: describes the length and type of exposure.

* DETECTOR: describes which detector the telescope for the observation used.

* FILTER: indicates which filter the telescope used.

None of these tags is required, but it is highly recommended that telescopes implementing an RTML server also include this information if available.

<ERROR> Tag

If an error occurs during the execution of a request, the <ERROR> tag returns information about the error. The tag defines the following attributes: 'project', 'request', 'target', 'error-code', and 'datetime'. All attributes are necessary to fully document the type of error, the time of its occurrence and which request gave rise to the error. The tag can also contain a message corresponding to error-code.

At the time of this writing, neither error-codes or error messages have been adopted.

<TELEM> Tag

If the observer requests verbose mode (use the 'verbose' attribute in the <RTML> tag), then the RTML server is directed to produce telemetry output. This output is essentially all of the actions carried out by the telescope in order to acquire an observation.

Possible changes to RTML DTD

Add a configuration section to allow the user to request the FITS files be named whatever they want and to allow the user to request that files such as the flats, bias, and raw images be returned.

Return to RTML Background Page.