AstroWCS - EranOfek/AstroPack GitHub Wiki

Description

Class Hierarchy: Base -> Component -> AstroWCS

AstroWCS is a container for astronomical World Coordinate System (WCS) data. The class also provides basic functionality with WCS data such as pixel coordinates to/from sky coordinates conversion.

See the follwoing papers for general definitions:

  • Greisen & Calabretta 2002, \aap, 395, 1061. doi:10.1051/0004-6361:20021326
  • Calabretta & Greisen 2002, \aap, 395, 1077. doi:10.1051/0004-6361:20021327

AstroWCS currently suports only the following projection types: TAN, TAN-SIP, TPV.

Also, it currently does not support WCSAXES>2.

Properties

  • NAXIS -- Number of axes
  • WCSAXES -- WCS dimensionality
  • CTYPE -- a cell array of WCS projection type, e.g., 'RA---TAN', 'RA-TAN-SIP', 'RA---TPV'
  • CUNIT -- a cell array of Axis units, e.g., 'deg'
  • RADESYS -- Astrometric system, e.g., 'ICRS'
  • LONPOLE -- Native Longitude of the Celestial Pole
  • LATPOLE -- Native Latitude of the Celestial Pole
  • EQUINOX
  • CRPIX -- Reference pixel
  • CRVAL -- World coordinates of the reference pixel
  • CD -- Linear projection matrix
  • PV -- Struct of projection distortion
  • RevPV -- Struct of reverse projection distortion
  • ProjType -- Projection type, e.g., 'TAN', 'TAN-SIP', 'TPV'
  • ProjClass -- Projection class, e.g., 'Zenithal'
  • CooName -- a cell array of Corrdinate names, e.g., 'RA', 'Dec'

For the following paramters, see definitions in Calabretta & Greisen 2002, \aap, 395, 1077. doi:10.1051/0004-6361:20021327:

  • AlphaP -- Celestial longitude of the native pole
  • DeltaP -- Celestial latitude of the native pole
  • PhiP -- Native Longitude of the Celestial Pole
  • Alpha0 -- Celestial longitude of the fiducial point
  • Delta0 -- Celestial latitude of the fiducial point
  • Phi0 -- Native longitude of the fiducial point
  • Theta0 -- Native latitude of the fiducial point
  • Tran2D -- Objcet of an astrometric transformation class

Parameters for quality of solution:

  • Success -- boolean, is astrometry solution reasnoable?
  • ErrorOnMean -- assymptotic-rms/sqrt(Ngood)
  • AssymRMS -- assymptotic-rms
  • AssymRMS -- number of good matches used for the solution
  • Additonal parameters: Resid, RefMag, RefColor, SrcX, SrcY, ResFit (structure with additional information. % setter will attempt to populate the other properties)

Why is this here? In principle this can be located in Tran2D. However, Tran2D describes only part of the full transformaion.

Methods

Main functions:

  • AstroWCS -- Basic constructor for AstroWCS class. User should usually use AstroWCS.header2wcs or AstroWCS.tran2wcs
  • header2wcs -- Create and populate an AstroWCS object from an AstroHeader object
  • tran2wcs -- Create and populate an AstroWCS object from a Tran2D object
  • xrayHeader2wcs -- Read X-Ray telescope/mission header into WCS object
  • wcs2header -- Convert AstroWCS object to new AstroHeader object or update an existing AstroHeader object
  • wcs2keyCell -- Create a cell array of WCS fields from AstroWCS object
  • cropWCS -- Update AstroWCS for a cropped region
  • sky2xy -- Convert celestial coordinates to pixel coordinates
  • xy2sky -- Convert pixel coordinates to celestial coordinates
  • xy2refxy -- Given X, Y coordinates in an image, convert to X,Y in reference coordinate system, by using WCS info of both images to tranlstae XY to refXY.
  • xy2refxyDisp -- Calculate the displacement field D between current image to refernce image, by using WCS info of both images to tranlstae XY to refXY.
  • getScale -- Get pixel scale from CD matrix
  • addCornersCoo2header -- Add RA/Dec of image corners to header
  • isSkyCooInImage -- Check if RA/Dec are within image footprint (CCDSEC)
  • cooImage -- Return the image center and corners coordinates
  • plotRMS -- plot RMS vs. magnitude plot for astrometric solution

Low-level functions:

