autoastrom

NAME

autoastrom - Automatically add astrometry to an astronomical image.

SYNOPSIS

autoastrom m51.sdf
autoastrom --catalogue=usno@eso --match=RITMatch --verbose m51.sdf
autoastrom --help

DESCRIPTION

This program can be used to automatically correct or add astrometry to an astronomical image. It can automatically download reference catalogue information to use for correlation, insert the astrometric results into the original image, and make the astrometry available as a set of FITS-WCS headers.

OPTIONS

The following options are supported:

bestfitlog

When ASTROM finds a solution, information about the best fit is written to this file. This file is a textfile containing the number of terms, the central right ascension and declination, the average pixel RMS, the distortion factor (when applicable) and the FITS file containing the WCS headers for all of the fits found. For the best fit, this file also lists the number of stars used in the fit, the mean plate scale in arcseconds, and the RMS in fitted r, x, and y.

Type: string; default: none.

catalogue

This is the name of the online catalogue to use to find reference stars. The argument should be one of the catalogue names recognised by SkyCat. The list of available catalogues depends on the configuration file used; the 'short_name' entries in the file are the allowable values of this option.

Type: string; default: 'usno@eso'

ccdcatalogue

Specifies a pre-existing catalogue of objects in the CCD frame. The format is that produced as output by SExtractor when catalog_type is set to ASCII_HEAD. The file starts with a sequence of lines of the form:

<column> <colname> <optional comment>

The 'colnum' numbers run from 1 to the number of columns; the 'colname' is one of a set of column named defined in the SExtractor documentation; and 'optional comment' is some (ignored) annotation. The data immediately follows, in rows with the given number of columns in them. In each of these rows, any text following a # is ignored, and may be used for other annotation.

You control which columns SExtractor generates by specifying them in the SExtractor .param file. The catalogue must have all of the fields NUMBER, FLUX_ISO, X_IMAGE, Y_IMAGE, A_IMAGE, B_IMAGE, X2_IMAGE, Y2_IMAGE, ERRX2_IMAGE, ERRY2_IMAGE, ISOAREA_IMAGE, of which X2_IMAGE, Y2_IMAGE, A_IMAGE, B_IMAGE, ERRX2_IMAGE, ERRY2_IMAGE are not generated by default.

If you include the option --keeptemps to avoid deleting the temporary work directory, you will be able to scavenge the extractor output from there if this is useful to you.

Type: string; default: none

defects

This option is currently unsupported but will be reinstated at some point in the future.

detectedcatalogue

Specifies a file which receives a dump of the objects detected in the NDF, with their astrometric positions corrected. The file is in the Cluster format with thirteen columns: a zero in the first column, followed by the item's ID, the right ascension and declination in space-separated format, the x and y position of the source on the CCD, an instrumental magnitude, the error in the instrumental magnitude, and extraction flags.

Type: string; default: none.

help

Print usage information and defaults, and exits.

insert

If true, the final fit to the astrometry is inserted into the input NDF as an AST WCS component. If false (--noinsert), the insertion is not done, so presumably you have decided to handle the WCS information in a different way, and have set the --keepfits option to retain the WCS information.

Type: switch; default: true.

iterrms_abs

When the absolute RMS of a fit reaches this value, iterations will cease and the current WCS will be used.

Type: real; default; none.

iterrms_diff

When the difference between the current RMS and the previous fit's RMS reaches this value, iterations will cease and the current WCS will be used.

Type: real; default; none.

keepfits

The normal mode of operation is for the script to insert the final astrometry into the input NDF, as an AST WCS component. Instead, or additionally, you can save this information as a FITS-WCS file, named by this option.

Type: switch; default: false.

keeptemps

If true, temporary files will not be deleted at the end of processing. This is useful for debugging, both at the low level when there is something wrong with the script itself, but also when you wish to examine the sequence of calls to FINDOFF and ASTROM, or examine the ASTROM input and output files.

All the temporary files are created in a temporary directory which is reported during the script's execution.

Type: switch; default: false

man

If true, print this man page and exit.

Type: switch; default: false.

match

Specifies an alternative matching algorithm. The default algorithm is 'match', which is an implementation of the FOCAS matching algorithm by Michael W Richmond. A version of this is distributed with autoastrom, but it should be compatible with any later version.

