File Exchange

image thumbnail

ASTROTNSTACK align and stack astro-photography pictures

version (285 KB) by Emmanuel Farhi
Automatically align and stack astro-photography pictures


Updated 16 Apr 2018

GitHub view license on GitHub

ASTROTNSTACK: automatically align and stack astro-photography pictures.
This function gets a list of images, and automatically determines bright stars
as control points. These are followed along pictures, and used to build an
affine transformation at constant scale (e.g. a rotation and translation).
All images are stacked over the first image used as reference. The images can
be given as file names (may include wildcards), or matrices from e.g. imread,
and support both RGB and gray images.
As stars are used for the alignment, this method is suited for deep sky
images, but not for planetary imaging.

This function does not make use of the phase correlation technique, but
operates directly on the raw images. It assumes that at least two bright
stars remain on each picture, but tolerate translations and rotations, as
well as stars/control points that appear/disappear on the field of view.
The procedure also ignores very sharp peaks, assuming they originate from dead
pixels (and would then be static over images, leading to traces).

It is highly recommended to specify a 'dark' frame filename, which will be
subtracted to all images, in order to e.g. remove most hot/dead pixels.
To get such a 'dark', use your camera alone and shot once with the cap on, same
settings as the other pictures (duration, ISO). Image should be full black.

You may as well specify a 'flat' frame filename, which will be divided
to all images, in order to counter vignetting (darker borders).
To get such a 'flat', shot once with the scope pointing at a uniform view
(sky, white wall). Adapt the duration so that you get a rather gray image
(not full black or white).

During the procedure, the current image and its stars/control points are
indicated, as well as the stacked image. A waitbar indicates the progress.
To abort the procedure, close the waitbar. The stacked image so far will be
saved and returned.
Supported image formats include JPG, PNG, TIFF, FITS.

The resulting stacked image is stored using the first/reference image name,
adding '_stacked', in the PNG format. This routine can stack a hundred 4k
images within 15 minutes. Memory requirements are about 2Gb for 4k images.

We recommend that you further use DarkTable or RawTherapee to enhance the low
intensity features (black, brightness, contrast).

Syntax: [stacked, output] = astrotnstack(images, dark, flat, N)
stacked = astrotnstack;

images: a filename name or cell of file names, that may include wildcards, or
matrix (rgb, gray). When not given or empty, a file selector pops-up.
dark: a single dark frame which is subtracted to all images.
When not given or empty, a file selector pops-up. Use 'cancel' button
to proceed without dark subtraction.
flat: a single flat frame which is divided to all images.
When not given or empty, a file selector pops-up. Use 'cancel' button
to proceed without flat normalisation.
N: the max number of control points to use. N=20 default.

Input can also be given as a structure with fields:
N: max number of control points (default is 20)
tol_rot: rotation tolerance in degrees (default is 3 deg)
tol_trans: translation tolerance (default is 0.01 = 1% of width)
test: when 1, images are analysed, but result is not written.
silent: when 1, no image/wait bar is displayed (faster).
dark: indicates dark frame (single image)
flat: indicates flat frame (single image)
images: images to stack (filename, may use wildcard, or matrix)

or even as unsorted name/value pairs such as in:
[stacked, output] = astrotnstack('images','*.JPG', 'dark','Dark.PNG', 'N',15)

stacked: stacked images.
output: a structure with the file names, rotations and translations.

astrotnstack('*.PNG', 'Dark.png', 'Flat.PNG');
astrotnstack({'*.PNG', imread('file.jpg') }, 'Dark.png', 'Flat.PNG');
astrotnstack('*.PNG', 'Dark.png', 'Flat.PNG', 'silent', 1);


See also:
Deep Sky Stacker
Rot'n Stack

E. Farhi Dec 2017 GPL2. Version 1.6.3

Cite As

Emmanuel Farhi (2020). ASTROTNSTACK align and stack astro-photography pictures (, GitHub. Retrieved .

Comments and Ratings (4)

Emmanuel Farhi

Hello Faheem,

The final image is rescaled in luminance to fully cover the image bit-depth, i.e. bring lowest luminance to 0, and highest to e.g. 65535. This way, the total information encoded retains the maximum dynamic range of the original images. This often tends to brighten the final image.

Faheem Shakoor

Thanks for the code.
I don't know why but the code is giving too bright image as a result, the histogram is concentrated slightly left of the center.
Can you please help me out with that where I,m wrong?

Emmanuel Farhi

Thanks arnold for the positive comments. I've updated astrotnstack (1.6) to handle gray-scale images (1 layer), and to be able to input directly either file names,or directly matrices after an initial treatment (e.g. imread).


works very well! Many thanks!
two things I would recommend:

1. adjust it so it works for grayscale images as well.
Index exceeds matrix dimensions.

Error in astrotnstack>rgb2gray (line 807)
gray = (0.2989 * rgb(:,:,1)) + (0.5870 *
rgb(:,:,2)) + (0.1140 * rgb(:,:,3));

Error in astrotnstack>find_control_points (line
im= rgb2gray(im);

Error in astrotnstack (line 262)
points = find_control_points(im, totalimages,
N, points, tol_trans*size(im,1));

2. add the ability to use matlab matrices, cells or other classes instead of loading external files. This would make pre-processing in matlab easier.


fixed support for FITS images and documentation.

now hosted on GitHub.

Fix 'silent' mode.

Now also support gray images, as well as filenames and matrices from e.g. imread.

Support for uint8/uint16 images. Better search for control points (stars). Allow silent mode (faster).

Compatibility with Octave

back to a single file 'all in one' easier to carry around.

support for FITS. Indicate supported file formats.

handle flat field normalisation. Inline functions moved to 'private'.

Display metrics from the transformations

enhance contrast in stacked image

final image as PNG 16 bits

more robust rotation determination

improved search for stars/control points

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