ccd – image processing tools

The ccd module contains classes and functions for processing CCD images or similar.

Detailed analysis tools are in phot and spec – this module is mainly for low-level operations like direct viewing of images, calibrations, and similar.

Classes and Inheritance Structure

Module API

class astropysics.ccd.ASinhScaling(ccdimobj=None, **kwargs)

Bases: astropysics.ccd.DataScaling

invtransform(invarray)

name = 'asinh'

transform(imagearray)

class astropysics.ccd.ArrayImage(arr, range=None, scaling=None, ival=None)

Bases: astropysics.ccd.CCDImage

arr can be an array or a 2-tuple (nx,ny).

ival sets the initial value - if it is None, the array is not initialized. Otherwise, the array is set to the ival value.

range and scaling set those properties (see CCDImage)

static load(fn)

save(fn)

class astropysics.ccd.CCDImage(range=None, scaling=None)

Bases: object

The base class for CCD images. Subclasses should follow the guidelines below to support various formats/file types.

MUST implement:

• _extractArray(self,range) – should return the 2d (x,y) array corresponding to the range (xlower,xupper,ylower,yupper) or None for entire image. Raise IndexError if the range is not valid
• _applyArray(self,range,data) – should take the provided range and apply the data to whatever the base store is for that range. Raise IndexError if the range is not valid, or AttributeError if the data should be read-only.

Note that these two methods in principle operate independent of the CCDImage internal representation, so if desired, _applyArray can just update the same backing store that _extractArray uses

The following image properties are defined, defaulting to None. They may be set or overridden as appropriate

• zeropoint
• pixelscale
• band

Note that the coordinate system in python is 0-based - the first pixel is (0,0), NOT (1,1)

activateRange(range)

chooses the range to activate for further operations

can either be None (whole file), a 4-tuple of the form (xl,xu,yl,yu) or a 3-tuple of the form (xcen,ycen,radius)

Note that the 3-tuple form will be range-checked and auto-shrunk if the radius is too big, but the 4-tuple will not

applyChanges()

clipInvalids(action='mask')

clip points that are non-finite (i.e. NaN or infinite)

action is a replacement action (see clipSigma)

clipOutliers(limits=(1, 99), percentage=True, action='noclipmedian')

clip points lying outside the range specified in the 2-sequence limits

if percentage is outside True, the limits are percentages, otherwise fractions

action is a replacement action (see clipSigma)

clipSigma(sigma=12, fullsig=True, action='noclipmedian')

if fullsig is true, the whole image is used for computing the standard deviation instead of just the active region

action can be a value to set the outliers to, ‘mean’,’median’, ‘noclipmean’,’noclipmedian’, ‘fullmean’, or ‘fullmedian’, or ‘mask’

returns number of pixels replaced

clipThreshold(thresh=0, action='mask', comp='<')

clip data points that are above/below a threshold

thresh is the threshold

comp can be ‘<’, ‘>’,’<=’, or ‘>=’ for clipping points that are less that, greater than, less than or equal to, or greater than or equal to the threshold.

action is a replacement action (see clipSigma)

data

direct access to the array holding the current data. If this data is subsequently edited, applyChanges() should be called to ensure consistancy orientation is such that array should be indexed as data[x,y]

getStats()

return mean,median,stddev,min, and max for the scaled active region

offsetData(offset='minp1')

apply a global offset to all the current data

offset can either by a value or ‘gmin’ to offset the data by the global minimum or ‘gminp1’ to offset the lowest value to 1, or ‘min’ or ‘minp1’ to use the selected area minimum

pixelscale

Pixel scale of the image in

plotHist(perc=None, gauss=None, clf=True, **kwargs)

kwargs go into hist reset defaults: ‘log’->True,’bins’->100 or 25,’histtype’->’step’

plotImage(valrange='p99', flipaxis=None, invert=False, cb=True, scalebar=None, axes='image', clickinspect=True, clf=True, colormap='gray', **kwargs)

This plots the associated active range of the image using matplotlib

valrange can be:

