File Exchange

image thumbnail


version 19.0312 (8.46 MB) by Emmanuel Farhi
A Matlab class to annotate astrophotography images (identify objects/astrometry)


Updated 22 Jul 2020

View Version History

GitHub view license on GitHub

astrometry: A Matlab class to annotate astrophotography images (identify objects/astrometry)



This Matlab class allows to use the software, either installed
locally, or through internet connection, in order to solve (annotate)
astrophotography images.


First navigate to the matlab-astrometry directory or type:

addpath /path/to/matlab-astrometry

Then use:

as = astrometry;
Create a solver, but does not solve.
Use solve(as, file) or local(as, file) or web(as, file) afterwards.

as = astrometry(file, ...); image(as);
Solve the given astrophotography image with local or web method.
Then plot the result. Additional arguments may include name/value pairs
(see example below):

ra: approximate RA coordinate (e.g. deg or 'hh:mm:ss')
dec: approximate DEC coordinate (e.g. deg or 'deg:mm:ss')
radius: approximate field size (in deg)
scale-low: lower estimate of the field coverage (in [deg], e.g. 0.1)
scale-high: upper estimate of the field coverage (in [deg], e.g. 180)

These two syntaxes will try first any local installation, and
if failed, the service.

Going further

as = astrometry.load(dir); image(as);
Read an existing set of files stored in a given directory.
The directory may contain WCS, CORR, RDLS, JSON, and image.
Then plot the result. This allows to get previous data files, or obtained
externally, and label them. The 'as' astrometry object must have been used
to solve or import astrometry data.

[x,y] = sky2xy(as, ra, dec)
Convert a RA/DEC set of coordinates (in [deg] or 'hh:mm:ss'/'deg::mm:ss')
into pixel coordinates on the image. The 'as' astrometry object must have
been used to solve or import astrometry data.

[ra, dec] = xy2sky(as, x,y)
[ra, dec] = xy2sky(as, x,y, 'string')
Convert pixel coordinates on the image into a RA/DEC set of coordinates
(in [deg]). When given a 'string' argument, the result is given in
'hh:mm:ss'/'deg:mm:ss'. The 'as' astrometry object must have been used
to solve or import astrometry data.

f = astrometry.findobj('object name')
Return information about a named object (star, deep sky object) from the
data base. Example: astrometry.findobj('M33')

as = astrometry.local(file, ...);
Explicitly use the local 'solve-field' installation.
See above for the additional arguments.

as = astrometry.web(file, ...);
Explicitly use the web service.
See above for the additional arguments.

For a solved image, the corresponding sky view is displayed on . The 'as' astrometry object must have been used
to solve or import astrometry data.

Using results
Once an image has been solved with the 'as' object, you can use the astrometry results.

The annotation is done asynchronously, and the Matlab prompt is recovered.
You may use getstatus(as) to inquire for the solve-plate status (running, success, failed).
To wait for the end of the annotation, use waitfor(as).

* as.result.RA and as.result.Dec provide the center coordinates of the
field (in [deg]), while as.result.RA_hms and as.result.Dec_dms provide the
'HH:MM:SS' and 'Deg:MM:SS' coordinates.
* The field rotation wrt sky is stored in as.result.rotation.
* The pixel scale is given in [arcmin/pixel] as as.result.pixel_scale.
* The field extension is given with its bounds as as.result.RA_min, as.result.RA_max,
as.result.Dec_min, and as.result.Dec_min.
* The constellation name is stored in as.result.Constellation.

Improving the plate-solve efficiency

To facilitate the plate-solve/annotation of images, you may:

* specify the field size with additional arguments such as:
astrometry(..., 'scale-low', 0.5, 'scale-high',2)

* provide an initial guess for the location, and its range, such as:
astrometry('examples/M13-2018-05-19.jpg','ra','01:33:51','dec','30:39:35','radius', 2)

* add more star data bases (e.g. 2MASS over Tycho2).


as=astrometry('examples/M13-2018-05-19.jpg','scale-low', 0.5, 'scale-high',2);


load(astrometry, dir)
local(astrometry, filename, ...)
web(astrometry, filename, ...)
sky2sx(as, ra, dec)
xy2sky(as, x, y)
findobj(as, 'name')


Local installation (recommended)

On Linux systems, install the '' package, as well as the
'tycho2' data base. On Debian-class systems, this is achieved with:

sudo apt install astrometry-data-tycho2 sextractor

On other systems, you will most probably need to compile it.
RedHat/Arch/MacOSX have specific installation instructions.

Cite As

Emmanuel Farhi (2021). matlab-astrometry (, GitHub. Retrieved .

Comments and Ratings (1)

Alex Friedman

Hi Emmanuel,

I am trying to use the web service with my API key from and the program immediately returns a failed plate solve message. I have tried one of my own images and your example test case and both fail to plate solve. Is there something else I need to modify besides the API key?


MATLAB Release Compatibility
Created with R2010a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!