Package cds.healpix

Class HealpixNested

java.lang.Object
cds.healpix.HealpixNested
All Implemented Interfaces:
HashComputer, HierarchyItem, NeighbourSelector, VerticesAndPathComputer

public final class HealpixNested extends Object implements HashComputer, VerticesAndPathComputer, NeighbourSelector
Implementation of the HEALPix tessellation using the NESTED scheme: the NESTED scheme consists in the concatenation of 12 z-order curves, one by HEALPix base cell.
The hash value in the NESTED scheme is build as follow: 0...0bbbb112233...
With
  • 0...0: unused bits
  • bbbb: the 4 bits coding the base cell, in [0, 11]
  • 11: the 2 bits of the z-order curve coding depth 1
  • 22: the 2 bits of the z-order curve coding depth 2
  • 33: the 2 bits of the z-order curve coding depth 3
  • ...
The constructor is protected. to get an instance, see the Healpix.getNested(int) or Healpix.getNested(int, FillingCurve2DType). WARNING: As pointed out by Mark Taylor, to use the methods of the HashComputer and VerticesAndPathComputer interfaces, you **MUST** be sure that no other code running on the same JVM can call those methods a the same time. Else, you should use newHashComputer() and newVerticesAndPathComputer().
Author:
F.-X. Pineau
  • Method Details

    • depth

      public int depth()
      Description copied from interface: HashComputer
      Returns the depth of the hash computed by HashComputer.hash(double, double) method.
      Specified by:
      depth in interface HashComputer
      Specified by:
      depth in interface HierarchyItem
      Returns:
      the depth of the hash computed by HashComputer.hash(double, double) method.
    • newHashComputer

      public HashComputer newHashComputer()
      In multi-threaded environments, each thread must have its own HashComputer since HashComputer is not thread safe.
      Returns:
      a new HashComputer, to be used in a distinct thread.
    • newHashComputerWithAux

      public HashComputerWithAux newHashComputerWithAux(AuxiliaryAxis auxAxis)
      WARNING: the return object in not thread-safe!
      Parameters:
      auxAxis - object describing the auxiliary axis
      Returns:
      a new HashComputerWithAux, to be used in a distinct thread.
    • hash

      public long hash(double lonRad, double latRad)
      This method is **not** thread safe. For better performances, use one HashComputer created by newHashComputer() per thread. WARNING: this method IS NOT thread safe. In multi-threaded environments, use the method EXTRA WARNING: As pointed out by Mark Taylor, to use this method you **MUST** be sure that no other code running on the same JVM can call it a the same time. Else, use newHashComputer(). newHashComputer() to create a HashComputer for each thread.
      Specified by:
      hash in interface HashComputer
      Parameters:
      lonRad - longitude (in radians) of the the coordinate we want the HEALPix hash value.
      latRad - latitude (in radians) of the coordinate we want the HEALPix hash value.
      Returns:
      the HEALPix hash value of the given coordinate.
    • newVerticesAndPathComputer

      public VerticesAndPathComputer newVerticesAndPathComputer()
      Returns a VerticesAndPathComputer, to be used in a distinct thread.
      Returns:
      a VerticesAndPathComputer, to be used in a distinct thread.
    • center

      public double[] center(long hash)
      Description copied from interface: VerticesAndPathComputer
      Compute the position on the unit sphere of the center (in the Euclidean projection plane) of the cell associated to the given hash value.
      Specified by:
      center in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the unprojected center
      Returns:
      the unprojected position (on the unit sphere) of the center of the cell in the Euclidean plane. The lon and lat coordinate are stored in the returned array at indices VerticesAndPathComputer.LON_INDEX and VerticesAndPathComputer.LAT_INDEX respectively. Lat in [-pi/2, pi/2] radians, lon is in [0, 2pi] radians.
    • center

      public void center(long hash, double[] resultLonLat)
      Description copied from interface: VerticesAndPathComputer
      See VerticesAndPathComputer.center(long), except that the result is stored in the given array.
      Specified by:
      center in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the unprojected center.
      resultLonLat - array used to store the result. Must be of size >= 2.
    • vertex

      public double[] vertex(long hash, CompassPoint.Cardinal cardinalPoint)
      Description copied from interface: VerticesAndPathComputer
      Compute the position of an HEALPix cell vertex on the unit sphere.
      Specified by:
      vertex in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the given vertex.
      cardinalPoint - location of the vertex with respect to the cell center
      Returns:
      the position (on the unit sphere) of the vertex located at the given cardinal direction from the center of the given cell. The lon and lat coordinate are stored in the returned array at indices VerticesAndPathComputer.LON_INDEX and VerticesAndPathComputer.LAT_INDEX respectively. Lat is in [-pi/2, pi/2] radians, lon is in [0, 2pi] radians.
    • vertex

      public void vertex(long hash, CompassPoint.Cardinal cardinalPoint, double[] resultLonLat)
      Description copied from interface: VerticesAndPathComputer
      See VerticesAndPathComputer.vertex(long, Cardinal), except that the result is stored in the given array.
      Specified by:
      vertex in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the given vertex.
      cardinalPoint - location of the vertex with respect to the cell center
      resultLonLat - array used to store the result. Must be of size >= 2.
    • vertices

      public EnumMap<CompassPoint.Cardinal,double[]> vertices(long hash, EnumSet<CompassPoint.Cardinal> cardinalPoints)
      Description copied from interface: VerticesAndPathComputer
      Returns the vertices located at the given cardinal points. If you want the full 4 vertices, simply use EnumSet.allOf(Cardinal). For West and East vertices, use EnumSet.of(Cardinal.W, Cardinal.E).
      Specified by:
      vertices in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the given vertices.
      cardinalPoints - locations of the vertices we look for the positions
      Returns:
      the positions (on the unit sphere) of the vertices located at the given cardinal directions from the center of the given cell. The lon and lat coordinates of each vertex are stored in the arrays at indices VerticesAndPathComputer.LON_INDEX and VerticesAndPathComputer.LAT_INDEX respectively. Lat is in [-pi/2, pi/2] radians, lon is in [0, 2pi] radians.
    • vertices

      public void vertices(long hash, EnumMap<CompassPoint.Cardinal,double[]> cardinalPoints)
      Description copied from interface: VerticesAndPathComputer
      See VerticesAndPathComputer.vertices(long, EnumSet). The difference is that the user provides a pre-set Map. The structure of the Map is not modified, but the coordinates of the values (array values) are overwritten. An error will be thrown if a value is null or contains less than two elements.
      Specified by:
      vertices in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the given vertices.
      cardinalPoints - the map to be modified y
    • pathAlongCellSide

      public double[][] pathAlongCellSide(long hash, CompassPoint.Cardinal fromVertex, CompassPoint.Cardinal toVertex, boolean isToVertexIncluded, int nSegments)
      Description copied from interface: VerticesAndPathComputer
      Compute points on a given side of a given HEALPix cell on the unit sphere.
      Specified by:
      pathAlongCellSide in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for side path on the unit sphere.
      fromVertex - direction (from the cell center) of the path starting vertex
      toVertex - direction (from the cell center) of the path ending vertex
      isToVertexIncluded - if false, the result contains nSegments points and do no include the result ending vertex. Else the result contains nSegments + 1 points.
      nSegments - number of segments in the path from the starting vertex to the ending vertex
      Returns:
      a list of points on the given side of the given HEALPix cell on the unit sphere.
    • pathAlongCellSide

      public void pathAlongCellSide(long hash, CompassPoint.Cardinal fromVertex, CompassPoint.Cardinal toVertex, boolean isToVertexIncluded, int nSegments, double[][] pathPoints)
      Description copied from interface: VerticesAndPathComputer
      See VerticesAndPathComputer.pathAlongCellSide(long, Cardinal, Cardinal, boolean, int). The difference is that the user provides a list of points whose coordinates are going to be overwritten. An error will be thrown if the array (of array) is not large enough (i.e. its is smaller than nSegments or nSegments + 1) or if one of the array is null or contains less than two elements.
      Specified by:
      pathAlongCellSide in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for side path on the unit sphere.
      fromVertex - direction (from the cell center) of the path starting vertex
      toVertex - direction (from the cell center) of the path ending vertex
      isToVertexIncluded - if false, the result contains nSegments points and do no include the result ending vertex. Else the result contains nSegments + 1 points.
      nSegments - number of segments in the path from the starting vertex to the ending vertex
      pathPoints - object used to store the result.
    • pathAlongCellEdge

      public double[][] pathAlongCellEdge(long hash, CompassPoint.Cardinal startingVertex, boolean clockwiseDirection, int nSegmentsBySide)
      Specified by:
      pathAlongCellEdge in interface VerticesAndPathComputer
      Parameters:
      hash - hash value of the cell we look for the edge path on the unit sphere.
      startingVertex - direction (from the cell center) of the path starting vertex
      clockwiseDirection - if true, result points are stored in a clockwise direction order, else they are stored in counter-clockwise direction order.
      nSegmentsBySide - number of segments in each each side is divided. Hence, the total number of points in the result is 4 x nSegmentsBySide.
      Returns:
      a list of points on the given edge of the given HEALPix cell on the unit sphere, clockwise or counter-clockwise ordered.
    • pathAlongCellEdge

      public void pathAlongCellEdge(long hash, CompassPoint.Cardinal startingVertex, boolean clockwiseDirection, int nSegmentsBySide, double[][] pathPoints)
      Description copied from interface: VerticesAndPathComputer
      See VerticesAndPathComputer.pathAlongCellEdge(long, Cardinal, boolean, int). The difference is that the user provides a list of points whose coordinates are going to be overwritten. An error will be thrown if the array (of array) is not large enough (i.e. its is smaller than 4 *nSegments) or if one of the array is null or contains less than two elements.
      Specified by:
      pathAlongCellEdge in interface VerticesAndPathComputer
      Parameters:
      hash - hash hash value of the cell we look for the edge path on the unit sphere.
      startingVertex - direction (from the cell center) of the path starting vertex
      clockwiseDirection - if true, result points are stored in a clockwise direction order, else they are stored in counter-clockwise direction order.
      nSegmentsBySide - number of segments in each each side is divided. Hence, the total number of points in the result is 4 x nSegmentsBySide.
      pathPoints - object used to store the result.
    • newNeighbourSelector

      public NeighbourSelector newNeighbourSelector()
      The internal NeighbourSelector being thread-safe and unmutable, we return it instead of creating a new instance.
      Returns:
      the internal neighbour selector.
    • neighbour

      public long neighbour(long hash, CompassPoint.MainWind direction)
      Description copied from interface: NeighbourSelector
      The hash value of the neighbour of the cell of given hash, in the given deirection.
      Specified by:
      neighbour in interface NeighbourSelector
      Parameters:
      hash - ash value of the cell we are looking for the neighbour.
      direction - direction of the neighbour we are looking for.
      Returns:
      -1 if there is no neighbour in the given direction (hashes located at corners of base hases).
    • neighbours

      public NeighbourList neighbours(long hash)
      Description copied from interface: NeighbourSelector
      Returns the list of the hash of the cells surrounding the cell defined by the given hash. The number of surrounding cells can be 8 (for all cells except the cells located at the corners of the 12 depth 0 cells), 7 (for the west and east corners of the polar caps, i.e. depth 0 cells number 0, 1, 2, 4, 8, 9, 10 and 11, or for the north and south corners of the equatorial regions, i.e. depth 0 cells number 4, 5, 6 and 7), or 6 for depth 0 pixels.
      Specified by:
      neighbours in interface NeighbourSelector
      Parameters:
      hash - hash value of the cell we are looking for the neighbours.
      Returns:
      the list of neighbours hashes
    • neighbours

      public void neighbours(long hash, NeighbourList result)
      Description copied from interface: NeighbourSelector
      Equivalent of NeighbourSelector.neighbours(long) but passing in argument the list object to be filled. WARNING: the content of the provided list is overwritten, and be sure the list is large enough (at least of size 8). And the value -1 is returned if the given hash has no neighbour at the given main wind direction.
      Specified by:
      neighbours in interface NeighbourSelector
      Parameters:
      hash - the hash code we want the neighbours
      result - which contains the list of neighbours from index 0 to the number of neighbours
    • neighbours

      public void neighbours(long hash, FlatHashList result)
      Description copied from interface: NeighbourSelector
      Idem as NeighbourSelector.neighbours(long, NeighbourList) except that the result is put in a simple FlatHashList. WARNING: the content of the provided list is overwritten, and be sure the list is large enough (at least of size 8).
      Specified by:
      neighbours in interface NeighbourSelector
      Parameters:
      hash - the hash code we want the neighbours
      result - which contains the list of neighbours from index 0 to the number of neighbours
    • neighbours

      public NeighbourList neighbours(long hash, EnumSet<CompassPoint.MainWind> directions)
      Description copied from interface: NeighbourSelector
      Equivalent of NeighbourSelector.neighbours(long, FlatHashList) but with the list of direction of the wanted neighbours.
      Specified by:
      neighbours in interface NeighbourSelector
      Parameters:
      hash - hash value of the cell we are looking for the neighbours.
      directions - the directions of the neighbours we are looking for.
      Returns:
      the list of the hash of the neighbours of the cell having the given hash.
    • neighbours

      public void neighbours(long hash, EnumSet<CompassPoint.MainWind> directions, NeighbourList result)
      Description copied from interface: NeighbourSelector
      Equivalent of NeighbourSelector.neighbours(long, FlatHashList) but with the list of direction of the wanted neighbours. And the value -1 is returned if the given hash has no neighbour at the given main wind direction.
      Specified by:
      neighbours in interface NeighbourSelector
      Parameters:
      hash - hash value of the cell we are looking for the neighbours.
      directions - the directions of the neighbours we are looking for.
      result - the list holding the result.
    • internalEdges

      public FlatHashList internalEdges(long hash, int deltaDepth)
      Specified by:
      internalEdges in interface NeighbourSelector
    • internalEdges

      public void internalEdges(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      internalEdges in interface NeighbourSelector
    • sortedInternalEdges

      public FlatHashList sortedInternalEdges(long hash, int deltaDepth)
      Specified by:
      sortedInternalEdges in interface NeighbourSelector
    • sortedInternalEdges

      public void sortedInternalEdges(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedInternalEdges in interface NeighbourSelector
    • sortedInternalEdge

      public FlatHashList sortedInternalEdge(long hash, int deltaDepth, CompassPoint.Ordinal direction)
      Specified by:
      sortedInternalEdge in interface NeighbourSelector
    • sortedInternalEdge

      public void sortedInternalEdge(long hash, int deltaDepth, CompassPoint.Ordinal direction, FlatHashList result)
      Specified by:
      sortedInternalEdge in interface NeighbourSelector
    • sortedInternalEdgeNE

      public FlatHashList sortedInternalEdgeNE(long hash, int deltaDepth)
      Specified by:
      sortedInternalEdgeNE in interface NeighbourSelector
    • sortedInternalEdgeNE

      public void sortedInternalEdgeNE(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedInternalEdgeNE in interface NeighbourSelector
    • sortedInternalEdgeNW

      public FlatHashList sortedInternalEdgeNW(long hash, int deltaDepth)
      Specified by:
      sortedInternalEdgeNW in interface NeighbourSelector
    • sortedInternalEdgeNW

      public void sortedInternalEdgeNW(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedInternalEdgeNW in interface NeighbourSelector
    • sortedInternalEdgeSE

      public FlatHashList sortedInternalEdgeSE(long hash, int deltaDepth)
      Specified by:
      sortedInternalEdgeSE in interface NeighbourSelector
    • sortedInternalEdgeSE

      public void sortedInternalEdgeSE(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedInternalEdgeSE in interface NeighbourSelector
    • sortedInternalEdgeSW

      public FlatHashList sortedInternalEdgeSW(long hash, int deltaDepth)
      Specified by:
      sortedInternalEdgeSW in interface NeighbourSelector
    • sortedInternalEdgeSW

      public void sortedInternalEdgeSW(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedInternalEdgeSW in interface NeighbourSelector
    • internalCorner

      public long internalCorner(long hash, int deltaDepth, CompassPoint.Cardinal direction)
      Specified by:
      internalCorner in interface NeighbourSelector
    • internalCornerN

      public long internalCornerN(long hash, int deltaDepth)
      Specified by:
      internalCornerN in interface NeighbourSelector
    • internalCornerS

      public long internalCornerS(long hash, int deltaDepth)
      Specified by:
      internalCornerS in interface NeighbourSelector
    • internalCornerE

      public long internalCornerE(long hash, int deltaDepth)
      Specified by:
      internalCornerE in interface NeighbourSelector
    • internalCornerW

      public long internalCornerW(long hash, int deltaDepth)
      Specified by:
      internalCornerW in interface NeighbourSelector
    • externalEdges

      public FlatHashList externalEdges(long hash, int deltaDepth)
      Specified by:
      externalEdges in interface NeighbourSelector
    • externalEdges

      public void externalEdges(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      externalEdges in interface NeighbourSelector
    • sortedExternalEdges

      public FlatHashList sortedExternalEdges(long hash, int deltaDepth)
      Specified by:
      sortedExternalEdges in interface NeighbourSelector
    • sortedExternalEdges

      public void sortedExternalEdges(long hash, int deltaDepth, FlatHashList result)
      Specified by:
      sortedExternalEdges in interface NeighbourSelector
    • newConeComputer

      public HealpixNestedFixedRadiusConeComputer newConeComputer(double coneRadiusRad)
      Returns a HealpixNestedFixedRadiusConeComputer, to be used in a distinct thread.
      Parameters:
      coneRadiusRad - radius of the cone.
      Returns:
      a HealpixNestedFixedRadiusConeComputer, to be used in a distinct thread.
    • newConeComputerApprox

      public HealpixNestedFixedRadiusConeComputer newConeComputerApprox(double coneRadiusRad)
      Simpler version of the cone search, but at the cost of approximation (false positives).
      Parameters:
      coneRadiusRad - radius of the cone
      Returns:
      an object allowing to perform fixed radius cone search queries.
    • newConeComputer4Xmatch

      public HealpixNestedFixedRadiusCone4XMatch newConeComputer4Xmatch(double coneRadiusRad)
      We suppose here that the radius of the (cross-match) cone is smaller that the typical size of the cell by a factor at least 2 or 3. The algorithm is design to be very fast, at the cost of very raw approxiations (false positives).
      Parameters:
      coneRadiusRad - radius of the cone
      Returns:
      an object allowing to perform fixed radius cone search queries.
    • newPolygonComputer

      public HealpixNestedPolygonComputer newPolygonComputer()
      Returns a new instance of HealpixNestedPolygonComputer at this object depth.
      Returns:
      a new instance of HealpixNestedPolygonComputer at this object depth.
    • newEllipticalConeComputer

      public NestedEllipticalConeComputerApprox newEllipticalConeComputer(double aRad, double bRad, double paRad)
      Simple ellipse search, but at the cost of approximations (leading to false positive). The smallest the ratio between the HEALPix (deeper) cells area over the elliptical cone area , the more accurate the result is.
      Parameters:
      aRad - semi-major axis of the elliptical cone, in radians
      bRad - semi-minor axis of the elliptical cone, in radians
      paRad - position angle (using as North the point lon=0, lat = pi/2)) of the elliptical cone, in radians
      Returns:
      an object allowing to perform fixed elliptical cone search queries.
    • toRing

      public long toRing(long nestedHash)
      Returns the ring representation if the given nested hash.
      Parameters:
      nestedHash - an HEALPix cell nested hash.
      Returns:
      the ring representation if the given nested hash.
    • regularRingEncode

      public long regularRingEncode(long baseCellHash, int iInBasePixel, int jInBasePixel)
      Encode the given data into the ring scheme hash.
      Parameters:
      baseCellHash - base cell number, in [0, 12[.
      iInBasePixel - x-axis (i.e. South-East) z-curve coordinate in the base cell.
      jInBasePixel - y-axis (i.e. South West) z-curve coordinate in the base cell.
      Returns:
      the ring encoded hash of the given base cell and coordinates in the base cell.
    • toNested

      public long toNested(long ringHash)
      Returns the nested representation if the given ring hash.
      Parameters:
      ringHash - an HEALPix cell ring hash.
      Returns:
      the nested representation if the given ring hash.
    • dividedBy4Quotient

      public long dividedBy4Quotient(long d)