ASCfit automatic astrometric package
ascfit3.5 Jan-2011

Go to AJP home page for latest ASCFIT version

This is ASCfit package, reference: Joergensen, Riis, Betto & Pickles, 2002, ASPC, 281, 2071
obtainable from Andrew Pickles, apickles at lcogt.net, Las Cumbres Observatory Global Telescope
http://lcogt.net/ajp/ascfit3.5.tar.gz

Usage: ascfit FITSfile [-options]
included subdirectory "test1" contains a number of single image test examples, with TESTDRIVE_notes showing example fits

Additional (large) download http://lcogt.net/ajp/ascfit_test.tar.gz
contains more fitted examples of Hale telescope LFC mosaic, and WIRC dither images.


                    ____________________________________
                   |        FITS file                  |
                   |at telescope RA/DEC and Equinox,   |
                   |at DATE-OBS for EPOCH for PM       |
                   |corrections to NOMAD star coords   |
                   |[and with SECPIX/PIXSCAL info]     |
                   -------------------------------------
                            |                  |
                            v                  v
                  ______________    ____________________________
                 |sextractor->  |  |findnomad1 -> findnomad1.dat|
                 |asc_sextr.cat |  |format_nomad -> asc_ref.cat |
                 ---------------   -----------------------------
                               |    |
                               v    v
                       _______________________
                       |   starfit -> WCS     |
                       |addhead -> FITS header|
                       -----------------------

CHANGELOG

CHANGES from version 3.4
------------------------

changed the default linuxpc compile to gcc -m32 -W
fixed sort_arr[4] overflow in gen_triang().
verify compilation on CentOS & Ubuntu 64 bit architectures

CHANGES from version 3.3
------------------------

* ascfit modified to handle colons or spaces in RA/DEC FITS coordinates better
* starfit modified to handle wide-field images better (tolerance scaled to pixel size, rather than fixed in arcsec)

CHANGES from version 3.0
------------------------

o increased string length SMAX=200 in str_key7.h for long addhead issues
o fixed "||" error in asc_math
o fixed xycoord to read UTSTART/UT and space separated sexagesimals 
o fix ascfit3.1 to also cope with space separated RA/DEC sexagesimals
o ascfit3.2 has improvements to asc_math (min/max), fhrd (output)
  starfit (silent) and xycoord (output)
o fitstats (new script) lists user-selected FITS headers - can be useful for perusing large directories
o u_long changed to unsigned long in fitsio.c 

CHANGES from version 2.4/2.5
----------------------------

2007: findnomad1 from cdsclient.tar provides fast web-access to NOMAD
        catalog - avoids any need for local star (USNO) catalogs.
        Main fitting routine re-renamed starfit, several passed
        reference bugs fixed, and code cleaned to work with gcc-4.0

CHANGES from version 2.3
------------------------
2005/06: getusnobn.py "silent" switch: default is verbose operation,
		if used with -s or --silent (no arg) it will run silently.
	 for NOMAD the default is to screen/sort on K-mag instead of R-mag.
	 ubcone/wr_starcat.c: stdout option for easier "rsh" operation.
	 starfit_ub: fixed bug with passed header lengths (bt).

CHANGES from version 2.2
------------------------
2005/01: added Python script to access USNO/NOMAD on the web
	  getusnobn.py written by Derek Fox (derekfox@astro.caltech.edu)
	 fix some input & array boundary problems in starfit_ub_lib.c

CHANGES from version 2.1
------------------------
2004/12: starfit: changed names from USNO -> ASTREF and from CCD -> IMAGE
	  improved error messages (for defocus, infrared etc.)
	  added read_d_file in starfit_lib to skip #comment-lines and read
	  columns selected for USNO-B or NOMAD/ir star catalog files
	 ascfit: added flags to select NOMAD RA/DEC/JKMAG columns
	  removed obsolete references to pikala and msqbin etc.

CHANGES from version 2.0
------------------------
2004/3:	dropped USNO-A and 2MASS catalogs, 
	switch to USNO-B with ubcone, and starfit_ub.
