.. doctest-skip-all .. _astroquery.astrometry_net: ************************************************************ Astrometry.net plate solutions (`astroquery.astrometry_net`) ************************************************************ Getting started =============== The module `astroquery.astrometry_net` provides the astroquery interface to the `astrometry.net`_ plate solving service. Given a list of known sources in an image and their fluxes or an image, `astrometry.net`_ matches the image to the sky and constructs a WCS solution. To use `astroquery.astrometry_net` you will need to set up an account at `astrometry.net`_ and get your API key. The API key is available under your profile at `astrometry.net`_ when you are logged in. Setting API key for astroquery.astrometry_net --------------------------------------------- Adding API key to astroquery.cfg ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Go to https://nova.astrometry.net and sign in. 2. Copy your API key 3. Add the following to your config file located at ``$HOME/.astropy/config/astroquery.cfg`` .. code-block:: python [astrometry_net] ## The Astrometry.net API key. api_key = ## Name of server server = http://nova.astrometry.net ## Default timeout for connecting to server timeout = 120 4. Add your API key to the config file! For more information about `astropy.config`, see: https://docs.astropy.org/en/stable/config/index.html Using keyring to store API key ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can use the `keyring `_ module to store your API key. .. code-block:: python >>> import keyring >>> keyring.set_password('astroquery:astrometry_net', None, 'apikeyhere') If you have multiple users and keys you can change ``None`` to another name to assign usernames to different keys. Now you can include the `keyring `_ module to set your API key. .. code-block:: python >>> import keyring >>> from astroquery.astrometry_net import AstrometryNet WARNING: Astrometry.net API key not found in configuration file [astroquery.astrometry_net.core] WARNING: You need to manually edit the configuration file and add it [astroquery.astrometry_net.core] WARNING: You may also register it for this session with AstrometryNet.key = 'XXXXXXXX' [astroquery.astrometry_net.core] >>> ast = AstrometryNet() WARNING: Astrometry.net API key not found in configuration file [astroquery.astrometry_net.core] WARNING: You need to manually edit the configuration file and add it [astroquery.astrometry_net.core] WARNING: You may also register it for this session with AstrometryNet.key = 'XXXXXXXX' [astroquery.astrometry_net.core] >>> ast.api_key = keyring.get_password('astroquery:astrometry_net', '') For multiple users, replace the empty argument with the desired username. .. code-block:: python >>> ast.api_key = keyring.get_password('astroquery:astrometry_net', 'username') .. note:: Be aware that some information you submit to `astrometry.net`_ is publicly available even if the raw image isn't. For example, the log of each job is accessible if one knows the job id regardless of the permissions set for the image. The log will contain the RA/Dec of the solution. For publicly viewable images or source lists `astrometry.net`_ includes links to download the FITS files for the image. Solving from a list of sources ============================== The most efficient way to use `astrometry.net`_ is to pass it a list of sources in an image instead of uploading the entire image. The data can be in an `astropy.table.Table`, pandas data frame or something other structure. The only important requirement is that **the list must be sorted by flux in descending order**. In the example below, assume that ``catalog.fits`` is a table of pixel positions (columns ``X_IMAGE`` and ``Y_IMAGE``) and flux (column ``FLUX``) and perhaps other columns, and that the image is 3073 by 2048 pixels. The ``solve_timeout`` used below is the time, in seconds, to allow the `astrometry.net`_ server to find a solution. It typically makes sense for this to be a longer time than the timeout set in `astroquery.astrometry_net.AstrometryNetClass.TIMEOUT`, which is intended to act primarily as a timeout for network transactions. TODO: Insert link to an actual catalog .. code-block:: python from astropy.table import Table from astroquery.astrometry_net import AstrometryNet ast = AstrometryNet() ast.api_key = 'XXXXXXXXXXXXXXXX' sources = Table.read('catalog.fits') # Sort sources in ascending order sources.sort('FLUX') # Reverse to get descending order sources.reverse() image_width = 3073 image_height = 2048 wcs_header = ast.solve_from_source_list(sources['X_IMAGE'], sources['Y_IMAGE'], image_width, image_height, solve_timeout=120) If `astrometry.net`_ is able to find a solution it is returned as an `astropy.io.fits.Header`. If it is unable to find a solution an empty dictionary is returned instead. For more details, see :ref:`handling_results`. Solving from an image ===================== There are two ways to get a solution from an image: 1. Detect sources in the image and upload the source list to get the plate solution. 2. Upload the image entire image. `astrometry.net`_ will detect sources and attempt to determine a solution. In both cases, use `astroquery.astrometry_net.AstrometryNetClass.solve_from_image`. There are a few settings common to both cases that make it convenient to use pointing information from the FITS header of the image: ``ra_key`` Name of the key in the FITS header that contains the RA. ``dec_key`` Name of the key in the FITS header that contains the RA. ``ra_dec_units`` Tuple specifying the units of the right ascension and declination in the header. The default value is ``('hour', 'degree')``. Detect sources and upload source list ------------------------------------- To use this method you must have the package `photutils`_ installed. .. code-block:: python from astroquery.astrometry_net import AstrometryNet ast = AstrometryNet() ast.api_key = 'XXXXXXXXXXXXXXXX' wcs_header = ast.solve_from_image('/path/to/image.fit') There are a few settings specific to this case: ``FWHM`` The rough full-width half-max of stars in the image, in pixels. ``detect_threshold`` The number of standard deviations above background a source needs to be to count as a detection. For more options see :ref:`common_settings`. If `astrometry.net`_ is able to find a solution it is returned as an `astropy.io.fits.Header`. If it is unable to find a solution an empty dictionary is returned instead. For more details, see :ref:`handling_results`. Upload image ------------ Keep in mind that uploading an image requires transferring roughly 10,000 times the data as uploading a source list. It would almost certainly take less time to find the sources in your image locally and upload that source list than it would to upload the image. The image will be uploaded under two circumstances. You call `~astroquery.astrometry_net.AstrometryNetClass.solve_from_image` and either + do not have `photutils`_ installed, or + set ``force_image_upload=True``. For example: .. code-block:: python from astroquery.astrometry_net import AstrometryNet ast = AstrometryNet() ast.api_key = 'XXXXXXXXXXXXXXXX' wcs_header = ast.solve_from_image('/path/to/image.fit', force_image_upload=True) If `astrometry.net`_ is able to find a solution it is returned as an `astropy.io.fits.Header`. If it is unable to find a solution an empty dictionary is returned instead. For more details, see :ref:`handling_results`. .. _handling_results: Testing for success, failure and time outs ========================================== There are three outcomes from a call to either `~astroquery.astrometry_net.AstrometryNetClass.solve_from_source_list` or `~astroquery.astrometry_net.AstrometryNetClass.solve_from_image`. + The solve succeeds: the return value is an `astropy.io.fits.Header` generated by `astrometry.net`_ whose content is the WCS solution. + The solve fails: the return value is an empty dictionary. + The solve neither succeeds nor fails before it times out: A ``TimeoutError`` is raised. This does *not* mean the job has failed. It simply means the solve did not complete in the time allowed by the ``solve_timeout`` argument, whose default value is `astroquery.astrometry_net.AstrometryNetClass.TIMEOUT`. In this case it often makes sense to recheck the submission. Code to handle these cases looks something like this: .. code-block:: python from astroquery.astrometry_net import AstrometryNet ast = AstrometryNet() ast.api_key = 'XXXXXXXXXXXXXXXX' try_again = True submission_id = None while try_again: try: if not submission_id: wcs_header = ast.solve_from_image('/path/to/image.fit', submission_id=submission_id) else: wcs_header = ast.monitor_submission(submission_id, solve_timeout=120) except TimeoutError as e: submission_id = e.args[1] else: # got a result, so terminate try_again = False if wcs_header: # Code to execute when solve succeeds else: # Code to execute when solve fails .. _common_settings: Settings common to all solve methods ==================================== In order to speed up the astrometric solution it is possible to pass a dictionary of settings to `~astroquery.astrometry_net.AstrometryNetClass.solve_from_source_list` or `~astroquery.astrometry_net.AstrometryNetClass.solve_from_image`. If no settings are passed to the build function then a set of default parameters will be used, although this will increase the time it takes astrometry.net to generate a solution. It is recommended to at least set the bounds of the pixel scale to a reasonable value. Most of the following descriptions are taken directly from `astrometry.net`_. Scale ----- It is important to set the pixel scale of the image as accurate as possible to increase the speed of astrometry.net. From astrometry.net: "Most digital-camera images are at least 10 degrees wide; most professional-grade telescopes are narrower than 2 degrees." Several parameters are available to set the pixel scale. ``scale_units`` - Units used by pixel scale variables - Possible values: * ``arcsecperpix``: arcseconds per pixel * ``arcminwidth``: width of the field (in arcminutes) * ``degwidth``:width of the field (in degrees) * ``focalmm``: focal length of the lens (for 35mm film equivalent sensor) ``scale_type`` - Type of scale used - Possible values: * ``ul``: Set upper and lower bounds. If ``scale_type='ul'`` the parameters ``scale_upper`` and ``scale_lower`` must be set to the upper and lower bounds of the pixel scale respectively * ``ev``: Set the estimated value with a given error. If ``scale_type='ev'`` the parameters ``scale_est`` and ``scale_err`` must be set to the estiimated value (in pix) and error (percentage) of the pixel scale. Parity ------ Flipping an image reverses its "parity". If you point a digital camera at the sky and submit the JPEG, it probably has negative parity. If you have a FITS image, it probably has positive parity. Selecting the right parity will make the solving process run faster, but if in doubt just try both. ``parity`` can be set to the following values: - ``0``: positive parity - ``1``: negative parity - ``2``: try both Star Positional Error --------------------- When we find a matching "landmark", we check to see how many of the stars in your field match up with stars we know about. To do this, we need to know how much a star in your field could have moved from where it should be. The unit for positional error is in pixels and is set by the key ``positional_error``. Limits ------ In order to narrow down our search, you can supply a field center along with a radius. We will only search in indexes which fall within this area. To set limits use all of the following parameters: ``center_ra``: center RA of the field (in degrees) ``center_dec``: center DEC of the field (in degrees) ``radius``: how far the actual RA and DEC might be from the estimated values (in degrees) Tweak ----- By default we try to compute a SIP polynomial distortion correction with order 2. You can disable this by changing the order to 0, or change the polynomial order by setting ``tweak_order``. CRPIX Center ------------ By default the reference point (CRPIX) of the WCS we compute can be anywhere in your image, but often it's convenient to force it to be the center of the image. This can be set by choosing ``crpix_center=True``. License and Sharing ------------------- The Astrometry.net [website](https://nova.astrometry.net/) allows users to upload images as well as catalogs to be used in generating an astrometric solution, so the site gives users the choice of licenses for their publically available images. Since the astroquery astrometry.net api is only uploading a source catalog the choice of ``public_visibility``, ``allow_commercial_use``, and ``allow_modifications`` are not really relevant and can be left to their defaults, although their settings are described below Visibility ^^^^^^^^^^ By default all images/source lists uploaded are publicly available. To change this use the setting ``publicly_visible='n'``. .. note:: Be aware that some information you submit to `astrometry.net`_ is publicly available even if the raw image isn't. For example, the log of each job is accessible if one knows the job id regardless of the permissions set for the image. The log will contain the RA/Dec of the solution. For publicly viewable images `astrometry.net`_ includes links to download the FITS files for the image. License ^^^^^^^ There are two parameters that describe setting a license: ``allow_commercial_use``: Chooses whether or not an image uploaded to astrometry.net is licensed for commercial use. This can either be set to ``y``, ``n``, or ``d``, which uses the default license associated with the api key. ``allow_modifications``: Whether or not images uploaded to astrometry.net are allowed to be modified by other users. This can either be set to ``y``, ``n``, or ``d``, which uses the default license associated with the api key. Reference/API ============= .. automodapi:: astroquery.astrometry_net :no-inheritance-diagram: .. _astrometry.net: https://astrometry.net/ .. _photutils: https://photutils.readthedocs.io