PixTools (javadoc for PixTools)
Date: 2012-07-30

gov.fnal.eag.healpix

## Class PixTools

- java.lang.Object
- - gov.fnal.eag.healpix.PixTools

-     public class PixTools
      extends java.lang.Object

  contains methods translated from HEALPix Fortran90 with increased map resolution in comparison to original Fortran code.
  Author:
    N Kuropatkin Created on Mar 10, 2005 Modified on December 18 2007 Corrected arithmetic and mistyping April 20 2008, Mark Taylor made modifications to make the class thread safe 11-Jan-2012

    All methods are thread safe. This class can be used as a singleton, the singleton instance being available from the `getInstance()` method. For compatibility with previous versions however it is possible to construct new instances using the default constructor.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static double` | `HALFPI`
    `private static int` | `ns_max`
    `private static double` | `PI`
    `private static long[]` | `pix2x`
    `private static long[]` | `pix2y`
    `private static int` | `pixmax`
    `private static PixTools` | `pixTools` Singleton instance.
    `private static double` | `TWOPI`
    `private static double` | `twothird`
    `private static long[]` | `x2pix`
    `private static int` | `xmax`
    `private static int` | `xmid`
    `private static long[]` | `y2pix`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PixTools()` default constructor

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `ang2pix_nest(long nside, double theta, double phi)` renders the pixel number pix (NESTED scheme) for a pixel which contains a point on a sphere at coordinates theta and phi, given map resolution parameter nside.
    `long` | `ang2pix_ring(long nside, double theta, double phi)` renders the pixel number ipix (RING scheme) for a pixel which contains a point with coordinates theta and phi, given the map resolution parameter nside.
    `javax.vecmath.Vector3d` | `Ang2Vec(double theta, double phi)` calculates vector corresponding to angles theta (co-latitude measured from North pole, in [0,pi] radians) phi (longitude measured eastward in [0,2pi] radians) North pole is (x,y,z) = (0, 0, 1)
    `double` | `AngDist(javax.vecmath.Vector3d v1, javax.vecmath.Vector3d v2)` calculates angular distance (in radians) between 2 Vectors v1 and v2 In general dist = acos(v1.v2) except if the vectors are almost aligned
    `java.lang.Object[]` | `convert_inplace_long(java.lang.String subcall, java.lang.Object[] map)` converts a 8 byte Object map from RING to NESTED and vice versa in place, ie without allocation a temporary map (Has no reason for Java).
    `java.lang.Object[]` | `convert_nest2ring(long nside, java.lang.Object[] map)` make the conversion NEST to RING
    `java.lang.Object[]` | `convert_ring2nest(long nside, java.lang.Object[] map)` makes the conversion RING to NEST
    `javax.vecmath.Vector3d` | `crossProduct(javax.vecmath.Vector3d v1, javax.vecmath.Vector3d v2)` calculate cross product of two vectors
    `double` | `dotProduct(javax.vecmath.Vector3d v1, javax.vecmath.Vector3d v2)` calculates a dot product (inner product) of two 3D vectors the result is double
    `java.util.ArrayList` | `getDisc_ring(long nside, javax.vecmath.Vector3d vector0, double radius)` an obsolete method.
    `static PixTools` | `getInstance()` Returns singleton instance.
    `long` | `GetNSide(double pixsize)` calculate requared nside given pixel size in arcsec
    `java.util.ArrayList` | `InRing(long nside, long iz, double phi0, double dphi, boolean nest)` returns the list of pixels in RING or NEST scheme with latitude in [phi0 - dpi, phi0 + dphi] on the ring iz in [1, 4*nside -1 ] The pixel id numbers are in [0, 12*nside^2 - 1] the indexing is in RING, unless nest is set to 1
    `double[]` | `intrs_intrv(double[] d1, double[] d2)` computes the intersection di of 2 intervals d1 (= [a1,b1]) and d2 (= [a2,b2]) on the periodic domain (=[A,B] where A and B arbitrary) ni is the resulting number of intervals (0,1, or 2) if a1 b1 then d1 = {x | a1 <=x <= B U A <=x <=b1}
    `private PixInfo` | `makePix2Vect_Nest(long nside, long ipix)` renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside.
    `private PixInfo` | `makePix2Vect_ring(long nside, long ipix)` renders vector (x,y,z) coordinates of the nominal pixel center for pixel ipix (RING scheme) given the map resolution parameter nside.
    `private void` | `mk_pix2xy()` creates an array of pixel numbers pix2x from x and y coordinates in the face.
    `private static void` | `mk_xy2pix()` fills arrays x2pix and y2pix giving the number of the pixel laying in (x,y).
    `java.util.ArrayList` | `neighbours_nest(long nside, long ipix)` returns 7 or 8 neighbours of any pixel in the nested scheme The neighbours are ordered in the following way: First pixel is the one to the south ( the one west of the south direction is taken for pixels that don't have a southern neighbour).
    `long` | `nest2ring(long nside, long ipnest)` converts from NESTED to RING pixel numbering
    `long` | `next_in_line_nest(long nside, long ipix)` calculates the pixel that lies on the East side (and the same latitude) as the given NESTED pixel number - ipix
    `long` | `Npix2Nside(long npix)` returns nside such that npix = 12*nside^2, nside should be power of 2 and smaller than ns_max if not return -1
    `long` | `Nside2Npix(long nside)` calculates npix such that npix = 12*nside^2 ,nside should be a power of 2, and smaller than ns_max otherwise return -1
    `double[]` | `pix2ang_nest(long nside, long ipix)` Renders theta and phi coordinates of the normal pixel center for the pixel number ipix (NESTED scheme) given the map resolution parameter nside.
    `double[]` | `pix2ang_ring(long nside, long ipix)` renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (RING scheme) given the map resolution parameter nside
    `javax.vecmath.Vector3d` | `pix2vect_nest(long nside, long ipix)` renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside.
    `javax.vecmath.Vector3d` | `pix2vect_ring(long nside, long ipix)` returns the vector pointing in the center of the pixel ipix.
    `double[][]` | `pix2vertex_nest(long nside, long ipix)` renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside.
    `double[][]` | `pix2vertex_ring(long nside, long ipix)` returns double [][] with coordinates of the pixel corners.
    `private long[]` | `pix2xy_nest(long nside, long ipf)` gives the x,y coordinates in a face from pixel number within the face (NESTED) schema.
    `double` | `PixRes(long nside)` calculates angular resolution of the pixel map in arc seconds.
    `double[]` | `PolarToRaDec(double[] polar)` returns ra, dec in degrees given polar coordinates in radians
    `java.util.ArrayList` | `query_disc(long nside, javax.vecmath.Vector3d vector, double radius, int nest, int inclusive)` generates in the RING or NESTED scheme all pixels that lays within an angular distance Radius of the center.
    `java.util.ArrayList` | `query_polygon(long nside, java.util.ArrayList vlist, long nest, long inclusive)` finds pixels that lay within a CONVEX polygon defined by its vertex on sphere
    `java.util.ArrayList` | `query_strip(long nside, double theta1, double theta2, long nest)` finds pixels having a colatitude (measured from North pole) : theta1 < colatitude < theta2 with 0 <= theta1 < theta2 <= Pi if theta2 < theta1 then pixels with 0 <= colatitude < theta2 or theta1 < colatitude < Pi are returned
    `java.util.ArrayList` | `query_triangle(long nside, javax.vecmath.Vector3d v1, javax.vecmath.Vector3d v2, javax.vecmath.Vector3d v3, long nest, long inclusive)` generates a list of pixels that lay inside a triangle defined by the three vertex vectors
    `double[]` | `RaDecToPolar(double[] radec)` returns polar coordinates in radians given ra, dec in degrees
    `long` | `ring2nest(long nside, long ipring)` converts pixel number from ring numbering schema to the nested one
    `long` | `RingNum(long nside, double z)` returns the ring number in {1, 4*nside - 1} calculated from z coordinate
    `double` | `SurfaceTriangle(javax.vecmath.Vector3d v1, javax.vecmath.Vector3d v2, javax.vecmath.Vector3d v3)` calculates the surface of spherical triangle defined by vertices v1,v2,v3 Algorithm: finds triangle sides and uses l'Huilier formula to compute "spherical excess" = surface area of triangle on a sphere of radius one see, eg Bronshtein, Semendyayev Eq 2.86 half perimeter hp = 0.5*(side1+side2+side3) l'Huilier formula x0 = tan( hp/2.) x1 = tan((hp - side1)/2.) x2 = tan((hp - side2)/2.) x3 = tan((hp - side3)/2.)
    `double[]` | `Vect2Ang(javax.vecmath.Vector3d v)` converts a Vector3d in a tuple of angles tup[0] = theta co-latitude measured from North pole, in [0,PI] radians, tup[1] = phi longitude measured eastward, in [0,2PI] radians
    `long` | `vect2pix_nest(long nside, javax.vecmath.Vector3d vector)` renders the pixel number pix (NESTED scheme) for a pixel which contains a point on a sphere at coordinate vector (x,y,z), given the map resolution parameter nside.
    `long` | `vect2pix_ring(long nside, javax.vecmath.Vector3d vector)` renders the pixel number ipix (RING scheme) for a pixel which contains a point on a sphere at coordinate vector (x,y,z), given the map resolution parameter nside
    `java.util.Vector` | `VectProd(java.util.Vector v1, java.util.Vector v2)` calculates a vector production of two vectors.
    `private long` | `xy2pix_nest(long nside, long ix, long iy, long face_num)` gives the pixel number ipix (NESTED) corresponding to ix, iy and face_num
    `double[]` | `xyzToPolar(double x, double y, double z)` returns polar coordinates of a point on unit sphere given Cartesian coordinates

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### twothird

          private static final double twothird

      See Also:
        Constant Field Values

    - #### PI

          private static final double PI

      See Also:
        Constant Field Values

    - #### TWOPI

          private static final double TWOPI

      See Also:
        Constant Field Values

    - #### HALFPI

          private static final double HALFPI

      See Also:
        Constant Field Values

    - #### ns_max

          private static final int ns_max

      See Also:
        Constant Field Values

    - #### xmax

          private static final int xmax

      See Also:
        Constant Field Values

    - #### pixmax

          private static final int pixmax

      See Also:
        Constant Field Values

    - #### xmid

          private static final int xmid

      See Also:
        Constant Field Values

    - #### x2pix

          private static final long[] x2pix

    - #### y2pix

          private static final long[] y2pix

    - #### pix2x

          private static final long[] pix2x

    - #### pix2y

          private static final long[] pix2y

    - #### pixTools

          private static final PixTools pixTools

      Singleton instance.

  - ### Constructor Detail

    - #### PixTools

          public PixTools()

      default constructor

  - ### Method Detail

    - #### query_strip

          public java.util.ArrayList query_strip(long nside,
                                        double theta1,
                                        double theta2,
                                        long nest)
                                          throws java.lang.Exception

      finds pixels having a colatitude (measured from North pole) : theta1 < colatitude < theta2 with 0 <= theta1 < theta2 <= Pi if theta2 < theta1 then pixels with 0 <= colatitude < theta2 or theta1 < colatitude < Pi are returned
      Parameters:
        `nside` - long the map resolution parameter
        `theta1` - lower edge of the colatitude
        `theta2` - upper edge of the colatitude
        `nest` - long if = 1 result is in NESTED scheme
      Returns:
        ArrayList of pixel numbers (long)
      Throws:
        `java.lang.Exception`
        `java.lang.IllegalArgumentException`

    - #### query_polygon

          public java.util.ArrayList query_polygon(long nside,
                                          java.util.ArrayList vlist,
                                          long nest,
                                          long inclusive)
                                            throws java.lang.Exception

      finds pixels that lay within a CONVEX polygon defined by its vertex on sphere
      Parameters:
        `nside` - the map resolution
        `vlist` - ArrayList of vectors defining the polygon vertices
        `nest` - if set to 1 use NESTED scheme
        `inclusive` - if set 1 returns all pixels crossed by polygon boundaries
      Returns:
        ArrayList of pixels algorithm: the polygon is divided into triangles vertex 0 belongs to all triangles
      Throws:
        `java.lang.Exception`
        `java.lang.IllegalArgumentException`

    - #### query_triangle

          public java.util.ArrayList query_triangle(long nside,
                                           javax.vecmath.Vector3d v1,
                                           javax.vecmath.Vector3d v2,
                                           javax.vecmath.Vector3d v3,
                                           long nest,
                                           long inclusive)
                                             throws java.lang.Exception

      generates a list of pixels that lay inside a triangle defined by the three vertex vectors
      Parameters:
        `nside` - long map resolution parameter
        `v1` - Vector3d defines one vertex of the triangle
        `v2` - Vector3d another vertex
        `v3` - Vector3d yet another one
        `nest` - long 0 (default) RING numbering scheme, if set to 1 the NESTED scheme will be used.
        `inclusive` - long 0 (default) only pixels whose centers are inside the triangle will be listed, if set to 1 all pixels overlaping the triangle will be listed
      Returns:
        ArrayList with pixel numbers
      Throws:
        `java.lang.Exception`
        `java.lang.IllegalArgumentException`

    - #### intrs_intrv

          public double[] intrs_intrv(double[] d1,
                             double[] d2)

      computes the intersection di of 2 intervals d1 (= [a1,b1]) and d2 (= [a2,b2]) on the periodic domain (=[A,B] where A and B arbitrary) ni is the resulting number of intervals (0,1, or 2) if a1 b1 then d1 = {x | a1 <=x <= B U A <=x <=b1}
      Parameters:
        `d1` - double[] first interval
        `d2` - double[] second interval
      Returns:
        double[] one or two intervals intersections

    - #### getDisc_ring

          public java.util.ArrayList getDisc_ring(long nside,
                                         javax.vecmath.Vector3d vector0,
                                         double radius)

      an obsolete method. Use query_disc instead.
      Parameters:
        `nside` -
        `vector0` -
        `radius` -
      Returns:
        - ArrayList of long

    - #### query_disc

          public java.util.ArrayList query_disc(long nside,
                                       javax.vecmath.Vector3d vector,
                                       double radius,
                                       int nest,
                                       int inclusive)

      generates in the RING or NESTED scheme all pixels that lays within an angular distance Radius of the center.
      Parameters:
        `nside` - long map resolution
        `vector` - Vector3d pointing to the disc center
        `radius` - double angular radius of the disc (in RADIAN )
        `nest` - int 0 (default) if output is in RING scheme, if set to 1 output is in NESTED
        `inclusive` - int 0 (default) only pixels whose centers lay in the disc are listed, if set to 1, all pixels overlapping the disc are listed. In the inclusive mode the radius is increased by half the pixel size. In this case most probably all neighbor pixels will be listed even with very small radius. In case of exclusive search and very small radius when the disc lays completely inside a pixel the pixel number is returned using vector2pix method.
      Returns:
        ArrayList of pixel numbers calls: RingNum(nside, ir) InRing(nside, iz, phi0, dphi,nest) vector2pix(nside,ipix)

    - #### pix2ang_ring

          public double[] pix2ang_ring(long nside,
                              long ipix)

      renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (RING scheme) given the map resolution parameter nside
      Parameters:
        `nside` - long map resolution
        `ipix` - long pixel number
      Returns:
        double[] theta,phi

    - #### pix2vect_ring

          public javax.vecmath.Vector3d pix2vect_ring(long nside,
                                             long ipix)

      returns the vector pointing in the center of the pixel ipix. The vector is calculated by makePix2Vect_ring method
      Parameters:
        `nside` - map resolution
        `ipix` - pixel number
      Returns:
        Vector3d

    - #### pix2vertex_ring

          public double[][] pix2vertex_ring(long nside,
                                   long ipix)

      returns double [][] with coordinates of the pixel corners. The array is calculated by makePix2Vect_ring method
      Parameters:
        `nside` - map resolution
        `ipix` - pixel number
      Returns:
        double[][] list of vertex coordinates

    - #### makePix2Vect_ring

          private PixInfo makePix2Vect_ring(long nside,
                                  long ipix)

      renders vector (x,y,z) coordinates of the nominal pixel center for pixel ipix (RING scheme) given the map resolution parameter nside. It also calculates (x,y,z) positions of the four vertices in order N,W,S,E. These results are returned in a PixInfo object. Those can be used using pix2Vect_ring and pix2vert_ring methods
      Parameters:
        `nside` - long map resolution
        `ipix` - pixel number
      Returns:
        result object

    - #### ang2pix_ring

          public long ang2pix_ring(long nside,
                          double theta,
                          double phi)

      renders the pixel number ipix (RING scheme) for a pixel which contains a point with coordinates theta and phi, given the map resolution parameter nside.
      Parameters:
        `nside` - long map resolution parameter
        `theta` - double theta
        `phi` - - double phi
      Returns:
        long ipix

    - #### vect2pix_ring

          public long vect2pix_ring(long nside,
                           javax.vecmath.Vector3d vector)

      renders the pixel number ipix (RING scheme) for a pixel which contains a point on a sphere at coordinate vector (x,y,z), given the map resolution parameter nside
      Parameters:
        `nside` - long map resolution
        `vector` - Vector3d of the point coordinates
      Returns:
        long pixel number
      Throws:
        `java.lang.IllegalArgumentException`

    - #### pix2ang_nest

          public double[] pix2ang_nest(long nside,
                              long ipix)

      Renders theta and phi coordinates of the normal pixel center for the pixel number ipix (NESTED scheme) given the map resolution parameter nside.
      Parameters:
        `nside` - map resolution parameter - long
        `ipix` - long pixel number
      Returns:
        double[] (theta, phi)
      Throws:
        `java.lang.IllegalArgumentException`

    - #### pix2vect_nest

          public javax.vecmath.Vector3d pix2vect_nest(long nside,
                                             long ipix)

      renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside. Also calculates the (x,y,z) positions of 4 pixel vertices (corners) in the order N,W,S,E. These can be get using method pix2vertex_nest.
      Parameters:
        `nside` - the map resolution
        `ipix` - long pixel number
      Returns:
        Vector3d
      Throws:
        `java.lang.IllegalArgumentException`

    - #### pix2vertex_nest

          public double[][] pix2vertex_nest(long nside,
                                   long ipix)

      renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside. Also calculates the (x,y,z) positions of 4 pixel vertices (corners) in the order N,W,S,E.
      Parameters:
        `nside` - the map resolution
        `ipix` - long pixel number
      Returns:
        double[3][4] 4 sets of vector components
      Throws:
        `java.lang.IllegalArgumentException`

    - #### makePix2Vect_Nest

          private PixInfo makePix2Vect_Nest(long nside,
                                  long ipix)

      renders vector (x,y,z) coordinates of the nominal pixel center for the pixel ipix (NESTED scheme ) given the map resolution parameter nside. Tis can be get using method pix2vect_nest Also calculates the (x,y,z) positions of 4 pixel vertices (corners) in the order N,W,S,E. The result can be used using method pix2vertex_nest.
      Parameters:
        `nside` - long the map resolution
        `ipix` - long pixel number
      Returns:
        result

    - #### ang2pix_nest

          public long ang2pix_nest(long nside,
                          double theta,
                          double phi)

      renders the pixel number pix (NESTED scheme) for a pixel which contains a point on a sphere at coordinates theta and phi, given map resolution parameter nside. The computation is made to the highest resolution available and then degraded to required resolution by integer division. It makes sure that the treatment of round-off will be consistent for every resolution.
      Parameters:
        `nside` - the map resolution parameter
        `theta` - double theta coordinate in radians
        `phi` - double phi coordinate in radians
      Returns:
        pixel number long
      Throws:
        `java.lang.IllegalArgumentException`

    - #### convert_nest2ring

          public java.lang.Object[] convert_nest2ring(long nside,
                                             java.lang.Object[] map)

      make the conversion NEST to RING
      Parameters:
        `nside` - the map resolution parameter
        `map` - Object[] the map in NESTED scheme
      Returns:
        - Object[] a map in RING scheme
      Throws:
        `java.lang.IllegalArgumentException`

    - #### convert_ring2nest

          public java.lang.Object[] convert_ring2nest(long nside,
                                             java.lang.Object[] map)

      makes the conversion RING to NEST
      Parameters:
        `nside` - long resolution
        `map` - map in RING
      Returns:
        map in NEST
      Throws:
        `java.lang.IllegalArgumentException`

    - #### convert_inplace_long

          public java.lang.Object[] convert_inplace_long(java.lang.String subcall,
                                                java.lang.Object[] map)

      converts a 8 byte Object map from RING to NESTED and vice versa in place, ie without allocation a temporary map (Has no reason for Java). This method is more general but slower than convert_nest2ring. This method is a wrapper for functions ring2nest and nest2ring. Their names are supplied in the subcall argument.
      Parameters:
        `subcall` - String name of the method to use.
        `map` - Object[] map
      Returns:
        resulting Object[] map.
      Throws:
        `java.lang.IllegalArgumentException`

    - #### neighbours_nest

          public java.util.ArrayList neighbours_nest(long nside,
                                            long ipix)

      returns 7 or 8 neighbours of any pixel in the nested scheme The neighbours are ordered in the following way: First pixel is the one to the south ( the one west of the south direction is taken for pixels that don't have a southern neighbour). From then on the neighbors are ordered in the clockwise direction.
      Parameters:
        `nside` - the map resolution
        `ipix` - long pixel number
      Returns:
        ArrayList
      Throws:
        `java.lang.IllegalArgumentException`

    - #### InRing

          public java.util.ArrayList InRing(long nside,
                                   long iz,
                                   double phi0,
                                   double dphi,
                                   boolean nest)

      returns the list of pixels in RING or NEST scheme with latitude in [phi0 - dpi, phi0 + dphi] on the ring iz in [1, 4*nside -1 ] The pixel id numbers are in [0, 12*nside^2 - 1] the indexing is in RING, unless nest is set to 1
      Parameters:
        `nside` - long the map resolution
        `iz` - long ring number
        `phi0` - double
        `dphi` - double
        `nest` - boolean format flag
      Returns:
        ArrayList of pixels
      Throws:
        `java.lang.IllegalArgumentException` - Modified by N. Kuropatkin 07/09/2008 Corrected several bugs and make test of all cases.

    - #### next_in_line_nest

          public long next_in_line_nest(long nside,
                               long ipix)

      calculates the pixel that lies on the East side (and the same latitude) as the given NESTED pixel number - ipix
      Parameters:
        `nside` - long resolution
        `ipix` - long pixel number
      Returns:
        long next pixel in line
      Throws:
        `java.lang.IllegalArgumentException`

    - #### vect2pix_nest

          public long vect2pix_nest(long nside,
                           javax.vecmath.Vector3d vector)

      renders the pixel number pix (NESTED scheme) for a pixel which contains a point on a sphere at coordinate vector (x,y,z), given the map resolution parameter nside. The computation is made to the highest resolution available (nside=ns_max) and then degraded to that requared (by Integer division) this doesn't cost much, and it makes sure that the treatment of round-off will be consistent for every resolution
      Parameters:
        `nside` - long the map resolution
        `vector` - Vewctor3d the input vector
      Returns:
        pixel long
      Throws:
        `java.lang.IllegalArgumentException`

    - #### xy2pix_nest

          private long xy2pix_nest(long nside,
                         long ix,
                         long iy,
                         long face_num)

      gives the pixel number ipix (NESTED) corresponding to ix, iy and face_num
      Parameters:
        `nside` - the map resolution parameter
        `ix` - Integer x coordinate
        `iy` - Integer y coordinate
        `face_num` - long face number
      Returns:
        long pixel number ipix
      Throws:
        `java.lang.IllegalArgumentException`

    - #### pix2xy_nest

          private long[] pix2xy_nest(long nside,
                           long ipf)

      gives the x,y coordinates in a face from pixel number within the face (NESTED) schema.
      Parameters:
        `nside` - long resolution parameter
        `ipf` - long pixel number
      Returns:
        ixiy long[] contains x and y coordinates
      Throws:
        `java.lang.IllegalArgumentException`

    - #### mk_pix2xy

          private void mk_pix2xy()

      creates an array of pixel numbers pix2x from x and y coordinates in the face. Suppose NESTED scheme of pixel ordering Bits corresponding to x and y are interleaved in the pixel number in even and odd bits.

    - #### ring2nest

          public long ring2nest(long nside,
                       long ipring)

      converts pixel number from ring numbering schema to the nested one
      Parameters:
        `nside` - long resolution
        `ipring` - long pixel number in ring schema
      Returns:
        long pixel number in nest schema
      Throws:
        `java.lang.IllegalArgumentException`

    - #### nest2ring

          public long nest2ring(long nside,
                       long ipnest)

      converts from NESTED to RING pixel numbering
      Parameters:
        `nside` - long resolution
        `ipnest` - long NEST pixel number
      Returns:
        ipring long RING pixel number
      Throws:
        `java.lang.IllegalArgumentException`

    - #### mk_xy2pix

          private static void mk_xy2pix()

      fills arrays x2pix and y2pix giving the number of the pixel laying in (x,y). x and y are in [1,512] the pixel number is in [0, 512**2 -1] if i-1 = sum_p=0 b_p*2^p then ix = sum+p=0 b_p*4^p iy = 2*ix ix + iy in [0,512**2 -1]

    - #### RingNum

          public long RingNum(long nside,
                     double z)

      returns the ring number in {1, 4*nside - 1} calculated from z coordinate
      Parameters:
        `nside` - long resolution
        `z` - double z coordinate
      Returns:
        long ring number

    - #### Ang2Vec

          public javax.vecmath.Vector3d Ang2Vec(double theta,
                                       double phi)

      calculates vector corresponding to angles theta (co-latitude measured from North pole, in [0,pi] radians) phi (longitude measured eastward in [0,2pi] radians) North pole is (x,y,z) = (0, 0, 1)
      Parameters:
        `theta` - double
        `phi` - double
      Returns:
        Vector3d
      Throws:
        `java.lang.IllegalArgumentException`

    - #### Vect2Ang

          public double[] Vect2Ang(javax.vecmath.Vector3d v)

      converts a Vector3d in a tuple of angles tup[0] = theta co-latitude measured from North pole, in [0,PI] radians, tup[1] = phi longitude measured eastward, in [0,2PI] radians
      Parameters:
        `v` - Vector3d
      Returns:
        double[] out_tup out_tup[0] = theta out_tup[1] = phi

    - #### Npix2Nside

          public long Npix2Nside(long npix)

      returns nside such that npix = 12*nside^2, nside should be power of 2 and smaller than ns_max if not return -1
      Parameters:
        `npix` - long the number of pixels in the map
      Returns:
        long nside the map resolution parameter

    - #### Nside2Npix

          public long Nside2Npix(long nside)

      calculates npix such that npix = 12*nside^2 ,nside should be a power of 2, and smaller than ns_max otherwise return -1
      Parameters:
        `nside` - long the map resolution
      Returns:
        npix long the number of pixels in the map

    - #### SurfaceTriangle

          public double SurfaceTriangle(javax.vecmath.Vector3d v1,
                               javax.vecmath.Vector3d v2,
                               javax.vecmath.Vector3d v3)
                                 throws java.lang.Exception

      calculates the surface of spherical triangle defined by vertices v1,v2,v3 Algorithm: finds triangle sides and uses l'Huilier formula to compute "spherical excess" = surface area of triangle on a sphere of radius one see, eg Bronshtein, Semendyayev Eq 2.86 half perimeter hp = 0.5*(side1+side2+side3) l'Huilier formula x0 = tan( hp/2.) x1 = tan((hp - side1)/2.) x2 = tan((hp - side2)/2.) x3 = tan((hp - side3)/2.)
      Parameters:
        `v1` - Vector3d
        `v2` - Vector3d
        `v3` - Vector3d vertices of the triangle
      Returns:
        double the triangle surface
      Throws:
        `java.lang.Exception`

    - #### AngDist

          public double AngDist(javax.vecmath.Vector3d v1,
                       javax.vecmath.Vector3d v2)
                         throws java.lang.Exception

      calculates angular distance (in radians) between 2 Vectors v1 and v2 In general dist = acos(v1.v2) except if the vectors are almost aligned
      Parameters:
        `v1` - Vector3d
        `v2` - Vector3d
      Returns:
        double dist
      Throws:
        `java.lang.Exception`

    - #### VectProd

          public java.util.Vector VectProd(java.util.Vector v1,
                                  java.util.Vector v2)
                                    throws java.lang.Exception

      calculates a vector production of two vectors.
      Parameters:
        `v1` - Vectror containing 3 elements of Number type
        `v2` - Vector containing 3 elements of Number type
      Returns:
        Vector of 3 Objects of Double type
      Throws:
        `java.lang.Exception`

    - #### dotProduct

          public double dotProduct(javax.vecmath.Vector3d v1,
                          javax.vecmath.Vector3d v2)
                            throws java.lang.Exception

      calculates a dot product (inner product) of two 3D vectors the result is double
      Parameters:
        `v1` - 3d Vector of Number Objects (Double, long .. )
        `v2` - 3d Vector
      Returns:
        double
      Throws:
        `java.lang.Exception`

    - #### crossProduct

          public javax.vecmath.Vector3d crossProduct(javax.vecmath.Vector3d v1,
                                            javax.vecmath.Vector3d v2)

      calculate cross product of two vectors
      Parameters:
        `v1` - Vector3d
        `v2` - Vector3d
      Returns:
        Vector3d result of the product

    - #### PixRes

          public double PixRes(long nside)

      calculates angular resolution of the pixel map in arc seconds.
      Parameters:
        `nside` -
      Returns:
        double resolution in arcsec

    - #### GetNSide

          public long GetNSide(double pixsize)

      calculate requared nside given pixel size in arcsec
      Parameters:
        `pixsize` - in arcsec
      Returns:
        long nside parameter

    - #### RaDecToPolar

          public double[] RaDecToPolar(double[] radec)

      returns polar coordinates in radians given ra, dec in degrees
      Parameters:
        `radec` - double array containing ra,dec in degrees
      Returns:
        res double array containing theta and phi in radians res[0] = theta res[1] = phi

    - #### PolarToRaDec

          public double[] PolarToRaDec(double[] polar)

      returns ra, dec in degrees given polar coordinates in radians
      Parameters:
        `polar` - double array polar[0] = phi in radians polar[1] = theta in radians
      Returns:
        double array radec radec[0] = ra in degrees radec[1] = dec in degrees

    - #### xyzToPolar

          public double[] xyzToPolar(double x,
                            double y,
                            double z)

      returns polar coordinates of a point on unit sphere given Cartesian coordinates
      Parameters:
        `x` - - Cartesian coordinate x of a point on unit sphere
        `y` - - y coordinate
        `z` - - z coordinate
      Returns:
        double [] theta,phi

    - #### getInstance

          public static PixTools getInstance()

      Returns singleton instance.