# Precision Levels

## Canonical Precisions

Due to base-29 quantization, not every Hilbert order `p` produces a distinct code length. Only **canonical precisions** create unique grids. Requesting a non-canonical `p` silently snaps to the nearest canonical one.

```python
import yoro

for level in yoro.precision_levels(domain="CI"):
    print(
        f"p={level['precision']:>2}  "
        f"{level['code_length']} chars  "
        f"{level['grid_size']:>8}×{level['grid_size']:<8}  "
        f"~{level['resolution_m']:>10.2f} m"
    )
```

### Cote d'Ivoire (`CI`)

| Code Length | Precision (p) | Grid | Resolution | Use Case |
|:-----------:|:-------------:|:----:|:----------:|----------|
| 1 | 2 | 4×4 | ~177 km | Country quadrant |
| 2 | 4 | 16×16 | ~44 km | Region |
| 3 | 7 | 128×128 | ~5.5 km | City |
| 4 | 9 | 512×512 | ~1.4 km | Neighborhood |
| **5** | **12** | **4096×4096** | **~173 m** | **Block (default)** |
| 6 | 14 | 16K×16K | ~43 m | Building |
| 7 | 17 | 131K×131K | ~5.4 m | Entrance |
| 8 | 19 | 524K×524K | ~1.35 m | Meter-level |
| 9 | 21 | 2M×2M | ~34 cm | Sub-meter |
| 10 | 24 | 16M×16M | ~4 cm | Centimeter |

## Snap Precision

If you request a non-canonical precision, Yoro snaps to the canonical one:

```python
yoro.snap_precision(10)  # → 12 (both use 5-character codes)
yoro.snap_precision(11)  # → 12
yoro.snap_precision(12)  # → 12 (already canonical)

yoro.snap_precision(18)  # → 19 (both use 8-character codes)
```

## Resolution by Domain

Resolution depends on the domain's geographic extent. Larger domains (like `XX` global) have coarser resolution at the same precision:

```python
yoro.resolution(12, "CI")  # ~173 m (small country)
yoro.resolution(12, "XX")  # ~5,533 m (entire globe)
```

## Choosing a Precision

| Need | Precision | Characters |
|------|-----------|-----------|
| Rough area (delivery zone) | 7-9 | 3-4 |
| Address (house/building) | 12-14 | 5-6 |
| Exact location (survey point) | 17-19 | 7-8 |
| Sub-meter (precision agriculture) | 21+ | 9+ |

The default precision of 12 (5 characters) is a good balance for most addressing use cases: ~173 m in Cote d'Ivoire, enough to identify a building or intersection.
