Package astLib :: Module astImages
[hide private]
[frames] | no frames]

Module astImages

source code

module for simple .fits image tasks (rotation, clipping out sections, making .pngs etc.)

(c) 2007-2014 Matt Hilton

http://astlib.sourceforge.net

Some routines in this module will fail if, e.g., asked to clip a section from a .fits image at a position not found within the image (as determined using the WCS). Where this occurs, the function will return None. An error message will be printed to the console when this happens if astImages.REPORT_ERRORS=True (the default). Testing if an astImages function returns None can be used to handle errors in scripts.

Functions [hide private]
dictionary
clipImageSectionWCS(imageData, imageWCS, RADeg, decDeg, clipSizeDeg, returnWCS=True)
Clips a square or rectangular section from an image array at the given celestial coordinates.
source code
numpy array
clipImageSectionPix(imageData, XCoord, YCoord, clipSizePix)
Clips a square or rectangular section from an image array at the given pixel coordinates.
source code
dictionary
clipRotatedImageSectionWCS(imageData, imageWCS, RADeg, decDeg, clipSizeDeg, returnWCS=True)
Clips a square or rectangular section from an image array at the given celestial coordinates.
source code
dictionary
clipUsingRADecCoords(imageData, imageWCS, RAMin, RAMax, decMin, decMax, returnWCS=True)
Clips a section from an image array at the pixel coordinates corresponding to the given celestial coordinates.
source code
dictionary
scaleImage(imageData, imageWCS, scaleFactor)
Scales image array and WCS by the given scale factor.
source code
dictionary
intensityCutImage(imageData, cutLevels)
Creates a matplotlib.pylab plot of an image array with the specified cuts in intensity applied.
source code
dictionary
resampleToTanProjection(imageData, imageWCS, outputPixDimensions=[600,600])
Resamples an image and WCS to a tangent plane projection.
source code
dictionary
resampleToWCS(im1Data, im1WCS, im2Data, im2WCS, highAccuracy=False, onlyOverlapping=True)
Resamples data corresponding to second image (with data im2Data, WCS im2WCS) onto the WCS of the first image (im1Data, im1WCS).
source code
 
generateContourOverlay(backgroundImageData, backgroundImageWCS, contourImageData, contourImageWCS, contourLevels, contourSmoothFactor=0, highAccuracy=False)
Rescales an image array to be used as a contour overlay to have the same dimensions as the background image, and generates a set of contour levels.
source code
 
saveBitmap(outputFileName, imageData, cutLevels, size, colorMapName)
Makes a bitmap image from an image array; the image format is specified by the filename extension.
source code
 
saveContourOverlayBitmap(outputFileName, backgroundImageData, backgroundImageWCS, cutLevels, size, colorMapName, contourImageData, contourImageWCS, contourSmoothFactor, contourLevels, contourColor, contourWidth)
Makes a bitmap image from an image array, with a set of contours generated from a second image array overlaid.
source code
 
saveFITS(outputFileName, imageData, imageWCS=None)
Writes an image array to a new .fits file.
source code
numpy array
histEq(inputArray, numBins)
Performs histogram equalisation of the input numpy array.
source code
numpy array
normalise(inputArray, clipMinMax)
Clips the inputArray in intensity and normalises the array such that minimum and maximum values are 0, 1.
source code
Variables [hide private]
  REPORT_ERRORS = True
Function Details [hide private]

clipImageSectionWCS(imageData, imageWCS, RADeg, decDeg, clipSizeDeg, returnWCS=True)

source code 

Clips a square or rectangular section from an image array at the given celestial coordinates. An updated WCS for the clipped section is optionally returned, as well as the x, y pixel coordinates in the original image corresponding to the clipped section.

Note that the clip size is specified in degrees on the sky. For projections that have varying real pixel scale across the map (e.g. CEA), use clipUsingRADecCoords instead.

Parameters:
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS) - astWCS.WCS object
  • RADeg (float) - coordinate in decimal degrees
  • decDeg (float) - coordinate in decimal degrees
  • clipSizeDeg (float or list in format [widthDeg, heightDeg]) - if float, size of square clipped section in decimal degrees; if list, size of clipped section in degrees in x, y axes of image respectively
  • returnWCS (bool) - if True, return an updated WCS for the clipped section
