Package cds.healpix

# Class HealpixNestedFast

java.lang.Object
cds.healpix.HealpixNestedFast

All Implemented Interfaces:
  `HashComputer`, `HierarchyItem`, `NeighbourSelector`, `VerticesAndPathComputer`

public final class HealpixNestedFast extends Object implements HashComputer, VerticesAndPathComputer, NeighbourSelector
A faster, thread-safe, but ugly (sorry: less readable) version of `HealpixNested`. The code has also been "denormalise" to try to be faster: we introduce redundancy by suppressing method calls when a method must return more than one elements, ... Motivations: in Java, all arguments of a function are passed-by-value. And, like most languages, a function returns only one output. It means that if, e.g. a function as to return a pair of coordinate you have only two solutions: the first one is to instantiate an object containing the pair of coordinates and return it, or the method have to take an object and set the pair of coordinates. In this "fast version", we duplicate code to avoid creating objects inside critical methods and we write the results in arguments instead of returning new objects. The instantiation of an object in Java is cheap, but it cost is not negligible compared to the speed of HEALPix methods.

Author:
  F.-X. Pineau

## Field Summary

Fields
Modifier and Type
Field
Description
`static final byte[][]`
`D0H_NEIGHBOURS`
For each of the 12 hash of depth 0, contains the list of the depth 0 neighbours sorted by increasing hash value.
`static final byte[][][]`
`NEIGHBOURS`

### Fields inherited from interface cds.healpix.NeighbourSelector

`ALL_MAIN_WINDS`

### Fields inherited from interface cds.healpix.VerticesAndPathComputer

`ALL_CARDINAL_POINTS, LAT_INDEX, LON_INDEX`

## Constructor Summary

Constructors
Constructor
Description
`HealpixNestedFast(int depth, FillingCurve2DType fillingCurveType)`

## Method Summary

Modifier and Type
Method
Description
`double[]`
`center(long hash)`
Compute the position on the unit sphere of the center (in the Euclidean projection plane) of the cell associated to the given hash value.
`void`
`center(long hash, double[] resultLonLat)`
See `VerticesAndPathComputer.center(long)`, except that the result is stored in the given array.
`int`
`depth()`
Returns the depth of the hash computed by `HashComputer.hash(double, double)` method.
`FlatHashList`
`externalEdges(long hash, int deltaDepth)`
`void`
`externalEdges(long hash, int toEdgeDeltaDepth, FlatHashList result)`
`long`
`hash(double lonRad, double latRad)`
Returns the HEALPix hash value of the given coordinate at this object depth.
`long`
`internalCorner(long hash, int toEdgeDeltaDepth, CompassPoint.Cardinal direction)`
`long`
`internalCornerE(long hash, int toEdgeDeltaDepth)`
`long`
`internalCornerN(long hash, int toEdgeDeltaDepth)`
`long`
`internalCornerS(long hash, int toEdgeDeltaDepth)`
`long`
`internalCornerW(long hash, int toEdgeDeltaDepth)`
`FlatHashList`
`internalEdges(long hash, int toEdgeDeltaDepth)`
`void`
`internalEdges(long hash, int toEdgeDeltaDepth, FlatHashList result)`
`long`
`neighbour(long hash, CompassPoint.MainWind direction)`
The hash value of the neighbour of the cell of given hash, in the given deirection.
`NeighbourList`
`neighbours(long hash)`
Returns the list of the hash of the cells surrounding the cell defined by the given hash.
`void`
`neighbours(long hash, FlatHashList neighbours)`
Idem as `NeighbourSelector.neighbours(long, NeighbourList)` except that the result is put in a simple `FlatHashList`.
`void`
`neighbours(long hash, NeighbourList result)`
Equivalent of `NeighbourSelector.neighbours(long)` but passing in argument the list object to be filled.
`NeighbourList`
`neighbours(long hash, EnumSet<CompassPoint.MainWind> directions)`
Equivalent of `NeighbourSelector.neighbours(long, FlatHashList)` but with the list of direction of the wanted neighbours.
`void`
`neighbours(long hash, EnumSet<CompassPoint.MainWind> directions, NeighbourList result)`
Equivalent of `NeighbourSelector.neighbours(long, FlatHashList)` but with the list of direction of the wanted neighbours.
`double[][]`
`pathAlongCellEdge(long hash, CompassPoint.Cardinal startingVertex, boolean clockwiseDirection, int nSegmentsBySide)`
`void`
`pathAlongCellEdge(long hash, CompassPoint.Cardinal startingVertex, boolean clockwiseDirection, int nSegmentsBySide, double[][] pathPoints)`
See `VerticesAndPathComputer.pathAlongCellEdge(long, Cardinal, boolean, int)`.
`double[][]`
`pathAlongCellSide(long hash, CompassPoint.Cardinal fromVertex, CompassPoint.Cardinal toVertex, boolean isToVertexIncluded, int nSegments)`
Compute points on a given side of a given HEALPix cell on the unit sphere.
`void`
`pathAlongCellSide(long hash, CompassPoint.Cardinal fromVertex, CompassPoint.Cardinal toVertex, boolean isToVertexIncluded, int nSegments, double[][] pathPoints)`
See `VerticesAndPathComputer.pathAlongCellSide(long, Cardinal, Cardinal, boolean, int)`.
`FlatHashList`
`sortedExternalEdges(long hash, int deltaDepth)`
`void`
`sortedExternalEdges(long hash, int toEdgeDeltaDepth, FlatHashList result)`
`FlatHashList`
`sortedInternalEdge(long hash, int deltaDepth, CompassPoint.Ordinal direction)`
`void`
`sortedInternalEdge(long hash, int deltaDepth, CompassPoint.Ordinal direction, FlatHashList result)`
`FlatHashList`
`sortedInternalEdgeNE(long hash, int deltaDepth)`
`void`
`sortedInternalEdgeNE(long hash, int deltaDepth, FlatHashList result)`
`FlatHashList`
`sortedInternalEdgeNW(long hash, int deltaDepth)`
`void`
`sortedInternalEdgeNW(long hash, int deltaDepth, FlatHashList result)`
`FlatHashList`
`sortedInternalEdges(long hash, int deltaDepth)`
`void`
`sortedInternalEdges(long hash, int toEdgeDeltaDepth, FlatHashList result)`
`FlatHashList`
`sortedInternalEdgeSE(long hash, int deltaDepth)`
`void`
`sortedInternalEdgeSE(long hash, int deltaDepth, FlatHashList result)`
`FlatHashList`
`sortedInternalEdgeSW(long hash, int deltaDepth)`
`void`
`sortedInternalEdgeSW(long hash, int deltaDepth, FlatHashList result)`
`double[]`
`vertex(long hash, CompassPoint.Cardinal cardinalPoint)`
Compute the position of an HEALPix cell vertex on the unit sphere.
`void`
`vertex(long hash, CompassPoint.Cardinal vertexDirection, double[] resultLonLat)`
See `VerticesAndPathComputer.vertex(long, Cardinal)`, except that the result is stored in the given array.
`void`
`vertices(long hash, EnumMap<CompassPoint.Cardinal,double[]> cardinalPoints)`
See `VerticesAndPathComputer.vertices(long, EnumSet)`.
`EnumMap<CompassPoint.Cardinal,double[]>`
`vertices(long hash, EnumSet<CompassPoint.Cardinal> cardinalPoints)`
Returns the vertices located at the given cardinal points.

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

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

