ExH3o

https://hexdocs.pm/ex_h3o/
Admin
ExH3o provides fast Elixir bindings for h3o, a Rust implementation of Uber's H3 geospatial indexing...
Tokens:17,507
Snippets:156
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### compact/1 examples

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Examples of compacting H3 cell sets.

```elixir
iex> children = ExH3o.children(0x8928308280fffff, 10)
iex> ExH3o.compact(children)
[0x8928308280fffff]

iex> ExH3o.compact([])
[]
```

--------------------------------

### uncompact/2 examples

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Examples of expanding compacted H3 cell sets to a target resolution.

```elixir
iex> children = ExH3o.children(0x8928308280fffff, 10)
iex> compacted = ExH3o.compact(children)
iex> uncompacted = ExH3o.uncompact(compacted, 10)
iex> Enum.sort(uncompacted) == Enum.sort(children)
true

iex> ExH3o.uncompact([0x8928308280fffff], 9)
[0x8928308280fffff]

iex> ExH3o.uncompact([], 5)
[]
```

--------------------------------

### polyfill/2 usage example

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

An example demonstrating how to use polyfill with a list of vertices to retrieve H3 cells at resolution 9.

```elixir
iex> polygon = [{37.77, -122.42}, {37.77, -122.41}, {37.78, -122.41}, {37.78, -122.42}]
iex> cells = ExH3o.polyfill(polygon, 9)
iex> length(cells) > 0
true
```

--------------------------------

### from_string/1 example

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Example showing from_string parsing a hex string into an H3 cell index.

```elixir
iex> ExH3o.from_string("8928308280fffff")
0x8928308280fffff
```

--------------------------------

### to_string/1 example

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Example showing to_string converting an H3 cell index to its hex string representation.

```elixir
iex> ExH3o.to_string(0x8928308280fffff)
"8928308280fffff"
```

--------------------------------

### is_valid/1 examples

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Examples showing is_valid returning true for a valid cell and false for an invalid one.

```elixir
iex> ExH3o.is_valid(0x8928308280fffff)
true

iex> ExH3o.is_valid(0)
false
```

--------------------------------

### is_pentagon/1 examples

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Examples showing is_pentagon returning false for a non-pentagon cell and true for a pentagon cell.

```elixir
iex> ExH3o.is_pentagon(0x8928308280fffff)
false

iex> ExH3o.is_pentagon(0x8009fffffffffff)
true
```

--------------------------------

### ExH3o usage examples

Source: https://hexdocs.pm/ex_h3o/readme.html

Shows common ExH3o operations: converting coordinates to H3 cells, round-tripping back to coordinates, grid queries (k_ring, children, parent, is_pentagon, grid_distance), and polygon fill. The example uses a coordinate near San Francisco.

```elixir
# Convert a {lat, lng} coordinate to an H3 cell at a given resolution
cell = ExH3o.from_geo({37.7749, -122.4194}, 9)
# => 617700169958686719

# Round-trip back to coordinates
ExH3o.to_geo(cell)
# => {37.77490199, -122.41942334}

# Grid queries
ExH3o.k_ring(cell, 2)           # cells within distance 2
ExH3o.children(cell, 11)        # child cells at a finer resolution
ExH3o.parent(cell, 7)           # parent cell at a coarser resolution
ExH3o.is_pentagon(cell)         # pentagon check
ExH3o.grid_distance(cell_a, cell_b)

# Polygon fill
polygon = [
  {37.770, -122.420},
  {37.770, -122.410},
  {37.780, -122.410},
  {37.780, -122.420},
  {37.770, -122.420}
]
ExH3o.polyfill(polygon, 9)
```

--------------------------------

### ExH3o invalid input raises ArgumentError

Source: https://hexdocs.pm/ex_h3o/readme.html

Demonstrates that invalid input raises an ArgumentError rather than returning an error tuple. To get {:ok, _} | {:error, _} results, wrap the call site in try/rescue.

```elixir
ExH3o.from_geo({900.0, 0.0}, 9)
# ** (ArgumentError) argument error

ExH3o.get_resolution(0)
# ** (ArgumentError) argument error
```

--------------------------------

### Get children cells with ExH3o.children/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the children cells at a specified resolution. The target resolution must be greater than or equal to the current cell's resolution.

```elixir
iex> children = ExH3o.children(0x8928308280fffff, 10)
iex> length(children)
7
```

--------------------------------

