Class 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 
      Modifier and Type Class Description
      protected class  HealpixBase.Xyf  
    • Constructor Summary

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

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

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • 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

      • xyf2pix

        protected long xyf2pix​(int ix,
                               int iy,
                               int face_num)
      • 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