Returns: dictionary
clipped image section (numpy array), updated astWCS WCS object for clipped image section, and coordinates of clipped section in imageData in format {'data', 'wcs', 'clippedSection'}.

clipImageSectionPix(imageData, XCoord, YCoord, clipSizePix)

source code 

Clips a square or rectangular section from an image array at the given pixel coordinates.

Parameters:
  • imageData (numpy array) - image data array
  • XCoord (float) - coordinate in pixels
  • YCoord (float) - coordinate in pixels
  • clipSizePix (float or list in format [widthPix, heightPix]) - if float, size of square clipped section in pixels; if list, size of clipped section in pixels in x, y axes of output image respectively
Returns: numpy array
clipped image section

clipRotatedImageSectionWCS(imageData, imageWCS, RADeg, decDeg, clipSizeDeg, returnWCS=True)

source code 

Clips a square or rectangular section from an image array at the given celestial coordinates. The resulting clip is rotated and/or flipped such that North is at the top, and East appears at the left. An updated WCS for the clipped section is also returned. Note that the alignment of the rotated WCS is currently not perfect - however, it is probably good enough in most cases for use with ImagePlot for plotting purposes.

Note that the clip size is specified in degrees on the sky. For projections that have varying real pixel scale across the map (e.g. CEA), use clipUsingRADecCoords instead.

Parameters:
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS) - astWCS.WCS object
  • RADeg (float) - coordinate in decimal degrees
  • decDeg (float) - coordinate in decimal degrees
  • clipSizeDeg (float) - if float, size of square clipped section in decimal degrees; if list, size of clipped section in degrees in RA, dec. axes of output rotated image respectively
  • returnWCS (bool) - if True, return an updated WCS for the clipped section
Returns: dictionary
clipped image section (numpy array), updated astWCS WCS object for clipped image section, in format {'data', 'wcs'}.

Note: Returns 'None' if the requested position is not found within the image. If the image WCS does not have keywords of the form CD1_1 etc., the output WCS will not be rotated.

clipUsingRADecCoords(imageData, imageWCS, RAMin, RAMax, decMin, decMax, returnWCS=True)

source code 

Clips a section from an image array at the pixel coordinates corresponding to the given celestial coordinates.

Parameters:
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS) - astWCS.WCS object
  • RAMin (float) - minimum RA coordinate in decimal degrees
  • RAMax (float) - maximum RA coordinate in decimal degrees
  • decMin (float) - minimum dec coordinate in decimal degrees
  • decMax (float) - maximum dec coordinate in decimal degrees
  • returnWCS (bool) - if True, return an updated WCS for the clipped section
Returns: dictionary
clipped image section (numpy array), updated astWCS WCS object for clipped image section, and corresponding pixel coordinates in imageData in format {'data', 'wcs', 'clippedSection'}.

Note: Returns 'None' if the requested position is not found within the image.

scaleImage(imageData, imageWCS, scaleFactor)

source code 

Scales image array and WCS by the given scale factor.

Parameters:
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS) - astWCS.WCS object
  • scaleFactor (float or list or tuple) - factor to resize image by - if tuple or list, in format [x scale factor, y scale factor]
Returns: dictionary
image data (numpy array), updated astWCS WCS object for image, in format {'data', 'wcs'}.

intensityCutImage(imageData, cutLevels)

source code 

Creates a matplotlib.pylab plot of an image array with the specified cuts in intensity applied. This routine is used by saveBitmap and saveContourOverlayBitmap, which both produce output as .png, .jpg, etc. images.

Parameters:
  • imageData (numpy array) - image data array
  • cutLevels (list) - sets the image scaling - available options:
    • pixel values: cutLevels=[low value, high value].
    • histogram equalisation: cutLevels=["histEq", number of bins ( e.g. 1024)]
    • relative: cutLevels=["relative", cut per cent level (e.g. 99.5)]
    • smart: cutLevels=["smart", cut per cent level (e.g. 99.5)]

    ["smart", 99.5] seems to provide good scaling over a range of different images.