### Get parent cell with ExH3o.parent/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the parent cell at a specified coarser resolution. If the target resolution equals the current resolution, the cell itself is returned.

```elixir
iex> parent = ExH3o.parent(0x8928308280fffff, 8)
iex> ExH3o.get_resolution(parent)
8
```

--------------------------------

### Get unidirectional edge with ExH3o.get_unidirectional_edge/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the directed edge index between two neighboring cells. Both cells must share an edge.

```elixir
iex> edge = ExH3o.get_unidirectional_edge(0x8928308280fffff, 0x8928308280bffff)
iex> edge > 0
true
```

--------------------------------

### Get resolution of an H3 index

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the resolution (0-15) of the given H3 cell index. Raises ArgumentError if the index is invalid.

```elixir
@spec get_resolution(cell()) :: resolution()
```

```elixir
iex> ExH3o.get_resolution(0x8928308280fffff)
9
```

--------------------------------

### grid_distance(a, b)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the grid distance between two H3 cell indices. The grid distance is the minimum number of cell hops needed to get from one cell to the other.

```APIDOC
## grid_distance(a, b)

### Description
Returns the grid distance between two H3 cell indices. Grid distance is the minimum number of cell hops needed to get from one cell to the other.

### Function Signature
```elixir
@spec grid_distance(cell(), cell()) :: integer()
```

### Parameters
- **a** (cell) - Required - The first H3 cell index.
- **b** (cell) - Required - The second H3 cell index.

### Returns
- **integer** - The grid distance between the two cells.

### Raises
- `ArgumentError` if either cell is not a valid H3 index, or if the distance cannot be computed (cells very far apart or across pentagons).

### Example
```elixir
iex> ExH3o.grid_distance(0x8928308280fffff, 0x8928308280fffff)
0
```
```

--------------------------------

### Development Workflow Commands

Source: https://hexdocs.pm/ex_h3o/readme.html

Standard commands for fetching dependencies, compiling the project, running tests, and executing code quality tools like formatters and linters.

```bash
# Fetch deps
mix deps.get

# Compile (builds the Rust staticlib + C NIF)
mix compile

# Run the test suite
mix test

# Formatter / linter / type checker
mix format --check-formatted
mix credo --strict
mix dialyzer
```

--------------------------------

### Run performance benchmarks

Source: https://hexdocs.pm/ex_h3o/readme.html

Execute the provided benchmark scripts to compare performance against erlang-h3 on your own hardware.

```bash
mix run bench/single_cell.exs
mix run bench/collections.exs
mix run bench/polyfill.exs
```

--------------------------------

### Running Performance Benchmarks

Source: https://hexdocs.pm/ex_h3o/readme.html

Commands to execute specific benchmark suites located in the bench/ directory to measure performance across different operations.

```bash
mix run bench/single_cell.exs     # scalar per-call ops
mix run bench/collections.exs     # k_ring, children, compact, uncompact
mix run bench/polyfill.exs        # polygon fill across sizes
mix run bench/gc_deep_dive.exs    # side-by-side GC pressure measurement
mix run bench/stress.exs          # concurrent-load stress harness
```

--------------------------------

### Get base cell of an H3 index

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the base cell number (0-121) for a given H3 index. Raises ArgumentError if the index is invalid.

```elixir
@spec get_base_cell(cell()) :: non_neg_integer()
```

```elixir
iex> base = ExH3o.get_base_cell(0x8928308280fffff)
iex> base in 0..121
true
```

--------------------------------

### ExH3o usage: from_geo, to_geo, k_ring, children, parent, polyfill

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Covers core ExH3o operations: converting a coordinate to an H3 cell at resolution 9, round-tripping to coordinates, grid queries with k_ring/children/parent, and polyfill. The comments show expected return values for from_geo and to_geo.

```elixir
# Convert a coordinate to an H3 cell at resolution 9
cell = ExH3o.from_geo({37.7749, -122.4194}, 9)
# => 617_700_169_957_507_071

# Round-trip back to coordinates
ExH3o.to_geo(cell)
# => {37.77492, -122.41946}

# Grid queries
ExH3o.k_ring(cell, 2)    # all cells within distance 2
ExH3o.children(cell, 11) # child cells two resolutions deeper
ExH3o.parent(cell, 7)    # parent cell two resolutions coarser

# Polygon fill
ExH3o.polyfill([{37.77, -122.42}, {37.77, -122.41}, {37.78, -122.41}], 9)
```

