# Class HealpixBase

java.lang.Object
healpix.essentials.HealpixTables
healpix.essentials.HealpixBase

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `HealpixMapDouble, HealpixMapFloat, HealpixProc`

public class HealpixBase extends HealpixTables
Basic opersations related to the HEALPix pixelisation. This class is conceptually very similar the the Healpix_Base class of Healpix_cxx. It supports the NESTED scheme for nside parameters which are powers of 2, and the RING scheme for arbitrary positive nside parameters. The maximum supported nside parameter is 2^29.

See Also:
  - Serialized Form

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected final class`
`HealpixBase.Xyf`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected double`
`fact1`
`protected double`
`fact2`
`protected long`
`ncap`
`protected long`
`nl2`
`protected long`
`nl3`
`protected long`
`nl4`
`protected long`
`npface`
`protected long`
`npix`
`static final long`
`ns_max`
Maximum Nside parameter; equivalent to 2^`order_max`.
`protected long`
`nside`
The Nside parameter.
`protected int`
`order`
The order of the map; -1 when `nside` is not a power of 2.
`static final int`
`order_max`
Maximum order parameter
`protected Scheme`
`scheme`
The ordering scheme.

### Fields inherited from class HealpixTables

`ctab, facearray, jpll, jrll, swap_cycle, swaparray, utab, xoffset, yoffset`

## Constructor Summary

Constructors
Constructor
Description
`HealpixBase()`
Initializes the object to Nside=1 and scheme=NESTED.
`HealpixBase(long nside_in, Scheme scheme_in)`
Initializes the object to a user-supplied Nside and ordering scheme.

## Method Summary

Modifier and Type
Method
Description
`long`
`ang2pix(Pointing ptg)`
Returns the pixel which contains the supplied Pointing.
`Vec3[]`
`boundaries(long pix, int step)`
Returns a set of points along the boundary of the given pixel.
`long`
`getNpix()`
Returns the total number of pixels in the pixelisation.
`int`
`getNside()`
Returns the current Nside parameter.
`int`
`getOrder()`
Returns the current order parameter.
`Scheme`
`getScheme()`
Returns the current ordering scheme.
`protected long`
`loc2pix(healpix.essentials.Hploc loc)`
`double`
`maxPixrad()`
Returns the maximum angular distance between a pixel center and its corners.
`long[]`
`neighbours(long ipix)`
Returns the neighboring pixels of ipix.
`long`
`nest2ring(long ipnest)`
Returns ring pixel number for the supplied nested pixel number.
`static long`
`npix2Nside(long npix)`
Calculates the Nside parameter from the number of pixels.
`static long`
`nside2Npix(long nside)`
Calculates the number of pixels from the Nside parameter.
`static int`
`nside2order(long nside)`
Calculates the map order from its Nside parameter.
`static long`
`order2Npix(int order)`
Calculates the number of pixels from the order parameter.
`Pointing`
`pix2ang(long pix)`
Returns the Pointing corresponding to the center of the supplied pixel.
`protected healpix.essentials.Hploc`
`pix2loc(long pix)`
`long`
`pix2ring(long pix)`
Compute ring index from pixel number.
`Vec3`
`pix2vec(long pix)`
Returns the normalized 3-vector corresponding to the center of the supplied pixel.
`protected HealpixBase.Xyf`
`pix2xyf(long pix)`
`Zphi`
`pix2zphi(long pix)`
Returns the Zphi corresponding to the center of the supplied pixel.
`RangeSet`
`queryDisc(Pointing ptg, double radius)`
Returns a range set of pixels whose centers lie within a given disk.
`RangeSet`
`queryDiscInclusive(Pointing ptg, double radius, int fact)`
Returns a range set of pixels which overlap with a given disk.
`RangeSet`
`queryPolygon(Pointing[] vertex)`
Returns a range set of pixels whose centers lie within the convex polygon defined by the `vertex` array.
`RangeSet`
`queryPolygonInclusive(Pointing[] vertex, int fact)`
Returns a range set of pixels that overlap with the convex polygon defined by the `vertex` array.
`RangeSet`
`queryStrip(double theta1, double theta2, boolean inclusive)`
Returns a range set of pixels whose centers lie within a given latitude range (if `inclusive==false`), or which overlap with this range (if `inclusive==true`).
`long`
`ring2nest(long ipring)`
Returns nested pixel number for the supplied ring pixel number.
`double`
`ring2theta(long ring)`
Returns the colatitude for the requested ring.
`protected HealpixBase.Xyf`
`ring2xyf(long pix)`
`double`
`ring2z(long ring)`
Returns the z-coordinate (equivalent to the cosine of the colatitude) for the requested ring.
`void`
`setNside(long nside_in)`
Adjusts the object to nside_in.
`void`
`setNsideAndScheme(long nside_in, Scheme scheme_in)`
Adjusts the object to nside_in and scheme_in.
`void`
`setScheme(Scheme scheme_in)`
Adjusts the object to scheme.
`long`
`vec2pix(Vec3 vec)`
Returns the pixel which contains the supplied Vec3.
`protected long`
`xyf2pix(int ix, int iy, int face_num)`
`protected long`
`xyf2pix(HealpixBase.Xyf xyf)`
`long`
`zphi2pix(Zphi zphi)`
Returns the pixel which contains the supplied Zphi.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### order_max