## Field Details

### D0H_NEIGHBOURS

public static final byte[][] D0H_NEIGHBOURS
For each of the 12 hash of depth 0, contains the list of the depth 0 neighbours sorted by increasing hash value.

### NEIGHBOURS

public static final byte[][][] NEIGHBOURS

## Constructor Details

### HealpixNestedFast

public HealpixNestedFast(int depth, FillingCurve2DType fillingCurveType)

## 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.

### hash

public long hash(double lonRad, double latRad)
Description copied from interface: `HashComputer`
Returns the HEALPix hash value of the given coordinate at this object depth. WARNING: depending on the implementation, this method may or may not be thread-safe.

Specified by:
  `hash` in interface `HashComputer`
Parameters:
  `lonRad` - longitude in radians, must support reasonably large positive and negative values producing accurate results with a naive range reduction like modulo 2*pi (i.e. without having to resort on Cody-Waite or Payne Hanek range reduction).
  `latRad` - latitude in [-pi/2, pi/2] radians
Returns:
  the hash value associated to the given coordinate, at this object depth.

### 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 vertexDirection, 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.
  `vertexDirection` - 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.

### neighbours

public void neighbours(long hash, FlatHashList neighbours)
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
  `neighbours` - which contains the list of neighbours from index 0 to the number of neighbours

### 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 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, 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, 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 toEdgeDeltaDepth)

Specified by:
  `internalEdges` in interface `NeighbourSelector`

### internalEdges

public void internalEdges(long hash, int toEdgeDeltaDepth, 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 toEdgeDeltaDepth, 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`

### 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`

### 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`

### 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 toEdgeDeltaDepth, CompassPoint.Cardinal direction)

Specified by:
  `internalCorner` in interface `NeighbourSelector`

### internalCornerN

public long internalCornerN(long hash, int toEdgeDeltaDepth)

Specified by:
  `internalCornerN` in interface `NeighbourSelector`

### internalCornerS

public long internalCornerS(long hash, int toEdgeDeltaDepth)

Specified by:
  `internalCornerS` in interface `NeighbourSelector`

### internalCornerE

public long internalCornerE(long hash, int toEdgeDeltaDepth)

Specified by:
  `internalCornerE` in interface `NeighbourSelector`

### internalCornerW

public long internalCornerW(long hash, int toEdgeDeltaDepth)

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 toEdgeDeltaDepth, 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 toEdgeDeltaDepth, FlatHashList result)

Specified by:
  `sortedExternalEdges` in interface `NeighbourSelector`