healpix

README

healpix

This is a library providing Go bindings to the official C++ library for HEALPix, which is a scheme for partitioning a sphere into numbered regions.

I wanted this to support implementing "cone search" with a B-Tree, so the only APIs which are exposed are ones that assist with that goal. It's not hard to add more if you want more of the features of the C++ library though, please open an issue if you could use something more.

Installation and use

You'll need to have the healpix_cxx library installed. That is, you'll need libhealpix_cxx.so, and you'll need the healpix_cxx development headers. These need to be on the machine that actually builds your Go code, as well as where it executes (unless you build statically, see below).

This library uses pkg-config to find the healpix libraries.

The simplest way to do this may be to use your package manager, like with sudo apt install libhealpix-cxx-dev. But...

Building healpix_cxx from source

If you want to build from source, here's how I do it on Ubuntu:

# Install all required tools
sudo apt-get install autoconf automake libtool pkg-config

# Install cfitsio library
sudo apt install libcfitsio-dev libcfitsio8

# Download source
git checkout git@github.com:spenczar/healpixmirror.git
cd healpixmirror

# Prepare libsharp
cd src/common_libraries/libsharp
autoreconf -i
cd

# Prepare cxx
cd src/cxx
autoreconf -i
cd

# Configure system- you'll be prompted to say where libcfitsio.so is found
./configure

# Actually build
make -j

# Install pkg-config files
cp lib/pkgconfig/libsharp.pc /usr/share/pkgconfig/libsharp.pc
cp lib/pkgconfig/healpix_cxx.pc /usr/share/pkgconfig/healpix_cxx.pc

Static builds

Fully-encapsulated static builds that link against C libraries are possible in Go, but they require a special invocation of the go build command. Specifically (at least on Linux, with Go 1.14):

go build -ldflags "-linkmode external -extldflags -static"

Your mileage may vary. This might be different for your system.

Development

This library uses SWIG to generate wrappers around the C++ healpix_cxx and libsharp libraries. Use the run_swig.sh script to execute this. You may get some warnings.

Documentation

Index

• type HEALPixMapper
  • func NewHEALPixMapper(order int, scheme OrderingScheme) (*HEALPixMapper, error)
  • func (m *HEALPixMapper) PixelAt(ptg Pointing) int
  • func (m *HEALPixMapper) PointingToCenter(pixel int) Pointing
  • func (m *HEALPixMapper) QueryDisc(pointing Pointing, r float64) []PixelRange
  • func (m *HEALPixMapper) QueryDiscInclusive(pointing Pointing, r float64, resolution int) []PixelRange
• type OrderingScheme
• type PixelRange
• type Pointing
  • func RADec(ra, dec float64) Pointing
  • func (p Pointing) RADec() (ra, dec float64)

Types

type HEALPixMapper

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

A HEALPixMapper is a persistent map with a given order for indexing positions on a sphere.

func NewHEALPixMapper

func NewHEALPixMapper(order int, scheme OrderingScheme) (*HEALPixMapper, error)

NewHEALPixMapper creates a persistent HEALPixMapper. The order parameter controls how finely the sphere is pixelated; higher values of order correspond to finer pixelization. Order must be between 0 and 14.

func (*HEALPixMapper) PixelAt

func (m *HEALPixMapper) PixelAt(ptg Pointing) int

PixelAt returns the number of the pixel which contains the given angular coordinates indicated by ptg.

func (*HEALPixMapper) PointingToCenter

func (m *HEALPixMapper) PointingToCenter(pixel int) Pointing

PointingToCenter returns a pointing towards the center of the pixel with the given number.

func (*HEALPixMapper) QueryDisc

func (m *HEALPixMapper) QueryDisc(pointing Pointing, r float64) []PixelRange

QueryDisc returns the set of all pixels whose centers lie within a disk. The disc is centered at pointing, and has a radius of r radians.

func (*HEALPixMapper) QueryDiscInclusive

func (m *HEALPixMapper) QueryDiscInclusive(pointing Pointing, r float64, resolution int) []PixelRange

QueryDiscInclusive returns the set of all pixels which overlap with the disk defined by pointing and radius r (measured in radians). resolution should be an integer which determines the resolution used for the overlapping test.

For Nested HEALPix, resolution must be a power of 2. For Ring, it can be any positive integer. A typical choice would be 4.

Note that this method may return some pixels which don't overlap wiht the disk at all. The higher resolution is chosen, the fewer false positives are returned, at the cost of increased run time.

This method is more efficient in the Ring scheme.

type OrderingScheme

type OrderingScheme int

An OrderingScheme is a class of pixel orderings for HEALPix.

const (
	Ring OrderingScheme = 1
	Nest OrderingScheme = 1
)

type PixelRange

type PixelRange struct {
	Start, Stop int
}

PixelRange represents a contiguous sequence of pixels. Its Stop field indicates the first pixel in the range, and its Stop field indicates the first pixel which is not in the range (in other words, this represents `[Start, Stop)`).

type Pointing

type Pointing struct {
	// Theta is the polar angle in radians.
	Theta float64
	// Phi is the azimuthal angle in radians.
	Phi float64
}

A Pointing is a structure describing an orientation in polar coordinates.

func RADec

func RADec(ra, dec float64) Pointing

RADec returns a pointing corresponding to a given right ascension and declination, both in degrees.

func (Pointing) RADec

func (p Pointing) RADec() (ra, dec float64)

RADec returns the right ascension and declination, in degrees, corresponding to the pointing.