healpix

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2024 License: MIT Imports: 4 Imported by: 1

README

healpix

A Go-lang implementation of the HEALPix projection and pixelization of a sphere. This package is early stage and not yet recommended for integration. However, features incorporated into the master branch generally have good test coverage.

The HEALPix pixelization is 'equal-area' for each pixel: a pixel at the equator of the sphere contains the same resolution of data as a pixel at the poles (unlike many pixelizations based on more common projections). The resolution increments as a scaled, squared power of 2, and this package supports spheres divided into up to 12*((2^29)^2) pixels, i.e. 29 different levels of resolution.

HEALPix supports two basic pixel numbering schemes:

  1. Nested - useful for efficient querying of nearest neighbors for individual pixels
  2. Ring - useful for efficient spherical harmonic computations

A third numbering scheme, Nested Unique, allows for the selection of pixels at different scales of resolution, allowing for 'sparse' HEALPix queries and data set representations in addition to the default 'dense' representation.

Roadmap

  • - Querying nearest neighbors
  • - Support 'Nested Unique' pixel numbering (for multiresolution)
  • - Support Cartesian 3-vector 'positions'
  • - Querying discs
  • - Querying polygons
  • - Multiresolution pixel range sets

References

The following prior works were studied carefully to aid the implementation of this package.

Gorski, et al. "HEALPix: A Framework for High-Resolution Discretization and Fast Analysis of Data Distributed on the Sphere" The Astrophysical Journal, 622:759–771, 2005 April 1. Link

I. Martinez-Castellanos, et al. "Multiresolution HEALPix Maps for Multiwavelength and Multimessenger Astronomy" The Astronomical Journal, vol. 63, no. 6, 2022 May 11. Link

Reinecke & Hivon. "Efficient data structures for masks on 2D grids" Astronomy and Astrophysics, vol. 580, 2015 August 19. Link

Documentation

Index

Constants

View Source 
const (
	BasePixelsPerRow int = 4
	BasePixelRows    int = 3
)

Variables

This section is empty.

Functions

func IsValidNSide 

func IsValidNSide(test int) bool

Check whether the given number is a valid NSide value for a healpix map.

func IsValidOrder 

func IsValidOrder(test int) bool

Check whether the given number is a valid order value to create a healpix map.

func MaxNSide 

func MaxNSide() int

The maximum possible number of subpixels on the side of a base pixel of a healpix map on the currently executing machine. Significantly smaller on 32-bit machines than on 64-bit machines.

func MaxOrder 

func MaxOrder() int

The maximum possible order of a healpix map supported on the currently executing machine. Significantly smaller on 32-bit machines than on 64-bit machines.

func Neighbor 

func Neighbor(hp Healpix, scheme HealpixScheme, where Where, xo int, yo int) int

Given a desired coordinate on a healpix map, return the pixel index of of the desired neighbor pixel of in the selected HEALPix numbering scheme.

func Neighbors 

func Neighbors(hp Healpix, where Where, scheme HealpixScheme) []int

Given a desired coordinate on a healpix map, return the pixel indices of each neighbor pixel of the selected coordinate in the HEALPix index scheme desired.

Types

type Face 

type Face struct {
	// contains filtered or unexported fields
}

Access the properties of a base pixel, or 'face', of a HEALPix map.

func NewFace 

func NewFace(faceId int) Face

Return the face at the given index, from 0 - 11.

func (Face) FaceId 

func (f Face) FaceId() int

Returns the index of the face.

func (Face) FaceRow 

func (f Face) FaceRow() int

Returns the row index, starting from 0, in which the face resides.

func (Face) Neighbor 

func (f Face) Neighbor(xOffset int, yOffset int) int

Return the face id of the neighbor of the current face in the given direction. Each of x and y expects one of three values: -1, 0, or 1. In this scheme, x and y have 0 at the bottom most vertex of the face (which are arrayed as diamonds conceptually), and each increases outward along the diamond boundary, x along the left side and y along the right side. So x,y == -1,-1 is the directly southern neighbor; x,y == 1,1 is the directly northern neighbor, and x,y == -1,1 is the northwestern neighbor.

func (Face) SouthernmostVertex 

func (f Face) SouthernmostVertex() (int, int)

Return the x and y coordinate of the southernmost vertex of this face in abstract face division coordinates. x ranges from 0 - 7, y ranges from 0 - 4

type FacePixel 

type FacePixel struct {
	// contains filtered or unexported fields
}