Returns: dictionary
image section (numpy.array), matplotlib image normalisation (matplotlib.colors.Normalize), in the format {'image', 'norm'}.

Note: If cutLevels[0] == "histEq", then only {'image'} is returned.

resampleToTanProjection(imageData, imageWCS, outputPixDimensions=[600,600])

source code 

Resamples an image and WCS to a tangent plane projection. Purely for plotting purposes (e.g., ensuring RA, dec. coordinate axes perpendicular).

Parameters:
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS) - astWCS.WCS object
  • outputPixDimensions (list) - [width, height] of output image in pixels
Returns: dictionary
image data (numpy array), updated astWCS WCS object for image, in format {'data', 'wcs'}.

resampleToWCS(im1Data, im1WCS, im2Data, im2WCS, highAccuracy=False, onlyOverlapping=True)

source code 

Resamples data corresponding to second image (with data im2Data, WCS im2WCS) onto the WCS of the first image (im1Data, im1WCS). The output, resampled image is of the pixel same dimensions of the first image. This routine is for assisting in plotting - performing photometry on the output is not recommended.

Set highAccuracy == True to sample every corresponding pixel in each image; otherwise only every nth pixel (where n is the ratio of the image scales) will be sampled, with values in between being set using a linear interpolation (much faster).

Set onlyOverlapping == True to speed up resampling by only resampling the overlapping area defined by both image WCSs.

Parameters:
  • im1Data (numpy array) - image data array for first image
  • im1WCS (astWCS.WCS) - astWCS.WCS object corresponding to im1Data
  • im2Data (numpy array) - image data array for second image (to be resampled to match first image)
  • im2WCS (astWCS.WCS) - astWCS.WCS object corresponding to im2Data
  • highAccuracy (bool) - if True, sample every corresponding pixel in each image; otherwise, sample every nth pixel, where n = the ratio of the image scales.
  • onlyOverlapping (bool) - if True, only consider the overlapping area defined by both image WCSs (speeds things up)
Returns: dictionary
numpy image data array and associated WCS in format {'data', 'wcs'}

generateContourOverlay(backgroundImageData, backgroundImageWCS, contourImageData, contourImageWCS, contourLevels, contourSmoothFactor=0, highAccuracy=False)

source code 

Rescales an image array to be used as a contour overlay to have the same dimensions as the background image, and generates a set of contour levels. The image array from which the contours are to be generated will be resampled to the same dimensions as the background image data, and can be optionally smoothed using a Gaussian filter. The sigma of the Gaussian filter (contourSmoothFactor) is specified in arcsec.

Parameters:
  • backgroundImageData (numpy array) - background image data array
  • backgroundImageWCS (astWCS.WCS) - astWCS.WCS object of the background image data array
  • contourImageData (numpy array) - image data array from which contours are to be generated
  • contourImageWCS (astWCS.WCS) - astWCS.WCS object corresponding to contourImageData
  • contourLevels (list) - sets the contour levels - available options:
    • values: contourLevels=[list of values specifying each level]
    • linear spacing: contourLevels=['linear', min level value, max level value, number of levels] - can use "min", "max" to automatically set min, max levels from image data
    • log spacing: contourLevels=['log', min level value, max level value, number of levels] - can use "min", "max" to automatically set min, max levels from image data
  • contourSmoothFactor (float) - standard deviation (in arcsec) of Gaussian filter for pre-smoothing of contour image data (set to 0 for no smoothing)
  • highAccuracy (bool) - if True, sample every corresponding pixel in each image; otherwise, sample every nth pixel, where n = the ratio of the image scales.

saveBitmap(outputFileName, imageData, cutLevels, size, colorMapName)

source code 

Makes a bitmap image from an image array; the image format is specified by the filename extension. (e.g. ".jpg" =JPEG, ".png"=PNG).

