healpix.core
Class HealpixIndex

java.lang.Object
  extended by healpix.essentials.HealpixTables
      extended by healpix.essentials.HealpixBase
          extended by healpix.core.HealpixIndex
All Implemented Interfaces:
Serializable

public class HealpixIndex
extends HealpixBase
implements Serializable

Generic healpix routines but tied to a given NSIDE in the constructor Java version of some healpix routines from DSRI in java everything must be in a class - no functions floating about. Original algorithms Eric Hivon and Krzysztof M. Gorski. This code written by William O'Mullane extended by Emmanuel Joliet with some methods added from pix_tools F90 code port to Java. Performance for 64bits resolution improved using code from Jan Kotek and inspired in PCJ (http://pcj.sourceforge.net/)

Version:
$Id: HealpixIndex.java 164005 2011-01-10 11:10:33Z ejoliet $
Author:
William O'Mullane, extended by Emmanuel Joliet
See Also:
Serialized Form

Field Summary
static String REVISION
          the actual version from SVN
 
Fields inherited from class healpix.essentials.HealpixBase
ns_max, order_max
 
Constructor Summary
HealpixIndex()
          Default constructor nside = 1024.
HealpixIndex(int nSIDE2)
          Construct healpix routines tied to a given nside
HealpixIndex(int nside2, Scheme sch)
           
 
Method Summary
 long ang2pix_nest(double theta, double phi)
          renders the pixel number ipix ( scheme as defined for object) for a pixel which contains a point on a sphere at coordinates theta and phi, given the map resolution parameter nside
 long ang2pix_ring(double theta, double phi)
          renders the pixel number ipix (RING scheme) for a pixel which contains a point on a sphere at coordinates theta and phi, given the map resolution parameter nside the computation is made to the highest resolution available (nside=8192) and then degraded to that required (by integer division) this doesn't cost more, and it makes sure that the treatement of round-off will be consistent for every resolution
static SpatialVector 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)
static double angDist(SpatialVector v1, SpatialVector v2)
          calculates angular distance (in radians) between 2 Vectors v1 and v2.
static int bitdiff(long nside1, long nside2)
          return difference of number of bits in pixels of two nsides.
static int calculateNSide(double pixsize)
          calculate required nside given pixel size in arcsec
 SpatialVector[] corners_nest(long pix, int step)
          Returns set of points along the boundary of the given pixel in NEST scheme.
 SpatialVector[] corners_ring(long pix, int step)
          Returns set of points along the boundary of the given pixel in RING scheme.
static long[] getChildrenAt(long nside, long pix, int requiredNside)
          for a given pixel list all children pixels for it.
static double getPixRes(long nside)
          calculates angular resolution of the pixel map in arc seconds.
 double[] integration_limits_in_costh(int i_th)
          integration limits in cos(theta) for a given ring i_th, i_th > 0
 List<Long> neighbours_nest(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).
static long parentAt(long child, int childnside, int requirednside)
          return the parent PIXEL of a given pixel at some higher NSIDE.
 double[] pix2ang_nest(long ipix)
          Convert from pix number to angle renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (NESTED scheme) given the map resolution parameter nside
 double[] pix2ang_ring(long ipix)
          Convert from pix number to angle renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (RING scheme) given the map resolution parameter nside
 SpatialVector pix2vec_nest(long pix)
          Converts pix number in NEST scheme to the unit vector
 SpatialVector pix2vec_ring(long pix)
          Converts pix number in RING scheme to the unit vector
 void printVec(double[] vec)
          Prints the vec.
 LongRangeSet query_polygon(int nside, ArrayList<SpatialVector> vlist1, long nest, long inclusive)
          finds pixels that lie within a CONVEX polygon defined by its vertex on sphere
 LongRangeSet query_strip(int nside, double theta1, double theta2, long nest)
          finds pixels having a colatitude (measured from North pole) : theta1 < colatitude < theta2 with o <= theta1 < theta2 <= Pi if theta2 < theta1 then pixels with 0 <= colatitude < theta2 or theta1 < colatitude < Pi are returned
 LongRangeSet query_triangle(int nside, SpatialVector v1, SpatialVector v2, SpatialVector v3, long nest, long inclusive)
          generates a list of pixels that lie inside a triangle defined by the three vertex vectors
 LongRangeSet queryDisc(SpatialVector vec, double radius, boolean inclusive)
          now using the C++ one this is here for convenience to consruct the LongRangeSet.
 LongRangeSet queryDisc(SpatialVector vec, double radius, int nest, int inclusive)
          Deprecated. use oen without nest - scheme now in map
 int ring(long ipix)
          return ring number for given pix in ring scheme
static long ringNum(int nside, double z)
          returns the ring number in {1, 4*nside - 1} calculated from z coordinate
static double surfaceTriangle(SpatialVector v1, SpatialVector v2, SpatialVector 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.)
static double[] vec2Ang(SpatialVector v)
          converts a SpatialVector 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
static AngularPosition vec2AngularPosition(SpatialVector v)
           
 long vec2pix_nest(SpatialVector vec)
          Converts the unit vector to pix number in NEST scheme
 long vec2pix_ring(SpatialVector vec)
          Converts the unit vector to pix number in RING scheme
