Skip to main content

A Python interface for the Astrometry.net API.

Project description

Documentation Status Build & Tests Status

Quickstart

Install the package via pip:

pip install astrometry-net-client

Get your API key from: api_help, and paste it in a plaintext file (name it something like key).

A script called anc_upload should be included with the install, which can be used to upload a file via the API. For example, to upload a file named observation.fits use:

anc_upload --key-location ./api-key observation.fits

where the api key is given in the file api-key. The solved file will be placed in a subdirectory called anc_output. Multiple files can be given at the same time as well.

To make the solving faster, it is recommended to give known parameters of your image. For instance, if you know the plate scale of your image is 1.7 arcsec / pixel, you can specify it via the command line:

anc_upload --key-location ./api-key observation.fits --plate-scale 1.7

By default, a tolerance is set of 10% around this value. Alternatively, the field of view of the image can also be given via the –fov-width argument. Use anc_upload –help to see all the available options.

Introduction

This package is meant to be a simple but extensible interface for the Astrometry.net API. A higher level interface is offered through the Client class, combining most functionality. However, if you want more control over the requests (e.g. by manually checking the responses), you can also use the Job, Submission and UploadFile classes directly.

The structure of these classes tries to follow the pattern of the API itself, which is essentially:

  1. Upload some file (UploadFile), which requires an API key & a login (Session)

  2. The upload creates a submission (Submission), unique for each upload. This has to do some general processing, even before the uploaded image is processed.

  3. When the submission is done preprocessing, and the system is ready to process the uploaded file, a job (Job) is spawned for each image.

  4. The job then takes some time to process, and when it is done it can either be successful or fail.

  5. When successful, some information (e.g. found objects) and result files like the generated WCS header can be retrieved.

Using this package, these steps are (note that this is not the ideal way to upload multiple files):

from astrometry_net_client import Session
from astrometry_net_client import FileUpload

s = Session(api_key='xxxxxxxxx')
upl = FileUpload('some/file/name', session=s) # 1.
submission = upl.submit()                     # 2.
submission.until_done()                       # blocks until it is finished
job = submission.jobs[0]                      # 3.
job.until_done()                              # 4. (again blocks)
if job.success():
    wcs = job.wcs_file()                      # 5. (only if successful)
print(job.info())                             # works even though the job failed

Or with the higher level Client :

from astrometry_net_client import Client

c = Client(api_key='xxxxxxxxxx')

# WARNING: this can take a while, as it blocks until the file is solved.
# wcs will be None if upload is not successful
wcs = c.calibrate_file_wcs(filename)

One of the core ideas of this package is to try and make the minimal amount of requests possible and make them at a clear time. This is realized by the following initialize & send pattern:

r = Request(url)    # initialize (request not yet sent)
response = r.make() # send the request

Similarely, retrieving files like the WCS file (after a successful Job) will be done once and cached thereafter:

wcs = job.wcs_file()    # first call makes the actual request
wcs_2 = job.wcs_file()  # second call uses previously obtained result

Installation

Installation required python version 3.8 or greater.

Simpy install the package usng PyPi:

pip install astrometry-net-client

Note that the development and testing of this package is done on Linux, so it may not work on a different platform.

Installing From Source

Installing the package from source is made easy by the Makefile, once you have a local copy of the repository (e.g. by cloning, or downloading & extracting the repo ZIP).

It is heavily recommended to use a virtual environment. Create and activate one by running:

make virt-env
source .env/bin/activate
pip install wheel

Then build & install the package with (does not install development dependencies):

make install

Documentation

Documentation is available at Readthedocs

There is a local documentation available (defined by docstrings). To access it, first install the package and the development dependencies:

make dependencies

then generate the documentation (using Sphinx) by:

make documentation

The main page can then be found at (assuming you are in the project root) ./docs/_build/html/index.html. Open this (for example) with:

firefox ./docs/_build/html/index.html

Examples

Some example files/scripts are found at the examples entry of the documentation.

Some elaborate examples can be found in the examples directory. For more specific usage, refer to the documentation.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

astrometry_net_client-0.6.0.tar.gz (28.6 kB view details)

Uploaded Source

Built Distribution

astrometry_net_client-0.6.0-py3-none-any.whl (25.0 kB view details)

Uploaded Python 3

File details

Details for the file astrometry_net_client-0.6.0.tar.gz.

File metadata

  • Download URL: astrometry_net_client-0.6.0.tar.gz
  • Upload date:
  • Size: 28.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for astrometry_net_client-0.6.0.tar.gz
Algorithm Hash digest
SHA256 23eef3f395747bcb8a8b030c0b043c7b85db7b2b8f163add3d5fac73ecb9c818
MD5 2e99d7f9605d7e068b839799f84d4bf9
BLAKE2b-256 f961ec7abb35dd2de96d977e901ce8213fc725f7184b05941f3f0b35a9e1b87b

See more details on using hashes here.

File details

Details for the file astrometry_net_client-0.6.0-py3-none-any.whl.

File metadata

File hashes

Hashes for astrometry_net_client-0.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f003fd1b95a6760838de821f32d1777f2c8596f2b5666e1c1d348a311526be5e
MD5 30432125e7e9483fd61b313a9e3cc42d
BLAKE2b-256 c734c3c4698dea33c5729bd88107ac99ccb41f08b021f390688c850dfb4c0f90

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page