AstroImage - EranOfek/AstroPack GitHub Wiki

Description

Class Hierarchy: Base -> Component -> AstroImage

AstroImage is a container for images and images metadata, as well as basic functionality for image manipulation. In addition to the image itself, the AstroImage object may contain a background image, a variance image, a mask image, PSF, WCS, Header, and associated catalog. Among the basic functionality, are image arithmetics, cropping, header manipulation, and more. High level functionality (e.g., photometry, astrometry, coaddition, subtraction) for AstroImage is available in the imProc package. For additional help see manuals.main

Properties

  • Table - Get catalog data in table format. Can not use this to set catalog data.
  • ImageData - A SciImage object containing the science image. Most image-related methods will operate on this property by default.
  • BackData - A BackImage object containing the background image, or a background scalar.
  • VarData - A VarImage object containing the variance image, or a variance scalar.
  • MaskData - A MaskImage object containing the mask Image. Each pixel in the mask image corresponds to a pixel in the image. Each pixel is an integer, in which each bit is a flag for the existence of a problem or property (e.g., this pixel is saturated).
  • HeaderData - An AstroHeader object of the image headers.
  • CatData - An AstroCatalog object containing the catalog data.
  • PSFData - A PSFData object containing the PSF data.
  • WCS - An AstroWCS object containing the WCS data.
  • PropagateErr - A logical indicating if error propgation is activated when using operators.

Dependent Properties

These dependent properties allow accessing the image data directly, without going through the main subclasses.

  • Image - Get the image from ImageData.Image
  • Back - BackData.Data
  • Var - VarData.Data
  • Mask - MaskData.Data
  • Header - HeaderData.Data - The header in a 3-column cell format.
  • Key - HeaderData.Key - The header in a structure format.
  • Cat - CatData.Data

Additional & Hidden Properties

  • Relations - sets the relation between the dependent property and the data property.

Constructor

The AstroImage constructor is used to generate new objects from input images or from a list of files. Some examples:

% create a single object and supply the science image
AI = AstroImage({ones(10,10)})
% create a 2 by 2 array of empty images
AI = AstroImage([2 2]);
% set the HDU number and provide the background images
AI = AstroImage(FileNames,'HDU',1,'Back',FileNamesBack,'BackHDU',1);
% Provide the variance image and scale
AI = AstroImage({rand(10,10)},'var',{rand(5,5)},'VarScale',2);

Setters and getters

Most of the AstroImage settes and getters are straigtforwards. Some special functionality includes:

  • The WCS getter (e.g., AI.WCS) will first check if the WCS object is empty, and if this is the case then it will use AstroWCS.header2wcs function, to populate the WCS from the image header.

Static methods

  • imageIO2AstroImage - Convert an ImageIO object into an AstroImage object.
  • readImages2AstroImage - Create AstroImage object and read images into a specific property.
  • unitTest - unitTest for AstroImage.

Methods

Read / write methods

  • write1 - Write a single data property in a single element AstroImage to file General methods
  • isemptyImage - Check if data images in AstroImage object are empty.
  • sizeImage - Return the size of images in AstroImage object.
  • getImageVal - Get AstroImage image value at specific positions.

Examples

AI = AstroImage;
isemptyImage(AI)  % will return 1 because the image is empty
AI = AstroImage({rand(100,100), rand(200,200)});
isemptyImage(AI)  % will return [0 0] because the image is non empty

[Ny, Nx] = sizeImage(AI);   % return vectors of the Y/X size of the images

[ValIm, ValBack] = getImageVal(AI(1),[10,20],[10,20]); % get Image and Back value at some X, Y positions

Header Related Methods

  • isImType - Check if header IMTYPE keyword value equal some type.
  • julday - Return the Julian day for AstroImage object. If the julian day is not available, then it will be calculated from some of the dates keywords.
  • getStructKey - Get multiple keys from headers in multiple AstroImage and store in a structure array.
  • funHeader - Apply function of HeaderData properties in AstroImage array.
  • funHeaderScalar - Apply function that return a scalar on HeaderData properties in AstroImage array.
  • setKeyVal - Replace/insert keyword/value to HeaderData in AstroImage.

