landcheck 0.1.0__tar.gz

landcheck-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.egg-info/
+natural-earth-vector/
+data/*.geojson
+data/*.topojson
+data/*.pmtiles
+data/*.pkl
+!data/sample_*.geojson
+.venv/
+poetry.lock
+.DS_Store
+docs/data/
+.wrangler/
+osm-vector/osm_simplified_land_polygons.geojson.zip

landcheck-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: landcheck
+Version: 0.1.0
+Summary: Offline land/sea point lookup: 182 KB global dataset, microsecond answers with confidence, built on the Trifold T3 triangular DGGS
+Project-URL: Homepage, https://jaakla.github.io/trifold/landcheck.html
+Project-URL: Repository, https://github.com/jaakla/trifold
+License-Expression: MIT
+Keywords: coastline,dggs,geospatial,land,ocean,offline,point-in-polygon,sea
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Provides-Extra: batch
+Requires-Dist: numpy; extra == 'batch'
+Requires-Dist: t3grid; extra == 'batch'
+Description-Content-Type: text/markdown
+
+# landcheck — offline land/sea lookup 
+
+This is created as Trifold application (also test and demonstration)
+
+**Is this lat/long point on land or in the sea?** gets answered anywhere on
+Earth in ~1–13 µs, fully offline, from a small **182 KB** bundled dataset —
+with a confidence value for every answer. Works with Python and JavaScript.
+
+**[Live in-browser demo](https://jaakla.github.io/trifold/landcheck.html)** —
+classify sample or your own points (CSV / GeoJSON) on a map and watch the
+measured lookup rate; the page embeds the real JS library and dataset.
+
+```python
+import sys; sys.path.insert(0, "landcheck/python")
+from landcheck import LandCheck
+
+lc = LandCheck()
+lc.is_land(24.7536, 59.4370)          # True   (lon, lat — Tallinn)
+lc.check(-0.1276, 51.5072)
+# LandResult(land=True, kind='land', confidence=1.0, land_fraction=1.0,
+#            cell='TFA95BM', refined=False)
+```
+
+```js
+import { LandCheck } from "./landcheck/js/landcheck.mjs";
+const lc = await LandCheck.fromFile();          // NodeJs takes bundled data directly
+// OR:
+const lc = await LandCheck.fromUrl("/data/landsea_L10.tfls"); // browser needs to load data file online
+lc.isLand(24.7536, 59.437);           // true
+lc.check(-0.1276, 51.5072);
+// { land: true, kind: 'land', confidence: 1, landFraction: 1,
+//   cell: 'TFA95BM', refined: false }
+```
+
+## How it works
+
+The Trifold level-10 grid (~7 km triangles, 21M cells globally) is
+classified against Natural Earth 1:50m land: 6.15M cells touch land,
+of which 168,833 are *coastal* (mixed land/sea) and the rest are wholly
+interior. Because Trifold addresses sort hierarchically, every cell at
+any level maps to a contiguous range in the canonical level-10 index
+space (`face·4¹⁰ + path`), so the entire classification collapses to
+**153,884 run-length intervals** — 182 KB compressed, including a 4-bit
+land-area fraction for every coastal cell.
+
+A lookup is: locate the point's level-10 triangle (pure float math, no
+dependencies), then binary-search the runs.
+
+| answer kind | meaning | `land` | `confidence` |
+|---|---|---|---|
+| `land` | cell wholly inside land | `True` | 1.0 |
+| `sea` | cell absent from dataset | `False` | 1.0 |
+| `coast` | mixed cell | `land_fraction >= 0.5` | `max(f, 1−f)` |
+| `coast` + `refined` | decided by OSM polygon test | exact | 0.99 |
+
+**Measured accuracy** (30,000 uniform random points vs. exact polygon
+containment in the source dataset): 99.82% agreement overall; `land` and
+`sea` answers 100% correct; *all* residual error lives in `coast`
+answers, which self-report their lower confidence (mean calibration
+credit 0.997).
+
+Caveats inherited from the source data: Natural Earth 1:50m treats **lakes as land and omits islets** below its resolution; `coast` cells flag exactly where such risk is concentrated.
+
+## Optional coastal refinement (OSM)
+
+For applications that need near-exact coastlines, a second dataset
+(`coastal_osm_L10.tflr`, **12.7 MB**) stores OSM simplified land polygons
+([osmdata.openstreetmap.de](https://osmdata.openstreetmap.de/data/land-polygons.html))
+clipped to every triangle crossed by either the Natural Earth or OSM
+coastline, quantized to a cell-local 16-bit grid (~0.1 m) with delta-varint
+rings. When loaded, covered answers switch from the Natural Earth base or
+bulk land-fraction guess to an exact point-in-polygon test. This has
+**99.95% agreement** with full polygon containment on 4,000 random points inside the
+original coastal-cell sample (~23 µs per refined lookup, Python):
+
+```python
+lc = LandCheck(refine_path="landcheck/data/coastal_osm_L10.tflr")
+```
+
+```js
+await lc.loadRefinement("landcheck/data/coastal_osm_L10.tflr");
+```
+
+Only covered coastline cells pay the polygon-test cost. OSM can override a
+base `land` or `sea` answer when its coastline crosses a triangle that Natural
+Earth classified differently.
+
+Note on dataset semantics: the base layer keeps Natural Earth's view of
+the world for `land`/`sea` kinds. NE and OSM systematically disagree
+about Antarctica (OSM land polygons are clipped near the pole and draw
+ice-shelf edges differently). With refinement enabled, OSM is authoritative
+in every covered coastline cell.
+
+Command-line one-off checks (uses refinement automatically when the
+file is present):
+
+```console
+$ python landcheck/python/landcheck.py 24.7536 59.4370
+LAND  kind=land  confidence=1.000  land_fraction=1.0  cell=TFAVKGR  refined=False
+```
+
+## Performance
+
+| operation | speed |
+|---|---|
+| Python scalar `is_land` | ~13 µs/point (77k/s) |
+| Python batch `is_land_batch` (numpy) | ~2.8 µs/point (360k/s) |
+| JavaScript `isLand` (Node) | ~0.8 µs/point (1.2M/s) |
+| dataset load | ~30 ms |
+
+The Python library is dependency-free (stdlib only); `is_land_batch`
+optionally uses numpy + the trifold SDK. The JS library is a single
+ES module, works with browser + Node.
+
+## Files
+
+```
+build.py          TFLS builder: compacted L10 grid GeoJSON -> landsea_L10.tfls
+refine_build.py   TFLR builder: land polygons + TFLS -> coastal_osm_L10.tflr
+python/           landcheck.py (public API) · _fastloc.py (point location)
+js/landcheck.mjs  the JS library (same data, same answers)
+data/             landsea_L10.tfls (bundled) · coastal_osm_L10.tflr (optional)
+tests/            pytest + node:test suites, shared fixture (points.json)
+```
+
+Rebuild from a Trifold grid product:
+
+```bash
+python landcheck/build.py                  # needs data/global_tri_L10_compacted.geojson
+python landcheck/refine_build.py --land osm_simplified_land_polygons.geojson
+python landcheck/tests/make_fixture.py     # refresh cross-language fixture
+pytest landcheck/tests/ && node --test landcheck/tests/test_landcheck.mjs
+```
+
+## Format notes
+
+Custom data format is used to ensure compactness.
+
+**TFLS** (land/sea runs): 16-byte header + zlib stream of
+`varint(gap), varint(length<<1 | coastal)` per run, then 4-bit land
+fractions for coastal cells. **TFLR** (refinement): 12-byte header +
+zlib stream of `varint(Δindex), varint(code)` per covered cell, where
+code 0/1 = all sea/land and code n≥2 introduces n−1 quantized
+zigzag-delta rings combined by the even-odd rule. Both formats are
+level-agnostic (the level lives in the header), so the same tooling can
+serve an L8 (~30 KB) or L12 (~3 MB) variant.
+
+## Roadmap
+
+* **Country detection**: the run-length layer maps
+  each cell to a country id instead of a land bit (runs split at borders;
+  border cells carry clipped boundary polygons like TFLR does for
+  coastlines). Probably can use same formats, same lookup path, same confidence model.
+* Level-12 (~1.8 km trifolds) variant for higher-precision use.
+* Published packages (`pip install trifold-landcheck`, npm equivalent).

landcheck-0.1.0/README.md

@@ -0,0 +1,155 @@
+# landcheck — offline land/sea lookup 
+
+This is created as Trifold application (also test and demonstration)
+
+**Is this lat/long point on land or in the sea?** gets answered anywhere on
+Earth in ~1–13 µs, fully offline, from a small **182 KB** bundled dataset —
+with a confidence value for every answer. Works with Python and JavaScript.
+
+**[Live in-browser demo](https://jaakla.github.io/trifold/landcheck.html)** —
+classify sample or your own points (CSV / GeoJSON) on a map and watch the
+measured lookup rate; the page embeds the real JS library and dataset.
+
+```python
+import sys; sys.path.insert(0, "landcheck/python")
+from landcheck import LandCheck
+
+lc = LandCheck()
+lc.is_land(24.7536, 59.4370)          # True   (lon, lat — Tallinn)
+lc.check(-0.1276, 51.5072)
+# LandResult(land=True, kind='land', confidence=1.0, land_fraction=1.0,
+#            cell='TFA95BM', refined=False)
+```
+
+```js
+import { LandCheck } from "./landcheck/js/landcheck.mjs";
+const lc = await LandCheck.fromFile();          // NodeJs takes bundled data directly
+// OR:
+const lc = await LandCheck.fromUrl("/data/landsea_L10.tfls"); // browser needs to load data file online
+lc.isLand(24.7536, 59.437);           // true
+lc.check(-0.1276, 51.5072);
+// { land: true, kind: 'land', confidence: 1, landFraction: 1,
+//   cell: 'TFA95BM', refined: false }
+```
+
+## How it works
+
+The Trifold level-10 grid (~7 km triangles, 21M cells globally) is
+classified against Natural Earth 1:50m land: 6.15M cells touch land,
+of which 168,833 are *coastal* (mixed land/sea) and the rest are wholly
+interior. Because Trifold addresses sort hierarchically, every cell at
+any level maps to a contiguous range in the canonical level-10 index
+space (`face·4¹⁰ + path`), so the entire classification collapses to
+**153,884 run-length intervals** — 182 KB compressed, including a 4-bit
+land-area fraction for every coastal cell.
+
+A lookup is: locate the point's level-10 triangle (pure float math, no
+dependencies), then binary-search the runs.
+
+| answer kind | meaning | `land` | `confidence` |
+|---|---|---|---|
+| `land` | cell wholly inside land | `True` | 1.0 |
+| `sea` | cell absent from dataset | `False` | 1.0 |
+| `coast` | mixed cell | `land_fraction >= 0.5` | `max(f, 1−f)` |
+| `coast` + `refined` | decided by OSM polygon test | exact | 0.99 |
+
+**Measured accuracy** (30,000 uniform random points vs. exact polygon
+containment in the source dataset): 99.82% agreement overall; `land` and
+`sea` answers 100% correct; *all* residual error lives in `coast`
+answers, which self-report their lower confidence (mean calibration
+credit 0.997).
+
+Caveats inherited from the source data: Natural Earth 1:50m treats **lakes as land and omits islets** below its resolution; `coast` cells flag exactly where such risk is concentrated.
+
+## Optional coastal refinement (OSM)
+
+For applications that need near-exact coastlines, a second dataset
+(`coastal_osm_L10.tflr`, **12.7 MB**) stores OSM simplified land polygons
+([osmdata.openstreetmap.de](https://osmdata.openstreetmap.de/data/land-polygons.html))
+clipped to every triangle crossed by either the Natural Earth or OSM
+coastline, quantized to a cell-local 16-bit grid (~0.1 m) with delta-varint
+rings. When loaded, covered answers switch from the Natural Earth base or
+bulk land-fraction guess to an exact point-in-polygon test. This has
+**99.95% agreement** with full polygon containment on 4,000 random points inside the
+original coastal-cell sample (~23 µs per refined lookup, Python):
+
+```python
+lc = LandCheck(refine_path="landcheck/data/coastal_osm_L10.tflr")
+```
+
+```js
+await lc.loadRefinement("landcheck/data/coastal_osm_L10.tflr");
+```
+
+Only covered coastline cells pay the polygon-test cost. OSM can override a
+base `land` or `sea` answer when its coastline crosses a triangle that Natural
+Earth classified differently.
+
+Note on dataset semantics: the base layer keeps Natural Earth's view of
+the world for `land`/`sea` kinds. NE and OSM systematically disagree
+about Antarctica (OSM land polygons are clipped near the pole and draw
+ice-shelf edges differently). With refinement enabled, OSM is authoritative
+in every covered coastline cell.
+
+Command-line one-off checks (uses refinement automatically when the
+file is present):
+
+```console
+$ python landcheck/python/landcheck.py 24.7536 59.4370
+LAND  kind=land  confidence=1.000  land_fraction=1.0  cell=TFAVKGR  refined=False
+```
+
+## Performance
+
+| operation | speed |
+|---|---|
+| Python scalar `is_land` | ~13 µs/point (77k/s) |
+| Python batch `is_land_batch` (numpy) | ~2.8 µs/point (360k/s) |
+| JavaScript `isLand` (Node) | ~0.8 µs/point (1.2M/s) |
+| dataset load | ~30 ms |
+
+The Python library is dependency-free (stdlib only); `is_land_batch`
+optionally uses numpy + the trifold SDK. The JS library is a single
+ES module, works with browser + Node.
+
+## Files
+
+```
+build.py          TFLS builder: compacted L10 grid GeoJSON -> landsea_L10.tfls
+refine_build.py   TFLR builder: land polygons + TFLS -> coastal_osm_L10.tflr
+python/           landcheck.py (public API) · _fastloc.py (point location)
+js/landcheck.mjs  the JS library (same data, same answers)
+data/             landsea_L10.tfls (bundled) · coastal_osm_L10.tflr (optional)
+tests/            pytest + node:test suites, shared fixture (points.json)
+```
+
+Rebuild from a Trifold grid product:
+
+```bash
+python landcheck/build.py                  # needs data/global_tri_L10_compacted.geojson
+python landcheck/refine_build.py --land osm_simplified_land_polygons.geojson
+python landcheck/tests/make_fixture.py     # refresh cross-language fixture
+pytest landcheck/tests/ && node --test landcheck/tests/test_landcheck.mjs
+```
+
+## Format notes
+
+Custom data format is used to ensure compactness.
+
+**TFLS** (land/sea runs): 16-byte header + zlib stream of
+`varint(gap), varint(length<<1 | coastal)` per run, then 4-bit land
+fractions for coastal cells. **TFLR** (refinement): 12-byte header +
+zlib stream of `varint(Δindex), varint(code)` per covered cell, where
+code 0/1 = all sea/land and code n≥2 introduces n−1 quantized
+zigzag-delta rings combined by the even-odd rule. Both formats are
+level-agnostic (the level lives in the header), so the same tooling can
+serve an L8 (~30 KB) or L12 (~3 MB) variant.
+
+## Roadmap
+
+* **Country detection**: the run-length layer maps
+  each cell to a country id instead of a land bit (runs split at borders;
+  border cells carry clipped boundary polygons like TFLR does for
+  coastlines). Probably can use same formats, same lookup path, same confidence model.
+* Level-12 (~1.8 km trifolds) variant for higher-precision use.
+* Published packages (`pip install trifold-landcheck`, npm equivalent).

landcheck-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "landcheck"
+version = "0.1.0"
+description = "Offline land/sea point lookup: 182 KB global dataset, microsecond answers with confidence, built on the Trifold T3 triangular DGGS"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["land", "sea", "ocean", "point-in-polygon", "geospatial", "offline", "dggs", "coastline"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: GIS",
+]
+
+[project.optional-dependencies]
+batch = ["numpy", "t3grid"]
+
+[project.scripts]
+landcheck = "landcheck:_main"
+
+[project.urls]
+Homepage = "https://jaakla.github.io/trifold/landcheck.html"
+Repository = "https://github.com/jaakla/trifold"
+
+# Repo layout is python/ + data/; assemble the installable package here.
+[tool.hatch.build.targets.wheel.force-include]
+"python/landcheck.py" = "landcheck/__init__.py"
+"python/_fastloc.py" = "landcheck/_fastloc.py"
+"data/landsea_L10.tfls" = "landcheck/data/landsea_L10.tfls"
+
+[tool.hatch.build.targets.sdist]
+include = ["python/landcheck.py", "python/_fastloc.py", "data/landsea_L10.tfls", "README.md"]

landcheck-0.1.0/python/_fastloc.py

@@ -0,0 +1,139 @@
+"""Fast scalar point location for landcheck.
+
+A dependency-free, pure-float re-statement of ``trifold.core.locate``,
+returning the canonical level-L cell index ``(face << 2L) | path_bits``
+directly.  The arithmetic (normalized-sum midpoints, plane-side tests
+with the -1e-14 tolerance, first-match child order, max-margin fallback)
+is bit-identical to the SDK implementation — the test suite cross-checks
+the two on a large random sample.  Roughly 20x faster per point than the
+numpy-scalar SDK path; for bulk work prefer
+``trifold.api.locate_address_batch``.
+"""
+from __future__ import annotations
+
+from math import sqrt, radians, cos, sin
+
+_EPS = -1e-14
+_LON_ROT = radians(7.3)
+
+_FACE_INDEXES = (
+    (0, 11, 5), (0, 5, 1), (0, 1, 7), (0, 7, 10), (0, 10, 11),
+    (1, 5, 9), (5, 11, 4), (11, 10, 2), (10, 7, 6), (7, 1, 8),
+    (3, 9, 4), (3, 4, 2), (3, 2, 6), (3, 6, 8), (3, 8, 9),
+    (4, 9, 5), (2, 4, 11), (6, 2, 10), (8, 6, 7), (9, 8, 1),
+)
+
+
+def _build_faces():
+    phi = (1.0 + sqrt(5.0)) / 2.0
+    raw = [
+        (-1.0, phi, 0.0), (1.0, phi, 0.0), (-1.0, -phi, 0.0), (1.0, -phi, 0.0),
+        (0.0, -1.0, phi), (0.0, 1.0, phi), (0.0, -1.0, -phi), (0.0, 1.0, -phi),
+        (phi, 0.0, -1.0), (phi, 0.0, 1.0), (-phi, 0.0, -1.0), (-phi, 0.0, 1.0),
+    ]
+    c, s = cos(_LON_ROT), sin(_LON_ROT)
+    verts = []
+    for x, y, z in raw:
+        n = sqrt(x * x + y * y + z * z)
+        x, y, z = x / n, y / n, z / n
+        verts.append((c * x - s * y, s * x + c * y, z))
+    faces = [(verts[i], verts[j], verts[k]) for i, j, k in _FACE_INDEXES]
+    cents = []
+    for v0, v1, v2 in faces:
+        cx, cy, cz = v0[0] + v1[0] + v2[0], v0[1] + v1[1] + v2[1], v0[2] + v1[2] + v2[2]
+        n = sqrt(cx * cx + cy * cy + cz * cz)
+        cents.append((cx / n, cy / n, cz / n))
+    return faces, cents
+
+
+_FACES, _CENTROIDS = _build_faces()
+
+
+def _mid(a, b):
+    x, y, z = a[0] + b[0], a[1] + b[1], a[2] + b[2]
+    n = sqrt(x * x + y * y + z * z)
+    return (x / n, y / n, z / n)
+
+
+def _side(a, b, p):
+    """dot(cross(a, b), p)"""
+    return ((a[1] * b[2] - a[2] * b[1]) * p[0]
+            + (a[2] * b[0] - a[0] * b[2]) * p[1]
+            + (a[0] * b[1] - a[1] * b[0]) * p[2])
+
+
+def locate_index(lon: float, lat: float, level: int) -> int:
+    """Canonical cell index ``(face << 2*level) | path_bits`` for a point."""
+    lam, phi = radians(lon), radians(lat)
+    cp = cos(phi)
+    p = (cp * cos(lam), cp * sin(lam), sin(phi))
+
+    tri = None
+    face = -1
+    for f, t in enumerate(_FACES):
+        v0, v1, v2 = t
+        if (_side(v0, v1, p) >= _EPS and _side(v1, v2, p) >= _EPS
+                and _side(v2, v0, p) >= _EPS):
+            face, tri = f, t
+            break
+    if tri is None:  # numeric edge case: nearest face centroid
+        best = -2.0
+        for f, c in enumerate(_CENTROIDS):
+            d = c[0] * p[0] + c[1] * p[1] + c[2] * p[2]
+            if d > best:
+                best, face = d, f
+        tri = _FACES[face]
+
+    path = 0
+    v0, v1, v2 = tri
+    for _ in range(level):
+        m01, m12, m20 = _mid(v0, v1), _mid(v1, v2), _mid(v2, v0)
+        children = ((v0, m01, m20), (m01, v1, m12), (m20, m12, v2), (m01, m12, m20))
+        digit = -1
+        for d, (c0, c1, c2) in enumerate(children):
+            if (_side(c0, c1, p) >= _EPS and _side(c1, c2, p) >= _EPS
+                    and _side(c2, c0, p) >= _EPS):
+                digit = d
+                break
+        if digit < 0:  # tolerance fallback: max min-margin, first max
+            best = None
+            for d, (c0, c1, c2) in enumerate(children):
+                m = min(_side(c0, c1, p), _side(c1, c2, p), _side(c2, c0, p))
+                if best is None or m > best:
+                    best, digit = m, d
+        v0, v1, v2 = children[digit]
+        path = (path << 2) | digit
+    return (face << (2 * level)) | path
+
+
+def index_to_triangle(index: int, level: int):
+    """Unit-sphere vertices ``(v0, v1, v2)`` of a canonical cell index."""
+    face = index >> (2 * level)
+    path = index & ((1 << (2 * level)) - 1)
+    v0, v1, v2 = _FACES[face]
+    for shift in range(2 * (level - 1), -1, -2):
+        digit = (path >> shift) & 3
+        m01, m12, m20 = _mid(v0, v1), _mid(v1, v2), _mid(v2, v0)
+        if digit == 0:
+            v0, v1, v2 = v0, m01, m20
+        elif digit == 1:
+            v0, v1, v2 = m01, v1, m12
+        elif digit == 2:
+            v0, v1, v2 = m20, m12, v2
+        else:
+            v0, v1, v2 = m01, m12, m20
+    return v0, v1, v2
+
+
+def index_to_lonlat_ring(index: int, level: int):
+    """Triangle ring in degrees, antimeridian-unwrapped to continuous
+    longitudes (may exceed 180), matching the grid GeoJSON convention."""
+    from math import atan2, asin, degrees
+
+    ring = []
+    for x, y, z in index_to_triangle(index, level):
+        ring.append((degrees(atan2(y, x)), degrees(asin(max(-1.0, min(1.0, z))))))
+    lons = [lon for lon, _ in ring]
+    if max(lons) - min(lons) > 180.0:  # antimeridian crossing: unwrap east
+        ring = [(lon + 360.0 if lon < 0.0 else lon, lat) for lon, lat in ring]
+    return ring

landcheck-0.1.0/python/landcheck.py

@@ -0,0 +1,372 @@
+"""landcheck — offline land/sea lookup for lon/lat points (Trifold subproject).
+
+A ~180 KB bundled dataset answers "is this point on land?" anywhere on
+Earth in microseconds, fully offline.  Built from the Trifold level-10
+grid (~7 km triangles) classified against Natural Earth 1:50m land.
+
+    >>> from landcheck import LandCheck
+    >>> lc = LandCheck()
+    >>> lc.is_land(24.75, 59.44)        # lon, lat — Tallinn
+    True
+    >>> r = lc.check(-0.1276, 51.5072)  # London
+    >>> r.land, r.kind, round(r.confidence, 2)
+    (True, 'land', 1.0)
+
+Answer semantics
+----------------
+kind='land'   cell is wholly inside land            -> land, confidence 1.0
+kind='sea'    cell absent from the dataset           -> sea,  confidence 1.0
+kind='coast'  mixed cell; the bundled land fraction of the cell is used:
+              land = fraction >= 0.5, confidence = max(f, 1 - f).
+
+With optional OSM refinement loaded, cells crossed by either source's
+coastline are decided by a clipped OSM polygon before the Natural Earth base
+classification is accepted.
+"""
+from __future__ import annotations
+
+import struct
+import zlib
+from array import array
+from bisect import bisect_right
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    from ._fastloc import (locate_index as _locate_index,
+                           index_to_lonlat_ring as _index_to_ring)
+except ImportError:  # imported as a plain module, not a package
+    from _fastloc import (locate_index as _locate_index,
+                          index_to_lonlat_ring as _index_to_ring)
+
+
+def _ringbox(index: int, level: int) -> tuple[float, float, float, float]:
+    ring = _index_to_ring(index, level)
+    lons = [p[0] for p in ring]
+    lats = [p[1] for p in ring]
+    return min(lons), min(lats), max(lons), max(lats)
+
+__all__ = ["LandCheck", "LandResult"]
+
+_B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"  # Crockford, as trifold.address
+
+
+def _index_to_compact(index: int, level: int) -> str:
+    """Compact Trifold address of a canonical cell index (e.g. 'TFAVKGR')."""
+    face = index >> (2 * level)
+    path = index & ((1 << (2 * level)) - 1)
+    bits = 2 * level
+    pad = (-bits) % 5
+    path <<= pad
+    chars = []
+    for shift in range(bits + pad - 5, -1, -5):
+        chars.append(_B32[(path >> shift) & 0x1F])
+    return "T" + _B32[face] + _B32[level] + "".join(chars)
+
+_MAGIC = b"TFLS"
+
+def _find_default_data() -> Path:
+    here = Path(__file__).resolve().parent
+    for cand in (here / "data" / "landsea_L10.tfls",          # installed package
+                 here.parent / "data" / "landsea_L10.tfls"):  # repo checkout
+        if cand.is_file():
+            return cand
+    return cand
+
+_DEFAULT_DATA = _find_default_data()
+
+_KIND_LAND = "land"
+_KIND_COAST = "coast"
+_KIND_SEA = "sea"
+
+
+@dataclass(frozen=True)
+class LandResult:
+    """One lookup answer."""
+    land: bool                  #: best land/sea call
+    kind: str                   #: 'land' | 'coast' | 'sea'
+    confidence: float           #: probability the ``land`` bool is right
+    land_fraction: float | None  #: land share of the cell (None if not bundled)
+    cell: str | None            #: compact Trifold address, None for open sea
+    refined: bool = False       #: True if a coastal refinement polygon decided it
+
+
+_REFINED_CONFIDENCE = 0.99  # OSM simplified polygons; quantization ~0.1 m
+
+
+class LandCheck:
+    """Offline land/sea point lookup. Thread-safe after construction.
+
+    ``refine_path`` optionally loads a TFLR coastal-refinement dataset
+    (see refine_build.py). Covered cells are decided by a point-in-polygon
+    test against clipped OSM land polygons before the base classification.
+    """
+
+    def __init__(self, data_path: str | Path = _DEFAULT_DATA,
+                 refine_path: str | Path | None = None):
+        raw = Path(data_path).read_bytes()
+        magic, version, level, flags, _, n_runs, n_coast = struct.unpack_from(
+            "<4sBBBBII", raw, 0)
+        if magic != _MAGIC:
+            raise ValueError(f"{data_path}: not a TFLS file")
+        if version != 1:
+            raise ValueError(f"{data_path}: unsupported TFLS version {version}")
+        self.level = level
+        body = zlib.decompress(raw[16:])
+
+        starts = array("I")
+        ends = array("I")
+        coastal = bytearray(n_runs)
+        coast_before = array("I")  # coastal cells in runs before this one
+        pos = 0
+        cursor = 0
+        n_coast_seen = 0
+
+        def read_varint() -> int:
+            nonlocal pos
+            shift = 0
+            value = 0
+            while True:
+                b = body[pos]
+                pos += 1
+                value |= (b & 0x7F) << shift
+                if not b & 0x80:
+                    return value
+                shift += 7
+
+        for i in range(n_runs):
+            cursor += read_varint()
+            packed = read_varint()
+            length = packed >> 1
+            starts.append(cursor)
+            ends.append(cursor + length)
+            coast_before.append(n_coast_seen)
+            if packed & 1:
+                coastal[i] = 1
+                n_coast_seen += length
+            cursor += length
+        if n_coast_seen != n_coast:
+            raise ValueError(f"{data_path}: coastal count mismatch")
+
+        self._starts = starts
+        self._ends = ends
+        self._coastal = bytes(coastal)
+        self._coast_before = coast_before
+        self._fractions = body[pos:] if flags & 1 else None
+        if self._fractions is not None and len(self._fractions) < (n_coast + 1) // 2:
+            raise ValueError(f"{data_path}: truncated fraction block")
+
+        self._refine = None
+        if refine_path is not None:
+            self.load_refinement(refine_path)
+
+    def load_refinement(self, path: str | Path) -> None:
+        """Load a TFLR coastal-refinement dataset (built by refine_build.py)."""
+        raw = Path(path).read_bytes()
+        magic, version, level, _, _, n_cells = struct.unpack_from("<4sBBBBI", raw, 0)
+        if magic != b"TFLR":
+            raise ValueError(f"{path}: not a TFLR file")
+        if version != 1:
+            raise ValueError(f"{path}: unsupported TFLR version {version}")
+        if level != self.level:
+            raise ValueError(f"{path}: level {level} != dataset level {self.level}")
+        body = zlib.decompress(raw[12:])
+        pos = 0
+
+        def read_varint() -> int:
+            nonlocal pos
+            shift = 0
+            value = 0
+            while True:
+                b = body[pos]
+                pos += 1
+                value |= (b & 0x7F) << shift
+                if not b & 0x80:
+                    return value
+                shift += 7
+
+        cells = {}
+        index = 0
+        for _ in range(n_cells):
+            index += read_varint()
+            code = read_varint()
+            if code < 2:
+                cells[index] = code  # 0 = all sea, 1 = all land
+            else:
+                rings = []
+                for _ in range(code - 1):
+                    n_pts = read_varint()
+                    pts = array("i")
+                    x = y = 0
+                    for _ in range(n_pts):
+                        zx, zy = read_varint(), read_varint()
+                        x += (zx >> 1) ^ -(zx & 1)
+                        y += (zy >> 1) ^ -(zy & 1)
+                        pts.append(x)
+                        pts.append(y)
+                    rings.append(pts)
+                cells[index] = rings
+        self._refine = cells
+
+    def _refined_land(self, index: int, lon: float, lat: float) -> bool | None:
+        """Exact land/sea from the refinement polygons, None if unavailable."""
+        if self._refine is None:
+            return None
+        entry = self._refine.get(index)
+        if entry is None:
+            return None
+        if isinstance(entry, int):
+            return bool(entry)
+        ring = _ringbox(index, self.level)
+        (minx, miny, maxx, maxy) = ring
+        if maxx > 180.0 and lon < 0.0:
+            lon += 360.0
+        qx = (lon - minx) * 65535.0 / (maxx - minx)
+        qy = (lat - miny) * 65535.0 / (maxy - miny)
+        inside = False  # even-odd rule over all rings
+        for pts in entry:
+            n = len(pts) // 2
+            x1, y1 = pts[2 * (n - 1)], pts[2 * (n - 1) + 1]
+            for i in range(n):
+                x2, y2 = pts[2 * i], pts[2 * i + 1]
+                if (y1 > qy) != (y2 > qy):
+                    if qx < x1 + (qy - y1) * (x2 - x1) / (y2 - y1):
+                        inside = not inside
+                x1, y1 = x2, y2
+        return inside
+
+    # ------------------------------------------------------------- lookups
+    def check(self, lon: float, lat: float) -> LandResult:
+        """Full answer for one point (lon, lat in degrees, WGS84)."""
+        if not -180.0 <= lon <= 180.0:
+            raise ValueError("longitude must be in [-180, 180]")
+        if not -90.0 <= lat <= 90.0:
+            raise ValueError("latitude must be in [-90, 90]")
+        index = _locate_index(lon, lat, self.level)
+        run = bisect_right(self._starts, index) - 1
+        hit = run >= 0 and index < self._ends[run]
+        refined = self._refined_land(index, lon, lat)
+        if refined is not None:
+            fraction = (self._fraction_at(run, index)
+                        if hit and self._coastal[run]
+                        else (1.0 if hit else 0.0))
+            return LandResult(refined, _KIND_COAST, _REFINED_CONFIDENCE,
+                              fraction, _index_to_compact(index, self.level),
+                              refined=True)
+        if not hit:
+            return LandResult(False, _KIND_SEA, 1.0, 0.0, None)
+        cell = _index_to_compact(index, self.level)
+        if not self._coastal[run]:
+            return LandResult(True, _KIND_LAND, 1.0, 1.0, cell)
+        fraction = self._fraction_at(run, index)
+        if fraction is None:
+            return LandResult(True, _KIND_COAST, 0.5, None, cell)
+        return LandResult(fraction >= 0.5, _KIND_COAST,
+                          max(fraction, 1.0 - fraction), fraction, cell)
+
+    def is_land(self, lon: float, lat: float) -> bool:
+        """Best land/sea bool for one point."""
+        index = _locate_index(lon, lat, self.level)
+        refined = self._refined_land(index, lon, lat)
+        if refined is not None:
+            return refined
+        run = bisect_right(self._starts, index) - 1
+        if run < 0 or index >= self._ends[run]:
+            return False
+        if not self._coastal[run]:
+            return True
+        fraction = self._fraction_at(run, index)
+        return True if fraction is None else fraction >= 0.5
+
+    def is_land_batch(self, lons, lats):
+        """Vectorised lookup for many points (requires numpy + trifold).
+
+        Returns a boolean numpy array; orders of magnitude faster than a
+        Python loop for large inputs.
+        """
+        import numpy as np
+        from trifold.api import locate_address_batch
+
+        addrs = locate_address_batch(lons, lats, self.level)
+        index = (addrs >> np.uint64(59 - 2 * self.level)).astype(np.int64)
+        starts = np.frombuffer(self._starts, dtype=np.uint32).astype(np.int64)
+        ends = np.frombuffer(self._ends, dtype=np.uint32).astype(np.int64)
+        run = np.searchsorted(starts, index, side="right") - 1
+        hit = (run >= 0) & (index < ends[np.maximum(run, 0)])
+        out = np.zeros(len(index), dtype=bool)
+        coastal = np.frombuffer(self._coastal, dtype=np.uint8).astype(bool)
+        hit_runs = run[hit]
+        is_coast = coastal[hit_runs]
+        land = ~is_coast
+        if self._fractions is not None and is_coast.any():
+            coast_before = np.frombuffer(self._coast_before,
+                                         dtype=np.uint32).astype(np.int64)
+            n = (coast_before[hit_runs] + index[hit] - starts[hit_runs])[is_coast]
+            nib = np.frombuffer(self._fractions, dtype=np.uint8)[n >> 1]
+            q = np.where(n & 1, nib >> 4, nib & 0x0F)
+            land = land.copy()
+            land[is_coast] = q >= 8  # fraction (q+0.5)/16 >= 0.5
+        else:
+            land = land | is_coast  # no fractions: coast counts as land
+        out[hit] = land
+        if self._refine:
+            for pos, cell_index in enumerate(index):
+                idx = int(cell_index)
+                if idx in self._refine:
+                    refined = self._refined_land(
+                        idx, float(lons[pos]), float(lats[pos]))
+                    if refined is not None:
+                        out[pos] = refined
+        return out
+
+    # ------------------------------------------------------------- helpers
+    def _fraction_at(self, run: int, index: int) -> float | None:
+        if self._fractions is None:
+            return None
+        n = self._coast_before[run] + (index - self._starts[run])
+        byte = self._fractions[n >> 1]
+        q = (byte >> 4) if n & 1 else (byte & 0x0F)
+        return (q + 0.5) / 16.0
+
+    @property
+    def stats(self) -> dict:
+        """Dataset summary (for diagnostics)."""
+        n_coast = sum(e - s for s, e, c in
+                      zip(self._starts, self._ends, self._coastal) if c)
+        n_land = sum(e - s for s, e, c in
+                     zip(self._starts, self._ends, self._coastal) if not c)
+        return {
+            "level": self.level,
+            "runs": len(self._starts),
+            "interior_cells": n_land,
+            "coastal_cells": n_coast,
+            "has_fractions": self._fractions is not None,
+            "has_refinement": self._refine is not None,
+        }
+
+
+def _main(argv=None) -> int:
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        prog="landcheck", description="offline land/sea lookup for a point")
+    ap.add_argument("lon", type=float, help="longitude (-180..180)")
+    ap.add_argument("lat", type=float, help="latitude (-90..90)")
+    ap.add_argument("--data", default=_DEFAULT_DATA)
+    ap.add_argument("--refine", default=None,
+                    help="optional TFLR coastal-refinement file")
+    args = ap.parse_args(argv)
+    refine = args.refine
+    if refine is None:
+        default_tflr = Path(args.data).parent / "coastal_osm_L10.tflr"
+        refine = default_tflr if default_tflr.exists() else None
+    result = LandCheck(args.data, refine_path=refine).check(args.lon, args.lat)
+    print(f"{'LAND' if result.land else 'SEA'}  kind={result.kind}  "
+          f"confidence={result.confidence:.3f}  "
+          f"land_fraction={result.land_fraction}  cell={result.cell}  "
+          f"refined={result.refined}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())