--------------------------------

### ExH3o.from_string/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Parses a hex string into an H3 cell index.

```APIDOC
## ExH3o.from_string/1

### Description
Parses a hex string into an H3 cell index.

### Function
`from_string(hex)`

### Parameters
- **hex** (string) - Required - Hex string representation.

### Returns
- **cell** - H3 cell index.
```

--------------------------------

### ExH3o.get_res0_indexes/0

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns all 122 resolution 0 (base cell) H3 indexes.

```APIDOC
## ExH3o.get_res0_indexes/0

### Description
Returns all 122 resolution 0 (base cell) H3 indexes.

### Function
`get_res0_indexes()`

### Returns
- **list of cell** - All base cell indexes.
```

--------------------------------

### Add ex_h3o dependency to mix.exs

Source: https://hexdocs.pm/ex_h3o/readme.html

Adds the ex_h3o package to your Elixir project dependencies. After adding, run mix deps.get and mix compile. On supported targets, a precompiled NIF is downloaded; otherwise, a source build is performed.

```elixir
def deps do
  [
    {:ex_h3o, "~> 0.1.0"}
  ]
end
```

--------------------------------

### compact/1 specification

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Type specification for the compact function.

```elixir
@spec compact([cell()]) :: [cell()]
```

--------------------------------

### ExH3o.uncompact/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Expands a compacted set of H3 cell indices to the given resolution.

```APIDOC
## ExH3o.uncompact/2

### Description
Expands a compacted set of H3 cell indices to the given resolution.

### Function
`uncompact(cells, resolution)`

### Parameters
- **cells** (list of cell) - Required - Compacted set.
- **resolution** (resolution) - Required - Target resolution.

### Returns
- **list of cell** - Expanded set.
```

--------------------------------

### Retrieve k-ring cells with k_ring/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns all cells within a grid distance of k from the origin cell. At k=0, it returns only the origin cell.

```elixir
@spec k_ring(cell(), non_neg_integer()) :: [cell()]
```

```elixir
iex> [cell] = ExH3o.k_ring(0x8928308280fffff, 0)
iex> cell == 0x8928308280fffff
true

iex> cells = ExH3o.k_ring(0x8928308280fffff, 1)
iex> length(cells)
7
```

--------------------------------

### Calculate k-ring distances

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns a list of {cell, distance} tuples for all cells within a specified k-ring distance from the origin cell.

```elixir
iex> pairs = ExH3o.k_ring_distances(0x8928308280fffff, 1)
iex> length(pairs)
7
```

--------------------------------

### ExH3o.from_geo/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Converts geographic coordinates to an H3 cell index at the given resolution. Returns a 64-bit H3 cell index.

```APIDOC
## ExH3o.from_geo/2

### Description
Converts geographic coordinates to an H3 cell index at the given resolution.

### Function
`from_geo(arg, resolution)`

### Parameters
- **arg** (coord) - Required - Geographic coordinate as `{latitude, longitude}` in degrees.
- **resolution** (resolution) - Required - H3 resolution, 0 (coarsest) through 15 (finest).

### Returns
- **cell** (cell) - A 64-bit H3 cell index.

### Example
```elixir
cell = ExH3o.from_geo({37.7749, -122.4194}, 9)
# => 617_700_169_957_507_071
```
```

--------------------------------

### ExH3o.to_string/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Converts a valid H3 cell index to its lowercase hex string representation.

```APIDOC
## ExH3o.to_string/1

### Description
Converts a valid H3 cell index to its lowercase hex string representation.

### Function
`to_string(cell)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.

### Returns
- **string** - Lowercase hex string.
```

--------------------------------

### Calculate max_k_ring_size

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the maximum number of cells in a k-ring of size k using the formula 3k² + 3k + 1.

```elixir
@spec max_k_ring_size(non_neg_integer()) :: non_neg_integer()
```

```elixir
iex> ExH3o.max_k_ring_size(0)
1

iex> ExH3o.max_k_ring_size(1)
7

iex> ExH3o.max_k_ring_size(2)
19
```

--------------------------------

### from_geo(arg, resolution)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Converts geographic coordinates to an H3 cell index at the given resolution. Takes a {lat, lng} tuple in degrees and a resolution (0-15). Raises ArgumentError for out-of-range or non-finite coordinates, and FunctionClauseError for invalid arguments.

```APIDOC
## from_geo(arg, resolution)