public static final int order_max
Maximum order parameter

See Also:
  - Constant Field Values

### ns_max

public static final long ns_max
Maximum Nside parameter; equivalent to 2^`order_max`.

See Also:
  - Constant Field Values

### order

protected int order
The order of the map; -1 when `nside` is not a power of 2.

### nside

protected long nside
The Nside parameter.

### nl2

protected long nl2

### nl3

protected long nl3

### nl4

protected long nl4

### npface

protected long npface

### npix

protected long npix

### ncap

protected long ncap

### fact1

protected double fact1

### fact2

protected double fact2

### scheme

protected Scheme scheme
The ordering scheme.

## Constructor Details

### HealpixBase

public HealpixBase()
Initializes the object to Nside=1 and scheme=NESTED.

### HealpixBase

public HealpixBase(long nside_in, Scheme scheme_in) throws Exception
Initializes the object to a user-supplied Nside and ordering scheme.

Parameters:
  `nside_in` - the Nside parameter
  `scheme_in` - the ordering scheme
Throws:
  `Exception`

## Method Details

### ring2xyf

protected HealpixBase.Xyf ring2xyf(long pix)

### pix2xyf

protected HealpixBase.Xyf pix2xyf(long pix)

### xyf2pix

protected long xyf2pix(int ix, int iy, int face_num)

### xyf2pix

protected long xyf2pix(HealpixBase.Xyf xyf)

### nside2order

public static int nside2order(long nside) throws Exception
Calculates the map order from its Nside parameter.

Parameters:
  `nside` - the Nside parameter
Returns:
  the map order corresponding to `nside`; -1 if `nside` is not a power of 2.
Throws:
  `Exception`

### npix2Nside

public static long npix2Nside(long npix) throws Exception
Calculates the Nside parameter from the number of pixels.

Parameters:
  `npix` - the number of pixels
Returns:
  the computed Nside parameter
Throws:
  `Exception`

### nside2Npix

public static long nside2Npix(long nside) throws Exception
Calculates the number of pixels from the Nside parameter.

Parameters:
  `nside` - the Nside parameter
Returns:
  the computed number of pixels
Throws:
  `Exception`

### order2Npix

public static long order2Npix(int order) throws Exception
Calculates the number of pixels from the order parameter.

Parameters:
  `order` - the order parameter
Returns:
  the computed number of pixels
Throws:
  `Exception`

### setNside

public void setNside(long nside_in) throws Exception
Adjusts the object to nside_in.

Parameters:
  `nside_in` - the new Nside parameter
Throws:
  `Exception`

### setNsideAndScheme

