By Andrés del Pozo

Script for creating mosaics of deep sky astronomical images using their coordinates. [more]

Keywords: mosaic, alignment, coordinates



1 Introduction


Mosaics in PixInsight can be done using the tool StarAlignment for aligning the images. This tool works comparing the overlapping areas between the target image and a reference image and trying to find a match between them. Then computes a lineal transformation that converts the geometry of the target image so that it is similar to the reference image.

This usually works very well but it has a few limitations:

  • When building mosaics, StarAlignment can only match the images when there is a big enough overlapping area. For example, it can not align images from the segmented sensors of professional telescopes.
  • When building mosaics, StarAlignment aligns the images by pairs. When a mosaic is formed by many tiles the process is prone to mismatchings caused by accumulating errors. Although this can be avoided using a reference image that cover the whole mosaic area, the script MosaicByCoordinates resolves this problem in a easier and elegant way.
  • StarAlignment can not create mosaic of really big areas that cover most or all the sky.

MosaicByCoordinates tries to solve this shortcomings using a different approach to the alignment: Instead of matching an image against other, it requires that the images are plate solved. Knowing the coordinates of each pixel of the image the script can reproject them so the geometries of the images are compatible.

The geometry of the image has to be defined using the convention FITS World Coordinate System (WCS)[1] [2] . This can be done using the scripts ImageSolver or ManualImageSolver. There are also other applications that can solve images using this convention as PinPoint.

MosaicByCoordinates can cope with two kind of geometric distortions:

  • Projection distortions: When two images are not centered in the same point they have different projections. The difference in the projections causes that there is not a lineal transformation between them. This effect is stronger in images with short focal length.
    The following animation shows an example of this effect. The images have been generated from catalog data and the only geometric distortions are caused by the projection. As can be seen in the animation, the Orion asterism has different distortions in each frame.

    Figure 1

  • Geometric optical aberrations: The plate solving of astronomical images is usually done supposing that the optical system can be modeled by a Gnomonic projection [3]. However, many lenses or telescopes don't follow strictly this projection. The images from these optical systems can not be solved with high accuracy using only lineal polynomials. ImageSolver and ManualImageSolver can use higher degree polynomials to model the geometric distortions. MosaicByCoordinates can use the distortion model generated by the plate solving process for fixing it when aligning images with different distortions.
    The following image is the distortion map from an image taken with a 17mm lens. It shows the difference between the image and an "ideal" lens that generates images using Gnomonic projection.

    Figure 2

MosaicByCoordinates can generate the mosaic using different projections with different properties. For example, the Gnomonic projection is useful for narrowfield images, Mercator for medium/wide field images and Hammer-Aitoff can be used for all-sky images. A more detailed description of the supported projections can be found in the Projections document.

As a result, MosaicByCoordinates can be used for generating wide field mosaics where the tiles have little or no overlapping and when the tiles have strong distortions caused by short focal lenses.

2 Usage


2.1 Tiles

The list of tiles contains the images that will be aligned. You have to add to this list all the images that compose the mosaic.

Add files

This button opens the file dialog for adding files to the tiles list.

Add windows

This button opens a dialog that allows to add open images to the list of tiles. This dialog shows the windows open in PixInsight where you can choose which are added to the list of tiles.

The results of the alignment of these images are not written to a file. Instead, windows with the resulting images are open in the workspace of PixInsight.

Remove images

Removes the selected images from the list.

Clear list

Removes all the images from the list.

2.2 Geometry

The geometry is defined by several parameters that can be calculated by the script or chosen by the user. Each field has a checkbox that when left unchecked means that its value should be calculated by the script.


The projection of the image determines how the celestial sphere is mapped to a plane. MosaicByCoordinates supports several projections with different characteristics. If the checkbox is not checked the projection will be chosen by the script.

The Advanced button allows to select the coordinates of the origin of the projection. If you are not familiar with the projections you should set the origin of the projection to the center of the image.

Coordinates of the center of the mosaic

This parameter determines the center of the mosaic. Usually the automatic value is adequate, but sometimes it is necessary to change it. For example, when the mosaic covers the whole sky you could want to change which part of the sky will be at the center of the mosaic.


This is the resolution of the mosaic expressed in seconds per pixel. Since some projections can distort heavily the image, this value is only true for the coordinates at the center of the projection.

The automatic calculation sets this value to the smallest of all the tiles.


This is the rotation angle of the mosaic. The automatic calculation sets this value to the rotation of the first tile.


Dimension in pixels of the final image. The button Calculate calculates the minimum values for these fields that cover all the tiles. Sometimes these can be very large so the script trunks them to 20000 pixels.


This button calculates the values for the geometry fields set to automatic. It analyzes the tiles an calculates the best geometry for the mosaic. It tries to set the center of the mosaic such as the final image is as small as possible.

2.3 Options


This option determines the quality of the output:

  • Fast : This option calculates the alignment transformation for a few pixels and then approximates the transformation for the rest of pixels using splines. The quality of the transformation is usually good enough for most uses but it is not guaranteed that all the pixels are correct.
  • High quality : This option calculates the alignment transformation for all the pixels in the image. The quality of the result is the best possible but the process can be quite slow, up to several minutes for each image.

