some more figures and Z7 stuff

Author: allixender

.gitignore

@@ -222,3 +222,4 @@ yarn-error.log*
 website/build/
 website/.docusaurus/
 .docusaurus/
+.DS_Store

website/docs/api/traversal.md

@@ -5,6 +5,63 @@ title: Traversal Functions
 
 # Traversal Functions
 
+This page is directly based off [Renoud and Shaw's work on the Z7 C++ prototype][renoud2025]
+
+This is a work-in-progress to explore the possibility of neighbor traversal in the Z7 domain. Z7 is based on
+the Generalized Balanced Ternary (GBT) numeral system described in [Lucas, Gibson (1982)][lucas1982],
+[van Roessel (1988)][vanRoessel1988], and [Wikipedia (2025)][wikipedia2025].
+
+## Rotation Pattern
+
+Lucas and Gibson (1982) gave examples of GBT with exclusively counter-clockwise (CCW) rotation. The disadvantage of this
+approach is that the orientation of the hexagons at the different hierarchy levels quickly diverge from each other.
+[White et al. (1992)][white1992] proposed an alternating rotation direction (CW, CCW, CW, ...) to maintain an alignment
+of hexagon
+orientations across hierarchy levels. Kmoch et al. (2025) adopted this alternating rotation pattern for Z7 assigning CW
+to odd resolutions and CCW to even resolutions.
+
+For reference purposes a rendering of three hierarchies of alternating GBT rotation is included (CW, CCW, CW).
+
+<img src="https://raw.githubusercontent.com/wrenoud/Z7/refs/heads/main/images/grid.svg" width="200" alt="3 hierarchies in Z7's alternating GBT pattern"></img>
+
+### GBT Addition
+
+| Counter-clockwise (CCW)                                                                                        | Clockwise (CW)                                                                                               |
+|----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| <img src="/images/neighbors-neighbors-ccw.png" width="300" alt="Single digit GBT addition with CCW rotation"></img> | <img src="/images/neighbors-neighbors-cw.png" width="300" alt="Single digit GBT addition with CW rotation"></img> |
+
+## References
+
+1. Renoud and Shaw (2025).
+   [Z7][renoud2025]. _GitHub[renoud2025]
+   Series, 6_(32). https://doi.org/10.5194/agile-giss-6-32-2025
+2. Lucas, D., & Gibson, L. (1982). [_Automated Analysis of imagery_][lucas1982]. Air Force Office of Scientific
+   Research. https://apps.dtic.mil/sti/tr/pdf/ADA125710.pdf. (No. AFOSRTR830055).
+3. Sahr, K. (2011). [Hexagonal discrete global grid systems for geospatial computing][sahr2011]. _Archives of
+   Photogrammetry Cartography and Remote Sensing, 22_, 363–376.
+4. van Roessel, J. W. (1988).
+   [Conversion of Cartesian coordinates from and to Generalized Balanced Ternary addresses][vanRoessel1988].
+   _Photogrammetric Engineering & Remote Sensing, 54_(11), 1565–1570.
+5. White, D., Kimerling, J. A., & Overton, S. W. (1992).
+   [Cartographic and Geometric Components of a Global Sampling Design for Environmental Monitoring][white1992].
+   _Cartography and Geographic Information Systems_, 19(1), 5-22. https://doi.org/10.1559/152304092783786636
+6. Wikipedia Contributors. (2025, December 16). [_Generalized balanced ternary_][wikipedia2025]. Wikipedia; Wikimedia
+   Foundation.
+
+---
+
+[wikipedia2025]: https://en.wikipedia.org/wiki/Generalized_balanced_ternary
+
+[renoud2025]: https://github.com/wrenoud/Z7/
+
+[vanRoessel1988]: https://web.archive.org/web/20250523045258/https://www.asprs.org/wp-content/uploads/pers/1988journal/nov/1988_nov_1565-1570.pdf
+
+[white1992]: https://www.tandfonline.com/doi/pdf/10.1559/152304092783786636?casa_token=lyaVPE0vjcQAAAAA:GL0QWw01pvr2AQWJgmNcjHH_rCp3VLv5jayMi7O9Kb7jC_l2KFt2b98GvnRcOhi4qSXV-FXXxUYAVg
+
+[sahr2011]: https://www.researchgate.net/publication/266415994_Hexagonal_discrete_global_grid_systems_for_geospatial_computing
+
+[lucas1982]: https://apps.dtic.mil/sti/tr/pdf/ADA125710.pdf
+
 :::note Coming soon
 This page is under construction.
 :::

website/docs/concepts/z7-indexing.md

@@ -1,10 +1,135 @@
 ---
 id: z7-indexing
+sidebar_position: 5
 title: Z7 Indexing
 ---
 
 # Z7 Indexing
 
-:::note Coming soon
-This page is under construction.
-:::
+The **Z7 index** is the core data structure of IGEO7. A single 64-bit integer encodes everything needed to identify a cell: which base cell it belongs to, its resolution, and its exact position within the hierarchy.
+
+## Why a Hierarchical Index?
+
+Traditional geographic coordinate systems (lat/lng, UTM) identify a *point* on the Earth's surface. For spatial analysis at scale, you often need:
+
+- **Aggregation:** group fine-resolution observations into coarser cells
+- **Neighbourhood queries:** find all cells adjacent to a given cell
+- **Spatial joins:** map observations to a uniform grid
+
+A hierarchical index like Z7 enables all of these in O(1) or O(r) time (where r is the resolution), without any geometry computation.
+
+## Structure
+
+A Z7 index is a 64-bit unsigned integer with this layout:
+
+```
+Bits 63–60  │  Bits 59–57  │  Bits 56–54  │  ...  │  Bits 2–0
+────────────┼──────────────┼──────────────┼───────┼──────────
+ Base cell  │   Digit 1    │   Digit 2    │  ...  │  Digit 20
+  (4 bits)  │   (3 bits)   │   (3 bits)   │       │  (3 bits)
+```
+
+- **Base cell (4 bits):** which of the 12 icosahedral pentagonal base cells (0–11) the cell belongs to
+- **Resolution digits (20 × 3 bits):** one digit per resolution level, value 0–6 for valid digits, 7 as an "end-of-resolution" sentinel
+
+## The 12 Base Cells
+
+IGEO7 starts from the **12 vertices of the icosahedron**, which become the 12 pentagonal cells at resolution 0. All other cells at all resolutions are hexagons that subdivide the faces around these vertices.
+
+This is fundamentally different from H3, which has 122 resolution-0 cells formed by a mixed aperture 4→3 pre-subdivision. IGEO7's simpler base gives it 5 additional resolution levels.
+
+![The 12 pentagonal base cells on the icosahedron](/images/plot3_pentagon_noquad.png)
+
+## Aperture 7 Subdivision
+
+At each resolution step, every hexagonal cell is subdivided into **7 children**:
+
+![ISEA7H aperture-7 refinement showing parent cell subdivided into 7 children](/images/isea7h_refinement.png)
+
+- **Digit 0:** centre child — directly below the parent centroid
+- **Digits 1–6:** six surrounding children, numbered in space-filling curve order
+
+Pentagons are an exception: they have 6 children (1 centre + 5 surrounding), since pentagons have only 5 edges.
+
+## Reading a Z7 Index
+
+The Z7 string format `"0800433"` decodes as:
+
+| Part | Value | Meaning |
+|---|---|---|
+| `08` | base cell 8 | one of the 12 icosahedron vertices |
+| `0` | digit 1 = 0 | centre child at resolution 1 |
+| `0` | digit 2 = 0 | centre child at resolution 2 |
+| `4` | digit 3 = 4 | child 4 at resolution 3 |
+| `3` | digit 4 = 3 | child 3 at resolution 4 |
+| `3` | digit 5 = 3 | child 3 at resolution 5 |
+
+This cell is at **resolution 5** (5 valid digits after the base cell).
+
+## Parent–Child Relationships
+
+**Parent:** remove the last digit.
+
+```python
+z7_str = "0800433"
+parent  = z7_str[:-1]   # "080043"  (resolution 4)
+```
+
+**Children:** append digits 0–6.
+
+```python
+children = [z7_str + str(d) for d in range(7)]
+# ["08004330", "08004331", ..., "08004336"]
+```
+
+This works identically on the integer representation via bit operations:
+
+```python
+# Get parent (set last valid digit group to 0b111)
+def get_parent(z7_int: int, resolution: int) -> int:
+    shift = 57 - 3 * (resolution - 1)
+    mask = ~(0x7 << shift)
+    return (z7_int & mask) | (0x7 << shift)
+```
+
+## The Space-Filling Curve
+
+The Z7 index order is not arbitrary — it defines a **space-filling curve** over the sphere. Cells that are adjacent in Z7 integer order tend to be spatially close. This property:
+
+![Z7 space-filling curve index order](/images/plot_index_order.png)
+
+- Improves cache locality when processing large datasets in index order
+- Makes range scans on indexed database columns spatially coherent
+- Is analogous to the Hilbert curve used in many raster spatial indexing schemes
+
+## Digit 0: The Centre Cell
+
+The digit `0` always means "the child that contains the parent's centroid". This is a consistent orientation anchor: no matter which base cell or resolution you're at, digit `0` is always the spatial centre.
+
+This means the **path of all-zero digits** (e.g., `"080000...0"`) traces a straight line from the icosahedron vertex down to the finest resolution, always staying at the centre of each parent cell.
+
+## Comparison with H3 Indexing
+
+| Property | Z7 (IGEO7) | H3 |
+|---|---|---|
+| Index size | 64-bit integer | 64-bit integer |
+| Base cell bits | 4 (values 0–11) | 7 (values 0–121) |
+| Digit size | 3 bits (values 0–6, 7=sentinel) | 3 bits (values 0–6, 7=sentinel) |
+| Max resolution | 20 | 15 |
+| Digit encoding | 0=centre, 1–6=surrounding | 0=centre, 1–6=surrounding |
+| String format | `BB` + up to 20 octal digits | 15-hex-char string |
+
+The indexing philosophy is nearly identical — both use 64-bit integers with 3-bit resolution digits and a sentinel value. The key differences are at the base cell level: Z7 has 12 pure-aperture-7 base cells; H3 has 122 mixed-aperture base cells.
+
+## Neighbourhood Traversal
+
+Finding neighbours requires Z7 arithmetic — specifically, Central Place Indexing (CPI) addition with carry propagation across base cell boundaries. This is implemented in [IGEO7.jl](https://github.com/allixender/IGEO7.jl) and the [C++ work](https://github.com/wrenoud/Z7/) by W.Renoud J.Shaw.
+
+
+
+## See Also
+
+- [Z7 Bit Layout](../reference/z7-bit-layout) — detailed binary encoding
+- [Z7 String Format](../reference/z7-string-format) — the two external string representations
+- [Aperture 7 Hierarchy](./aperture7) — the subdivision geometry
+- [Pentagons](./pentagons) — the 12 special cells

website/docs/installation.md

@@ -1,10 +1,116 @@
 ---
 id: installation
+sidebar_position: 2
 title: Installation
 ---
 
 # Installation
 
-:::note Coming soon
-This page is under construction.
+IGEO7 is implemented in **DGGRID** (the core C++ engine) and accessed via the **dggrid4py** Python wrapper. You need both.
+
+## 1. Install DGGRID
+
+DGGRID is a C++ command-line tool. You need a compiled binary on your system.
+
+### Pre-built binaries
+
+Download a pre-built binary from the [DGGRID releases page](https://github.com/sahrk/DGGRID/releases).
+
+### Build from source
+
+```bash
+git clone https://github.com/sahrk/DGGRID.git
+cd DGGRID
+mkdir build && cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make -j$(nproc)
+sudo make install   # installs to /usr/local/bin/dggrid
+```
+
+**Requirements:** CMake ≥ 3.12, a C++17 compiler (GCC ≥ 7 or Clang ≥ 5).
+
+Verify the installation:
+
+```bash
+dggrid --version
+```
+
+### Setting the path
+
+dggrid4py locates the DGGRID binary via the `DGGRID_PATH` environment variable or an explicit path in the API call:
+
+```bash
+export DGGRID_PATH=/usr/local/bin/dggrid
+```
+
+## 2. Install dggrid4py
+
+dggrid4py is the Python wrapper that drives DGGRID programmatically.
+
+### With pip
+
+```bash
+pip install dggrid4py
+```
+
+### With conda / mamba
+
+```bash
+conda install -c conda-forge dggrid4py
+```
+
+### Dependencies
+
+| Package | Purpose |
+|---|---|
+| `geopandas` | Geospatial DataFrames with geometry support |
+| `shapely` | Geometry objects (polygons, points) |
+| `pandas` | Tabular data |
+| `numpy` | Array operations |
+
+All are installed automatically.
+
+## 3. (Optional) DGGAL / pydggal
+
+For a pure-Python alternative with no subprocess calls, [DGGAL](https://github.com/ecere/dggal) implements IGEO7 natively as `ISEA7H_Z7`. Install the Python binding:
+
+```bash
+pip install dggal
+```
+
+## 4. Verify the setup
+
+```python
+import os
+from dggrid4py import DGGRIDv7
+
+dggrid = DGGRIDv7(
+    executable=os.environ.get("DGGRID_PATH", "/usr/local/bin/dggrid"),
+    working_dir="/tmp",
+    capture_logs=True,
+    silent=True,
+)
+
+# Quick sanity check: generate grid stats for resolution 5
+df = dggrid.grid_stats_table("IGEO7", 5)
+print(df)
+```
+
+Expected output (truncated):
+
+```
+   Resolution  # Cells     Area (km^2)
+0           0       12  51006562.172409
+1           1       72   7286651.738916
+...
+5           5   168072      3034.840374
+```
+
+:::tip Working directory
+dggrid4py creates temporary metafiles in `working_dir`. `/tmp` works well on Linux/macOS. The directory is cleaned up automatically after each call.
 :::
+
+## Next Steps
+
+- [Quickstart](./quickstart) — generate your first IGEO7 cells
+- [dggrid4py ecosystem page](./ecosystem/dggrid4py) — full API reference for the Python wrapper