static SpatialVector vector(double theta, double phi)
          Construct a SpatialVector from the angle (theta,phi)
 
Methods inherited from class healpix.essentials.HealpixBase
ang2pix, boundaries, getNpix, getNside, getOrder, getScheme, maxPixrad, neighbours, nest2ring, npix2Nside, nside2Npix, nside2order, order2Npix, pix2ang, pix2ring, pix2vec, pix2zphi, queryDisc, queryDiscInclusive, queryPolygon, queryPolygonInclusive, queryStrip, ring2nest, ring2theta, ring2z, setNside, setNsideAndScheme, setScheme, vec2pix, zphi2pix
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REVISION

public static final String REVISION
the actual version from SVN

See Also:
Constant Field Values
Constructor Detail

HealpixIndex

public HealpixIndex()
Default constructor nside = 1024.


HealpixIndex

public HealpixIndex(int nSIDE2)
             throws Exception
Construct healpix routines tied to a given nside

Parameters:
nSIDE2 - resolution number
Throws:
Exception

HealpixIndex

public HealpixIndex(int nside2,
                    Scheme sch)
             throws Exception
Throws:
Exception
Method Detail

ang2pix_nest

public long ang2pix_nest(double theta,
                         double phi)
                  throws Exception
renders the pixel number ipix ( scheme as defined for object) for a pixel which contains a point on a sphere at coordinates theta and phi, given the map resolution parameter nside

Parameters:
theta - angle (along meridian), in [0,Pi], theta=0 : north pole
phi - angle (along parallel), in [0,2*Pi]
Returns:
pixel index number
Throws:
Exception

pix2ang_nest

public double[] pix2ang_nest(long ipix)
                      throws Exception
Convert from pix number to angle renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (NESTED scheme) given the map resolution parameter nside

Parameters:
ipix - pixel index number
Returns:
double array of [theta, phi] angles in radians [0,Pi], [0,2*Pi]
Throws:
Exception

pix2ang_ring

public double[] pix2ang_ring(long ipix)
                      throws Exception
Convert from pix number to angle renders theta and phi coordinates of the nominal pixel center for the pixel number ipix (RING scheme) given the map resolution parameter nside

Parameters:
ipix - pixel index number
Returns:
double array of [theta, phi] angles in radians [0,Pi], [0,2*Pi]
Throws:
Exception

ang2pix_ring

public long ang2pix_ring(double theta,
                         double phi)
                  throws Exception
renders the pixel number ipix (RING scheme) for a pixel which contains a point on a sphere at coordinates theta and phi, given the map resolution parameter nside the computation is made to the highest resolution available (nside=8192) and then degraded to that required (by integer division) this doesn't cost more, and it makes sure that the treatement of round-off will be consistent for every resolution

Parameters:
theta - angle (along meridian), in [0,Pi], theta=0 : north pole
phi - angle (along parallel), in [0,2*Pi]
Returns:
pixel index number
Throws:
Exception

integration_limits_in_costh

public double[] integration_limits_in_costh(int i_th)
integration limits in cos(theta) for a given ring i_th, i_th > 0

Parameters:
i_th - ith ring
Returns:
limits

ring

public int ring(long ipix)
         throws Exception
return ring number for given pix in ring scheme

Parameters:
ipix - pixel index number in ring scheme
Returns:
ring number
Throws:
Exception

vector

public static SpatialVector vector(double theta,
                                   double phi)
Construct a SpatialVector from the angle (theta,phi)

Parameters:
theta - angle (along meridian), in [0,Pi], theta=0 : north pole
phi - angle (along parallel), in [0,2*Pi]
Returns:
vector SpatialVector

vec2pix_nest

public long vec2pix_nest(SpatialVector vec)
                  throws Exception
Converts the unit vector to pix number in NEST scheme

Parameters:
vec - SpatialVector
Returns:
pixel index number in nest scheme
Throws:
Exception

vec2pix_ring

public long vec2pix_ring(SpatialVector vec)
                  throws Exception
Converts the unit vector to pix number in RING scheme

Parameters:
vec - SpatialVector
Returns:
pixel index number in ring scheme
Throws:
Exception

pix2vec_nest

public SpatialVector pix2vec_nest(long pix)
                           throws Exception
Converts pix number in NEST scheme to the unit vector

Parameters:
pix - pixel index number in nest scheme
Returns:
SpatialVector
Throws:
Exception

pix2vec_ring

public SpatialVector pix2vec_ring(long pix)
                           throws Exception
Converts pix number in RING scheme to the unit vector

Parameters:
pix - pixel index number in ring scheme
Returns:
SpatialVector
Throws:
Exception

corners_nest

public SpatialVector[] corners_nest(long pix,
                                    int step)
                             throws Exception
Returns set of points along the boundary of the given pixel in NEST scheme. Step 1 gives 4 points on the corners.

Parameters:
pix - pixel index number in nest scheme
step -
Returns:
SpatialVector for each points
Throws:
Exception

corners_ring

public SpatialVector[] corners_ring(long pix,
                                    int step)
                             throws Exception