2004/10: attempted URL access to USNO-B (local disk copy not necessary)

CHANGES from version 1.3
------------------------
2002/8: fixed problems finding some stars
        added ty2rd to include TYCHO2 catalog

CHANGES from version 1.1
------------------------
2002: upgraded csquare, crect, msqbin to cross DEC boundaries better

CHANGES from version 1.0 (which used USNO-A/crect and 2MASS/msqbin)
------------------------ 
2001-sep: changed 2mass_2bin to compress err_angle information better,
and include Rmag, blend_flag and id_opt in compressed 2MASS binary
files with 24 instead of 22 bytes/star.  
Changed msqbin to use HTONL to determine byte-order (BIGendian or not)
like csquare/crect - and read the compressed files on Sparc or Intel CPUs.

DESCRIPTION ----------- 

ascfit (Automatic Stellar Coordinate fitting) comprises a GNU bash
script "ascfit" which calls a collection of C programs, all of which
can be run individually. For each FITS image, 
i) ascfit uses "sextractor" to identify an image list of 
   star X-Y centroids in "asc_sextr.cat"
ii) it uses "findnomad1" to extract a corresponding list of
    astrometric reference star RA-Dec coordinates from the NOMAD
    catalogs in a square around the base telescope coordinates, 
    in "asc_ref.cat"
iii) it uses "starfit" to compare image and reference stars and match
     triangles, identifying a minimum number of corresponding stars, and
iv) calculates a linear fit in terms of scale and orientation.  Then
    ascfit uses "addhead" to write the WCS information to the FITS header,
    typically to an accuracy of 0.2-0.3 arcsec/pixel. (It does not fit edge
    distortion which may be caused by telescope or camera optics).  It can
    be used for optical or infrared images, and trailed stellar images if
    the telescope was tracking at a non-sidereal rate. In the latter case,
    the WCS corresponds to the mid-exposure time.

Usage:  adds WCS coordinates to single or multiple 
       fits files depending on whether  is complete, or the root 
       of multiple files. 
Type "ascfit" with no arguments for usage and list of options.

The core program "starfit" matches stars (triangle fitting) between 2 lists:
"asc_sextr.cat" => asc_imgcat... are generated by "sextractor" 
	searching for & centroiding stars in the FITS image, and
"asc_ref.cat"   => asc_refcat... are generated by "findnomad1"
	extracting a list of stars from the USNO NOMAD catalog in an area 
	corresponding to the telescope pointing.

Most computational time is spent in sextractor; starfit should work with
image catalogs produced by other means if given in the right format. Flags 
are provided to enable starfit to read the relevant columns from then
the astrometric reference catalogs.

PROGRAMS NEEDED
-------------------------------
Source extractor can be downloaded separately from the web at
http://terapix.iap.fr/sextractor/

The NOMAD catalogs can be accessed over the web using the
CDSclient script findnomad1, obtainable from
http://vizier.u-strasbg.fr/doc/cdsclient.html

LIST of PROGRAMS (and usage messages - if run with no arguments):
(or access man pages at man -M ~$HOME/ascfit_3.0/man )
-----------------
addhead		program to add or modify FITS headers
	Usage: 'addhead fits_file header_key value comment' (comment optional)
  	or   'addhead fitsfile -f file' 
        	  -'file' containing lines in format: key value comment
                	in file the comment is NOT optional 

		addhead is used to modify the input fits_file(s) headers
		 to add the WCS information.
----------------
asc_math	mathematical operations used in the ascfit script
		to handle floats, sexagesimals, etc.
		asc_math is used in ascfit to perform simple operations 
		 on FITS coords and variables.

	Usage: asc_math arg1 opr arg2   or  asc_math arg1 opr 
	   opr = +, -, x, /, cos, sin, tan, dms2deg, deg2dms  
	         dmsadd, dmssub, hmsadd, hmssub 
	eg  asc_math 50.1 + 10.4 
        ->  60.500000
            asc_math 12:24:12.1 hmsadd 0:1:13.3
	->  +12:25:25.40 