public void setNsideAndScheme(long nside_in, Scheme scheme_in) throws Exception
Adjusts the object to nside_in and scheme_in.

Parameters:
  `nside_in` - the new Nside parameter
  `scheme_in` - the new ordering scheme
Throws:
  `Exception`

### getScheme

public Scheme getScheme()
Returns the current ordering scheme.

Returns:
  the current ordering scheme

### getNside

public int getNside()
Returns the current Nside parameter.

Returns:
  the current Nside parameter

### getNpix

public long getNpix()
Returns the total number of pixels in the pixelisation.

Returns:
  the current total number of pixels

### setScheme

public void setScheme(Scheme scheme_in) throws Exception
Adjusts the object to scheme.

Parameters:
  `scheme_in` - the new ordering scheme
Throws:
  `Exception`

### getOrder

public int getOrder()
Returns the current order parameter.

Returns:
  the current map order parameter.

### ang2pix

public long ang2pix(Pointing ptg) throws Exception
Returns the pixel which contains the supplied Pointing.

Parameters:
  `ptg` - the requested location on the sphere.
Returns:
  the pixel number containing the location.
Throws:
  `Exception`

### pix2ang

public Pointing pix2ang(long pix) throws Exception
Returns the Pointing corresponding to the center of the supplied pixel.

Parameters:
  `pix` - the requested pixel number.
Returns:
  the pixel's center coordinates.
Throws:
  `Exception`

### vec2pix

public long vec2pix(Vec3 vec) throws Exception
Returns the pixel which contains the supplied Vec3.

Parameters:
  `vec` - the requested location on the sphere (need not be normalized).
Returns:
  the pixel number containing the location.
Throws:
  `Exception`

### pix2vec

public Vec3 pix2vec(long pix) throws Exception
Returns the normalized 3-vector corresponding to the center of the supplied pixel.

Parameters:
  `pix` - the requested pixel number.
Returns:
  the pixel's center coordinates.
Throws:
  `Exception`

### ring2nest

public long ring2nest(long ipring) throws Exception
Returns nested pixel number for the supplied ring pixel number.

Parameters:
  `ipring` - the requested pixel number in RING scheme.
Returns:
  the corresponding pixel number in NESTED scheme.
Throws:
  `Exception`

### nest2ring

public long nest2ring(long ipnest) throws Exception
Returns ring pixel number for the supplied nested pixel number.

Parameters:
  `ipnest` - the requested pixel number in NESTED scheme.
Returns:
  the corresponding pixel number in RING scheme.
Throws:
  `Exception`

### loc2pix

protected long loc2pix(healpix.essentials.Hploc loc)

### zphi2pix

public long zphi2pix(Zphi zphi)
Returns the pixel which contains the supplied Zphi.

Parameters:
  `zphi` - the requested location on the sphere.
Returns:
  the pixel number containing the location.

### pix2loc

protected healpix.essentials.Hploc pix2loc(long pix)

### pix2zphi

public Zphi pix2zphi(long pix)
Returns the Zphi corresponding to the center of the supplied pixel.

Parameters:
  `pix` - the requested pixel number.
Returns:
  the pixel's center coordinates.

### neighbours

public long[] neighbours(long ipix) throws Exception
Returns the neighboring pixels of ipix. This method works in both RING and NEST schemes, but is considerably faster in the NEST scheme.

Parameters:
  `ipix` - the requested pixel number.
Returns:
  array with indices of the neighboring pixels. The returned array contains (in this order) the pixel numbers of the SW, W, NW, N, NE, E, SE and S neighbor of ipix. If a neighbor does not exist (this can only happen for the W, N, E and S neighbors), its entry is set to -1.
Throws:
  `Exception`

### maxPixrad

public double maxPixrad()
Returns the maximum angular distance between a pixel center and its corners.

Returns:
  maximum angular distance between a pixel center and its corners.

### ring2z

public double ring2z(long ring)
Returns the z-coordinate (equivalent to the cosine of the colatitude) for the requested ring. This method also accepts the not-really-existing ring indices 0 and 4*Nside, which correspond to North and South Poles, respectively.