### Description
Converts geographic coordinates to an H3 cell index at the given resolution. Takes a `{lat, lng}` tuple in degrees and a resolution (0-15). Returns the H3 cell index containing the given coordinates. Accepts integer coordinates as well as floats. The Elixir wrapper coerces them to floats before calling the NIF.

### Function Signature
```elixir
@spec from_geo(coord(), resolution()) :: cell()
```

### Parameters
- **arg** (coord()) - Required - A `{lat, lng}` tuple in degrees.
- **resolution** (resolution()) - Required - The H3 resolution (0-15).

### Raises
- `ArgumentError` if the coordinate is out of range (lat not in [-90, 90] or lng not in [-180, 180]) or non-finite.
- `FunctionClauseError` if `lat` or `lng` is not a number, or if `resolution` is not in 0..15.

### Example
```elixir
iex> cell = ExH3o.from_geo({37.7749, -122.4194}, 9)
iex> ExH3o.is_valid(cell)
true
```
```

--------------------------------

### uncompact(cells, resolution)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Expands a compacted set of H3 cell indices to the given resolution. Each cell is dissolved into its descendants at the target resolution. This is the inverse of compact/1.

```APIDOC
## uncompact(cells, resolution)

### Description
Expands a compacted set of H3 cell indices to the given resolution. Each cell in the input is dissolved into its descendants at the target resolution. The target resolution must be equal to or finer than every cell's resolution. When a cell is already at the target resolution, it passes through unchanged. This is the inverse of `compact/1`.

### Method
Function

### Endpoint
ExH3o.uncompact(cells, resolution)

### Parameters
#### Function Parameters
- **cells** (list of cell()) - Required - The list of H3 cell indices to expand.
- **resolution** (resolution()) - Required - The target resolution, must be in 0..15.

### Request Example
```elixir
ExH3o.uncompact(compacted, 10)
```

### Response
#### Success Response
- **uncompacted_cells** (list of cell()) - The expanded set of cells at the target resolution.

#### Response Example
```elixir
[0x8928308280fffff]
```

### Errors
- **ArgumentError** - If the input contains invalid cells, or if `resolution` is coarser than any input cell's own resolution.
- **FunctionClauseError** - If `resolution` is not in 0..15.

```

--------------------------------

### k_ring(cell, k)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the cells within k-ring distance of the given cell. The k-ring (grid disk) returns all cells whose grid distance is at most k from the origin cell.

```APIDOC
## k_ring(cell, k)

### Description
Returns the cells within k-ring distance of the given cell. k-ring (grid disk) returns all cells whose grid distance is at most `k` from the origin cell. At k=0, returns only the origin. Cell count follows the formula 3k² + 3k + 1 for hexagonal cells.

### Function Signature
```elixir
@spec k_ring(cell(), non_neg_integer()) :: [cell()]
```

### Parameters
- **cell** (cell) - Required - The origin H3 cell index.
- **k** (non_neg_integer) - Required - The ring distance.

### Returns
- **list of cell** - The list of H3 cell indices within the k-ring.

### Raises
- `ArgumentError` if `cell` is not a valid H3 index.

### Examples
```elixir
iex> [cell] = ExH3o.k_ring(0x8928308280fffff, 0)
iex> cell == 0x8928308280fffff
true

iex> cells = ExH3o.k_ring(0x8928308280fffff, 1)
iex> length(cells)
7
```
```

--------------------------------

### ExH3o.max_k_ring_size/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the maximum number of cells in a k-ring of size `k`.

```APIDOC
## ExH3o.max_k_ring_size/1

### Description
Returns the maximum number of cells in a k-ring of size `k`.

### Function
`max_k_ring_size(k)`

### Parameters
- **k** (integer) - Required - Ring size.

### Returns
- **integer** - Maximum number of cells.
```

--------------------------------

### get_res0_indexes/0

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns all 122 resolution 0 (base cell) H3 indexes, which are the ancestors of all other cells.

```elixir
@spec get_res0_indexes() :: [cell()]
```

```elixir
iex> cells = ExH3o.get_res0_indexes()
iex> length(cells)
122
```

--------------------------------

### ExH3o.get_unidirectional_edge/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the directed edge index from origin to destination.

```APIDOC
## ExH3o.get_unidirectional_edge/2

### Description
Returns the directed edge index from origin to destination.

### Function
`get_unidirectional_edge(origin, destination)`

