PyAST - A Python Interface to the starlink AST library

D.S. Berry & T. Jenness
3rd February 2020
Version 3.14.1

Contents

• Introduction
  • What is PyAST?
  • What is AST?
  • About this document
  • Requirements
  • Obtaining and installing PyAST
  • Using PyAST
  • PyAST License
• Notes on individual classes
  • Channel
  • FitsChan
  • Frame
  • KeyMap
  • Plot
• Visualising and exploring FrameSets with astviewer
• Examples
  • Read a WCS Calibration from a Dataset
  • Validate WCS Information
  • Display AST Data
  • Convert Between Pixel and World Coordinates
  • Test if a WCS is a Celestial Coordinate System
  • Ensure that WCS Axes are in a Specified Order
  • Format Coordinates for Display
  • Display Coordinates as they are Transformed
  • Read Coordinates Entered by a User
  • Modify a WCS Calibration
  • Write a Modified WCS Calibration to a Dataset
  • Display a Graphical Coordinate Grid Over a Greyscale Image
  • Create a FITS binary table holding a MOC describing a sky region
  • Check for overlap between a FITS image and a FITS MOC
  • Read a MOC from a text file and plot its outline
  • Create a string-encoded MOC describing a specified set of cells
• High level functions
• Unimplemented AST functions
• Implemented AST functions
  • astAddCell - Adds a single HEALPix cell into an existing Moc
  • astAddColumn - Add a new column definition to a table
  • astAddFrame - Add a Frame to a FrameSet to define a new coordinate system
  • astAddMocData - Adds a FITS binary table into an existing Moc
  • astAddMocString - Adds a JSON or string-encoded MOC into an existing Moc
  • astAddParameter - Add a new global parameter definition to a table
  • astAddPixelMask - Add a set of pixels to a Moc
  • astAddRegion - Add a Region into a Moc
  • astAngle - Calculate the angle subtended by two points at a third point
  • astAxAngle - Returns the angle from an axis, to a line through two points
  • astAxDistance - Find the distance between two axis values
  • astAxOffset - Add an increment onto a supplied axis value
  • astBBuf - Begin a new graphical buffering context
  • astBorder - Draw a border around valid regions of a Plot
  • astBoundingBox - Return a bounding box for previously drawn graphics
  • astBox - Create a Box
  • astChannel - Create a Channel
  • astChebyMap - Create a ChebyMap
  • astCircle - Create a Circle
  • astCirclePars - Returns the geometric parameters of an Circle
  • astClear - Clear attribute values for an Object
  • astClip - Set up or remove clipping for a Plot
  • astCmpFrame - Create a CmpFrame
  • astCmpMap - Create a CmpMap
  • astCmpRegion - Create a CmpRegion
  • astColumnName - Get the name of the column at a given index within the Table
  • astColumnNull - Get or set the null value for an integer column of a FITS table
  • astColumnShape - Returns the shape of the values in a named column
  • astColumnSize - Get the number of bytes needed to hold a full column of data
  • astConvert - Determine how to convert between two coordinate systems
  • astConvex - Create a new Polygon representing the convex hull of a 2D data grid
  • astCopy - Copy an Object
  • astCurrentTime - Return the current system time
  • astCurve - Draw a geodesic curve
  • astDSBSpecFrame - Create a DSBSpecFrame
  • astDecompose - Decompose a Mapping into two component Mappings
  • astDelFits - Delete the current FITS card in a FitsChan
  • astDistance - Calculate the distance between two points in a Frame
  • astDownsize - Reduce the number of vertices in a Polygon
  • astEBuf - End the current graphical buffering context
  • astEllipse - Create a Ellipse
  • astEllipsePars - Returns the geometric parameters of an Ellipse
  • astEmptyFits - Delete all cards in a FitsChan
  • astEscapes - Control whether graphical escape sequences are included in strings
  • astFindFits - Find a FITS card in a FitsChan by keyword
  • astFindFrame - Find a coordinate system with specified characteristics
  • astFitsChan - Create a FitsChan
  • astFitsTable - Create a FitsTable
  • astFluxFrame - Create a FluxFrame
  • astFormat - Format a coordinate value for a Frame axis
  • astFrame - Create a Frame
  • astFrameSet - Create a FrameSet
  • astGenCurve - Draw a generalized curve
  • astGet - Get an attribute value for an Object
  • astGetCell - Identify the next cell in a normalised Moc
  • astGetFits<X> - Get a named keyword value from a FitsChan
  • astGetFrame - Obtain a pointer to a specified Frame in a FrameSet
  • astGetMapping - Obtain a Mapping that converts between two Frames in a FrameSet
  • astGetMocData - Get the FITS binary table data describing a Moc
  • astGetMocHeader - Get the FITS binary table headers describing a Moc
  • astGetMocString - Get the JSON or string-encoded representation of a Moc
  • astGetRefPos - Return the reference position in a specified celestial coordinate system
  • astGetRegionBounds - Returns the bounding box of Region
  • astGetRegionDisc - Returns the centre and radius of a disc containing a 2D Region
  • astGetRegionFrame - Obtain a pointer to the encapsulated Frame within a Region
  • astGetRegionMesh - Return a mesh of points covering the surface or volume of a Region
  • astGetRegionPoints - Returns the positions that define the given Region
  • astGetTableHeader - Get the FITS headers from a FitsTable
  • astGetTables - Retrieve any FitsTables currently in a FitsChan
  • astGrid - Draw a set of labelled coordinate axes
  • astGridLine - Draw a grid line (or axis) for a Plot
  • astGrismMap - Create a GrismMap
  • astHasAttribute - Test if an Object has a named attribute
  • astHasColumn - Returns a flag indicating if a column is present in a Table
  • astHasParameter - Returns a flag indicating if a named global parameter is present in a Table
  • astIntersect - Find the point of intersection between two geodesic curves
  • astInterval - Create a Interval
  • astInvert - Invert a Mapping
  • astKeyMap - Create a KeyMap
  • astLinearApprox - Obtain a linear approximation to a Mapping, if appropriate
  • astLock - Lock an Object for exclusive use by the calling thread
  • astLutMap - Create a LutMap
  • astMapBox - Find a bounding box for a Mapping
  • astMapRegion - Transform a Region into a new Frame using a given Mapping
  • astMapSplit - Split a Mapping up into parallel component Mappings
  • astMark - Draw a set of markers for a Plot
  • astMask - Mask a region of a data grid
  • astMatchAxes - Find any corresponding axes in two Frames
  • astMathMap - Create a MathMap
  • astMatrixMap - Create a MatrixMap
  • astMoc - Create a Moc
  • astMocChan - Create a MocChan
  • astNegate - Negate the area represented by a Region
  • astNorm - Normalise a set of Frame coordinates
  • astNormMap - Create a NormMap
  • astNullRegion - Create a NullRegion
  • astOffset - Calculate an offset along a geodesic curve
  • astOffset2 - Calculate an offset along a geodesic curve in a 2D Frame
  • astOutline - Create a new Polygon outling values in a 2D data grid
  • astOverlap - Test if two regions overlap each other
  • astParameterName - Get the name of the global parameter at a given index within the Table
  • astPcdMap - Create a PcdMap
  • astPermAxes - Permute the axis order in a Frame
  • astPermMap - Create a PermMap
  • astPickAxes - Create a new Frame by picking axes from an existing one
  • astPlot - Create a Plot
  • astPointInRegion - Tests if a single point is inside a Region
  • astPointList - Create a PointList
  • astPolyCurve - Draw a series of connected geodesic curves
  • astPolyMap - Create a PolyMap
  • astPolyTran - Fit a PolyMap inverse or forward transformation
  • astPolygon - Create a Polygon
  • astPrism - Create a Prism
  • astPurgeRows - Remove all empty rows from a table
  • astPurgeWCS - Delete all cards in the FitsChan describing WCS information
  • astPutCards - Store a set of FITS header cards in a FitsChan
  • astPutFits - Store a FITS header card in a FitsChan
  • astPutTable - Store a single FitsTable in a FitsChan
  • astPutTableHeader - Store new FITS headers in a FitsTable
  • astPutTables - Store one or more FitsTables in a FitsChan
  • astQuadApprox - Obtain a quadratic approximation to a 2D Mapping
  • astRate - Calculate the rate of change of a Mapping output
  • astRateMap - Create a RateMap
  • astRead - Read an Object from a Channel
  • astReadFits - Read cards into a FitsChan from the source function
  • astRebin - Rebin a region of a data grid
  • astRebinSeq - Rebin a region of a sequence of data grids
  • astRegionOutline - Draw the outline of an AST Region
  • astRemapFrame - Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet
  • astRemoveColumn - Remove a column from a table
  • astRemoveFrame - Remove a Frame from a FrameSet
  • astRemoveParameter - Remove a global parameter from a table
  • astRemoveRegions - Remove any Regions from a Mapping
  • astRemoveRow - Remove a row from a table
  • astRemoveTables - Remove one or more tables from a FitsChan
  • astResample - Resample a region of a data grid
  • astResolve - Resolve a vector into two orthogonal components
  • astRetainFits - Indicate that the current card in a FitsChan should be retained
  • astSame - Test if two AST pointers refer to the same Object
  • astSet - Set an attribute value for an Object
  • astSetFits<X> - Store a keyword value in a FitsChan
  • astSetRefPos - Set the reference position in a specified celestial coordinate system
  • astShiftMap - Create a ShiftMap
  • astShow - Display a textual representation of an Object on standard output
  • astSimplify - Simplify a Mapping
  • astSkyFrame - Create a SkyFrame
  • astSkyOffsetMap - Returns a Mapping which goes from absolute coordinates to offset coordinates
  • astSlaMap - Create an SlaMap
  • astSpecFluxFrame - Create a SpecFluxFrame
  • astSpecFrame - Create a SpecFrame
  • astSpecMap - Create a SpecMap
  • astSphMap - Create a SphMap
  • astStcsChan - Create an StcsChan
  • astTable - Create a Table
  • astTableSource - Register a source function for accessing tables in FITS files
  • astTest - Test if an Object attribute value is set
  • astTestCell - Tests if a single HEALPix cell is included in a Moc
  • astTestFits - See if a named keyword has a defined value in a FitsChan
  • astText - Draw a text string for a Plot
  • astTimeAdd - Add a time coordinate conversion to a TimeMap
  • astTimeFrame - Create a TimeFrame
  • astTimeMap - Create a TimeMap
  • astTranGrid - Transform a grid of positions
  • astTranMap - Create a TranMap
  • astTranN - Transform N-dimensional coordinates
  • astTune - Set or get an integer-valued AST global tuning parameter
  • astTuneC - Set or get a character-valued AST global tuning parameter
  • astUnformat - Read a formatted coordinate value for a Frame axis
  • astUnitMap - Create a UnitMap
  • astUnitNormMap - Create a UnitNormMap
  • astUnlock - Unlock an Object for use by other threads
  • astVersion - Return the version of the AST library being used
  • astWarnings - Returns any warnings issued by the previous read or write operation
  • astWcsMap - Create a WcsMap
  • astWinMap - Create a WinMap
  • astWrite - Write an Object to a Channel
  • astWriteFits - Write out all cards in a FitsChan to the sink function
  • astZoomMap - Create a ZoomMap