-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
12 changed files
with
415 additions
and
126 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # Hierarchial grid functions | ||
|
|
||
| ## `GetParentForResolution` (`h3ToParent`) | ||
| Gets the parent (coarser) index at the specified resolution. | ||
| ```cs | ||
| var index = new H3Index(0x89283080dcbffff); | ||
| var parentIndex = index.GetParentForResolution(5); | ||
| ``` | ||
|
|
||
| Note that you'll get back `H3Index.Invalid` (aka upstream's `H3_NULL`) if you specify an invalid parent resolution (<= the index resolution). | ||
|
|
||
| ## `GetChildCenterForResolution` (`h3ToCenterChild`) | ||
| Gets the center child (finer) index at the specified resolution. | ||
|
|
||
| ```cs | ||
| var index = new H3Index(0x89283080dcbffff); | ||
| var childIndex = index.GetChildCenterForResolution(12); | ||
| ``` | ||
|
|
||
| As with the `GetParentForResolution` method, you'll get `H3Index.Invalid` if your child resolution is invalid (>= the index resolution). | ||
|
|
||
| ## `GetChildrenForResolution` (`h3ToChildren`) | ||
| Gets all of the child (finer) indexes at the specified resolution as an `IEnumerable<H3Index>`. | ||
|
|
||
| ```cs | ||
| var index = new H3Index(0x89283080dcbffff); | ||
| var children = index.GetChildrenAtResolution(12); | ||
|
|
||
| // iterate, use .ToList() etc.. | ||
| ``` | ||
|
|
||
| ## `Compact` (`compact`) | ||
| Takes a set of cells and compacts them by removing duplicates and pruning full child branches to the parent level. This is also done for all parents recursively to get the minimum number of indexes that perfectly cover the defined space. Returns a `List<H3Index>` (**not** an `IEnumerable<H3Index>`, so be weary of large numbers of input cells as we have to iterate / track them all as part of the compaction algorithm). | ||
|
|
||
| ```cs | ||
| // given some enumerable set of indexes.. | ||
| IEnumerable<H3Index> indexes = ...; | ||
| // .. return the compacted set | ||
| var compacted = indexes.Compact(); | ||
| ``` | ||
|
|
||
| ## `UncompactToResolution` (`uncompact`) | ||
| Takes a compacted set of cells and expands back to the original set of cells at a specific resolution. Returns an `IEnumerable<H3Index>`. | ||
|
|
||
| ```cs | ||
| // given a compacted set of indexes | ||
| var compactedIndexes = ...; | ||
| // .. get the uncompacted set at res 10 | ||
| var uncompacted = compactedIndexes.UncompactToResolution(10); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| # Indexing functions | ||
|
|
||
| ## From/To Value Types | ||
|
|
||
| ```cs | ||
| // from string (stringToH3) | ||
| var index = new H3Index("89283080dcbffff"); | ||
|
|
||
| // to string (h3ToString) | ||
| var str = index.ToString(); | ||
| ``` | ||
| ```cs | ||
| // from ulong | ||
| var index = new H3Index(0x89283080dcbffff); | ||
|
|
||
| // operators allow for implicit casting | ||
| H3Index index = 0x89283080dcbffff; | ||
| ulong value = index; | ||
| ``` | ||
|
|
||
| ## From/To Geospatial Coordinates | ||
|
|
||
| To create an index based upon a geospatial coordinate and a target H3 resolution (`geoToH3`): | ||
|
|
||
| ```cs | ||
| // from lon/lat, with a resolution of 9 -- note NTS Coordinates are longitude (X) first, | ||
| // latitude (Y) second, unlike upstream/Model.GeoCoord which is latitude then longitude | ||
| // (AND in radians, not degrees). | ||
| var coordinate = new Coordinate(-122.40898669969357, 37.81331899988944); | ||
| var index = coordinate.ToH3Index(9); | ||
| ``` | ||
| ```cs | ||
| // or if you have a Point | ||
| var index = H3Index.FromPoint(point, 9); | ||
| ``` | ||
|
|
||
| You can use `GeoCoord`s with radian inputs as well, which can be handy if you've got existing code using them you want to port over: | ||
|
|
||
| ```cs | ||
| using H3.Model; | ||
|
|
||
| var index = H3Index.FromGeoCoord(new GeoCoord(0.659966917655, -2.1364398519396), 9); | ||
| ``` | ||
|
|
||
| To get the centroid of a given H3 index (`h3ToGeo`): | ||
|
|
||
| ```cs | ||
| // gives you a NTS Coordinate | ||
| var coordinate = index.ToCoordinate(); | ||
|
|
||
| // gives you a NTS Point | ||
| var point = index.ToPoint(); | ||
|
|
||
| // gives you GeoCoord | ||
| var geoCoord = index.ToGeoCoord(); | ||
| ``` | ||
|
|
||
| ## `GetCellBoundary` (`h3ToGeoBoundary`) | ||
| Returns the `Polygon` cell boundary of a given H3 index. | ||
|
|
||
| ```cs | ||
| // gives you a NTS Polygon | ||
| var polygon = index.GetCellBoundary(); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| # Index inspection functions | ||
| The `H3Index` class provides a wrapper around an index value, and provides convenient computed fields/properties for various index attributes: | ||
|
|
||
| ```cs | ||
| // h3GetResolution | ||
| int resolution = index.Resolution; | ||
|
|
||
| // h3GetBaseCell | ||
| Nodel.BaseCell baseCell = index.BaseCell; | ||
|
|
||
| // h3IsValid | ||
| bool isValid = index.IsValid; | ||
|
|
||
| // h3IsResClassII | ||
| bool isResClass3 = Utils.IsResolutionClass3(index.Resolution); | ||
|
|
||
| // h3IsPentagon | ||
| bool isPentagon = index.IsPentagon; | ||
|
|
||
| // h3MaxFaceCount | ||
| int maxFaces = index.MaximumFaceCount; | ||
| ``` | ||
|
|
||
| Note some of these properties are computed when you access them via bitwise manipulations of the index value. So, while they aren't overly expensive, if you're repeatedly checking certain properties in a loop or somthing similar you may want to consider caching their values, e.g.: | ||
|
|
||
| ```cs | ||
| // get the resolution once, instead of each loop iteration | ||
| var resolution = index.Resolution; | ||
| for (var r = 0; r <= resolution; r += 1>) { | ||
| // ... | ||
| } | ||
| ``` | ||
|
|
||
| ## `GetFaces` (`h3GetFaces`) | ||
| Find all icosahedron faces intersected by a given index. Faces are represented as integers from 0-19, inclusive. The array is sparse, and empty (no intersection) array values are represented by -1. | ||
|
|
||
| ```cs | ||
| var faces = index.GetFaces() | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Region Functions | ||
| Converts H3 indexes to and from polygonal areas. | ||
|
|
||
| ## `Fill` (`polyfill`) | ||
| Fills a `Geometry` (`Polygon` or `LinearRing`) with the indexes who's centroids are contained within. Returns `IEnumerable<H3Index>`. Supports polygons with holes. | ||
|
|
||
| ```cs | ||
| var reader = new WKTReader(geometryFactory); | ||
| var somePolygon = reader.Read("POLYGON ((-122.40898669969356 37.81331899988944, -122.47987669969707 37.81515719990604, -122.52471869969825 37.783587199903444, -122.51234369969448 37.70761319990403, -122.35447369969584 37.719806199904276, -122.38054369969613 37.78663019990699, -122.40898669969356 37.81331899988944))"); | ||
| var filled = somePolygon.Fill(7).ToList(); | ||
| ``` | ||
|
|
||
| ### Sample Output | ||
|
|
||
| `Polygon` being filled: | ||
|  | ||
|
|
||
| Output `MultiPolygon` showing all indicies at resolution 7: | ||
|  | ||
|
|
||
| There's also an overload that takes a `LineString` and traces it, returning the indexes along the path. | ||
|
|
||
| ## `GetCellBoundaries` (`h3SetToMultiPolygon`): | ||
| Returns a `MultiPolygon` containing all of the cell boundaries of the input set of indices. | ||
|
|
||
| ```cs | ||
| var filled = somePolygon.Fill(7).ToList(); | ||
| var multiPolygon = indexes.GetCellBoundaries(); | ||
| ``` | ||
|
|
||
| This produces the second image shown above. |
Oops, something went wrong.