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

Keywords: mosaic, alignment, coordinates




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:

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:

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.



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.


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.


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.

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.

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.

Figure 3




[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