### Parameters
- **origin** (cell) - Required - Origin cell.
- **destination** (cell) - Required - Destination cell.

### Returns
- **edge** - Directed edge index.
```

--------------------------------

### ExH3o.get_resolution/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the resolution (0-15) of the given H3 cell index.

```APIDOC
## ExH3o.get_resolution/1

### Description
Returns the resolution (0-15) of the given H3 cell index.

### Function
`get_resolution(cell)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.

### Returns
- **integer** - Resolution.
```

--------------------------------

### ExH3o.compact/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Compacts a set of H3 cell indices by replacing complete child sets with their parent cell, applied recursively.

```APIDOC
## ExH3o.compact/1

### Description
Compacts a set of H3 cell indices by replacing complete child sets with their parent cell, applied recursively.

### Function
`compact(cells)`

### Parameters
- **cells** (list of cell) - Required - Set of H3 cell indices.

### Returns
- **list of cell** - Compacted set.
```

--------------------------------

### ExH3o.children/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the children cells at the given resolution. Used for hierarchy queries.

```APIDOC
## ExH3o.children/2

### Description
Returns the children cells at the given resolution.

### Function
`children(cell, resolution)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.
- **resolution** (resolution) - Required - Target resolution for children.

### Returns
- **list of cell** - Children cells.

### Example
```elixir
ExH3o.children(cell, 11) # child cells two resolutions deeper
```
```

--------------------------------

### k_ring_distances(cell, k)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns a list of {cell, distance} tuples for each cell within k-ring distance of the given cell. The distance is the grid distance from the origin (0 for the origin itself, 1 for immediate neighbors, etc). Raises ArgumentError if the cell is not a valid H3 index.

```APIDOC
## k_ring_distances(cell, k)

### Description
Returns `{cell, distance}` tuples for each cell within k-ring distance of the given cell. The `distance` is the grid distance from the origin (0 for the origin itself, 1 for immediate neighbors, etc).

### Function Signature
```elixir
@spec k_ring_distances(cell(), non_neg_integer()) :: [{cell(), non_neg_integer()}]
```

### Parameters
- **cell** (cell()) - Required - A valid H3 index.
- **k** (non_neg_integer()) - Required - The k-ring distance.

### Raises
- `ArgumentError` if `cell` is not a valid H3 index.

### Example
```elixir
iex> pairs = ExH3o.k_ring_distances(0x8928308280fffff, 1)
iex> length(pairs)
7
```
```

--------------------------------

### ExH3o.parent/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the parent cell at the given resolution. Used for hierarchy queries.

```APIDOC
## ExH3o.parent/2

### Description
Returns the parent cell at the given resolution.

### Function
`parent(cell, resolution)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.
- **resolution** (resolution) - Required - Target resolution for parent.

### Returns
- **cell** - Parent cell.

### Example
```elixir
ExH3o.parent(cell, 7)    # parent cell two resolutions coarser
```
```

--------------------------------

### get_res0_indexes()

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns all 122 resolution 0 (base cell) H3 indexes. These are the coarsest cells in the H3 system and are the ancestors of all other cells.

```APIDOC
## get_res0_indexes()

### Description
Returns all 122 resolution 0 (base cell) H3 indexes. These are the coarsest cells in the H3 system and are the ancestors of all other cells.

### Function
`get_res0_indexes()`

### Parameters
None

### Returns
- **list of cell()** - List of all 122 resolution 0 H3 indexes.

### Example
```elixir
iex> cells = ExH3o.get_res0_indexes()
iex> length(cells)
122
```
```

--------------------------------

### cell() type definition

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Defines the cell type as a 64-bit H3 cell index.

```elixir
@type cell() :: non_neg_integer()
```

--------------------------------

### ExH3o.hex_area_m2/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the average hexagon area in square meters at the given resolution.

```APIDOC
## ExH3o.hex_area_m2/1

### Description
Returns the average hexagon area in square meters at the given resolution.

### Function
`hex_area_m2(resolution)`

### Parameters
- **resolution** (resolution) - Required - H3 resolution.

### Returns
- **float** - Area in square meters.
```

--------------------------------

### ExH3o.num_hexagons/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the total number of unique H3 indexes at the given resolution.

```APIDOC
## ExH3o.num_hexagons/1

### Description
Returns the total number of unique H3 indexes at the given resolution.

### Function
`num_hexagons(resolution)`

### Parameters
- **resolution** (resolution) - Required - H3 resolution.

### Returns
- **integer** - Number of unique indexes.
```