Returns set of points along the boundary of the given pixel in RING scheme. Step 1 gives 4 points on the corners. Mainly for graphics = you may not want to use LARGE NSIDEs..

Parameters:
pix - pixel index number in ring scheme
step -
Returns:
SpatialVector for each points
Throws:
Exception

getPixRes

public static double getPixRes(long nside)
calculates angular resolution of the pixel map in arc seconds.

Parameters:
nside -
Returns:
double resolution in arcsec

calculateNSide

public static int calculateNSide(double pixsize)
calculate required nside given pixel size in arcsec

Parameters:
pixsize - in arcsec
Returns:
long nside parameter

ang2Vec

public static SpatialVector 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 - angle (along meridian), in [0,Pi], theta=0 : north pole
phi - angle (along parallel), in [0,2*Pi]
Returns:
SpatialVector
Throws:
IllegalArgumentException

vec2AngularPosition

public static AngularPosition vec2AngularPosition(SpatialVector v)

vec2Ang

public static double[] vec2Ang(SpatialVector v)
converts a SpatialVector 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 - SpatialVector
Returns:
double[] out_tup out_tup[0] = theta out_tup[1] = phi

surfaceTriangle

public static double surfaceTriangle(SpatialVector v1,
                                     SpatialVector v2,
                                     SpatialVector v3)
                              throws 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 - SpatialVector
v2 - SpatialVector
v3 - SpatialVector vertices of the triangle
Returns:
double the triangle surface in steradians of the spherical triangle with vertices vec1, vec2, vec3
Throws:
Exception

angDist

public static double angDist(SpatialVector v1,
                             SpatialVector v2)
                      throws Exception
calculates angular distance (in radians) between 2 Vectors v1 and v2.

Parameters:
v1 - SpatialVector
v2 - SpatialVector
Returns:
double dist
Throws:
Exception

queryDisc

public LongRangeSet queryDisc(SpatialVector vec,
                              double radius,
                              int nest,
                              int inclusive)
                       throws Exception
Deprecated. use oen without nest - scheme now in map

now using the C++ one this is here for compatibility

Parameters:
vec -
radius -
nest -
inclusive -
Returns:
a LongRangeSet containing all relevant pixels
Throws:
Exception

queryDisc

public LongRangeSet queryDisc(SpatialVector vec,
                              double radius,
                              boolean inclusive)
                       throws Exception
now using the C++ one this is here for convenience to consruct the LongRangeSet. It somply calls the queryDisc passing in a LongRangeSetBuilder.

Parameters:
vec -
radius -
inclusive -
Returns:
a LongRangeSet containing all relevant pixels
Throws:
Exception

ringNum

public static long ringNum(int 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

query_polygon

public LongRangeSet query_polygon(int nside,
                                  ArrayList<SpatialVector> vlist1,
                                  long nest,
                                  long inclusive)
                           throws Exception
finds pixels that lie within a CONVEX polygon defined by its vertex on sphere

Parameters:
nside - the map resolution
vlist1 - 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:
Exception

printVec

public void printVec(double[] vec)
Prints the vec.

Parameters:
vec - the vec

query_triangle

public LongRangeSet query_triangle(int nside,
                                   SpatialVector v1,
                                   SpatialVector v2,
                                   SpatialVector v3,
                                   long nest,
                                   long inclusive)
                            throws Exception
generates a list of pixels that lie 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:
Exception - if the triangle is degenerated

query_strip

public LongRangeSet query_strip(int nside,
                                double theta1,
                                double theta2,
                                long nest)
                         throws Exception
finds pixels having a colatitude (measured from North pole) : theta1 < colatitude < theta2 with o <= 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:
Exception

neighbours_nest

public List<Long> neighbours_nest(long ipix)
                           throws Exception
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:
ipix - long pixel number
Returns:
ArrayList
Throws:
Exception
IllegalArgumentException

parentAt

public static long parentAt(long child,
                            int childnside,
                            int requirednside)
                     throws Exception
return the parent PIXEL of a given pixel at some higher NSIDE. One must also provide the nsode of the given pixel as otherwise it can not be known. This only makes sense for Nested Scheme. This is basically a simple bit shift in the difference of number of bits between the two NSIDEs.

Parameters:
child - the pixel
childnside - nside of the pixel
requirednside - nside to upgrade to
Returns:
the new pixel number
Throws:
Exception

bitdiff

public static int bitdiff(long nside1,
                          long nside2)
return difference of number of bits in pixels of two nsides.

Parameters:
nside1 -
nside2 -
Returns:
number of bits difference between the pixel ids.

getChildrenAt

public static long[] getChildrenAt(long nside,
                                   long pix,
                                   int requiredNside)
                            throws Exception
for a given pixel list all children pixels for it. This is simply a matter of shifting the pixel number left by the difference in NSIDE bits and then listing all numbers which fill the empty bits. BEWARE - not checking you are not trying to go too DEEP.

Parameters:
nside - nside of pix
pix - the pixel
requiredNside - the nside you want the children at
Returns:
children pixels
Throws:
Exception

"Built from revision exported"