Examples

AI = AstroImage({rand(10,10), rand(10,10)});
funHeader(AI,@insertKey,{'GAIN',2,''});
AI.julday   % get the JD
AI.getStructKey({'EXPTIME','NAXIS1'})  % generate a structure array of requested keywords for all images
AI.isImType('bias');   % check if IMTYPE keyword (or synonym) is 'bias'.
% set the value of some keywords in the header
AI.setKeyVal('TYPE','science');

Mask Related methods

  • maskSet - Set the value of a bit in a bit mask (Maskdata) in AstroImage.

Additional functionality related Mask images is available in the imProc.mask subpackage. This include functions like maskCR, maskHoles, maskSaturated, maskSourceNoise, replaceMaskedPixVal, etc.

Examples

% set the "Saturated" bit in the mask image of an AstroImage
% Here Flag is a matrix of logicals indicating saturated pixels.
AI.maskSet(Flag,'Saturated')

Convert data types

  • astroImage2ImageComponent - Convert an AstroImage data into SciImage, BackImage, etc. objects.
  • astroImage2AstroCatalog - Convert the CataData in AstroImage object into an AstroCatalog object array.
  • cast - Cast the image/back/var data in AstroImage (transform to a new type).
  • object2array - Convert an AstroImage object that contains scalars into an array.

Examples

AI.cast('single'); % covert the Image, Back, Var to single type

Operate functions on AstroImage sub-classes

These methods activate functions that belong to the AstroImage properties.

  • subtractBackground - Subtract the background from an image and set the IsBackSubtracted to true.
  • funCat - Apply function of Cat properties in AstroImage array.
  • funWCS - Apply function of WCS properties in AstroImage array.
  • funPSF - Apply function of PSF properties in AstroImage array.
  • propagateWCS - Given An AstroImage with WCS property, propagate it to the header and catalog Operators
  • funUnary - Apply an unary function on AstroImage object.
  • funUnaryScalar - Apply a unary operator that return scalar on AstroImage and return an numeric array
  • funBinary - Apply a binary operator to AstroImage
  • funBinaryProp - Apply binary function on a single property of AstroImage
  • funBinaryImVar - Apply a binary operator with error propagation to the ImageData and VarData.
  • crop - crop an AstroImage images and catalogs and update WCS
  • plus - Apply the plus operator between AstroImage objects.
  • minus - Apply the minus operator between AstroImage objects.
  • times - Apply the times operator between AstroImage objects.
  • rdivide - Apply the rdivide operator between AstroImage objects.
  • conv - Convolve images with their PSF, or another PSF
  • filter - Filter images with their PSF, or another PSF

Examples

% add images
AI = AstroImage({ones(3,3)});
AI2 = AstroImage({ones(3,3)});
AI = funBinary(AI,3,@plus); % eq. to AI = AI+3;
Result = funBinary(AI,AI2,@plus); % eq. to Result = AI+AI2;
% subtract only the back image
AI = AstroImage({ones(3,3)},'Back',{2*ones(3,3)});
AI2 = AstroImage({ones(3,3)},'Back',{ones(3,3)});
Result = funBinaryProp(AI,AI2,@minus,'DataProp','BackData');

% using overload operators
AI + 1   % will add one to all images
AI + AI2  % will add the images.
AI.*3     % will multiply all image pixels by 3
AI./2     % dividing all images by 2
[AI, AI] - AI2 % subytact the image in AI2 from the two images in the left operand

% crop an image by CCDSEC
AI.crop([101 200 101 300]);

% convolving an image with a gaussian with 2-pixels sigma
AI.conv(imUtil.kernel2.gauss(2));

Operations using imProc & pipeline

The imProc package contains more advanced functionality for analyzing and manipulating AstroImage and AstroCatalog objects. This includes functions to estimate background, find and measure sources, astrometry, transformations, coadditon, image subtraction and more. This is further discussed in the imProc documentation. The pipeline package contains high-level functionality for common processing problems, like calibrating images, finding sources, astrometry, and coaddition.