• a 2-tuple with (lower,upper) range to display
• ‘s#’/’sigma#’/’sig#’ to use the specified S.D.s from the median
• ‘n#’ to ignore the highest and lowest n values
• ‘p##.#’ to use the central ## percent of the values for ranging
• (p or n can be ##,## to give lower,upper bounds)
• (if ‘g’ appears in any of the above codes, the global value is used)
• ‘i#,#,#,#’ to ignore the specified values in the calculation of the range

scalebar can be False/None to show no scale bar, a 2-tuple (color,unitstring) , or True (red with ” scale)

axes can be ‘image’ or ‘sky’

if clickinspect is True, will return the cid of the matplotlib event

colormap is the name of a colormap (or None to not change the map)

kwargs are passed into matplotlib imshow

range

returns or sets the range (setting is same as calling activateRange)

scaling

setScaling(scalefunc=None, **kwargs)

Sets the scaling to apply for this image - either a string for the name of a builtin scale function or a DataScaling object, in which case kwargs will be applied to the initializer

if None, LinearScaling will be used

shape

tuple with dimensions of the currently selected image (the internal representation is flipped for FITS - this is the correct orientation)

size

number of pixels in the currently selected image

zeropoint

The photometric zero-point for this CCDImage, to be used in other processing tasks (see astropysics.phot)

class astropysics.ccd.CCDNoise(gain=1, readnoise=0, snoise=0, floor=None, ceiling=None)

Bases: astropysics.ccd.NoiseModel

Noise model for a CCD with a poissonian term for electrons/photons and a gaussian term for read noise (constant noise), sensitivity noise (e.g. noise proportional to the data), and uniform noise

gain is in e-/ADU

readnoise is in e-

snoise is the ‘sensitivity’ or ‘scale’ noise as a fraction of the adu signal

var(data)

class astropysics.ccd.DataScaling(ccdimobj=None, **kwargs)

Bases: object

The base class for objects that scale the data in a CCDImage. Subclasses should override:

• ‘name’

  an attribute with the name of the transform

• ‘transform’

  accepts a 2D array of the image data and outputs a 2D array of the same shape

• ‘invtransform’

  accepts a 2D array of altered data and outpts a 2D array of the same shape. Expected to match the property x = invtransform(transform(x)) . If it is set to None, it is assumed that an inverse transform is impossible

the __init__ method can be overridden, but will be called with the CCDImage object as the first argument

invtransform = None

name = None

transform(imagearray)

class astropysics.ccd.ExponentialScaling(ccdimobj=None, **kwargs)

Bases: astropysics.ccd.DataScaling

invtransform(invarray)

name = 'exp'

transform(imagearray)

class astropysics.ccd.FitsImage(fnordata, range=None, scaling=None, hdu=0, memmap=0)

Bases: astropysics.ccd.CCDImage

A CCDImage representation of a FITS file. Note that this class requires pyfits <http://www.stsci.edu/resources/software_hardware/pyfits> to work at all.

Parameters:

• fnordata –

  The filename or data to use to create this object. Can be:

  • A string

    Specifies a file name to a fits file that will be used as the image data source.

  • An array

    Will be used to create a single-HDU fits file with a default header.

  • A list of arrays

    Will be used to create a multi-HDU fits file with all default headers. Not that it must be a list and not any other type of sequence.

  • (hdr,array)

    Array is a numpy array, and hdr is a pyfits.Header object or a dictionary that will be used to populate the header entries. This will create a single HDU with the provided array and header.

  • (hdrs,arrays)

    Same as the previous form, but arrays and hdrs must be lists, not any other sequence type, and must be the same length. They will be used to create multiple HDUs.

• range – The initial value for the range attribute.
• scaling – The initial value for the scaling attribute.
• hdu (int) – The HDU to use initially as the current data for this CCDImage.
• memmap – If True/1, the loaded file will be memory-mapped to drive instead of being loaded into memory. Passed into pyfits.open() if fnordata is a filename, and otherwise ignored.

close()

Closes the file associated with this FitsImage. Many operations will fail after this occurs.

hdu

the hdu of the current fits file

save(fn, **kwargs)

Save this image to a new fits file. kwargs will be passed to pyfits.HDUList.writeto

Be default, this will overwrite a file of the same name - if this is not desired, set the clobber keyword to False.

class astropysics.ccd.GaussianNoise(sigma)

Bases: astropysics.ccd.NoiseModel

var(data)

class astropysics.ccd.HDF5Image

Bases: astropysics.ccd.CCDImage

A CCDImage with an HDF5 file as the backing store.

Warning

This class is a work in progress and may not work right now

class astropysics.ccd.ImageBiasSubtractor

Bases: astropysics.pipeline.PipelineElement

Subtracts a dark/bias frame or uses an overscan region to define a bias or bias curve to subtract. The order of operations is:

1. Subtract any frame specified in biasframe
2. Subtract the overall bias level determined by biasregion
3. Subtract the bias determined by the overscan region specified in overscan

Any of these operations may be ommitted if the necessary attribute are set to None.

• biasframe: an image matching the input’s shape that will be subtracted or None to skip this step.

• biasregion:

  A 4-tuple defining a region as (xmin,xmax,ymin,ymax) Or None to skip this step.

• overscan: an integer defining the edge of the overscan region, or a 2-tuple of the form (edge,bool) where the boolean indicates if the it is a left edge/starting at 0 (True, default) or a right edge (False)

• overscanaxis: sets the axis along which the overscan region is defined (typcally the readout axis): ‘x’/0 or ‘y’/1, assumed for the overscan

• overscanfit: sets the default fitting method for the overscan region (if used) or None to just use the combined value directly

• interactive: if True, interactively fit the overscan curve

• combinemethod:

  The method used to combine the pixels in the bias region or overscan region to produce the overall subtraction value. Can be:

  • ‘mean’
  • ‘median’
  • ‘max’
  • ‘min’
  • A callable that takes a sequence of matched images and returns an image of the size of the inputs.

• trim: trim off the overscan region if it is specified * save:if True, stores the final image and any fit curve as attributes lastimage or lastcurve on this object.

plInteract(data, pipeline, elemi)

plProcess(data, pipeline, elemi)

subtractFromImage(image)

Subtract the bias frame and/or do the bias/overscan region subtraction.

Parameters:image (2D ndarray) – An array with the image data. Returns:A 2D numpy array of the image data with the subtractions applied.

class astropysics.ccd.ImageCombiner

Bases: astropysics.pipeline.PipelineElement

Combines a sequence of images into a single image.

Attributes that control combining are:

• method

  Can be any of:

  • ‘mean’
  • ‘median’
  • ‘sum’
  • A callable that takes a sequence of matched images and returns an image of the size of the inputs.
  • A sequence of floats that will be used as weights - the images will be added together with those weights.

• shifts: a sequence of 2-tuples that are taken as the amount to offset each image before combining (in pixels)

• shiftorder: order of the spline interpolation used when images are shifted

• trim: if True, the image is trimmed based on the shifts to only include the pixels where the images overlap

• sigclip: the number of standard deviations from the mean before a point is rejected from the combination. If None, no sigma clipping is performed

• save: if True, the last set of operations will be stored for later use (see below)

these attributes will be set at each operation:

• lastimage: the last result of combineImages
• mask: the mask of altered/rejected pixels from the last result

combineImages(images)

Combines images into a single image.

Parameters:images – A sequence of 2D numpy arrays with the image data to be combined. Returns:A 2D numpy array of images produced by combining the inputs.

isSequenceType()

isSequenceType(a) – Return True if a has a sequence type, False otherwise.

plProcess(data, pipeline, elemi)

class astropysics.ccd.ImageFlattener

Bases: astropysics.pipeline.PipelineElement

This object flattens an image using a flat field image

the following attributes determine the flatfielding behavior: * flatfield: the field to use to generate the flatting response * combine: ‘mean’,’median’,’min’,’max’, or a callable * save: store ‘lastimage’ as the last image that was flatted

flattenImage(image)

plProcess(data, pipeline, elemi)

class astropysics.ccd.LinearScaling(ccdimobj=None, **kwargs)

Bases: astropysics.ccd.DataScaling

invtransform(invarray)

name = 'linear'

transform(imagearray)

class astropysics.ccd.LogScaling(ccdimobj, lower=0, upper=1, base=None)

Bases: astropysics.ccd.DataScaling

linearly maps the values to a valid range and applies logarithmic scaling to the result, such that the output ranges from lower to upper.

Alternatively, if the base is specified, the log is taken with respect to that base without ranging.

if upper is None, just offsets to the lower range if lower is None, logarithmic scaling is applied directly

TODO:work out better inverse rescaling - for now setting it to None

invtransform(invarray)

name = 'log'

transform(imagearray)

class astropysics.ccd.NoiseModel

Bases: object

Abstract base class for noise models. subclasses should implement the _dataPlusNoise method, and optionally, var (variance)

the floor and ceiling attributes (if not None) set the lowest/highest values - any time noise results in a value smaller/larger than the value, it is set to this value

SNR(data)

ceiling = None

floor = None

noise(data)

computes the noise for the given input data.

nvar = 100

std(data)

var(data)

returns the variance of this noise model for each point in the input data

the nvar attribute is used to determine the number of calculations to use to estimate the variance.

class astropysics.ccd.PoissonNoise

Bases: astropysics.ccd.NoiseModel

var(data)

class astropysics.ccd.PowerScaling(ccdimobj, power=2)

Bases: astropysics.ccd.DataScaling

invtransform(invarray)

name = 'power'

transform(imagearray)

class astropysics.ccd.SurfaceBrightnessScaling(ccdimgobj)

Bases: astropysics.ccd.DataScaling

invtransform(invarray)

name = 'sb'

transform(imagearray)

class astropysics.ccd.UniformNoise(lower, upper, frac=False)

Bases: astropysics.ccd.NoiseModel

var(data)

astropysics.ccd.kcorrect_images(images, bands, z, range=None, zeropoints=None, pixelareas=None, retdict=False, offset=None, **kckwargs)

This function performs kcorrections pixel-by-pixel on a matched set of images. Note that one must be carefule to ensure the images are matched (e.g. they must be degraded to the largest PSF image), something that this function does nothing about. See astropysics.phot.kcorrect for more details on the k-correction algorithm

images are a sequence of CCDImage objects, or a list of filenames that will be loaded as images (using the 0th hdu if FITS).

bands should be the photometric bands of each of the images as accepted by kcorrect

z is the redshift to correct this image to

range is the range from each of the images to select

zeropoints and pixelareas (sq asec) will be deduced from the CCDImage properties zeropoint and pixelscale if they are not provided (if they are, they will everwrite the existing properties)

offset is the type of offset to be used (passed into offsetData)

extra kwargs will be passed into astropysics.phot.kcorrect

returns absmag,kcorrection,chi2 as arrays shaped like the input range (for absmag and kcorrection, the first dimension is the bans)

if True, retdict means the absmag and kcorrection will be returned as dictionaries of arrays with the band names as the keys

astropysics.ccd.load_image_file(fn, **kwargs)

Factory function for generating CCDImage objects from a file with filename fn - the exact class type will be inferred from the extension. kwargs will be passed into the appropriate constructor.

Currently only supports FITS files.

astropysics.ccd.mosaic_objects(xcens, ycens, radii, images, row=None, titles=None, noticks=True, clf=True, logify=False, imdict=None, **kwargs)

generate mosaics of objects from different images xcens,ycens,and radii are the x,y of the center and the radius to plot images are the image filenames row determines which row of the mosaic the object is placed in. If None, an optimal square/rectangular mosaic will be used titles is a sequence of strings to title each object if noticks is True, x and y ticks are not drawn clf determines if the figure is cleared before the mosaic is generated imdict is a dictionary with values that are CCDImage objects. Any image filenames will be placed into the provided dictionary keys with values generated by calling load_image_file() on the filenames

astropysics.ccd.o

alias of ExponentialScaling