Describes a discrete HEALPix pixel using the 'face' (base pixel) in which the pixel belongs, and it's relative x/y offset from the southernmost vertex of the face. So 0,0 is the x/y coordinate of the southernmost vertex on each face, and NSide-1,NSide-1 is the northernmost vertex of the face. X increases in a north-east direction, y increases in a north-west direction.

func NewFacePixel added in v0.1.0 

func NewFacePixel(face int, x int, y int) FacePixel

Create a new face pixel using the given coordinates.

func (FacePixel) Face 

func (p FacePixel) Face() int

Returns the index identifier of the face in which the pixel is found.

func (FacePixel) PixelId 

func (p FacePixel) PixelId(hp Healpix, scheme HealpixScheme) int

func (FacePixel) ToFacePixel 

func (p FacePixel) ToFacePixel(hp Healpix) FacePixel

func (FacePixel) ToNestPixel 

func (p FacePixel) ToNestPixel(hp Healpix) NestPixel

func (FacePixel) ToProjectionCoordinate 

func (p FacePixel) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (FacePixel) ToRingCoordinate 

func (p FacePixel) ToRingCoordinate(hp Healpix) RingCoordinate

func (FacePixel) ToRingPixel 

func (p FacePixel) ToRingPixel(hp Healpix) RingPixel

func (FacePixel) ToSphereCoordinate 

func (p FacePixel) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (FacePixel) ToUniquePixel 

func (p FacePixel) ToUniquePixel(hp Healpix) UniquePixel

func (FacePixel) X 

func (p FacePixel) X() int

Returns the row-index along the north-east direction of the face, increasing from the south to the north.

func (FacePixel) Y 

func (p FacePixel) Y() int

Returns the row-index along the north-west direction of the face, increasing from the south to the north.

type Healpix 

type Healpix interface {
	Order() int                 // Returns the exponent describing how many pixels are in the HEALPix map.
	Pixels() int                // Returns the total number of pixels in the HEALPix map.
	FaceSidePixels() int        // Returns the number of pixels on the side of each base pixel (NSide) of the HEALPix map.
	FacePixels() int            // Returns the number of pixels in each base pixel (face) of the HEALPix map.
	PolarRegionPixels() int     // Returns the number of pixels in each (north or south) polar region.
	Rings() int                 // Returns the number of rings in the HEALPix map.
	EquatorRing() int           // Returns the index of the ring that sits on the equator in the HEALPix map.
	PixelArea() float64         // Returns the area of a pixel in the HEALPix map in steradians.
	AngularResolution() float64 // Returns the angular resolution of the HEALPix map in degrees.
}

The base interface describing the core aspects of a HEALPix projection.

type HealpixOrder 

type HealpixOrder int

A description of a healpix map based on the order of the map. All other values are derived from this core descriptor (and computed each time they are accessed).

func NewHealpixOrder 

func NewHealpixOrder(order int) HealpixOrder

func (HealpixOrder) AngularResolution 

func (o HealpixOrder) AngularResolution() float64

func (HealpixOrder) EquatorRing 

func (o HealpixOrder) EquatorRing() int

func (HealpixOrder) FacePixels 

func (o HealpixOrder) FacePixels() int

func (HealpixOrder) FaceSidePixels 

func (o HealpixOrder) FaceSidePixels() int

func (HealpixOrder) Order 

func (o HealpixOrder) Order() int

Returns the exponent describing how many pixels are in the HEALPix map.

func (HealpixOrder) PixelArea 

func (o HealpixOrder) PixelArea() float64

func (HealpixOrder) Pixels 

func (o HealpixOrder) Pixels() int

func (HealpixOrder) PolarRegionPixels 

func (o HealpixOrder) PolarRegionPixels() int

func (HealpixOrder) Rings 

func (o HealpixOrder) Rings() int

type HealpixScheme 

type HealpixScheme int

A description of how pixels are accessed and stored on the machine. HEALPix provides two common indexing schemes for pixels: Ring and Nested. Ring starts pixel index 0 at the north pole and continues around the ring incrementing by one. When the first pixel is reach, the pixel numbering continues on the next ring below the north pole, again incrementing by one, until the south pole is reached. The Nested index is more complicated to describe textually, but allows for more efficient access of neighboring pixel indices mathemtically than the Ring scheme. Both are useful depending on the use case however. 

