Basics of IGEO7.jl

This tutorial introduces the basic concepts of the IGEO7 grid indexing system (Z7) and how to use the IGEO7.jl package for indexing and neighbor traversal.

using IGEO7

Understanding Z7 Indices

Z7 indices represent cells in the IGEO7 hexagonal discrete global grid. There are two primary internal representations:

1. Z7IndexUInt64: A lightweight wrapper around a UInt64 (most memory efficient).
2. Z7IndexComp: Decodes the digits once upon construction (faster for multiple accesses).

You can create an index from a string:

idx_str = "0103"
idx = z7string_to_index(idx_str)

Z7IndexUInt64(0x10ffffffffffffff)

We can inspect its properties:

println("Base Cell: ", get_base_cell(idx))
println("Resolution: ", get_resolution(idx))
println("Digits: ", get_digits(idx)[1:get_resolution(idx)])

Base Cell: 1
Resolution: 2
Digits: (0x00, 0x03)

Neighbor Traversal

Finding the immediate neighbors of a cell is the primary feature of this package. For most hexagonal cells, there are 6 neighbors. However, at the 12 vertices of the icosahedron (the "base cells"), the grid contains pentagonal cells, which only have 5 neighbors.

neighbors = get_neighbours(idx)

println("Neighbors of ", idx_str, ":")
for (i, n) in enumerate(neighbors)
    if n.raw != typemax(UInt64)
        println("  Direction ", i, ": ", index_to_z7string(n))
    else
        println("  Direction ", i, ": (Invalid/Pentagon Gap)")
    end
end

Neighbors of 0103:
  Direction 1: 0134
  Direction 2: 0161
  Direction 3: 0136
  Direction 4: 0100
  Direction 5: 0101
  Direction 6: 0106

Hierarchy and Parents

The IGEO7 grid is hierarchical. Every cell (except for resolution 0) has a parent cell that contains it at the previous resolution.

parent_idx = get_parent(idx)
println("Parent of ", idx_str, ": ", index_to_z7string(parent_idx))

Parent of 0103: 010

Resolution Statistics

You can also look up precomputed statistics for any resolution level (0 to 20):

res = 10
stats = get_resolution_stats(res)

println("Resolution ", res, " Stats:")
println("  Total Cells: ", stats.num_cells)
println("  Cell Area:   ", stats.area_km2, " km²")
println("  Length:      ", stats.cls_km, " km")

Resolution 10 Stats:
  Total Cells: 2824752492
  Cell Area:   0.18057 km²
  Length:      0.4794882 km

You can also search for the best resolution for your target requirements:

target_len = 100.0 # meters
found_res = find_resolution_by_cls_m(target_len, prefer=:closest)
println("Resolution closest to ", target_len, "m is: ", found_res)

Resolution closest to 100.0m is: 12

This page was generated using Literate.jl.