;+ ; NAME: ; ASTROMETRYNET_API ; ; PURPOSE: ; Update a fits file's WCS header using the "astrometrynet" API function. ; This service uses tools provided by Astrometry.net. For more details, visit http://astrometry.net/ ; ; EXPLANATION: ; The fits file will be uploaded on supernova.astrometry.net, then solved for a valid astrometry. The resulting WCS file ; will then be downloaded upon success, and used to update the original fits file's header. A keyword ASTRNET will be set ; to 1 in the fits file's header. If the astrometry fails, a keyword ASTRNET will be set to 0 in the fits file's header. ; ; More information on the astrometrynet project can be found here : http://astrometry.net/summary.html ; as well as in this paper : http://adsabs.harvard.edu/abs/2010AJ....139.1782L ; ; More information on astrometrynet's API can be found here : http://supernova.astrometry.net/api_help ; ; A short explanation on the principles behind astrometry.net can be found here : http://dx.doi.org/10.6084/m9.figshare.841644 ; ; More information on the Python API client can be found in the header of the "client.py" file (see REQUIREMENTS #5) ; ; REQUIREMENTS: ; (1) A valid API key must be obtained by creating an account on supernova.astrometry.net and visiting the page http://supernova.astrometry.net/api_help ; Note that your API key can change from time to time. ; (2) A config.dat file must be passed to this program in order for it to be functional. It can either be passed through the CONFIG_PATH ; header keyword or the $ASTROMETRYNET_CONFIG system variable. The configuration file must be a text file, and contain the following informations : ; ; API_KEY = rlybxguijlwrtepq ;THIS IS YOUR PERSONAL API KEY (SEE REQUIREMENTS #1 IN THE HEADER OF ASTROMETRYNET_API.PRO) ; PYTHON_PATH = python ;THIS IS THE PATH TO PYTHON ON YOUR MACHINE ; CLIENT_PATH = /Users/gagne/Documents/Python/Python_Library/03 - Astrometrynet/ ;THIS IS THE PATH TO THE PYTHON API CLIENT ROUTINE ON YOUR MACHINE ; JSON_PATH = /Users/gagne/Documents/Python/Python_Library/01 - Library/simplejson-3.4.0/ ;THIS IS THE PATH TO THE SIMPLEJSON PYTHON LIBRARY ON YOUR MACHINE ; TMPDIR_PATH = tmp/ ;THIS IS THE PATH TO A DIRECTORY ON YOUR MACHINE WHICH WILL BE USED AS A TEMPORARY REPOSITORY ; SERVER = http://supernova.astrometry.net/api/ ;THIS CONTAINS THE SERVER ; PRIVATE = 0 ;WHETHER YOUR IMAGE WILL BE PUBLICLY VISIBLE ON THE ASTROMETRYNET WEBSITE ; PARITY = 1 ;DEFAULT VALUE FOR THE PARITY KEYWORD ; ; (3) Python must be installed on the system. See https://www.python.org/download/ ; (4) The "simplejson" Python library must be installed. See https://pypi.python.org/pypi/simplejson/ ; (5) The "client.py" Python procedure provided by Astrometrynet must be installed. See http://trac.astrometry.net/browser/trunk/src/astrometry/net/client/ ; (6) You must cite Lang et al. (2010; http://adsabs.harvard.edu/abs/2010AJ....139.1782L) when you use this code. ; (7) You must include the following reference when you use this code : "This service uses tools provided by Astrometry.net. For more details, visit http://astrometry.net/" ; ; CALLING SEQUENCE: ; ASTROMETRYNET_API, fits_files, [ FSTART=fstart, CONFIG_PATH=config_path, SERVER=server, $ ; RA0=ra0, DEC0=dec0, RADIUS=radius, PLATESCALE=platescale, E_PLATESCALE=e_platescale, PARITY=parity, DEGREE=degree, $ ; EXTRACMD=extracmd, TIMEOUT=timeout, API_KEY=api_key, PYTHON_PATH=python_path, CLIENT_PATH=client_path, JSON_PATH=json_path, $ ; TMPDIR_PATH=tmpdir_path, VERIFY_WCS=verify_wcs, /PRIVATE, /RECURSIVE, /TRUST_WCS, /SKIP ] ; ; INPUTS: ; FITS_FILES = The path to a fits file, or a directory containing multiple fits files. In the latter case, the program will run on all fits files. ; ; OPTIONAL INPUT: ; FSTART = In the case where FITS_FILE is set as a fits file directory, this is the file number from which to start the astrometry. ; Preceding files will be ignored. ; CONFIG_PATH = This contains the path to the configuration file (see REQUIREMENTS #2) ; SERVER = The server which is to be used to build the astrometric solution, usually ; http://nova.astrometry.net/api/ or http://supernova.astrometry.net/api/ (Default value is SERVER key in the CONFIG file - See REQUIREMENTS #2) ; RA0 = Estimated position of the submitted field in right ascention (degrees). ; This is passed to client.py as the --ra keyword. ; DEC0 = Estimated position of the submitted field in declination (degrees). ; This is passed to client.py as the --dec keyword. ; RADIUS = Radius (in degrees) to search for around the estimated field position. ; This is passed to client.py as the --radius keyword. ; PLATESCALE = Estimated platescale for the input image, in arcseconds per pixel. ; This keyword (and E_PLATESCALE) are passed to client.py as the [X] keywords, adding "--scale-units arcsecperpix". ; E_PLATESCALE = Error on the estimated platescale. ; This keyword (and PLATESCALE) are passed to client.py as the [X] keywords, adding "--scale-units arcsecperpix". ; PARITY = Scalar string specifying which image parity to try. (1 for positive or 0 for negative, default is trying both). ; This is passed to client.py as the --parity keyword. Generally, fits files will have a positive parity (1) ; and photographies will have a negative parity (0) ; DEGREE = Set the polynomial degree for the astrometry solution. The default is 2. This is passed to client.py as [X] ; EXTRACMD = Scalar string containing extra commands to pass to the Python code client.py. Use correct syntax (refer to ; the contents of client.py). ; TIMEOUT = Total time (in minutes) before the astrometrynet child process is killed (if no solution has been found). ; Default is no time limit. ; API_KEY = Your personal API key for the astrometrynet service. This keyword takes precedence over the value found in the configuration file. ; PYTHON_PATH = The path to Python on your machine. This keyword takes precedence over the value found in the configuration file. ; CLIENT_PATH = The path to the Python API client on your machine. This keyword takes precedence over the value found in the configuration file. ; JSON_PATH = The path to the simplejson library on your machine. This keyword takes precedence over the value found in the configuration file. ; TMPDIR_PATH = A temporary directory to store files on your machine. This keyword takes precedence over the value found in the configuration file. ; VERIFY_WCS = Verify fits file astrometry prior to making a new one. ; ; OPTIONAL INPUT KEYWORD: ; /TRUST_WCS - If this keyword is set, the astrometry already present in the fits file will be used to fasten the procedure. ; The plate scale will be trusted to ± 5% and the field position to ± 12 arcminutes. ; /PRIVATE = Whether or not your image will be visible on the astrometrynet website. ; This keyword takes precedence over the value found in the configuration file. ; /RECURSIVE = Make astrometry on all fits files in subdirectories (only relevant when FITS_FILES keyword is a directory itself). ; /SKIP = Skip files with a good astrometry from astrometrynet (ASTRNET = 1 in their headers) ; ; NOTE: ; ; This routine returns SIP polynomials describing the image distortion, understood by the astrolib and documented on ; http://tdc-www.harvard.edu/wcstools/SIP_distortion_v1_0.pdf ; ; PROCEDURES USED: ; READCOL, READFITS(), SXPAR(), XY2AD, MKHDR, WRITEFITS, SPAWN_ASTROMETRYNET_API, HEADFITS(), SXADDPAR, FILE_EXT(), ; STRKILL, EXTAST, PUTAST, TRANSFER_ALL_HDR_KEYS, SXADDHIST, STRMID_ARR(), STRPOS_ARR() ; ; MODIFICATION HISTORY: ; WRITTEN, Jonathan Gagne, April, 25 2014 ; MODIFIED, Jonathan Gagne, April 30, 2014 : Changed structure of spawned command for a more efficient catch of the Python child process PID ;-