const (
	// The HEALPix pixel numbering scheme in which pixel indexing starts 0 at the north pole and
	// increments laterally (around the ring of the same latitude) before moving down the globe
	// to the next 'ring'.
	RingScheme HealpixScheme = iota
	// The HEALPix pixel numbering scheme in which faces are split into a 'quadtree' like structure,
	// with the pixels numbered in a 'bottom-up' like fashion from the southernmost vertex of
	// of each face.
	NestScheme
)

type HealpixSide 

type HealpixSide int

A description of a healpix map based on the number of each pixels on each side of the base pixels of the map. Referred to as NSide in most HEALPix literature. All other values are derived from this core attributed (and computed on each access).

func NewHealpixSide 

func NewHealpixSide(nside int) HealpixSide

func (HealpixSide) AngularResolution 

func (o HealpixSide) AngularResolution() float64

func (HealpixSide) EquatorRing 

func (o HealpixSide) EquatorRing() int

func (HealpixSide) FacePixels 

func (o HealpixSide) FacePixels() int

func (HealpixSide) FaceSidePixels 

func (o HealpixSide) FaceSidePixels() int

func (HealpixSide) Order 

func (o HealpixSide) Order() int

func (HealpixSide) PixelArea 

func (o HealpixSide) PixelArea() float64

func (HealpixSide) Pixels 

func (o HealpixSide) Pixels() int

func (HealpixSide) PolarRegionPixels 

func (o HealpixSide) PolarRegionPixels() int

func (HealpixSide) Rings 

func (o HealpixSide) Rings() int

type NestPixel 

type NestPixel int

The index of a pixel in a HEALPix map using a 'quad-tree' division counting scheme that makes nearest neighbor searches more efficient.

func (NestPixel) PixelId 

func (p NestPixel) PixelId(hp Healpix, scheme HealpixScheme) int

func (NestPixel) ToFacePixel 

func (p NestPixel) ToFacePixel(hp Healpix) FacePixel

func (NestPixel) ToNestPixel 

func (p NestPixel) ToNestPixel(hp Healpix) NestPixel

Identity function on NestPixel to satisfy the Where interface.

func (NestPixel) ToProjectionCoordinate 

func (p NestPixel) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (NestPixel) ToRingCoordinate 

func (p NestPixel) ToRingCoordinate(hp Healpix) RingCoordinate

func (NestPixel) ToRingPixel 

func (p NestPixel) ToRingPixel(hp Healpix) RingPixel

func (NestPixel) ToSphereCoordinate 

func (p NestPixel) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (NestPixel) ToUniquePixel 

func (p NestPixel) ToUniquePixel(hp Healpix) UniquePixel

type ProjectionCoordinate 

type ProjectionCoordinate struct {
	// contains filtered or unexported fields
}

Represents a position on a HEALPix sphere projected into the standard HEALPix projection on a 2D plane.

func NewProjectionCoordinate added in v0.1.0 

func NewProjectionCoordinate(x float64, y float64) ProjectionCoordinate

func (ProjectionCoordinate) PixelId 

func (p ProjectionCoordinate) PixelId(hp Healpix, scheme HealpixScheme) int

func (ProjectionCoordinate) ToFacePixel 

func (coord ProjectionCoordinate) ToFacePixel(hp Healpix) FacePixel

func (ProjectionCoordinate) ToNestPixel 

func (p ProjectionCoordinate) ToNestPixel(hp Healpix) NestPixel

func (ProjectionCoordinate) ToProjectionCoordinate 

func (p ProjectionCoordinate) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (ProjectionCoordinate) ToRingCoordinate 

func (p ProjectionCoordinate) ToRingCoordinate(hp Healpix) RingCoordinate

func (ProjectionCoordinate) ToRingPixel 

func (p ProjectionCoordinate) ToRingPixel(hp Healpix) RingPixel

func (ProjectionCoordinate) ToSphereCoordinate 

func (p ProjectionCoordinate) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (ProjectionCoordinate) ToUniquePixel 

func (p ProjectionCoordinate) ToUniquePixel(hp Healpix) UniquePixel

func (ProjectionCoordinate) X 

func (p ProjectionCoordinate) X() float64

The horizontal component of the coordinate on the planar projection. Correlated with longitude in spherical coordinates.

func (ProjectionCoordinate) Y 

func (p ProjectionCoordinate) Y() float64

The vertical component of the coordinate on the planar projection. Correlated with lattitude in spherical coordinates.

type Ring 

type Ring struct {
	// contains filtered or unexported fields
}

Describes a ring of pixels in the HEALPix pixelization, and provides functionality on rings.

func NewRing 

func NewRing(base Healpix, index int) Ring