--------------------------------

### compact(cells)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Compacts a set of H3 cell indices by replacing complete child sets with their parent cell, applied recursively. All input cells must be at the same resolution and unique.

```APIDOC
## compact(cells)

### Description
Compacts a set of H3 cell indices by replacing complete child sets with their parent cell, applied recursively. All input cells must be at the same resolution and unique. Returns the minimal set of cells that covers the same area.

### Method
Function

### Endpoint
ExH3o.compact(cells)

### Parameters
#### Function Parameters
- **cells** (list of cell()) - Required - The list of H3 cell indices to compact.

### Request Example
```elixir
ExH3o.compact(children)
```

### Response
#### Success Response
- **compacted_cells** (list of cell()) - The minimal set of cells covering the same area.

#### Response Example
```elixir
[0x8928308280fffff]
```

### Errors
- **ArgumentError** - If the input contains invalid cells, cells at different resolutions, or duplicate cells.

```

--------------------------------

### from_string/1 spec

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Specification for the from_string function, which parses a hex string into an H3 cell index.

```elixir
@spec from_string(String.t()) :: cell()
```

--------------------------------

### uncompact/2 specification

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Type specification for the uncompact function.

```elixir
@spec uncompact([cell()], resolution()) :: [cell()]
```

--------------------------------

### ExH3o.hex_area_km2/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the average hexagon area in square kilometers at the given resolution.

```APIDOC
## ExH3o.hex_area_km2/1

### Description
Returns the average hexagon area in square kilometers at the given resolution.

### Function
`hex_area_km2(resolution)`

### Parameters
- **resolution** (resolution) - Required - H3 resolution.

### Returns
- **float** - Area in square kilometers.
```

--------------------------------

### children(cell, resolution)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the child cells of a given cell at a specified finer resolution. The target resolution must be finer than or equal to the cell's current resolution.

```APIDOC
## children(cell, resolution)

### Description
Returns the children cells at the given resolution. The target resolution must be finer than (greater than) or equal to the cell's current resolution. At the same resolution, returns a list containing only the cell itself. Hexagons produce 7 children at the next resolution; pentagons produce 6.

### Spec
@spec children(cell(), resolution()) :: [cell()]

### Parameters
- **cell** (cell()) - Required - The H3 cell index.
- **resolution** (resolution()) - Required - The target resolution, must be finer than or equal to the cell's current resolution.

### Raises
- `ArgumentError` if `cell` is not a valid H3 index, if `resolution` is coarser than the cell's own resolution, or if `resolution` is not in 0..15.

### Example
```
iex> children = ExH3o.children(0x8928308280fffff, 10)
iex> length(children)
7
```
```

--------------------------------

### to_geo_boundary/1 specification

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Type specification for the to_geo_boundary function.

```elixir
@spec to_geo_boundary(cell()) :: [coord(), ...]
```

--------------------------------

### polyfill/2 specification

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

The function specification for polyfill, which returns H3 cell indices within a polygon at a given resolution.

```elixir
@spec polyfill([coord()], resolution()) :: [cell()]
```

--------------------------------

### Calculate grid distance with grid_distance/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the minimum number of cell hops between two H3 indices. Raises ArgumentError for invalid indices or if the distance cannot be computed.

```elixir
@spec grid_distance(cell(), cell()) :: integer()
```

```elixir
iex> ExH3o.grid_distance(0x8928308280fffff, 0x8928308280fffff)
0
```

--------------------------------

### ExH3o.k_ring/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the cells within k-ring distance of the given cell. Used for grid queries.

```APIDOC
## ExH3o.k_ring/2

### Description
Returns the cells within k-ring distance of the given cell.

### Function
`k_ring(cell, k)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.
- **k** (integer) - Required - Ring distance.

### Returns
- **list of cell** - Cells within k-ring distance.

### Example
```elixir
ExH3o.k_ring(cell, 2)  # all cells within distance 2
```
```

--------------------------------

### to_geo(cell)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the center coordinates of the given H3 cell index. Returns {lat, lng} in degrees where lat is in [-90, 90] and lng is in [-180, 180]. Raises ArgumentError if the cell is not a valid H3 index.

```APIDOC
## to_geo(cell)

### Description
Returns the center coordinates of the given H3 cell index. Returns `{lat, lng}` in degrees where lat is in `[-90, 90]` and lng is in `[-180, 180]`.