---------------
ascfit         bash script to derive an astrometric and a coordinate list,
               combine them with triangle fitting (starfit) to derive a WCS,
               and attach the WCS to the FITS fileheader

        Usage: ascfit fits_file [-sw [value]]

   -version    report ascfit version
   -s          save updated fitsfile as a_fits_file
   -f out_file save updated fitsfile as out_file
   -showoff    show the coordinate offsets from the nominal (header) position
   -verbose #  turn verbose on: #=1 general, 2 coords, 3 sextractor, 4 starfit
   -wide    #  set field width (RA & DEC) in degrees (default from header)
   -perr    #  pointing error in arcsec - has effect of increasing wide
   -roff    #  user specified RAoffset in arcsec
   -doff    #  user specified DECoffset in arcsec
   -mra     #  user specified RAoffset in arcsec of mosaic chip 1
   -mdec    #  user specified DECoffset in arcsec of mosaic chip 1
   -racol   #  set RAcol in ASTREF (asc_ref.cat) file (NOMAD, def=2)
   -deccol  #  set DECcol in ASTREF (asc_ref.cat) file (NOMAD, def=3)
   -optcol  #  optical mag column in ASTREF file (NOMAD: B=10 V=11 R=12=def)
   -ircol   #  infrared mag column in ASTREF file (NOMAD: J=13 H=14 K=15=def)

--------------
fhrd		read FITS header items from FITS files
	Usage: fhrd fits_file KEY1 KEY2 ...
	eg:    fhrd ccd.001   RA   DEC  EPOCH    blaaa
->	       13:47:10.41  06:29:15.76 2000.000 0.000000

		fhrd is used in ascfit to read relevant (and optional)
		 fits header values
----------------
starfit	        renamed and several parameter passing issues fixed.
                should compile on macos (ppc & gcc-4 intel, & linux)

starfit		Program for finding the astrometric fit between a FITS image 
		and a catalog. Most options can be passed in by ascfit.
	usage: starfit -sw1 [value] -sw2 [value]...  
		( [value] only if a numeric argument is required)

  -d         : default options (must be used if no other options)
  -plot      : write data to files to be used in SM plots  (default off)
  -report    : writes output to screen                     (defaulf off)
  -final     : writes only final output                    (default off)
  -mag       : writes also the final magnitude fit         (default off)
  -car       : writes Plate Caree WCS fit
  -tan       : writes Plate Tamgent WCS fit (default - works better with ds9)
  -epoch     # epoch of obsn. (def 2000.0) for PM corrections to NOMAD coords.
  -nstar     # no. of brightest image stars to be matched (default 20)
  -refstar   # no. of brightest catalog ref stars to be matched (default 20)
  -estar     # no. of brightest (satd.) image stars to be excluded (default 0)
  -edge      # no. of pixels to be cut around edge of image (default 30)
  -scale     # scale given in arc sec/pixel  (default 0.3)
  -tolerance # scale variance as LN[actual/assumed] (default 0.15)
  -color     # color term in MAG=IRmag+color*(Optmag-IRmag)
  -xpix      # no. of pixels in X direction         (default 2100)
  -ypix      # no. of pixels in Y direction        (default 2068)
  -box      5# Xmin Xmax Ymin Ymax 0/1 for exclude/include only box
  -diffuse   # 0.0 accepts all, 1.0 only stars (default is 0.03)
  -debug     # debug level 1-5

		starfit is an implementation of "A Pattern-Matching 
		 Algorithm for Two-Dimensional Coordinate Lists" 
		 by E.J. Groth, Astronomical J. 91, 1244, 1986,
		 and provided by the Space Instrumentation Group of 
		 the Danish Technical Univerity (DTU).
		 It is used by ascfit to match the image and reference 
		 star lists, look for matching triples, and derive a linear
		 coordinate fit. It could be tweaked to correlate similar lists
		 derived by other means.