Get a new ring description from the given HEALPix map, at the given ring index. Ring indices start at the the north pole at 0, and increment southward by 1 until reaching the south pole. The largest ring index possible for a given HEALPix map is base.Rings() - 1. Panics if the ring index is invalid.

func (Ring) Base 

func (r Ring) Base() Healpix

The healpix map of which this ring is a part. This determines some of the properties of the rings, and combined with Index() represents a 'minimal cover' of the attributes of a ring.

func (Ring) Colatitude 

func (r Ring) Colatitude() float64

The latitude where the center of each pixel in the ring lies, in radians.

func (Ring) FirstIndex 

func (r Ring) FirstIndex() int

The equivalent Ring scheme pixel number of the first (0) pixel in this ring.

func (Ring) Index 

func (r Ring) Index() int

The index of the ring, proceeding from 0 at the north pole and incrementing toward the south pole by one.

func (Ring) IsOffset 

func (r Ring) IsOffset() bool

True if the first pixel of the ring has it's center not on 0 longitude, but just slightly off it. False if the first pixel of the ring has it's center on 0 longitude.

func (Ring) Latitude 

func (r Ring) Latitude() float64

The colatitutde where the center of each pixel in the ring lies, in radians.

func (Ring) Pixels 

func (r Ring) Pixels() int

The number of pixels in this ring.

type RingCoordinate 

type RingCoordinate struct {
	// contains filtered or unexported fields
}

Describes a HEALPix pixel as a combination of ring number and pixel-from-start-of-ring. The ring pixel numbering is analgous to this indexing scheme but with both components combined into a single number.

func NewRingCoordinate added in v0.1.0 

func NewRingCoordinate(ring int, pixelInRing int) RingCoordinate

Create a new pixel index from the ring in which the pixel is found, and it's offset from the meridian within the ring.

func (RingCoordinate) PixelId 

func (p RingCoordinate) PixelId(hp Healpix, scheme HealpixScheme) int

func (RingCoordinate) PixelInRing 

func (p RingCoordinate) PixelInRing() int

The index within the ring (assuming first pixel in the ring == 0) that contains the pixel.

func (RingCoordinate) Ring 

func (p RingCoordinate) Ring() int

The HEALPix ring the pixel is located in.

func (RingCoordinate) ToFacePixel 

func (p RingCoordinate) ToFacePixel(hp Healpix) FacePixel

func (RingCoordinate) ToNestPixel 

func (p RingCoordinate) ToNestPixel(hp Healpix) NestPixel

func (RingCoordinate) ToProjectionCoordinate 

func (p RingCoordinate) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (RingCoordinate) ToRingCoordinate 

func (p RingCoordinate) ToRingCoordinate(hp Healpix) RingCoordinate

func (RingCoordinate) ToRingPixel 

func (p RingCoordinate) ToRingPixel(hp Healpix) RingPixel

func (RingCoordinate) ToSphereCoordinate 

func (p RingCoordinate) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (RingCoordinate) ToUniquePixel 

func (p RingCoordinate) ToUniquePixel(hp Healpix) UniquePixel

type RingPixel 

type RingPixel int

The index of a pixel in a HEALPix map counting ring-wise down from the north pole.

func (RingPixel) PixelId 

func (p RingPixel) PixelId(hp Healpix, scheme HealpixScheme) int

func (RingPixel) RingId 

func (p RingPixel) RingId(hp Healpix) int

func (RingPixel) ToFacePixel 

func (p RingPixel) ToFacePixel(hp Healpix) FacePixel

func (RingPixel) ToNestPixel 

func (p RingPixel) ToNestPixel(hp Healpix) NestPixel

func (RingPixel) ToProjectionCoordinate 

func (p RingPixel) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (RingPixel) ToRingCoordinate 

func (p RingPixel) ToRingCoordinate(hp Healpix) RingCoordinate

func (RingPixel) ToRingPixel 

func (p RingPixel) ToRingPixel(hp Healpix) RingPixel

func (RingPixel) ToSphereCoordinate 

func (p RingPixel) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (RingPixel) ToUniquePixel 

func (p RingPixel) ToUniquePixel(hp Healpix) UniquePixel

type SphereCoordinate 

type SphereCoordinate struct {
	// contains filtered or unexported fields
}

A position on the sphere represented by two components, the latitude (0 at equator and +/- Pi/2 at poles) and the longitude (0 - 2Pi). Units in radians. ALso provides colatitude/longitude representation for familiarity, as colatitude is used more frequently in HEALPix applications.

