Script for solving the coordinates of astronomical images [more]

Keywords: coordinates, annotation




The ImageSolver script analyzes the geometry of an astronomical image and calculates the transformations necessary for converting pixel coordinates in celestial coordinates. The result is written in keywords of the FITS files so it can be used by other scripts like AnnotateImage or MosaicByCoordinates.

The coordinates are stored in the image following the specifications at [1] [2]. This makes them compatible with other applications.

This is not a "blind solver": The script requires to know in advance an approximation to the resolution and coordinates of the center of the image. Usually it is enough that the starting coordinates are inside of the image and that the resolution has an error less that 50%. The algorithm works comparing the image with the position of the stars extracted from a catalog. Then calculates a transformation matrix that converts from pixel coordinates to celestial coordinates. Since the script is designed for solving optical images it uses the Gnomonic projection that models how most optical systems generate the images.

The script can solve distorted images using non-lineal polynomials and/or distortion models. The distortion models are compatible with StarAlignment and can be generated using ManualImageSolver.

Some images can be difficult to solve because of the noise or low SNR, lack of enough stars or heavy distortions. In these cases ManualImageSolver should be able to solve the image.


Target Images

The target images are the images that the script will solver.

Active window

When this option is selected the script will solve the active image in PixInsight. This option is enabled only when there is at least one image open in the application. The solution will be stored as new keyword in the active image.

List of files

When this option is selected the script will solve a list of files. The results will be saved to the same directory as the original images and a file name composed of the original file name and a suffix.

The list can be managed with the buttons Add files, Remove files and Clear files.

Output file suffix

This suffix is added to the file name of the output files in order to differentiate them from the original files. This option is only available when the option List of files is checked.

Image Parameters


The Right ascension and Declination fields define the starting point for the algorithm. The coordinates have to be equatorial coordinates using the standard equinox J2000. These coordinates must be inside the image, and it is better that they as near to the center of the image as possible.

If the image has the keywords OBJCTRA and OBJCTDEC the script initializes the coordinates to the values of these keywords. Most capture programs have the capability of reading the position of the telescope and fill these keywords. Since having a good starting position is very important to configure the capture program to fill OBJCTRA and OBJCTDEC if possible.


This button opens a dialog that allows to search the name of astronomical objects in an online search engine (Sesame). The search can be done by name or identifier: "Rossete nebula", "Altair", "M31", "TYC 1058-3399-1". The coordinates of the selected object are copied to the Coordinates fields.


This fields defines the date when the image was taken. It is necessary for calculating the position of the stars using their proper motion.

If the image has a valid DATE-OBS keyword the script initializes this field to the date in this keyword.

Image Scale

The scale of the image can be defined using the fields Resolution or Focal length. These parameters don't need to be exact since the script is able to find its exact value. However the initial value should be as precise as possible since this increases the probability of the image being solved.

The parameter Focal Length can only be used when Pixel size has a value greater than zero. The focal length must be the effective focal length after taking in account focal reducers, Barlows or any effect that modifies the focal length. Some telescopes, like many amateur Schmidt–Cassegrain, the focusing is done moving the main mirror and this modifies the focal length of the system.

The parameter Focal Length is initialized automatically if the image has the keywords FOCALLEN and XPIXSZ.

Pixel size

This parameter defines the size in micrometers of the pixels of the image sensor. This parameter is optional, but if it is not filled, you can not use the focal length for defining the image scale. If you do use this parameter you must set the exact value since the script can not optimize it.

The parameter PixelSize is initialized automatically if the image has the keyword XPIXSZ.

Model Parameters

The script solves the image comparing it against stars extracted from a star catalog. This section describes how to configure the catalog.

Local catalog

If this option is selected the script uses a catalog stored locally. In this case you have to configure the path where the catalog is stored.

You can use the PPMX star catalog that can be downloaded from The file PPMX.bin has to be saved somewhere in your computer and then set its path in the script. This catalog has stars of magnitude less than 12.8.

VizieR star catalog

VizieR is an online catalog server that provides information of many catalogs. From the many catalog available the script allows to use a subset:

  • UCAC3: This catalog contains stars of magnitudes between 8 and 16.
  • PPMXL: This catalog contains stars of magnitude up to 20.
  • TYCHO-2: This catalog is the result of the Hipparcos space telescope and contains the 2.5 million brightest stars (magnitude<13).
  • BrightStars: This catalog contains the 9100 brightest stars (magnitude<8)

You have to select the catalog best suited for your image. For example for very wide field images (focal length<25mm) you should use the catalog BrightStars since it has enough stars and the queries are fast for big fields. PPMXL and UCAC-3 are useful for very deep images since they have very dim stars. However the queries in these two catalogs are very slow for big fields.

VizieR has several mirror servers that provide the same data. You have to select the best server for you, usually the nearest.

Limit magnitude

This parameter limits the number of stars extracted from the catalog to those with magnitude less than this value. This magnitude should be similar to the magnitude of the dimmest stars in the image. If the value is too low the script won't have enough stars to compare, but if it is too high the script will try to match stars of the image to stars that aren't visible. This will slow the process and it could confuse the algorithm and prevent finding a solution or worse: it could find a bad solution.

Advanced Parameters

Align algorithm

The first step for solving an image consists in aligning the image with StarAlignment using the catalog stars as reference. This parameter defines which algorithm StarAlignment uses during the alignment.

