Package healpix.essentials

## Class HealpixBase

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

All Implemented Interfaces:
  `java.io.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
`protected class` `HealpixBase.Xyf`

### Field Summary

Fields
`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 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 int` `order_max` Maximum order parameter
`protected Scheme` `scheme` The ordering scheme.

### Fields inherited from class healpix.essentials.HealpixTables

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

### Constructor Summary

Constructors
`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

All Methods Static Methods Instance Methods Concrete Methods
`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 java.lang.Object

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

### Field Detail

#### 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 Detail

#### HealpixBase

    public HealpixBase()

Initializes the object to Nside=1 and scheme=NESTED.

#### HealpixBase

    public HealpixBase​(long nside_in,
                       Scheme scheme_in)
                throws java.lang.Exception

Initializes the object to a user-supplied Nside and ordering scheme.

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

### Method Detail

#### 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 java.lang.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:
  `java.lang.Exception`

#### npix2Nside

    public static long npix2Nside​(long npix)
                           throws java.lang.Exception

Calculates the Nside parameter from the number of pixels.

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

#### nside2Npix

    public static long nside2Npix​(long nside)
                           throws java.lang.Exception

Calculates the number of pixels from the Nside parameter.

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

#### order2Npix

    public static long order2Npix​(int order)
                           throws java.lang.Exception

Calculates the number of pixels from the order parameter.

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

#### setNside

    public void setNside​(long nside_in)
                  throws java.lang.Exception

Adjusts the object to nside_in.

Parameters:
  `nside_in` - the new Nside parameter
Throws:
  `java.lang.Exception`

#### setNsideAndScheme

    public void setNsideAndScheme​(long nside_in,
                                  Scheme scheme_in)
                           throws java.lang.Exception

Adjusts the object to nside_in and scheme_in.

Parameters:
  `nside_in` - the new Nside parameter
  `scheme_in` - the new ordering scheme
Throws:
  `java.lang.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 java.lang.Exception

Adjusts the object to scheme.

Parameters:
  `scheme_in` - the new ordering scheme
Throws:
  `java.lang.Exception`

#### getOrder

    public int getOrder()

Returns the current order parameter.

Returns:
  the current map order parameter.

#### ang2pix

    public long ang2pix​(Pointing ptg)
                 throws java.lang.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:
  `java.lang.Exception`

#### pix2ang

    public Pointing pix2ang​(long pix)
                     throws java.lang.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:
  `java.lang.Exception`

#### vec2pix

    public long vec2pix​(Vec3 vec)
                 throws java.lang.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:
  `java.lang.Exception`

#### pix2vec

    public Vec3 pix2vec​(long pix)
                 throws java.lang.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:
  `java.lang.Exception`

#### ring2nest

    public long ring2nest​(long ipring)
                   throws java.lang.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:
  `java.lang.Exception`

#### nest2ring

    public long nest2ring​(long ipnest)
                   throws java.lang.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:
  `java.lang.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 java.lang.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:
  `java.lang.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 java.lang.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:
  `java.lang.Exception`

#### queryDisc

    public RangeSet queryDisc​(Pointing ptg,
                              double radius)
                       throws java.lang.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:
  `java.lang.Exception`

#### queryDiscInclusive

    public RangeSet queryDiscInclusive​(Pointing ptg,
                                       double radius,
                                       int fact)
                                throws java.lang.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:
  `java.lang.Exception`

#### queryPolygon

    public RangeSet queryPolygon​(Pointing[] vertex)
                          throws java.lang.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:
  `java.lang.Exception`

#### queryPolygonInclusive

    public RangeSet queryPolygonInclusive​(Pointing[] vertex,
                                          int fact)
                                   throws java.lang.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:
  `java.lang.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 java.lang.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:
  `java.lang.Exception`