Alternatively, you can use the FINDOFF application, which is part of CCDPACK. This does work, but is rather slow, and is completely thrown by a CCD image with unequal X and Y scales, making it essentially unusable if the image NDF does not have some astrometry already, or if you try to specify a position with --obsdata. Since it has different characteristics, though, it may work in some circumstances where 'match' does not. Again, the author of autoastrom would welcome feedback on this point.

Type: string; default: 'match'.

matchcatalogue

Specifies a file which receives a dump of the set of positions matched by the matching process. The file is formatted like a SExtractor output file, with five columns, containing (1) running object number, (2 and 3) RA and Dec of the source on the sky, and (4 and 5) x and y positions of the source on the CCD.

Type: string; default: absent -- no file written by default.

maxfit

The maximum order fit to use.

Type: integer; default: 9.

maxiter

The maximum number of iterations to perform.

Type: integer; default: 10.

maxobj_corr

The maximum number of objects to use from either catalogue to perform correlation on. This will take the brightest objects in the catalogues.

Type: integer; default: 500.

maxobj_image

The maximum number of objects to use from the image catalogue. This will take the brightest objects in the catalogue.

Type: integer; default: 500.

maxobj_query

The maximum number of objects to fetch from the catalogue server. The default is generous, and it's unlikely you'd need to change this.

Type: integer: default: 500.

messages

If true, the script will pass on messages from the Starlink applications which the script uses. These might be reassuring, but if you don't like the chatter, they can be suppressed with --nomessages.

Type: switch; default: true.

obsdata

Specifies a source for the observation data, including WCS information. The keyword has the multiple role of specifying the source of WCS information, supplying approximate WCS information directly, and supplying the observation data (time, observatory, temperature andpressure, and colour) which ASTROM needs if it is to attempt one of its higher-order fits. This information is only needed if it is missing from the NDF or any FITS extension it incorporates, and if you wish to attempt the slight increase in accuracy of the more elaborate fits.

For further information on this parameter, see SUN/242.

Type: string; defaults: see SUN/242.

skycatconfig

The SkyCat library has a default configuration file, which you can examine at http://archive.eso.org/skycat/skycat2.0.cfg. For some applications, it may be appropriate to use an alternative configuration file. If so, you can point to it using this option. For more information on SkyCat, catalogues, and the configuration file, see the SkyCat FAQ.

Type: string; default: built-in defaults.

skycatcatalogue_in

Specifies a pre-existing catalogue of objects as retrieved from SkyCat. The format of this catalogue must be the Cluster format as described in the documentation for --detectedcatalogue.

Type: string; default: none.

skycatcatalogue_out

After the SkyCat query has been performed, the catalogue returned can be saved to disk in this file. The format of this catalogue will be the Cluster format as described in the documentation for --detectedcatalogue.

If used in conjunction with the --skycatcatalogue_in option, this can be used as a poor-man's cache, avoiding potentially timely SkyCat queries.

Type: string; default: none.

temp

This option, if present, specifies the directory to be used for temporary files.

This has a double function: firstly and most straightforwardly, it indicates where temporary files should be created if, for some reason, the default location is unsuitable; secondly, if the script finds there a file (from a previous run) which it was about to generate, it does not regenerate it, but instead simply reuses it. The first function may be useful in some circumstances; the second is primarily a debugging facility, is subtle, and its use is discouraged.

Type: string; default: generated.

timeout

If present, this specifies how long, in seconds, the script should wait for its slave applications to complete. The default is three minutes. In some circumstances -- such as if you have a huge number of stars to match up -- this might be too short, so that the script loses patience before the slave application has finished, and produces a rather messy error message. In this circumstance, you can increase the timeout here.

Type: integer; default: 180.

verbose

If present, the script produces a good deal of chatter to the standard error; if false (--noverbose), this is suppressed.

Type: switch; default: false.

version

If present, write the version number ot the standard output and exit.

Type: switch; default: false.

SEE ALSO

Starlink User Note 242. RITMatch web page: http://spiff.rit.edu/match/ SkyCat FAQ: http://archive.eso.org/skycat/skycat-faq.html

AUTHORS

Brad Cavanagh <[email protected]>

COPYRIGHT

Copyright (C) 2008 Science and Technology Facilities Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA