alipy Package

alipy Package

This is alipy, a python package to quickly, automatically, and robustly identify geometrical transforms between optical astronomical images.

Authors:Malte Tewes

align Module

alipy.align.affineremap(filepath, transform, shape, alifilepath=None, outdir='alipy_out', makepng=False, hdu=0, verbose=True)[source]

Apply the simple affine transform to the image and saves the result as FITS, without using pyraf.

  • filepath (string) – FITS file to align
  • transform (SimpleTransform object) – as returned e.g. by alipy.ident()
  • shape (tuple) – Output shape (width, height)
  • alifilepath (string) – where to save the aligned image. If None, I will put it in the outdir directory.
  • makepng (boolean) – If True I make a png of the aligned image as well.
  • hdu – The hdu of the fits file that you want me to use. 0 is primary. If multihdu, 1 is usually science.
alipy.align.fromfits(infilename, hdu=0, verbose=True)[source]

Reads a FITS file and returns a 2D numpy array of the data. Use hdu to specify which HDU you want (default = primary = 0)

alipy.align.irafalign(filepath, uknstarlist, refstarlist, shape, alifilepath=None, outdir='alipy_out', makepng=False, hdu=0, verbose=True)[source]
Uses iraf geomap and gregister to align the image. Three steps :
  • Write the matched source lists into an input file for geomap
  • Compute a geomap transform from these stars.
  • Run gregister
  • filepath (string) – FITS file to be aligned
  • uknstarlist (list of Star objects) – A list of stars from the “unknown” image to be aligned, that matches to ...
  • refstarlist (list of Star objects) – ... the list of corresponding stars in the reference image.
  • shape (tuple) – Output shape (width, height)
  • alifilepath (string) – where to save the aligned image. If None, I put it in the default directory.
  • makepng (boolean) – If True I make a png of the aligned image as well.
  • hdu – The hdu of the fits file that you want me to use. 0 is primary. If multihdu, 1 is usually science.
alipy.align.shape(filepath, hdu=0, verbose=True)[source]

Returns the 2D shape (width, height) of a FITS image.

Parameters:hdu – The hdu of the fits file that you want me to use. 0 is primary. If multihdu, 1 is usually science.
alipy.align.tofits(outfilename, pixelarray, hdr=None, verbose=True)[source]

Takes a 2D numpy array and write it into a FITS file. If you specify a header (pyfits format, as returned by fromfits()) it will be used for the image. You can give me boolean numpy arrays, I will convert them into 8 bit integers.

ident Module

class alipy.ident.Identification(ref, ukn)[source]

Represents the identification of a transform between two ImgCat objects. Regroups all the star catalogs, the transform, the quads, the candidate, etc.

All instance attributes are listed below.

  • ref – ImgCat object of the reference image
  • ukn – ImgCat object of the unknown image
  • ok – boolean, True if the idendification was successful.
  • trans – The SimpleTransform object that represents the geometrical transform from ukn to ref.
  • uknmatchstars – A list of Star objects of the catalog of the unknown image...
  • refmatchstars – ... that correspond to these Star objects of the reference image.
  • medfluxratio – Median flux ratio between the images: “ukn * medfluxratio = ref” A high value corresponds to a shallow unknown image. It gets computed by the method calcfluxratio, using the matched stars.
  • stdfluxratio – Standard error on the flux ratios of the matched stars.

Computes a very simple median flux ratio between the images. The purpose is simply to get a crude guess, for images with e.g. different exposure times. Given that we have these corresponding star lists in hand, this is trivial to do once findtrans was run.

findtrans(r=5.0, verbose=True)[source]

Find the best trans given the quads, and tests if the match is sufficient

showmatch(show=False, verbose=True)[source]

A plot of the transformed stars and the candidate quad, ukns, hdu=0, visu=True, skipsaturated=False, r=5.0, n=500, sexkeepcat=False, sexrerun=True, verbose=True)[source]

Top-level function to identify transorms between images. Returns a list of Identification objects that contain all the info to go further.

  • ref (list of strings) – path to a FITS image file that will act as the “reference”.
  • ukns – list of paths to FITS files to be “aligned” on the reference. ukn stands for unknown.
  • hdu – The hdu of the fits files (same for all) that you want me to use. 0 is somehow “automatic”. If multihdu, 1 is usually science.
  • visu (boolean) – If yes, I’ll draw some visualizations of the process (good to understand problems, if the identification fails).
  • skipsaturated (boolean) – Should I skip saturated stars ?
  • r (float) – Identification radius in pixels of the reference image (default 5.0 should be fine).
  • n (int) – Number of brightest stars of each image to consider (default 500 should be fine).
  • sexkeepcat (boolean) – Put this to True if you want me to keep the SExtractor catalogs (in a dir “alipy_cats”).
  • sexrerun (boolean) – Put this to False if you want me to check if I have some previously kept catalogs (with sexkeepcat=True), instead of running SExtractor again on the images.


Make this guy accept existing asciidata catalogs, instead of only FITS images.

imgcat Module

class alipy.imgcat.ImgCat(filepath, hdu=0, cat=None)[source]

Represent an individual image and its associated catalog, starlist, quads etc.

makecat(rerun=True, keepcat=False, verbose=True)[source]

We add more quads, following the quadlevel.

makestarlist(skipsaturated=False, n=200, verbose=True)[source]
showquads(show=False, flux=True, verbose=True)[source]

Uses matplotlib to write/show the quads.


Uses f2n to write a png image with circled stars.


Sorting a coordinate array CCW to plot polygons ...

pysex Module

Author: Nicolas Cantale -

Small module wrapping sextractor. The idea is to have a single function taking an image and returning a sextractor catalog.

  • sextractor (mandatory)
  • astroasciidata (mandatory)
  • numpy (optional, needed for the array support)
  • pyfits (optional, needed for the array support)


import pysex cat =, params=[‘X_IMAGE’, ‘Y_IMAGE’, ‘FLUX_APER’], conf_args={‘PHOT_APERTURES’:5}) print cat[‘FLUX_APER’]'', imageref='', params=[], conf_file=None, conf_args={}, keepcat=True, rerun=False, catdir=None)[source]

Run sextractor on the given image with the given parameters.

image: filename or numpy array imageref: optional, filename or numpy array of the the reference image params: list of catalog’s parameters to be returned conf_file: optional, filename of the sextractor catalog to be used conf_args: optional, list of arguments to be passed to sextractor (overrides the parameters in the conf file)

keepcat : should I keep the sex cats ? rerun : should I rerun sex even when a cat is already present ? catdir : where to put the cats (default : next to the images)

Returns an asciidata catalog containing the sextractor output

Usage exemple:
import pysex cat =, params=[‘X_IMAGE’, ‘Y_IMAGE’, ‘FLUX_APER’], conf_args={‘PHOT_APERTURES’:5}) print cat[‘FLUX_APER’]

quad Module

Quads are asterisms of 4 stars, used to match the catalogs.

class alipy.quad.Quad(fourstars)[source]

A geometric “hash”, or asterism, as used in : It is made out of 4 stars, and it is shift / scale / rotation invariant

alipy.quad.makequads1(starlist, n=7, s=0, d=50.0, verbose=True)[source]

First trivial quad maker. Makes combis of the n brightest stars.

  • n (int) – number of stars to consider (brightest ones).
  • s (int) – how many of the brightest stars should I skip ? This feature is useful to avoid building quads with nearly saturated stars that are not available in other exposures.
  • d (float) – minimal distance between stars
alipy.quad.makequads2(starlist, f=5.0, n=6, s=0, d=50.0, verbose=True)[source]

Similar, but fxf in subareas roughly f times smaller than the full frame. s allows to skip the brightest stars in each region

  • f (float) – smallness of the subareas
  • n (int) – number of stars to consider in each subarea
  • d (float) – minimal distance between stars
  • s (int) – number of brightest stars to skip in each subarea

Function that tests if 4 stars are suitable to make a good quad...

alipy.quad.proposecands(uknquadlist, refquadlist, n=5, verbose=True)[source]

Function that identifies similar quads between the unknown image and a reference. Returns a dict of (uknquad, refquad, dist, trans)

alipy.quad.quadtrans(uknquad, refquad)[source]

Quickly return a transform estimated from the stars A and B of two quads.

alipy.quad.removeduplicates(quadlist, verbose=True)[source]

Returns a quadlist without quads with identical hashes...

star Module

Overhaul of cosmouline’s star module, for alipy2. This module contains stuff for geometric matching algorithms.

class, 0, 0, 0))[source]

Represents an affine transformation consisting of rotation, isotropic scaling, and shift. [x’, y’] = [[a -b], [b a]] * [x, y] + [c d]

apply((x, y))[source]

Applies the transform to a point (x, y)


The CCW rotation angle, in degrees


Returns the inverse transform !


Special output for scipy.ndimage.interpolation.affine_transform Returns (matrix, offset)

class, y=0.0, name='untitled', flux=-1.0, props={}, fwhm=-1.0, elon=-1.0)[source]

Simple class to represent a single source (usually stars, but not necessarily). In this module we often manipulate lists of such Star objects.


Returns the coords in form of an array.

Parameters:full (boolean) – If True, I also include flux, fwhm, elon

Returns the distance between the two stars.


Returns a list of dicts(star, dist, origpos), sorted by distance to self. The 0th star is the closest.

otherstarlist is not modified.


returns the “trigonometric” angle of the vector that goes from self to the otherstar, in degrees, border=0.01)[source]

Returns the area covered by the stars. Border is relative to max-min, nametofind)[source]

Returns a list of stars for which name == nametofind, refstars, verbose=True)[source]

I return the transform that puts the unknown stars (uknstars) onto the refstars. If you supply only two stars, this is using linalg.solve() – perfect solution. If you supply more stars, we use linear least squares, i.e. minimize the 2D error.

Formalism inspired by :, refstars, trans=None, r=5.0, verbose=True, getstars=False)[source]
Allows to:
  • get the number or matches, i.e. evaluate the quality of the trans
  • get corresponding stars from both lists (without the transform applied)
Parameters:getstars (boolean) – If True, I return two lists of corresponding stars, instead of just the number of matching stars

Inspired by the “formpairs” of alipy 1.0 ..., full=False)[source]

Transforms the starlist into a 2D numpy array for fast manipulations. First index is star, second index is x or y

Parameters:full (boolean) – If True, I also include flux, fwhm, elon[source]

Prints the stars ..., verbose='True')[source]

Reads a “manual” star catalog – by manual, I mean “not written by sextractor”. So this is typically a short file.

Comment lines start with #, blank lines are ignored. The format of a data line is

starname xpos ypos [flux]

The data is returned as a list of star objects., hdu=0, verbose=True, maxflag=3, posflux=True, minfwhm=2.0, propfields=[])[source]

sexcat is either a string (path to a file), or directly an asciidata catalog object as returned by pysex

Parameters:hdu – The hdu containing the science data from which I should build the catalog. 0 will select the only available extension. If multihdu, 1 is usually science.

We read a sextractor catalog with astroasciidata and return a list of stars. Minimal fields that must be present in the catalog :

maxflag : maximum value of the FLAGS that you still want to keep. Sources with higher values will be skipped.
  • FLAGS == 0 : all is fine
  • FLAGS == 2 : the flux is blended with another one; further info in the sextractor manual.
  • FLAGS == 4 At least one pixel of the object is saturated (or very close to)
  • FLAGS == 8 The object is truncated (too close to an image boundary)
  • FLAGS is the sum of these ...

posflux : if True, only stars with positive FLUX_AUTO are included.

propfields : list of FIELD NAMES to be added to the props of the stars.

I will always add FLAGS as a propfield by default., measure)[source]

We sort starlist according to measure : lowest first ! Where measure is one of flux, fwhm, elon[source]

We sort starlist according to flux : highest flux first !

Table Of Contents

Previous topic


This Page