healpix.core
Class HealpixIndex

java.lang.Object
  healpix.core.HealpixIndex

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

HealpixDataIndex, HealpixMapImp

public class HealpixIndex
extends Object
implements Serializable

Generic healpix routines but tied to a given NSIDE in the constructor Java version of some healpix routines from DSRI in java everthing 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,v 1.1.2.4 2010/02/22 14:55:50 healpix Exp $

Author:

William O'Mullane, extended by Emmanuel Joliet

See Also:

Serialized Form

REVISION

public static final String REVISION

the actual version from SVN

See Also:

Constant Field Values

ns_max

public static final int ns_max

The Constant ns_max.

See Also:

Constant Field Values

nsidelist

public static int[] nsidelist

Available nsides ..always poer of 2 ..

z0

public static final double z0

The Constant z0.

See Also:

Constant Field Values

nside

public int nside

The nside.

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

nside2order

public static int nside2order(int nside)

Gets the order from the nside

Parameters:

nside -

Returns:

order

log2

public static double log2(double num)

Log base two

Parameters:

num -

Returns:

log2

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

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

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 parametr 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

nest2ring

public long nest2ring(long ipnest)
               throws Exception

performs conversion from NESTED to RING pixel number

Parameters:

ipnest - pixel NEST index number

Returns:

RING pixel index number

Throws:

Exception

ring2nest

public long ring2nest(long ipring)
               throws Exception

performs conversion from RING to NESTED pixel number

Parameters:

ipring - pixel RING index number

Returns:

NEST 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

pixel_boundaries

public double[] pixel_boundaries(double i_th,
                                 double i_phi,
                                 int i_zone,
                                 double cos_theta)

calculate the points of crossing for a given theata on the boundaries of the pixel - returns the left and right phi crossings

Parameters:

i_th - ith pixel

i_phi - phi angle

i_zone - ith zone (0,...,3), a quarter of sphere

cos_theta - theta cosinus

Returns:

the left and right phi crossings

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 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(int 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 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

Vect2Ang

public double[] Vect2Ang(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

npix2Nside

public static long npix2Nside(long npix)

returns nside such that npix = 12*nside^2 nside should by power of 2 and smaller than ns_max if not return -1

Parameters:

npix - long the number of pixels in the map

Returns:

nside long the map resolution parameter

nside2Npix

public static long nside2Npix(int 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 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 In general dist = acos(v1.v2) except if the vectors are almost aligned

Parameters:

v1 - SpatialVector

v2 - SpatialVector

Returns:

double dist

Throws:

Exception

dotProduct

public double dotProduct(SpatialVector v1,
                         SpatialVector v2)
                  throws 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:

Exception

crossProduct

public SpatialVector crossProduct(SpatialVector v1,
                                  SpatialVector v2)

calculate cross product of two vectors

Parameters:

v1 - SpatialVector

v2 - SpatialVector

Returns:

SpatialVector result of the product

query_disc

public LongRangeSet query_disc(int nside,
                               SpatialVector vector,
                               double radius,
                               int nest,
                               int inclusive)

generates in the RING or NESTED scheme all pixels that lies 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 disk (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 pixsels whose center lie in the triangle are listed, if set to 1, all pixels overlapping the triangle are listed

Returns:

ArrayList of pixel numbers calls: RingNum(nside, ir) InRing(nside, iz, phi0, dphi,nest)

ringNum

public 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

inRing

public ArrayList<Long> inRing(long iz,
                              double phi0,
                              double dphi,
                              boolean nest)

Deprecated. use InRingLongSet

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:

iz - long ring number

phi0 - double

dphi - double

nest - boolean format flag

Returns:

ArrayList of pixels

Throws:

IllegalArgumentException

inRing

public ArrayList<Long> inRing(long iz,
                              double phi0,
                              double dphi,
                              boolean nest,
                              boolean conservative)

Deprecated. Use the InRingLongSet instead.

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:

iz - long ring number

phi0 - double

dphi - double

nest - boolean format flag

conservative - if true, include every intersected pixels, even if pixel CENTER is not in the range [phi_low, phi_hi]. If not, strict : include only pixels whose CENTER is in [phi_low, phi_hi]

Returns:

ArrayList of pixels

Throws:

IllegalArgumentException

InRing_nested_longset

public LongRangeSet InRing_nested_longset(int nside,
                                          long iz,
                                          double phi0,
                                          double dphi)
                                   throws Exception

returns the list of pixels in 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

Returns:

Long range set

Throws:

Exception

InRingLongSet

public LongRangeSet InRingLongSet(long nside,
                                  long iz,
                                  double phi0,
                                  double dphi)

returns the list of pixels in RING 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 NOTE: this is the f90 code 'in_ring' method ported to java with 'conservative' flag to false

Parameters:

nside - long the map resolution

iz - long ring number

phi0 - double

dphi - double

Returns:

set result

InRing

public void InRing(long nside,
                   long iz,
                   double phi0,
                   double dphi,
                   LongRangeSetBuilder res)

returns the list of pixels in RING 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 NOTE: this is the f90 code 'in_ring' method ported to java with 'conservative' flag to false

Parameters:

nside - long the map resolution

iz - long ring number

phi0 - double

dphi - double

res - result

inRingCxx

public ArrayList<Long> inRingCxx(long nside,
                                 long iz,
                                 double phi0,
                                 double dphi,
                                 boolean nest)

Deprecated. Don't use anymore, was only for

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 NOTE: this is the f90 code 'in_ring' method ported to java with 'conservative' flag to false

Parameters:

nside - long the map resolution

iz - long ring number

phi0 - double

dphi - double

nest - boolean format flag

Returns:

ArrayList of pixels

Throws:

IllegalArgumentException

next_in_line_nest

public long next_in_line_nest(long nside,
                              long ipix)
                       throws Exception

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:

Exception

IllegalArgumentException

query_polygon

public LongRangeSet query_polygon(int nside,
                                  ArrayList<Object> vlist,
                                  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

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:

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

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

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

getOrder

public int getOrder()

Gets the order value

Returns:

order

setOrder

public void setOrder(int order)

Sets the order

Parameters:

order -