Pixel interpolation

This option determines the algorithm for pixel interpolation. The available values are the same used in StarAlignment.

Clamping threshold

This parameter is explained in the documentation of StarAlignment.

2.4 Output images

Output directory

Path of the directory where the aligned images will be written. If it is empty, the images will be written at the same directories as the source images.

This parameter is not used when aligning windows since in this case the images are not written to the disk.

Output file suffix

This suffix will be appended to the filename when saving each image.

Overwrite existing files

If this option is not checked the alignment of an image fails when the output file already exists.

On error

This parameter determines what to do when there are errors during the process. The options are Continue, Abort and Ask user.

3 How to build a mosaic


The steps for building a mosaic using MosaicByCoordinates are these:

  1. Calibrate, register and integrate the subframes of each tile.
  2. Crop the tiles in order to remove the areas at the borders that were no covered by all the subframes.
  3. (Optional) If the tiles have gradients you should remove them using DynamicBackgroundExtraction.
  4. If the tiles are RGB you should do a color calibration.
  5. Solve the coordinates of all the tiles. This can be done with ImageSolver or MannualImageSolver. Please read the documentation for both scripts since it has useful tips about how to best solve the images.
    It is very important to remind that MosaicByCoordinates requires a "perfect" coordinates solution across the whole image. The quality of the alignment of the tiles depends on this process. If there is any kind of deviation in any part of an image (specially in the borders) the tiles would not get aligned correctly.
  6. Launch the script MosaicByCoordinates and add all the images that compose the mosaic to the tiles list. The script is designed for working with all the images of the mosaic at the same time. It is not optimal to process groups of images separately. If the tiles have separate images for each color channel, you should add to the script all the images of all the channels at the same time.
  7. The geometry of the resulting mosaic can be calculated automatically or you can choose which parameters you want to configure. The button Calculate analyzes the tiles and calculate the geometry of the mosaic. The calculated values can be seen in the fields of the dialog after Calculate finishes. You can change any of the fields if the automatic value is not as desired.
  8. Pressing OK the script begins the process. As a result the script generates a new image for each tile of the mosaic. These new images have the geometry of final mosaic. The contents of each tile are projected on its output image, leaving black the parts of the mosaic not covered by the tile.
  9. As the last step the tiles have to be merged. You can do this using PixelMath, GradientMergeMosaic or even ImageIntegration. GradientMergeMosaic is recommended when the tiles overlap and you do not want that the seams are visible in the result. ImageIntegration is useful when the tiles don't overlap. In this case the Combination parameter should be set to maximum.

This process is only a guideline and it should be adapted to the characteristics of the images.

For creating color mosaics using RGB, LRGB or narrowband data the color channels can be merged before aligning the tiles, or you can create a mosaic for each channel and then merge the mosaic of each channel. Both methods have advantages and disadvantages. Merging the channels before executing MosaicByCoordinates allows to do a different color calibration for each tile. This is useful when the light pollution causes a different color drift in each tile.

4 Tips


  • Since MosaicByCoordinates uses the coordinates of the image as the sole method for aligning the images, the coordinates solution must be of very high precision. It should have residuals of less than one pixel.
    For narrow field images taken with long focal lengths (usually more than 1000mm) and lenses of high optical quality, the solution usually doesn't need distortion correction. However, images taken with short focal lengths (<100mm) or lenses with strong aberrations (for example, Newton telescopes with coma), the coordinates should be calculated using distortion correction in order to achieve the required precision. These coordinates solutions can be calculated using both ImageSolver and ManualImageSolver.
  • The automatic calculation of the geometry of the algorithm is usually valid. However, you should check it and change any field necessary.
  • Projection selection:
    • In narrow field images (at most a few degrees) all the projections give very similar results. Gnomonic is recommended in this case because it is the fastest and more compatible projection.
    • For medium/wide field mosaics (5-120 degrees) you should use the Stereographic or Mercator projections.
    • For mosaics that cover the visible sky Orthographic projection is a good fit.
    • Hammer-Aitoff allows to make mosaics of the full sky sphere.
    • For images not covered by the previous cases you should try which projection is best for the image.
  • The generation of the tiles can be very slow (several minutes per tile). When you are trying to configure the geometry of the mosaic and you want to do several tests, you can temporarily configure the resolution to a higher value in order to reduce the final size of the mosaic and accelerate the process. Multiplying the resolution by 2 makes the script 4 times faster.
  • The "Fast" quality is useful to optimize the settings of the mosaic, however the "High quality" option usually is needed for the final image.

5 Limitations


  • Since this script requires to know the geometry of the images it can only work with images that can be plate solved. This is usually only possible for deep sky images where enough stars can be detected and matched to a catalog.
  • The maximum size of the image result of the creation of a mosaic is the same as the maximum size that PixInsight can open. The algorithm used in the script requires that the result of the alignment for each image is kept in memory, but each image is processed independently so it only keeps in memory one of the 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