func NewColatLonCoordinate added in v0.1.0 

func NewColatLonCoordinate(colat float64, lon float64) SphereCoordinate

Create a SphereCoordinate structure from a colatitude/longitude pair.

func NewLatLonCoordinate added in v0.1.0 

func NewLatLonCoordinate(lat float64, lon float64) SphereCoordinate

Create a SphereCoordinate structure from a latitude/longitude pair.

func (SphereCoordinate) Colatitude 

func (p SphereCoordinate) Colatitude() float64

The colatitude component of the coordinate on the sphere, in units of radians.

func (SphereCoordinate) Latitude 

func (p SphereCoordinate) Latitude() float64

The latitude component of the coordinate on the sphere, in units of radians.

func (SphereCoordinate) Longitude 

func (p SphereCoordinate) Longitude() float64

The longitude component of the coordinate on the sphere, in units of radians.

func (SphereCoordinate) PixelId 

func (p SphereCoordinate) PixelId(hp Healpix, scheme HealpixScheme) int

func (SphereCoordinate) ToFacePixel 

func (p SphereCoordinate) ToFacePixel(hp Healpix) FacePixel

func (SphereCoordinate) ToNestPixel 

func (p SphereCoordinate) ToNestPixel(hp Healpix) NestPixel

func (SphereCoordinate) ToProjectionCoordinate 

func (p SphereCoordinate) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (SphereCoordinate) ToRingCoordinate 

func (p SphereCoordinate) ToRingCoordinate(hp Healpix) RingCoordinate

func (SphereCoordinate) ToRingPixel 

func (p SphereCoordinate) ToRingPixel(hp Healpix) RingPixel

func (SphereCoordinate) ToSphereCoordinate 

func (p SphereCoordinate) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (SphereCoordinate) ToUniquePixel 

func (p SphereCoordinate) ToUniquePixel(hp Healpix) UniquePixel

type UniquePixel 

type UniquePixel int

The index of a pixel in a HEALPix map in nested numbering, combined with the order of the HEALPix map resolution. Useful for indexing in multiresolution HEALPix maps.

func (UniquePixel) PixelId 

func (p UniquePixel) PixelId(hp Healpix, scheme HealpixScheme) int

func (UniquePixel) ToFacePixel 

func (p UniquePixel) ToFacePixel(hp Healpix) FacePixel

func (UniquePixel) ToNestPixel 

func (p UniquePixel) ToNestPixel(hp Healpix) NestPixel

func (UniquePixel) ToProjectionCoordinate 

func (p UniquePixel) ToProjectionCoordinate(hp Healpix) ProjectionCoordinate

func (UniquePixel) ToRingCoordinate 

func (p UniquePixel) ToRingCoordinate(hp Healpix) RingCoordinate

func (UniquePixel) ToRingPixel 

func (p UniquePixel) ToRingPixel(hp Healpix) RingPixel

func (UniquePixel) ToSphereCoordinate 

func (p UniquePixel) ToSphereCoordinate(hp Healpix) SphereCoordinate

func (UniquePixel) ToUniquePixel 

func (p UniquePixel) ToUniquePixel(hp Healpix) UniquePixel

type Where 

type Where interface {
	ToNestPixel(Healpix) NestPixel                       // Convert the index to an equivalent pixel index in Nest scheme.
	ToUniquePixel(Healpix) UniquePixel                   // Convert the index to an equivalent pixel index in Nested Unique scheme, according to the HEALPix resolution supplied.
	ToRingPixel(Healpix) RingPixel                       // Convert the index to an equivalent pixel index in Ring scheme.
	ToFacePixel(Healpix) FacePixel                       // Convert the index to an equivalent face 'x & y' index.
	ToRingCoordinate(Healpix) RingCoordinate             // Convert the index to an equivalent ring & offset index.
	ToProjectionCoordinate(Healpix) ProjectionCoordinate // Convert the index to an x/y position on the planar HEALPix projection of the sphere.
	ToSphereCoordinate(Healpix) SphereCoordinate         // Convert the index to a latitude/longitude position on the sphere.

	PixelId(Healpix, HealpixScheme) int // Convert the index into an equivalent index for the given HEALPix pixel numbering scheme.
}

An interface for converting between different indexing schemes and accessing the desired pixel index given a HEALPix map with a specific indexing scheme, regardless of which scheme the index itself references.

Source Files

View all Source files

Directories

Path Synopsis
internal
intmath

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.