Parameters:
  `ring` - ring index: the northernmost ring in the map has index 1; ring indices are increasing towards the South pole.
Returns:
  z-coordinate of the ring.

### ring2theta

public double ring2theta(long ring)
Returns the colatitude for the requested ring. This method also accepts the not-really-existing ring indices 0 and 4*Nside, which correspond to North and South Poles, respectively.

Parameters:
  `ring` - ring index: the northernmost ring in the map has index 1; ring indices are increasing towards the South pole.
Returns:
  z-coordinate of the ring.

### queryStrip

public RangeSet queryStrip(double theta1, double theta2, boolean inclusive) throws Exception
Returns a range set of pixels whose centers lie within a given latitude range (if `inclusive==false`), or which overlap with this range (if `inclusive==true`).

The latitude range is defined as follows:

- if `theta1<theta2`, it is the range between `theta1` and `theta2`
- otherwise it is the range between 0 and `theta2`, and between `theta1` and pi.

This method currently only works in the RING scheme.

Throws:
  `Exception`

### queryDisc

public RangeSet queryDisc(Pointing ptg, double radius) throws Exception
Returns a range set of pixels whose centers lie within a given disk.

This method is more efficient in the RING scheme.

Parameters:
  `ptg` - the angular coordinates of the disk center
  `radius` - the radius (in radians) of the disk
Returns:
  the requested set of pixel number ranges
Throws:
  `Exception`

### queryDiscInclusive

public RangeSet queryDiscInclusive(Pointing ptg, double radius, int fact) throws Exception
Returns a range set of pixels which overlap with a given disk.

This method is more efficient in the RING scheme.

This method may return some pixels which don't overlap with the polygon at all. The higher `fact` is chosen, the fewer false positives are returned, at the cost of increased run time.

Parameters:
  `ptg` - the angular coordinates of the disk center
  `radius` - the radius (in radians) of the disk
  `fact` - The overlapping test will be done at the resolution `fact*nside`. For NESTED ordering, `fact` must be a power of 2, else it can be any positive integer. A typical choice would be 4.
Returns:
  the requested set of pixel number ranges
Throws:
  `Exception`

### queryPolygon

public RangeSet queryPolygon(Pointing[] vertex) throws Exception
Returns a range set of pixels whose centers lie within the convex polygon defined by the `vertex` array.

This method is more efficient in the RING scheme.

Parameters:
  `vertex` - an array containing the vertices of the requested convex polygon.
Returns:
  the requested set of pixel number ranges
Throws:
  `Exception`

### queryPolygonInclusive

public RangeSet queryPolygonInclusive(Pointing[] vertex, int fact) throws Exception
Returns a range set of pixels that overlap with the convex polygon defined by the `vertex` array.

This method is more efficient in the RING scheme.

This method may return some pixels which don't overlap with the polygon at all. The higher `fact` is chosen, the fewer false positives are returned, at the cost of increased run time.

Parameters:
  `vertex` - an array containing the vertices of the requested convex polygon.
  `fact` - The overlapping test will be done at the resolution `fact*nside`. For NESTED ordering, `fact` must be a power of 2, else it can be any positive integer. A typical choice would be 4.
Returns:
  the requested set of pixel number ranges
Throws:
  `Exception`

### pix2ring

public long pix2ring(long pix)
Compute ring index from pixel number. Works in both RING and NESTED schemes

Parameters:
  `pix` - pixel number
Returns:
  ring index (1 to 4Nside-1)

### boundaries

public Vec3[] boundaries(long pix, int step) throws Exception
Returns a set of points along the boundary of the given pixel. Step 1 gives 4 points on the corners. The first point corresponds to the northernmost corner, the subsequent points follow the pixel boundary through west, south and east corners.

Parameters:
  `pix` - pixel index number
  `step` - the number of returned points is 4*step
Returns:
  `Vec3` for each point
Throws:
  `Exception`