Parameters:
  • outputFileName (string) - filename of output bitmap image
  • imageData (numpy array) - image data array
  • cutLevels (list) - sets the image scaling - available options:
    • pixel values: cutLevels=[low value, high value].
    • histogram equalisation: cutLevels=["histEq", number of bins ( e.g. 1024)]
    • relative: cutLevels=["relative", cut per cent level (e.g. 99.5)]
    • smart: cutLevels=["smart", cut per cent level (e.g. 99.5)]

    ["smart", 99.5] seems to provide good scaling over a range of different images.

  • size (int) - size of output image in pixels
  • colorMapName (string) - name of a standard matplotlib colormap, e.g. "hot", "cool", "gray" etc. (do "help(pylab.colormaps)" in the Python interpreter to see available options)

saveContourOverlayBitmap(outputFileName, backgroundImageData, backgroundImageWCS, cutLevels, size, colorMapName, contourImageData, contourImageWCS, contourSmoothFactor, contourLevels, contourColor, contourWidth)

source code 

Makes a bitmap image from an image array, with a set of contours generated from a second image array overlaid. The image format is specified by the file extension (e.g. ".jpg"=JPEG, ".png"=PNG). The image array from which the contours are to be generated can optionally be pre-smoothed using a Gaussian filter.

Parameters:
  • outputFileName (string) - filename of output bitmap image
  • backgroundImageData (numpy array) - background image data array
  • backgroundImageWCS (astWCS.WCS) - astWCS.WCS object of the background image data array
  • cutLevels (list) - sets the image scaling - available options:
    • pixel values: cutLevels=[low value, high value].
    • histogram equalisation: cutLevels=["histEq", number of bins ( e.g. 1024)]
    • relative: cutLevels=["relative", cut per cent level (e.g. 99.5)]
    • smart: cutLevels=["smart", cut per cent level (e.g. 99.5)]

    ["smart", 99.5] seems to provide good scaling over a range of different images.

  • size (int) - size of output image in pixels
  • colorMapName (string) - name of a standard matplotlib colormap, e.g. "hot", "cool", "gray" etc. (do "help(pylab.colormaps)" in the Python interpreter to see available options)
  • contourImageData (numpy array) - image data array from which contours are to be generated
  • contourImageWCS (astWCS.WCS) - astWCS.WCS object corresponding to contourImageData
  • contourSmoothFactor (float) - standard deviation (in pixels) of Gaussian filter for pre-smoothing of contour image data (set to 0 for no smoothing)
  • contourLevels (list) - sets the contour levels - available options:
    • values: contourLevels=[list of values specifying each level]
    • linear spacing: contourLevels=['linear', min level value, max level value, number of levels] - can use "min", "max" to automatically set min, max levels from image data
    • log spacing: contourLevels=['log', min level value, max level value, number of levels] - can use "min", "max" to automatically set min, max levels from image data
  • contourColor (string) - color of the overlaid contours, specified by the name of a standard matplotlib color, e.g., "black", "white", "cyan" etc. (do "help(pylab.colors)" in the Python interpreter to see available options)
  • contourWidth (int) - width of the overlaid contours

saveFITS(outputFileName, imageData, imageWCS=None)

source code 

Writes an image array to a new .fits file.

Parameters:
  • outputFileName (string) - filename of output FITS image
  • imageData (numpy array) - image data array
  • imageWCS (astWCS.WCS object) - image WCS object

Note: If imageWCS=None, the FITS image will be written with a rudimentary header containing no meta data.

histEq(inputArray, numBins)

source code 

Performs histogram equalisation of the input numpy array.

Parameters:
  • inputArray (numpy array) - image data array
  • numBins (int) - number of bins in which to perform the operation (e.g. 1024)
Returns: numpy array
image data array

normalise(inputArray, clipMinMax)

source code 

Clips the inputArray in intensity and normalises the array such that minimum and maximum values are 0, 1. Clip in intensity is specified by clipMinMax, a list in the format [clipMin, clipMax]

Used for normalising image arrays so that they can be turned into RGB arrays that matplotlib can plot (see astPlots.ImagePlot).

Parameters:
  • inputArray (numpy array) - image data array
  • clipMinMax (list) - [minimum value of clipped array, maximum value of clipped array]
Returns: numpy array
normalised array with minimum value 0, maximum value 1