Class H3CoreV3
public class H3CoreV3 extends Object
This class is thread safe and can be used as a singleton. It is implemented on top of H3Core
.
Specific exceptions thrown may not be the same as V3.
This class will be removed in a future version of H3-Java.
-
Method Summary
Modifier and Type Method Description double
cellArea(long h3, AreaUnit unit)
Calculates the area of the given H3 cell.double
cellArea(String h3Address, AreaUnit unit)
Calculates the area of the given H3 cell.List<Long>
compact(Collection<Long> h3)
Returns a compacted set of indexes, at possibly coarser resolutions.List<String>
compactAddress(Collection<String> h3Addresses)
Returns a compacted set of indexes, at possibly coarser resolutions.double
edgeLength(int res, LengthUnit unit)
Returns the average edge length inunit
for indexes at resolutionres
.double
exactEdgeLength(long edge, LengthUnit unit)
Calculate the edge length of the given H3 edge.double
exactEdgeLength(String edgeAddress, LengthUnit unit)
Calculate the edge length of the given H3 edge.CoordIJ
experimentalH3ToLocalIj(long origin, long h3)
Convertsh3
to IJ coordinates in a local coordinate space defined byorigin
.CoordIJ
experimentalH3ToLocalIj(String originAddress, String h3Address)
Convertsh3Address
to IJ coordinates in a local coordinate space defined byoriginAddress
.long
experimentalLocalIjToH3(long origin, CoordIJ ij)
Converts the IJ coordinates to an index, using a local IJ coordinate space anchored byorigin
.String
experimentalLocalIjToH3(String originAddress, CoordIJ ij)
Converts the IJ coordinates to an index, using a local IJ coordinate space anchored byorigin
.long
geoToH3(double lat, double lng, int res)
Find the H3 index of the resolutionres
cell containing the lat/lon (in degrees)String
geoToH3Address(double lat, double lng, int res)
Find the H3 index of the resolutionres
cell containing the lat/lon (in degrees)long
getDestinationH3IndexFromUnidirectionalEdge(long h3)
Returns the destination index of the given unidirectional edge.String
getDestinationH3IndexFromUnidirectionalEdge(String h3)
Returns the destination index of the given unidirectional edge.List<Long>
getH3IndexesFromUnidirectionalEdge(long h3)
Returns the origin and destination indexes (in that order) of the given unidirectional edge.List<String>
getH3IndexesFromUnidirectionalEdge(String h3)
Returns the origin and destination indexes (in that order) of the given unidirectional edge.long
getH3UnidirectionalEdge(long a, long b)
Returns a unidirectional edge index representinga
towardsb
.String
getH3UnidirectionalEdge(String a, String b)
Returns a unidirectional edge index representinga
towardsb
.List<LatLng>
getH3UnidirectionalEdgeBoundary(long h3)
Returns a list of coordinates representing the given edge.List<LatLng>
getH3UnidirectionalEdgeBoundary(String h3)
Returns a list of coordinates representing the given edge.List<Long>
getH3UnidirectionalEdgesFromHexagon(long h3)
Returns all unidirectional edges originating from the given index.List<String>
getH3UnidirectionalEdgesFromHexagon(String h3)
Returns all unidirectional edges originating from the given index.long
getOriginH3IndexFromUnidirectionalEdge(long h3)
Returns the origin index of the given unidirectional edge.String
getOriginH3IndexFromUnidirectionalEdge(String h3)
Returns the origin index of the given unidirectional edge.Collection<Long>
getPentagonIndexes(int res)
Returns a collection of all topologically pentagonal cells at the given resolution.Collection<String>
getPentagonIndexesAddresses(int res)
Returns a collection of all topologically pentagonal cells at the given resolution.Collection<Long>
getRes0Indexes()
Returns a collection of all base cells (H3 indexes are resolution 0).Collection<String>
getRes0IndexesAddresses()
Returns a collection of all base cells (H3 indexes are resolution 0).List<List<List<LatLng>>>
h3AddressSetToMultiPolygon(Collection<String> h3Addresses, boolean geoJson)
Create polygons from a set of contiguous indexesint
h3Distance(long a, long b)
Returns the distance betweena
andb
.int
h3Distance(String a, String b)
Returns the distance betweena
andb
.int
h3GetBaseCell(long h3)
Returns the base cell number for this index.int
h3GetBaseCell(String h3Address)
Returns the base cell number for this index.Collection<Integer>
h3GetFaces(long h3)
Find all icosahedron faces intersected by a given H3 index, represented as integers from 0-19.Collection<Integer>
h3GetFaces(String h3)
Find all icosahedron faces intersected by a given H3 index, represented as integers from 0-19.int
h3GetResolution(long h3)
Returns the resolution of the provided indexint
h3GetResolution(String h3Address)
Returns the resolution of the provided indexboolean
h3IndexesAreNeighbors(long a, long b)
Returnstrue
if the two indexes are neighbors.boolean
h3IndexesAreNeighbors(String a, String b)
Returnstrue
if the two indexes are neighbors.boolean
h3IsPentagon(long h3)
Returnstrue
if this index is one of twelve pentagons per resolution.boolean
h3IsPentagon(String h3Address)
Returnstrue
if this index is one of twelve pentagons per resolution.boolean
h3IsResClassIII(long h3)
Determines if an index is Class III or Class II.boolean
h3IsResClassIII(String h3Address)
Determines if an index is Class III or Class II.boolean
h3IsValid(long h3)
Returns true if this is a valid H3 index.boolean
h3IsValid(String h3Address)
Returns true if this is a valid H3 index.List<Long>
h3Line(long start, long end)
Given two H3 indexes, return the line of indexes between them (inclusive of endpoints).List<String>
h3Line(String startAddress, String endAddress)
Given two H3 indexes, return the line of indexes between them (inclusive of endpoints).List<List<List<LatLng>>>
h3SetToMultiPolygon(Collection<Long> h3, boolean geoJson)
Create polygons from a set of contiguous indexeslong
h3ToCenterChild(long h3, int childRes)
Returns the center child at the given resolution.String
h3ToCenterChild(String h3, int childRes)
Returns the center child at the given resolution.List<Long>
h3ToChildren(long h3, int childRes)
Provides the children of the index at the given resolution.List<String>
h3ToChildren(String h3Address, int childRes)
Provides the children of the index at the given resolution.LatLng
h3ToGeo(long h3)
Find the latitude, longitude (both in degrees) center point of the cell.LatLng
h3ToGeo(String h3Address)
Find the latitude, longitude (degrees) center point of the cell.List<LatLng>
h3ToGeoBoundary(long h3)
Find the cell boundary in latitude, longitude (degrees) coordinates for the cellList<LatLng>
h3ToGeoBoundary(String h3Address)
Find the cell boundary in latitude, longitude (degrees) coordinates for the celllong
h3ToParent(long h3, int res)
Returns the parent of the index at the given resolution.String
h3ToParentAddress(String h3Address, int res)
Returns the parent of the index at the given resolution.String
h3ToString(long h3)
Converts fromlong
representation of an index toString
representation.boolean
h3UnidirectionalEdgeIsValid(long h3)
Returnstrue
if the given index is a valid unidirectional edge.boolean
h3UnidirectionalEdgeIsValid(String h3)
Returnstrue
if the given index is a valid unidirectional edge.double
hexArea(int res, AreaUnit unit)
Returns the average area inunit
for indexes at resolutionres
.List<List<Long>>
hexRange(long h3, int k)
Returns in order neighbor traversal.List<List<String>>
hexRange(String h3Address, int k)
Returns in order neighbor traversal.List<Long>
hexRing(long h3, int k)
Returns in order neighbor traversal, of indexes with distance ofk
.List<String>
hexRing(String h3Address, int k)
Returns in order neighbor traversal, of indexes with distance ofk
.List<Long>
kRing(long h3, int k)
Neighboring indexes in all directions.List<String>
kRing(String h3Address, int k)
Neighboring indexes in all directions.List<List<Long>>
kRingDistances(long h3, int k)
Neighboring indexes in all directions, ordered by distance from the origin index.List<List<String>>
kRingDistances(String h3Address, int k)
Neighboring indexes in all directions, ordered by distance from the origin index.List<List<String>>
kRings(String h3Address, int k)
Neighboring indexes in all directions.static H3CoreV3
newInstance()
Create by unpacking the H3 native library to disk and loading it.static H3CoreV3
newInstance(H3CoreLoader.OperatingSystem os, String arch)
Create by unpacking the H3 native library to disk and loading it.static H3CoreV3
newSystemInstance()
Create by using the H3 native library already installed on the system.long
numHexagons(int res)
Returns the number of unique H3 indexes at resolutionres
.double
pointDist(LatLng a, LatLng b, LengthUnit unit)
Return the distance along the sphere between two points.List<Long>
polyfill(List<LatLng> points, List<List<LatLng>> holes, int res)
Finds indexes within the given geofence.List<String>
polyfillAddress(List<LatLng> points, List<List<LatLng>> holes, int res)
Finds indexes within the given geofence.long
stringToH3(String h3Address)
Converts fromString
representation of an index tolong
representation.List<Long>
uncompact(Collection<Long> h3, int res)
Uncompacts all the given indexes to resolutionres
.List<String>
uncompactAddress(Collection<String> h3Addresses, int res)
Uncompacts all the given indexes to resolutionres
.
-
Method Details
-
newInstance
Create by unpacking the H3 native library to disk and loading it. The library will attempt to detect the correct operating system and architecture of native library to unpack.- Throws:
SecurityException
- Loading the library was not allowed by the SecurityManager.UnsatisfiedLinkError
- The library could not be loadedIOException
- The library could not be extracted to disk.
-
newInstance
public static H3CoreV3 newInstance(H3CoreLoader.OperatingSystem os, String arch) throws IOExceptionCreate by unpacking the H3 native library to disk and loading it. The library will attempt to extract the native library matching the given arguments to disk.- Throws:
SecurityException
- Loading the library was not allowed by the SecurityManager.UnsatisfiedLinkError
- The library could not be loadedIOException
- The library could not be extracted to disk.
-
newSystemInstance
Create by using the H3 native library already installed on the system.- Throws:
SecurityException
- The library could not be loadedUnsatisfiedLinkError
- The library could not be loaded
-
h3IsValid
public boolean h3IsValid(long h3)Returns true if this is a valid H3 index. -
h3IsValid
Returns true if this is a valid H3 index. -
h3GetBaseCell
public int h3GetBaseCell(long h3)Returns the base cell number for this index. -
h3GetBaseCell
Returns the base cell number for this index. -
h3IsPentagon
public boolean h3IsPentagon(long h3)Returnstrue
if this index is one of twelve pentagons per resolution. -
h3IsPentagon
Returnstrue
if this index is one of twelve pentagons per resolution. -
geoToH3
public long geoToH3(double lat, double lng, int res)Find the H3 index of the resolutionres
cell containing the lat/lon (in degrees)- Parameters:
lat
- Latitude in degrees.lng
- Longitude in degrees.res
- Resolution, 0 <= res <= 15- Returns:
- The H3 index.
-
geoToH3Address
Find the H3 index of the resolutionres
cell containing the lat/lon (in degrees)- Parameters:
lat
- Latitude in degrees.lng
- Longitude in degrees.res
- Resolution, 0 <= res <= 15- Returns:
- The H3 index.
-
h3ToGeo
Find the latitude, longitude (both in degrees) center point of the cell. -
h3ToGeo
Find the latitude, longitude (degrees) center point of the cell. -
h3ToGeoBoundary
Find the cell boundary in latitude, longitude (degrees) coordinates for the cell -
h3ToGeoBoundary
Find the cell boundary in latitude, longitude (degrees) coordinates for the cell -
kRing
Neighboring indexes in all directions.- Parameters:
h3Address
- Origin indexk
- Number of rings around the origin
-
kRings
Neighboring indexes in all directions.- Parameters:
h3Address
- Origin indexk
- Number of rings around the origin- Returns:
- List of
kRing(String, int)
results.
-
kRing
Neighboring indexes in all directions.- Parameters:
h3
- Origin indexk
- Number of rings around the origin
-
kRingDistances
Neighboring indexes in all directions, ordered by distance from the origin index.- Parameters:
h3Address
- Origin indexk
- Number of rings around the origin- Returns:
- A list of rings, each of which is a list of addresses. The rings are in order from closest to origin to farthest.
-
kRingDistances
Neighboring indexes in all directions, ordered by distance from the origin index.- Parameters:
h3
- Origin indexk
- Number of rings around the origin- Returns:
- A list of rings, each of which is a list of addresses. The rings are in order from closest to origin to farthest.
-
hexRange
Returns in order neighbor traversal.- Parameters:
h3Address
- Origin hexagon indexk
- Number of rings around the origin- Returns:
- A list of rings, each of which is a list of addresses. The rings are in order from closest to origin to farthest.
-
hexRange
Returns in order neighbor traversal.- Parameters:
h3
- Origin hexagon indexk
- Number of rings around the origin- Returns:
- A list of rings, each of which is a list of addresses. The rings are in order from closest to origin to farthest.
-
hexRing
Returns in order neighbor traversal, of indexes with distance ofk
.- Parameters:
h3Address
- Origin indexk
- Number of rings around the origin- Returns:
- All indexes
k
away from the origin
-
hexRing
Returns in order neighbor traversal, of indexes with distance ofk
.- Parameters:
h3
- Origin indexk
- Number of rings around the origin- Returns:
- All indexes
k
away from the origin
-
h3Distance
Returns the distance betweena
andb
. This is the grid distance, or distance expressed in number of H3 cells.In some cases H3 cannot compute the distance between two indexes. This can happen because:
- The indexes are not comparable (difference resolutions, etc)
- The distance is greater than the H3 core library supports
- The H3 library does not support finding the distance between the two cells, because of pentagonal distortion.
- Parameters:
a
- An H3 indexb
- Another H3 index- Returns:
- Distance between the two in grid cells
-
h3Distance
public int h3Distance(long a, long b)Returns the distance betweena
andb
. This is the grid distance, or distance expressed in number of H3 cells.In some cases H3 cannot compute the distance between two indexes. This can happen because:
- The indexes are not comparable (difference resolutions, etc)
- The distance is greater than the H3 core library supports
- The H3 library does not support finding the distance between the two cells, because of pentagonal distortion.
- Parameters:
a
- An H3 indexb
- Another H3 index- Returns:
- Distance between the two in grid cells
-
experimentalH3ToLocalIj
Convertsh3
to IJ coordinates in a local coordinate space defined byorigin
.The local IJ coordinate space may have deleted regions and warping due to pentagon distortion. IJ coordinates are only comparable if they came from the same origin.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
- Parameters:
origin
- Anchoring index for the local coordinate space.h3
- Index to find the coordinates of.- Returns:
- Coordinates for
h3
in the local coordinate space.
-
experimentalH3ToLocalIj
Convertsh3Address
to IJ coordinates in a local coordinate space defined byoriginAddress
.The local IJ coordinate space may have deleted regions and warping due to pentagon distortion. IJ coordinates are only comparable if they came from the same origin.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
- Parameters:
originAddress
- Anchoring index for the local coordinate space.h3Address
- Index to find the coordinates of.- Returns:
- Coordinates for
h3
in the local coordinate space.
-
experimentalLocalIjToH3
Converts the IJ coordinates to an index, using a local IJ coordinate space anchored byorigin
.The local IJ coordinate space may have deleted regions and warping due to pentagon distortion. IJ coordinates are only comparable if they came from the same origin.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
- Parameters:
origin
- Anchoring index for the local coordinate space.ij
- Coordinates in the local IJ coordinate space.- Returns:
- Index represented by
ij
-
experimentalLocalIjToH3
Converts the IJ coordinates to an index, using a local IJ coordinate space anchored byorigin
.The local IJ coordinate space may have deleted regions and warping due to pentagon distortion. IJ coordinates are only comparable if they came from the same origin.
This function is experimental, and its output is not guaranteed to be compatible across different versions of H3.
- Parameters:
originAddress
- Anchoring index for the local coordinate space.ij
- Coordinates in the local IJ coordinate space.- Returns:
- Index represented by
ij
-
h3Line
Given two H3 indexes, return the line of indexes between them (inclusive of endpoints).This function may fail to find the line between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon.
Notes:
- The specific output of this function should not be considered stable across library versions. The only guarantees the library provides are that the line length will be `h3Distance(start, end) + 1` and that every index in the line will be a neighbor of the preceding index.
- Lines are drawn in grid space, and may not correspond exactly to either Cartesian lines or great arcs.
- Parameters:
startAddress
- Start index of the lineendAddress
- End index of the line- Returns:
- Indexes making up the line.
-
h3Line
Given two H3 indexes, return the line of indexes between them (inclusive of endpoints).This function may fail to find the line between two indexes, for example if they are very far apart. It may also fail when finding distances for indexes on opposite sides of a pentagon.
Notes:
- The specific output of this function should not be considered stable across library versions. The only guarantees the library provides are that the line length will be `h3Distance(start, end) + 1` and that every index in the line will be a neighbor of the preceding index.
- Lines are drawn in grid space, and may not correspond exactly to either Cartesian lines or great arcs.
- Parameters:
start
- Start index of the lineend
- End index of the line- Returns:
- Indexes making up the line.
-
polyfillAddress
Finds indexes within the given geofence.- Parameters:
points
- Outline geofenceholes
- Geofences of any internal holesres
- Resolution of the desired indexes
-
polyfill
Finds indexes within the given geofence.- Parameters:
points
- Outline geofenceholes
- Geofences of any internal holesres
- Resolution of the desired indexes
-
h3AddressSetToMultiPolygon
public List<List<List<LatLng>>> h3AddressSetToMultiPolygon(Collection<String> h3Addresses, boolean geoJson)Create polygons from a set of contiguous indexes -
h3SetToMultiPolygon
Create polygons from a set of contiguous indexes -
h3GetResolution
Returns the resolution of the provided index -
h3GetResolution
public int h3GetResolution(long h3)Returns the resolution of the provided index -
h3ToParent
public long h3ToParent(long h3, int res)Returns the parent of the index at the given resolution.- Parameters:
h3
- H3 index.res
- Resolution of the parent,0 <= res <= h3GetResolution(h3)
- Throws:
IllegalArgumentException
-res
is not between 0 and the resolution ofh3
, inclusive.
-
h3ToParentAddress
Returns the parent of the index at the given resolution.- Parameters:
h3Address
- H3 index.res
- Resolution of the parent,0 <= res <= h3GetResolution(h3)
-
h3ToChildren
Provides the children of the index at the given resolution.- Parameters:
childRes
- Resolution of the children
-
h3ToChildren
Provides the children of the index at the given resolution.- Parameters:
h3
- H3 index.childRes
- Resolution of the children- Throws:
IllegalArgumentException
- Invalid resolution
-
h3ToCenterChild
Returns the center child at the given resolution.- Parameters:
h3
- Parent H3 indexchildRes
- Resolution of the child
-
h3ToCenterChild
public long h3ToCenterChild(long h3, int childRes)Returns the center child at the given resolution.- Parameters:
h3
- Parent H3 indexchildRes
- Resolution of the child
-
h3IsResClassIII
Determines if an index is Class III or Class II.- Returns:
true
if the index is Class III
-
h3IsResClassIII
public boolean h3IsResClassIII(long h3)Determines if an index is Class III or Class II.- Parameters:
h3
- H3 index.- Returns:
true
if the index is Class III
-
compactAddress
Returns a compacted set of indexes, at possibly coarser resolutions. -
compact
Returns a compacted set of indexes, at possibly coarser resolutions. -
uncompactAddress
Uncompacts all the given indexes to resolutionres
. -
uncompact
Uncompacts all the given indexes to resolutionres
. -
h3ToString
Converts fromlong
representation of an index toString
representation. -
stringToH3
Converts fromString
representation of an index tolong
representation. -
cellArea
Calculates the area of the given H3 cell.- Parameters:
h3Address
- Cell to find the area of.unit
- Unit to calculate the area in.- Returns:
- Cell area in the given units.
-
cellArea
Calculates the area of the given H3 cell.- Parameters:
h3
- Cell to find the area of.unit
- Unit to calculate the area in.- Returns:
- Cell area in the given units.
-
pointDist
Return the distance along the sphere between two points.- Parameters:
a
- First pointb
- Second pointunit
- Unit to return the distance in.- Returns:
- Distance from point
a
to pointb
-
exactEdgeLength
Calculate the edge length of the given H3 edge.- Parameters:
edgeAddress
- Edge to find the edge length of.unit
- Unit of measure to use.- Returns:
- Length of the given edge.
-
exactEdgeLength
Calculate the edge length of the given H3 edge.- Parameters:
edge
- Edge to find the edge length of.unit
- Unit of measure to use.- Returns:
- Length of the given edge.
-
hexArea
Returns the average area inunit
for indexes at resolutionres
.- Throws:
IllegalArgumentException
- Invalid parameter value
-
edgeLength
Returns the average edge length inunit
for indexes at resolutionres
.- Throws:
IllegalArgumentException
- Invalid parameter value
-
numHexagons
public long numHexagons(int res)Returns the number of unique H3 indexes at resolutionres
. -
getRes0IndexesAddresses
Returns a collection of all base cells (H3 indexes are resolution 0). -
getRes0Indexes
Returns a collection of all base cells (H3 indexes are resolution 0). -
getPentagonIndexesAddresses
Returns a collection of all topologically pentagonal cells at the given resolution. -
getPentagonIndexes
Returns a collection of all topologically pentagonal cells at the given resolution. -
h3IndexesAreNeighbors
public boolean h3IndexesAreNeighbors(long a, long b)Returnstrue
if the two indexes are neighbors. -
h3IndexesAreNeighbors
Returnstrue
if the two indexes are neighbors. -
getH3UnidirectionalEdge
public long getH3UnidirectionalEdge(long a, long b)Returns a unidirectional edge index representinga
towardsb
. -
getH3UnidirectionalEdge
Returns a unidirectional edge index representinga
towardsb
. -
h3UnidirectionalEdgeIsValid
public boolean h3UnidirectionalEdgeIsValid(long h3)Returnstrue
if the given index is a valid unidirectional edge. -
h3UnidirectionalEdgeIsValid
Returnstrue
if the given index is a valid unidirectional edge. -
getOriginH3IndexFromUnidirectionalEdge
public long getOriginH3IndexFromUnidirectionalEdge(long h3)Returns the origin index of the given unidirectional edge. -
getOriginH3IndexFromUnidirectionalEdge
Returns the origin index of the given unidirectional edge. -
getDestinationH3IndexFromUnidirectionalEdge
public long getDestinationH3IndexFromUnidirectionalEdge(long h3)Returns the destination index of the given unidirectional edge. -
getDestinationH3IndexFromUnidirectionalEdge
Returns the destination index of the given unidirectional edge. -
getH3IndexesFromUnidirectionalEdge
Returns the origin and destination indexes (in that order) of the given unidirectional edge. -
getH3IndexesFromUnidirectionalEdge
Returns the origin and destination indexes (in that order) of the given unidirectional edge. -
getH3UnidirectionalEdgesFromHexagon
Returns all unidirectional edges originating from the given index. -
getH3UnidirectionalEdgesFromHexagon
Returns all unidirectional edges originating from the given index. -
getH3UnidirectionalEdgeBoundary
Returns a list of coordinates representing the given edge. -
getH3UnidirectionalEdgeBoundary
Returns a list of coordinates representing the given edge. -
h3GetFaces
Find all icosahedron faces intersected by a given H3 index, represented as integers from 0-19.- Parameters:
h3
- Index to find icosahedron faces for.- Returns:
- A collection of faces intersected by the index.
-
h3GetFaces
Find all icosahedron faces intersected by a given H3 index, represented as integers from 0-19.- Parameters:
h3
- Index to find icosahedron faces for.- Returns:
- A collection of faces intersected by the index.
-