wcs

Documentation

Overview

Package wcs parses the FITS World Coordinate System keyword set defined in Greisen & Calabretta 2002 ("Representations of world coordinates in FITS", Paper I) into a typed in-memory struct.

This package is PARSING ONLY. It does not compute any projection math, celestial rotations, or coordinate conversions. The math lives in sibling package fits/wcs/transform.

Supported keyword vocabulary:

• Per-axis: CTYPEi, CUNITi, CRVALi, CRPIXi, CDELTi
• Linear transform: PCi_j, CDi_j (mutually exclusive per Paper I §2.1)
• Projection parameters: PVi_m, PSi_m
• Celestial: LONPOLE, LATPOLE, RADESYS, EQUINOX, EPOCH
• Observation time: MJD-OBS, DATE-OBS

Axes are 1-based per FITS convention; the exported slices in Header are indexed 0-based (so CTYPE[0] corresponds to CTYPE1, CRVAL[1] to CRVAL2, etc.) because Go slices are 0-based. This trade-off matches astropy.wcs.WCS and is documented on each field.

Index

• Variables
• type Header
  • func Parse(h *header.Header) (*Header, error)
  • func ParseAlt(h *header.Header, alt string) (*Header, error)
  • func (w *Header) CelestialProjCode() string
  • func (w *Header) IsCelestial() bool
  • func (w *Header) String() string
• type PVKey

Variables

var ErrConflictingMatrix = errors.New("fits/wcs: header contains both PC and CD matrices")

ErrConflictingMatrix is returned when the header contains both PCi_j and CDi_j cards, which is forbidden by Paper I §2.1.

Types

type Header

type Header struct {
	// NAxis is the number of WCS axes. It is the larger of WCSAXES (if
	// present) and the maximum axis index found on any per-axis keyword,
	// and falls back to the image's NAXIS if neither is set.
	NAxis int

	// Per-axis keywords; each slice has length NAxis.
	CType []string
	CUnit []string
	CRVal []float64
	CRPix []float64
	CDelt []float64

	// Linear transform matrices. PC is always NAxis × NAxis (identity if
	// the header has neither PC nor CD). CD is nil unless the header used
	// the CDi_j form.
	PC [][]float64
	CD [][]float64

	// Projection parameters. Absent entries are returned as zero value
	// with ok=false via Has/Get helpers below.
	PV map[PVKey]float64
	PS map[PVKey]string

	// Global celestial keywords.
	LonPole float64 // LONPOLE, degrees
	LatPole float64 // LATPOLE, degrees
	RadeSys string  // RADESYS (e.g. "ICRS", "FK5", "FK4")
	Equinox float64 // EQUINOX

	// Time of observation.
	DateObs string  // DATE-OBS
	MJDObs  float64 // MJD-OBS

	// ProjCode holds the 3-letter projection code extracted from the tail
	// of each CTYPEi (e.g. "TAN" from "RA---TAN"). For non-celestial axes
	// this is the empty string.
	ProjCode []string

	// AxisType holds the axis kind extracted from the leading portion of
	// CTYPEi (e.g. "RA", "DEC", "GLON", "GLAT", "ELON", "ELAT"). Empty for
	// non-celestial axes.
	AxisType []string

	// LonAxis and LatAxis are the 1-based indices of the longitude and
	// latitude axes, respectively, or 0 if a celestial axis pair was not
	// identified.
	LonAxis int
	LatAxis int

	// lonPoleSet / latPoleSet record whether the user supplied a value
	// explicitly; transform needs this to apply the default-by-projection
	// rules from Paper II §2.4 correctly.
	LonPoleSet bool
	LatPoleSet bool
}

Header is the parsed WCS keyword set for one coordinate representation.

The slices (CType, CUnit, CRVal, CRPix, CDelt, ProjCode, AxisType) are indexed 0-based: CType[0] corresponds to the FITS keyword CTYPE1.

PC and CD are row-major NAxis × NAxis matrices in the same 0-based indexing: PC[i][j] corresponds to PCi+1_j+1. PC is always populated (defaulting to the identity matrix). CD is nil unless the header used the CDi_j form. The two forms are mutually exclusive per Paper I §2.1; if both are present in the header, Parse returns an error.

func Parse

func Parse(h *header.Header) (*Header, error)

Parse reads a *header.Header and returns the primary (unsuffixed) WCS description. Equivalent to ParseAlt(h, "").

func ParseAlt

func ParseAlt(h *header.Header, alt string) (*Header, error)

ParseAlt reads a *header.Header (the parsed FITS header of an image HDU) and returns a typed WCS Header for the given alternate WCS description. Alt must be the empty string (for the primary WCS) or a single uppercase letter A-Z (for alternate descriptions per Paper I §3.7). Every per-axis and matrix keyword is searched with the alt suffix appended (e.g. CTYPE1A, CD1_1A) and falls back to no suffix only for WCSAXES and NAXIS (which are not duplicated per description).

Parse never panics on malformed input; keywords that fail to parse as their expected type are silently replaced with their defaults, matching the behavior of astropy.wcs.WCS. Structural contradictions (PC+CD both present) return an error.

func (*Header) CelestialProjCode

func (w *Header) CelestialProjCode() string

CelestialProjCode returns the common projection code for the celestial axis pair. It panics if IsCelestial() is false. If the longitude and latitude axes declare different projection codes (which is malformed input but seen in the wild), the longitude axis wins.

func (*Header) IsCelestial

func (w *Header) IsCelestial() bool

IsCelestial reports whether the header describes a celestial coordinate pair (longitude + latitude axis both identified).

func (*Header) String

func (w *Header) String() string

String returns a short human-readable summary used in diagnostic output.

type PVKey

type PVKey struct {
	Axis  int // i, 1-based
	Index int // m, 0-based per the FITS convention
}

PVKey identifies a PVi_m or PSi_m projection parameter: axis index i (1-based, matching the FITS keyword) and parameter index m.