### Function Signature
```elixir
@spec to_geo(cell()) :: coord()
```

### Parameters
- **cell** (cell()) - Required - A valid H3 index.

### Raises
- `ArgumentError` if `cell` is not a valid H3 index.

### Example
```elixir
iex> {lat, lng} = ExH3o.to_geo(0x8928308280fffff)
iex> lat >= -90.0 and lat <= 90.0 and lng >= -180.0 and lng <= 180.0
true
```
```

--------------------------------

### resolution() type definition

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Defines the resolution type as an integer range from 0 to 15.

```elixir
@type resolution() :: 0..15
```

--------------------------------

### to_string/1 spec

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Specification for the to_string function, which converts a valid H3 cell index to its lowercase hex string representation.

```elixir
@spec to_string(cell()) :: String.t()
```

--------------------------------

### hex_area_m2/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the average hexagon area in square meters at the given resolution, excluding pentagons. Raises FunctionClauseError if resolution is not between 0 and 15.

```elixir
@spec hex_area_m2(resolution()) :: float()
```

```elixir
iex> area = ExH3o.hex_area_m2(0)
iex> area > 4.0e12
true
```

--------------------------------

### polyfill(vertices, resolution)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the H3 cell indices whose centroids fall within the given polygon at the specified resolution. The polygon is specified as a list of {lat, lng} vertex tuples in degrees. At least 3 distinct vertices are required. Uses ContainsCentroid containment mode.

```APIDOC
## polyfill(vertices, resolution)

### Description
Returns the H3 cell indices whose centroids fall within the given polygon at the specified resolution. The polygon is specified as a list of {lat, lng} vertex tuples in degrees. At least 3 distinct vertices are required. Uses ContainsCentroid containment mode (cells whose centroids fall inside the polygon are included).

### Specification
@spec polyfill([coord()], resolution()) :: [cell()]

### Parameters
- **vertices** (list of coord()) - Required - List of {lat, lng} vertex tuples in degrees. At least 3 distinct vertices are required.
- **resolution** (resolution()) - Required - H3 resolution, 0 (coarsest) through 15 (finest).

### Raises
- **ArgumentError** if fewer than 3 vertices are provided, if any vertex is not a {float, float} tuple, or if the polygon is otherwise invalid.
- **FunctionClauseError** if vertices is not a list or resolution is not in 0..15.

### Example
```
iex> polygon = [{37.77, -122.42}, {37.77, -122.41}, {37.78, -122.41}, {37.78, -122.42}]
iex> cells = ExH3o.polyfill(polygon, 9)
iex> length(cells) > 0
true
```

### Types
#### cell()
```
@type cell() :: non_neg_integer()
```
A 64-bit H3 cell index.

#### coord()
```
@type coord() :: {float(), float()}
```
A geographic coordinate, {latitude, longitude} in degrees.

#### resolution()
```
@type resolution() :: 0..15
```
An H3 resolution, 0 (coarsest) through 15 (finest).
```

--------------------------------

### parent(cell, resolution)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the parent cell of a given cell at a specified coarser resolution. The target resolution must be coarser than or equal to the cell's current resolution.

```APIDOC
## parent(cell, resolution)

### Description
Returns the parent cell at the given resolution. The target resolution must be coarser than (less than) or equal to the cell's current resolution. When the target resolution equals the cell's resolution, the cell itself is returned (identity).

### Spec
@spec parent(cell(), resolution()) :: cell()

### Parameters
- **cell** (cell()) - Required - The H3 cell index.
- **resolution** (resolution()) - Required - The target resolution, must be coarser than or equal to the cell's current resolution.

### Raises
- `ArgumentError` if `cell` is not a valid H3 index, if `resolution` is finer than the cell's own resolution (the parent doesn't exist), or if `resolution` is not in 0..15.

### Example
```
iex> parent = ExH3o.parent(0x8928308280fffff, 8)
iex> ExH3o.get_resolution(parent)
8
```
```

--------------------------------

### ExH3o.to_geo/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the center coordinates of the given H3 cell index. Converts a cell back to a geographic coordinate.

```APIDOC
## ExH3o.to_geo/1

### Description
Returns the center coordinates of the given H3 cell index.

### Function
`to_geo(cell)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.

### Returns
- **coord** (coord) - Geographic coordinate as `{latitude, longitude}` in degrees.

### Example
```elixir
ExH3o.to_geo(cell)
# => {37.77492, -122.41946}
```
```