----------------
xycoord 	reads coordinates of pixel in processed image.
		key RA/HMS or DEC/DMS returns single values for use in scripts.
	Usage: xycoord fits_file X Y [key]
	eg:    xycoord ccd.001   1024 1024.5
RA=227.065567 J2000 DEC= -14.887243 at X,Y= 1024.0,1024.5 in  01K5_LINEA  
RA=15:08:15.74  DEC=-14:53:14.1  at mid-UT +07:13:43.84

		xycoord can be used to determine the coordinates of any
		pixel in a WCS appended fits file
----------------

MAKING programs
---------------

All source files are in the subdirectory src.

Before making the programs, choose paths for the parameter/config files 
(ascfit.sex, ascfit.par, default.nnw, gauss_2.0_3x3.conv), edit them
into the file ascfit.sex, and copy the files: default is /usr/local/lib

Sextractor executable "sex" must be in your path - default /usr/local/bin

  ascfit: line 342: SEX_FILE="/usr/local/lib/ascfit.sex"
         change to full path to the ascfit.sex parameter file,
	 from the sextractor distribution.

  ascfit.sex:	
	line 4: PARAMETERS_NAME  must be full path to ascfit.par
	(default /usr/local/lib/ascfit.par)

	line 12: FILTER_NAME must be full path to gauss_2.0_3x3.conv
	(default /usr/local/lib/gauss_2.0_3x3.conv #was gauss_5.0_9x9.conv )

	line 28: STARNNW_NAME must be full path to default.nnw
	(default /usr/local/lib/default.nnw)

When all this is in place cd to ascfit3.0 and type "make". This will list
the available machine structures. Type "make MACHINE=" 
to make the programs, then "make install" to put them in the
default area /usr/local/bin

ASCFIT details
--------------

The "ascfit" script uses the GNU bash shell.  To force a bash shell the
first line in the script must contain the path the the bash executable
(e.g. #!/bin/bash or #!/usr/local/bin/bash).

If you don't have bash, you can get it from the GNU pages at:
http://www.gnu.org/home.html			or
http://www.gnu.org/software/software.html	or, more precisely at
http://www.gnu.org/software/bash/bash.html
or re-write the script in some other shell.

ascfit writes (and overwrites) several files into the working area:
asc_param.dat	a list of the WCS headers written to the last file processed.
asc_ref.cat	a list of stars extracted from the catalog (USNO or 2MASS).
asc_sextr.cat	a list of stars produced by s_extractor.
		starfit operates on the last 2 catalog files.

If the plot flag is turned on ("ascfit  -plot") a larger list of files 
will be generated, all in column format, which can be plotted with your
favorite plot package. A set of SM macros is provided in case you use sm.

[SM is obtainable from http://www.astro.princeton.edu/~rhl/sm/]

Plot analysis is generally not necessary for a working system, but can
be useful for tracking down problems during setup, or with data from a
new instrument.

asc_imgcat.dat		all stars extracted by sextractor from the image
asc_refcat.dat		all stars found in the USNO or NOMAD reference catalog
asc_imgcat_bright.dat	selected brightest image stars
asc_refcat_bright.dat	selected brightest reference stars
asc_match1.dat		matched pairs from first match
asc_match2.dat		matched pairs from 2nd match
asc_match.dat		matched pairs from final match
asc_param1.dat		parameters from first match
asc_param2.dat		parameters from 2nd match
ascfit.sm		macro plotting files for SM
			run sm, "macro read ascfit.sm", type "plot_match 1"

S-Extractor:
------------

The AScfit package also requires the SExtractor tool by E. Bertin. The
"sex" excecutable for SEextractor must be placed in some directory 
contained in your path. For details on how to obtain
SExtractor see http://terapix.iap.fr/sextractor/.

More documentation can be found in directory doc. 
Man-pages should be moved to a suitable location (/usr/local/man/man1)
or accessed with "man -M ~$HOME/ascfit_3.0/man "

THANKS

Bjarne Thomsen, Dept. Physics at Aarhus University for help correcting several bugs.
http://www.phys.au.dk/main/person/uk/individ/bt.shtm