General:

  • populate_projMeta -- Populate projection metadata (Alpha0,Delta0,AlphaP,DeltaP,Phi0,Theta0,PhiP)
  • populateSucess -- Populate the sucess flag in the AstroWCS object The success flag indicate if the WCS solution and residuals are reasnoble.
  • set.ResFit -- setter for ResFit - will automatically populate related properties
  • polyTPVdef -- Return a table of TPV polynomial definition
  • polyTPVstruct -- Return a struct of TPV polynomial definition
  • copyElement - Custom copy of object properties Called from copy() of matlab.mixin.Copyable decendents

Functions helping to construct AstroWCS from AstroHeader:

  • read_ctype -- Read Obj.CTYPE to populate the fields: ProjType, ProjClass, CooName, and CUNIT (if empty or nan)
  • read_radesys_equinox -- Read from AstroHeader the RADESYS and EQUINOX. If any are missing fill with deafults.
  • build_CD -- Construct the CD matrix from AstroHeader. Either directly CD matrix, or PC+CDELT, or CDELT
  • build_PV_from_Header -- Construct a PV (distoration) structure from AstroHeader.
  • build_TPV_from_Header -- Construct a PV (distoration) structure from AstroHeader with TPV projection.
  • build_TANSIP_from_Header - Construct a PV or RevPV structure from AstroHeader with TAN-SIP projection.

Functions helping to construct AstroWCS from Tran2D:

  • build_PV_from_Tran2D - Construct a PV (distoration) structure from Tran2D object.
  • fill_TPV_KeyNames - Fill TPV keynames in a PV (distoration) structure.
  • fill_TANSIP_KeyNames - Fill TANSIP keynames in a PV (or RevPV) structure.

Functions related to xy2sky:

  • pix2interm -- Convert pixel coordinates (P) to intermediate coordinates (X), if requested also include distortion
  • interm2native -- Project intermediate coordinates to native coordinates
  • native2celestial -- Convert native coordinates to celestial coordinates
  • phitheta2alphadelta - Convert naitive coordinates (Phi,Theta) to celestial coordinates (alpha,delta)
  • forwardDistortion - Apply distortion to X,Y coordinates using the PV sturcture

Functions related to sky2xy:

  • celestial2native -- Convert celestial coordinates to native coordinates
  • native2interm -- Project native coordinates to intermediate coordinates
  • interm2pix -- Convert intermediate pixel coordinates to pixel coordinates, if requested also include distortion
  • alphadelta2phitheta - Convert celestial coordinates to native coordinates
  • backwardDistortion - Apply reverse (i.e. backward) distortion to X,Y coordinates using the PV sturcture

Examples

% construct an empty AstroWCS
AW = AstroWCS([2 2]);

% construct a AstroWCS from AstroHeader with full TAN projection
Im_name = 'FOCx38i0101t_c0f.fits';
AH = AstroHeader(Im_name);
AW = AstroWCS.header2wcs(AH);

% convert xy to sky and back
PX = rand(1,100) * AH.Key.NAXIS1;
PY = rand(1,100) * AH.Key.NAXIS2; 
[Alpha, Delta]  = AW.xy2sky(PX,PY);
[PX1,PY1]  = AW.sky2xy(Alpha,Delta);

% cropWCS
AW = AstroWCS.header2wcs(AH);
[Alpha, Delta]  = AW.xy2sky(PX,PY);
AW = AW.cropWCS([1,AH.Key.NAXIS1,1,AH.Key.NAXIS2],'centerCRPIX',true);
[Alpha2, Delta2]  = AW.xy2sky(PX,PY);

% construct a AstroWCS from Header with TPV projection
Im_name = 'WD0548-001_2457842_215821_Clear_meter.fits';
AH = AstroHeader(Im_name);
AW = AstroWCS.header2wcs(AH);

% Construct AstroWCS from Tran2D
TC=Tran2D; 
TC.symPoly; TC.ParX = ones(1,13);TC.ParY = ones(1,13);
TC.polyCoef; TC.polyRep;
NAXIS = 2; CRPIX(1,:) = [1.0 1.0]; CRVAL(1,:) = [0.0 0.0];
CD = eye(2); CTYPE(1,:) = {'RA---TPV' 'DEC--TPV'}; CUNIT(1,:) = {'deg' 'deg'};
AW = AstroWCS.tran2wcs(TC,'NAXIS',NAXIS,'CRPIX',CRPIX,'CRVAL',CRVAL,'CD',CD,'CTYPE',CTYPE,'CUNIT',CUNIT);

% Construct/update AstroHeader from AstroWCS
AH1 = AW.wcs2header;           
AH = AW.wcs2header(AH);

More examples can be found in AstroWCS.unitTest (https://github.com/EranOfek/AstroPack/blob/dev1/matlab/image/%40AstroWCS/unitTest.m).