--------------------------------

### ExH3o.k_ring_distances/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns `{cell, distance}` tuples for each cell within k-ring distance of the given cell.

```APIDOC
## ExH3o.k_ring_distances/2

### Description
Returns `{cell, distance}` tuples for each cell within k-ring distance of the given cell.

### Function
`k_ring_distances(cell, k)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.
- **k** (integer) - Required - Ring distance.

### Returns
- **list of {cell, integer}** - Tuples of cell and distance.
```

--------------------------------

### ExH3o.is_valid/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns whether `cell` is a valid H3 cell index.

```APIDOC
## ExH3o.is_valid/1

### Description
Returns whether `cell` is a valid H3 cell index.

### Function
`is_valid(cell)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.

### Returns
- **boolean** - True if valid.
```

--------------------------------

### ExH3o.to_geo_boundary/1

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the boundary vertices of the given H3 cell index.

```APIDOC
## ExH3o.to_geo_boundary/1

### Description
Returns the boundary vertices of the given H3 cell index.

### Function
`to_geo_boundary(cell)`

### Parameters
- **cell** (cell) - Required - A 64-bit H3 cell index.

### Returns
- **list of coord** - Boundary vertices.
```

--------------------------------

### coord() type definition

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Defines the coordinate type as a tuple of latitude and longitude in degrees.

```elixir
@type coord() :: {float(), float()}
```

--------------------------------

### get_resolution(cell)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the resolution (0-15) of the given H3 cell index.

```APIDOC
## get_resolution(cell)

### Description
Returns the resolution (0-15) of the given H3 cell index.

### Function Signature
`get_resolution(cell()) :: resolution()`

### Parameters
- **cell** (cell()) - Required - The H3 cell index.

### Returns
- **resolution()** - The resolution (0-15).

### Raises
- `ArgumentError` if `cell` is not a valid H3 index.

### Examples
```elixir
iex> ExH3o.get_resolution(0x8928308280fffff)
9
```
```

--------------------------------

### Calculate num_hexagons

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the total number of unique H3 indexes at a given resolution. Raises FunctionClauseError if resolution is not in the range 0-15.

```elixir
@spec num_hexagons(resolution()) :: non_neg_integer()
```

```elixir
iex> ExH3o.num_hexagons(0)
122

iex> ExH3o.num_hexagons(15)
569_707_381_193_162
```

--------------------------------

### get_unidirectional_edge(origin, destination)

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the directed edge index from an origin cell to a destination cell. Both cells must be neighbors (share an edge).

```APIDOC
## get_unidirectional_edge(origin, destination)

### Description
Returns the directed edge index from origin to destination. Both cells must be neighbors (share an edge).

### Spec
@spec get_unidirectional_edge(cell(), cell()) :: cell()

### Parameters
- **origin** (cell()) - Required - The origin H3 cell index.
- **destination** (cell()) - Required - The destination H3 cell index.

### Raises
- `ArgumentError` if either cell is not a valid H3 index, or if the two cells are not neighbors.

### Example
```
iex> edge = ExH3o.get_unidirectional_edge(0x8928308280fffff, 0x8928308280bffff)
iex> edge > 0
true
```
```

--------------------------------

### Convert geographic coordinates to H3 cell

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Converts a {lat, lng} tuple and a resolution (0-15) into an H3 cell index.

```elixir
iex> cell = ExH3o.from_geo({37.7749, -122.4194}, 9)
iex> ExH3o.is_valid(cell)
true
```

--------------------------------

### Convert H3 cell to geographic coordinates

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the center coordinates {lat, lng} of a given H3 cell index.

```elixir
iex> {lat, lng} = ExH3o.to_geo(0x8928308280fffff)
iex> lat >= -90.0 and lat <= 90.0 and lng >= -180.0 and lng <= 180.0
true
```

--------------------------------

### ExH3o.grid_distance/2

Source: https://hexdocs.pm/ex_h3o/ExH3o.html

Returns the grid distance between two H3 cell indices.

```APIDOC
## ExH3o.grid_distance/2

### Description
Returns the grid distance between two H3 cell indices.

### Function
`grid_distance(a, b)`

### Parameters
- **a** (cell) - Required - First cell.
- **b** (cell) - Required - Second cell.

### Returns
- **integer** - Grid distance.
```
Tokens:
Raw