There are two options:

  • Triangles: Uses a triangle similarity algorithm which is fast, works in most images but have problems in images with strong distortions.
  • Polygons: Uses an algorithm based on the comparison of polygons which is more tolerant to distortions and scale differences, but it doesn't work with mirrored images.

You should use Polygons when you are sure that the image is not mirrored and Triangles in the other cases.

Star sensitivity

This parameter configures the sensitivity of the star detection. Increase the value to detect less stars.

It is important to set a good value for this parameter so the script detects all the stars of the image and it doesn't mistake noise by stars. The default value of -1 is usually good for lineal images. Stretched images usually require a higher value (0-1).

You can use the option Show stars for knowing which stars are being detected.

Show stars

When this option is active the script generates a new image with marks on the position of the detected stars in the original image. It is useful for finding a good value for the Star sensitivity parameter.

Polynomial degree

This parameter defines the degree of the polynomial used for translating coordinates.

The WCS standard only supports degree 1 polynomials. When a larger value is used, ImageSolver stores the polynomial coefficients in nonstandard keywords. For compatibility reasons, a degree 1 (linear) polynomial is also calculated and stored in the WCS keywords.

You should use the value 1 when the image has not geometric distortions. This is usually true for images taken with focal lengths of 400mm or higher. For images with short focal lengths you have to use a higher degree (up to 5).

The options Show distortion map and Generate residuals image can help choosing the correct value for this parameter.

Show distortion map

When this option is activated the script creates a new window with a representation of the distortions in the image. The new image contains a grid with arrows at the center of each cell. The arrows point to the point where the center of the cells would be located if the image didn't have optical aberrations. Since usually the aberrations are quite small, the arrows are exaggerated ten times.

This option is only enabled when the polynomial degree is greater than one.

Figure 1

Generate distortion model

When this option is active the script generates a distortion model. This model can be used by StarAlignment or by ImageSolver for solving other images.

The model is save as a text file in the same directory as the image and with the same name and the extension .CSV. This option is only enabled when the polynomial degree is greater than one.

Distortion model

When the image has strong geometric distortions a distortion model helps to solve the image. The distortion models used by ImageSolver are compatible with the distortion models of StarAligment. The section Creation of a distortion model explains how to create a distortion model.

When using distortion models usually is necessary to set the degree of the polynomials to a value between 3 and 5.

Generate residuals image

When this option is selected the script generates an image which shows the residuals of the solution. The image shows as green crosses the predicted position of the control points using the calculated solution. Red lines from each control point join the predicted position to the actual position marked by the user.

This image can be used to analyze the errors of the solution. In a good solution all the red lines should be very short (in a perfect solution the lines should have degenerated to points). When most red lines are long the solution is not good. In this case you can try to increase the value of the degree of the polynomial.

Figure 2

Only apply optimization

This option requires that the image is already solved. The script doesn't apply the initial alignment algorithm but only tries to optimize the solution.

This option is useful when the image has a rough solution and we need to improve it. For example, after solving the image with ManualImageSolver using very few control points, Only apply optimization allows to get a more precise solution. This option is usefull to test the effect of different values of the degree of the polynomials.

What to do when the script doesn't solve an image

General tips

Stretched images

The histogram stretch is one of the fundamental steps processing an image. However it can interfere with ImageSolver: when the image is stretched the noise is also magnified and it can make noise to be confused with stars. Also the brightest stars get saturated and sometimes are not identified as stars. This situation can be detected activating the option Show stars.

Fortunately this problem is not very frequent but when it occurs you can solve it "un-stretching" the image:

Wide field images

In this context wide field images are those with a focal length of less than 100mm. These images usually are taken with lenses that have serious geometric distortions that can make quite difficult to solve them. There are a couple of strategies for solving these images:

If neither of these methods works, you can always use ManualImageSolver for solving the image.

Creation of a distortion model

The distortion models define how the pixels of an image are displaced from its theoretical position if the image were taken by an ideal optical system. The distortion models are usually only necessary for short focal lenses (less than 100-200mm) and most telescopes don't need them. The models have to be calculated for each lens and focal length (for variable focal lenses).

Although creating a distortion model can be quite involved, it only has to be done once for each focal length of each lens. Since most of the people uses only a few lenses for astronomical images this usually is not a problem.

For creating a distortion model you have to follow these steps:

How to copy the coordinates between images

There are two methods for copying the coordinates from one image to another:


The first method can be used when both images have exactly the same geometry: same dimensions and the stars in the same exact position. This is usually the case when you extract one of the channels of the image or between the original unprocessed image and the final image if there are not crops nor resizings.

In this case you can follow this instructions:

Beware that this copies all the keywords of the source image to the target image.


The second method is useful when you have a solved image and you want to crop and/or resize it without having to solve it again. It can be used when the geometry of the two images is not the same but there is a linear transformation between both images.



[1] E. W. Greisen, M. R. Calabretta (2002) Representations of World Coordinates in FITS, Astronomy & Astrophysics, 395, 1061-1075

[2] M. R. Calabretta, E. W. Greisen (2002) Representations of Celestial Coordinates in FITS, Astronomy & Astrophysics, 395, 1077-1122

[3] Wikipedia contributors, Gnomonic projection, Wikipedia, The Free Encyclopedia

Related Tools

StarAlignment, DynamicAlignment, GradientMergeMosaic

Related Scripts

ImageSolver, ManualImageSolver