Skip to content

armgit / Aleph

Public Imported from GitHub
0

Give satellite imagery, terrain data, buildings, streetview photos to your LLM

Add initial support for Google Earth 3D tiles

Belluxxa292620c441b
diff --git a/README.md b/README.md
index ff16ead..a1718f1 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
Aleph does two things:
-- Lets you draw a rectangle on the map and downloads **everything** inside it (buildings, elevation, HD satellite imagery, Street View photos).
+- Lets you draw a rectangle on the map and downloads **everything** inside it (buildings, elevation, HD satellite imagery, Street View photos, textured 3D models).
- Provides any of the above information for **specific points** on Earth, on the fly, via the CLI.
This was born as a way to let LLMs quickly gather information from the physical world, but you can just use it to have piece of the Earth on your laptop and do whatever you want with it.
diff --git a/aleph.py b/aleph.py
index dc238b8..4a8af8e 100644
--- a/aleph.py
+++ b/aleph.py
@@ -38,6 +38,9 @@ def describe(run):
elif mode == "osm":
label = "OSM map"
message = "1 extract" if estimate["osm_maps"] else "already saved"
+ elif mode == "mesh":
+ label = "3D mesh"
+ message = f"{estimate['mesh_nodes']:,} nodes down to level {stage['level']}"
else:
label = "Terrain"
message = f"{estimate['terrain_tiles']:,} tiles"
diff --git a/docs/cli.md b/docs/cli.md
index fef5f50..6e67d4f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -81,7 +81,15 @@ alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 -o captures
The command shows an estimate and asks before downloading. Add `--yes` to skip the prompt, or `--plan` to save a plan for later.
-Use `--sources` to select `streetview`, `satellite`, or `osm` (including terrain), or a combination.
+Use `--sources` to select `streetview`, `satellite`, or `osm` (including terrain), or a combination. These three are the default.
+
+Add `mesh` for Google Earth's textured 3D model of the area, saved as `mesh.glb`:
+
+```sh
+alephgeo capture create --bbox 41.8895 12.4910 41.8910 12.4940 --sources mesh satellite -o captures
+```
+
+`--mesh-level 1–22` sets the detail (default: `21`). Each level halves the texel size; `22` is the most detailed (about 4 cm per texel) and needs about four times as many downloads as `21`. Coordinates in `mesh.glb` are meters from the rectangle's center: x east, y up, z south.
Resume a capture or start a saved plan using its printed run folder:
diff --git a/src/assets/app.js b/src/assets/app.js
index 708de62..72030fe 100644
--- a/src/assets/app.js
+++ b/src/assets/app.js
@@ -10,7 +10,7 @@ const state = {config: null, captures: [], selected: null, map: null, ready: nul
previousView: null, rotating: null, terrainFocus: null, refreshing: false, lastRefresh: 0, popup: null};
const form = $("capture-form");
const maxDrawLatitude = 85.0511287; // Remain inside Mercator bounds after rounding to seven decimals.
-const names = {streetview: "STREET VIEW", satellite: "SATELLITE", osm: "OSM", terrain: "TERRAIN"};
+const names = {streetview: "STREET VIEW", satellite: "SATELLITE", osm: "OSM", terrain: "TERRAIN", mesh: "3D MESH"};
const resolutionNames = ["Lowest", "Very low", "Low", "Medium", "High", "Very high", "Maximum"];
const sphereResolutionNames = ["Lowest", "Low", "Medium", "High", "Very high", "Maximum"];
const layerGroups = {satellite: ["satellite"], buildings: ["buildings", "building-outlines"],
@@ -719,7 +719,7 @@ function renderCapturePanel() {
for (const section of form.querySelectorAll("[data-source]")) {
section.hidden = !form.querySelector(`input[name="include"][value="${section.dataset.source}"]`).checked;
}
- $("capture-settings").hidden = !["satellite", "streetview"].some((source) => form.querySelector(`input[name="include"][value="${source}"]`).checked);
+ $("capture-settings").hidden = !["satellite", "streetview", "mesh"].some((source) => form.querySelector(`input[name="include"][value="${source}"]`).checked);
$("sources-error").hidden = sources > 0;
$("start-capture").disabled = !state.config || !state.draftBounds || !sources || busy || Boolean(state.job?.active);
$("start-capture-label").textContent = state.submitting ? "Planning…" : "Plan capture";
@@ -733,6 +733,10 @@ function renderResolution() {
const sphereLabel = sphereResolutionNames[sphere.valueAsNumber];
$("sphere-resolution-value").value = sphereLabel;
sphere.setAttribute("aria-valuetext", sphereLabel);
+ const mesh = form.elements.mesh_level;
+ const meshLabel = resolutionNames[mesh.valueAsNumber - Number(mesh.min)];
+ $("mesh-level-value").value = meshLabel;
+ mesh.setAttribute("aria-valuetext", meshLabel);
const input = form.elements.satellite_zoom;
const label = resolutionNames[input.valueAsNumber - Number(input.min)];
$("resolution-value").value = label;
@@ -944,7 +948,7 @@ async function planCapture(event) {
const options = {include: data.getAll("include"), depth: data.get("depth"),
full_sphere: data.get("full_sphere") === "true",
streetview_format: data.get("streetview_format"), satellite_format: data.get("satellite_format")};
- for (const key of ["step", "fov", "delay", "satellite_zoom", "terrain_zoom", "sphere_zoom"]) options[key] = Number(data.get(key));
+ for (const key of ["step", "fov", "delay", "satellite_zoom", "terrain_zoom", "sphere_zoom", "mesh_level"]) options[key] = Number(data.get(key));
const bounds = [...state.draftBounds];
state.submitting = true;
setDrawMode(false);
@@ -1000,6 +1004,7 @@ function showPlan(plan) {
row("OSM map extracts", estimate.osm_maps.toLocaleString());
row("Terrain tiles", estimate.terrain_tiles.toLocaleString());
}
+ if (sources.includes("mesh")) row("3D mesh nodes", estimate.mesh_nodes.toLocaleString());
$("plan-error").hidden = true;
setDrawMode(false);
renderCapturePanel();
@@ -1129,6 +1134,7 @@ function bindEvents() {
$("edit-plan").addEventListener("click", editPlan);
$("satellite-resolution").addEventListener("input", renderResolution);
$("sphere-zoom").addEventListener("input", renderResolution);
+ $("mesh-level").addEventListener("input", renderResolution);
form.addEventListener("change", renderCapturePanel);
$("search").addEventListener("input", renderLibrary);
$("refresh").addEventListener("click", () => refreshLibrary(true).catch((error) => notice(error.message)));
diff --git a/src/assets/index.html b/src/assets/index.html
index 912b1d4..9aaa389 100644
--- a/src/assets/index.html
+++ b/src/assets/index.html
@@ -97,6 +97,7 @@
<label><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="M3 7h4l2-3h6l2 3h4v13H3Z"/><circle cx="12" cy="13" r="4"/></svg><strong>Street View</strong><input name="include" type="checkbox" value="streetview"></label>
<label><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m12 3 9 5-9 5-9-5 9-5Zm-9 9 9 5 9-5M3 16l9 5 9-5"/></svg><strong>Satellite imagery</strong><input name="include" type="checkbox" value="satellite"></label>
<label><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m2 20 7-14 4 7 3-5 6 12H2Zm4-8 3 2 3-3M13 13l3 3 3-2"/></svg><strong>Map & terrain</strong><input name="include" type="checkbox" value="osm"></label>
+ <label><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m12 2 9 5v10l-9 5-9-5V7l9-5Zm0 10 9-5M12 12 3 7m9 5v10"/></svg><strong>3D mesh</strong><input name="include" type="checkbox" value="mesh"></label>
</div>
<p id="sources-error" class="field-error" role="status" hidden>Choose at least one source.</p>
</fieldset>
@@ -122,6 +123,12 @@
<div class="resolution-scale" aria-hidden="true"><span>Lowest</span><span>Maximum</span></div>
</div>
</div>
+ <div class="settings-group" data-source="mesh">
+ <h3 class="settings-divider"><svg viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m12 2 9 5v10l-9 5-9-5V7l9-5Zm0 10 9-5M12 12 3 7m9 5v10"/></svg>3D mesh</h3>
+ <div class="resolution-heading"><label for="mesh-level">Mesh detail</label><output id="mesh-level-value" for="mesh-level"></output></div>
+ <input id="mesh-level" class="resolution-slider" name="mesh_level" type="range" min="16" max="22" step="1">
+ <div class="resolution-scale" aria-hidden="true"><span>Lowest</span><span>Maximum</span></div>
+ </div>
</fieldset>
<details id="advanced-settings" class="settings">
<summary>Advanced</summary>
diff --git a/src/capture.py b/src/capture.py
index ce33cdc..88c83e5 100644
--- a/src/capture.py
+++ b/src/capture.py
@@ -10,20 +10,21 @@ from pathlib import Path
from PIL import Image
-from . import satellite, streetview, terrain
+from . import mesh, satellite, streetview, terrain
from .common import MissingImagery, contained, now, number, open_image, positive, write_bytes, write_json
from .geo import bounds, collection, coordinate, feature, grid, pixel, tile_ring, tiles
-SOURCES = ("streetview", "satellite", "osm")
+SOURCES = ("streetview", "satellite", "osm", "mesh")
FORMAT_VERSION = 4
DEFAULT_OPTIONS = dict(
- include=list(SOURCES), step=30, fov=75, depth="roads", streetview_format="jpg",
+ include=["streetview", "satellite", "osm"], step=30, fov=75, depth="roads", streetview_format="jpg",
full_sphere=False, sphere_zoom=3,
- delay=0, satellite_zoom=18, satellite_format="jpg", terrain_zoom=14,
+ delay=0, satellite_zoom=18, satellite_format="jpg", terrain_zoom=14, mesh_level=21,
)
# Average connection speed / hardware timings, just to give an idea to the user, not precise
-REQUEST_SECONDS = dict(metadata=0.17, photo=0.46, sphere_tile=0.27, satellite_tile=0.25, terrain_tile=1.39)
+REQUEST_SECONDS = dict(metadata=0.17, photo=0.46, sphere_tile=0.27, satellite_tile=0.25, terrain_tile=1.39,
+ mesh_node=0.021)
SPHERE_TILES = (1, 2, 8, 32, 128, 512)
OSM_EXPORT_SECONDS = 10
@@ -35,6 +36,10 @@ TERRAIN_NOTES = {
"terrain": "Heights in meters (Int16 up to zoom 12, Float32 from zoom 13), EPSG:3857, without resampling. Full edge tiles extend beyond the rectangle. Tiles are checkpointed individually; terrain.tif is built after all terrain tiles are saved.",
"quality": "Terrain resolution, dates, accuracy and vertical reference vary by source. Higher zoom does not guarantee more detail.",
}
+MESH_NOTES = {
+ "mesh": "Google Earth 3D photogrammetry as glTF binary with Google's original JPEG textures and baked-in lighting. Coordinates are meters from the rectangle's center at sea level: x east, y up, z south. Heights are approximate.",
+ "selection": "Nodes are saved as downloaded in mesh/nodes/. Finer nodes replace their parent's octants; triangles are kept when their center is inside the rectangle. Levels stop where Google's data ends; level 22 is the most detailed.",
+}
README = b"""Aleph capture
@@ -49,6 +54,8 @@ satellite.png contains the same full-resolution pixels for easy viewing.
Transparent pixels mark missing imagery or unfinished downloads.
terrain.tif holds meters in EPSG:3857 (Int16 up to zoom 12, else Float32).
Keep terrain/tiles/ for resume and offline export.
+mesh.glb is Google Earth's textured 3D mesh in meters around the center.
+Keep mesh/nodes/ for resume and offline export.
Filenames in the manifest and GeoJSON are relative to this run folder.
See manifest.json for settings, sources, imagery dates, and coverage notes.
@@ -65,11 +72,12 @@ def settings(values=None):
options = {**DEFAULT_OPTIONS, **values}
include = options["include"]
if not isinstance(include, list) or not include or any(source not in SOURCES for source in include):
- raise ValueError("Choose one or more sources: streetview, satellite, osm.")
+ raise ValueError("Choose one or more sources: streetview, satellite, osm, mesh.")
options["include"] = [source for source in SOURCES if source in include]
positive(options["step"], "step")
number(options["delay"], "delay", 0)
- for key, low, high in (("fov", 5, 175), ("sphere_zoom", 0, 5), ("satellite_zoom", 1, 21), ("terrain_zoom", 1, 14)):
+ for key, low, high in (("fov", 5, 175), ("sphere_zoom", 0, 5), ("satellite_zoom", 1, 21), ("terrain_zoom", 1, 14),
+ ("mesh_level", 1, 22)):
options[key] = number(options[key], key, low, high, whole=True)
if type(options["full_sphere"]) is not bool:
raise ValueError("full_sphere must be true or false.")
@@ -106,6 +114,9 @@ def plan(client, area, options, progress):
if "osm" in options["include"]:
stages.append(dict(mode="osm", results=[], notes=OSM_NOTES))
stages.append(dict(mode="terrain", grid=grid(area, options["terrain_zoom"]), results=[], notes=TERRAIN_NOTES))
+ if "mesh" in options["include"]:
+ stage = mesh.plan(client, area, options["mesh_level"], progress, allow_empty=len(options["include"]) > 1)
+ stages.append(dict(stage, notes=MESH_NOTES))
return dict(format="aleph-python", version=FORMAT_VERSION, bounds=area, options=options,
started_at=now(), state="planned", stages=stages)
@@ -115,6 +126,8 @@ def total(stage):
return len(stage["samples"]) * (1 if stage["full_sphere"] else 2)
if stage["mode"] == "osm":
return 1
+ if stage["mode"] == "mesh":
+ return len(stage["nodes"])
return stage["grid"]["rows"] * stage["grid"]["columns"]
@@ -124,7 +137,7 @@ def estimate(run):
Excludes planning, initial regional PBF downloads, and final merged exports.
Partly downloaded spheres are counted in full; their cached tiles may save time.
"""
- counts = dict(streetview_photos=0, streetview_stops=0, satellite_tiles=0, terrain_tiles=0, osm_maps=0)
+ counts = dict(streetview_photos=0, streetview_stops=0, satellite_tiles=0, terrain_tiles=0, osm_maps=0, mesh_nodes=0)
requests = dict.fromkeys(REQUEST_SECONDS, 0)
for stage in run["stages"]:
remaining = total(stage) - len(stage["results"])
@@ -141,6 +154,8 @@ def estimate(run):
counts["satellite_tiles"] = requests["satellite_tile"] = remaining
elif stage["mode"] == "osm":
counts["osm_maps"] = remaining
+ elif stage["mode"] == "mesh":
+ counts["mesh_nodes"] = requests["mesh_node"] = remaining
else:
counts["terrain_tiles"] = requests["terrain_tile"] = remaining
seconds = sum(count * REQUEST_SECONDS[kind] for kind, count in requests.items())
@@ -243,7 +258,25 @@ def capture_terrain(stage, run, folder, client, progress):
progress("Downloading terrain tiles", i + 1, total(stage))
-STAGES = dict(streetview=capture_streetview, satellite=capture_satellite, osm=capture_osm, terrain=capture_terrain)
+def capture_mesh(stage, run, folder, client, progress):
+ done = len(stage["results"])
+ progress("3D mesh", done, total(stage))
+ nodes = stage["nodes"][done:]
+ for node, data in zip(nodes, mesh.fetch(client, map(mesh.address, nodes))):
+ if data is None:
+ stage["results"].append(dict(status="skipped", reason="The 3D mesh node is not available."))
+ else:
+ mesh.check(data)
+ name = f"mesh/nodes/{node[0]}.bin"
+ write_bytes(folder / name, data)
+ stage["results"].append(dict(filename=name))
+ done += 1
+ yield
+ progress("3D mesh", done, total(stage))
+
+
+STAGES = dict(streetview=capture_streetview, satellite=capture_satellite, osm=capture_osm, terrain=capture_terrain,
+ mesh=capture_mesh)
def export(run, folder, progress, *, rebuild=True):
@@ -261,6 +294,9 @@ def export(run, folder, progress, *, rebuild=True):
elif stage["mode"] == "terrain":
if len(stage["results"]) == total(stage) and (rebuild or not (folder / "terrain.tif").is_file()):
terrain.merge(folder / "terrain.tif", folder, stage["results"], stage["grid"], progress)
+ elif stage["mode"] == "mesh":
+ if len(stage["results"]) == total(stage) and (rebuild or not (folder / "mesh.glb").is_file()):
+ mesh.export(folder / "mesh.glb", folder, stage, run["bounds"], progress)
run["exports_saved"] = True
write_json(folder / "manifest.json", run)
@@ -371,6 +407,8 @@ def load(folder, *, check_files=True):
if stage["mode"] in ("satellite", "terrain"):
if stage["grid"] != grid(run["bounds"], options[stage["mode"] + "_zoom"]):
raise ValueError("Invalid saved tile grid.")
+ if stage["mode"] == "mesh" and stage["level"] != options["mesh_level"]:
+ raise ValueError("Invalid saved mesh level.")
if len(stage["results"]) > total(stage):
raise ValueError("Invalid saved progress.")
if not check_files:
diff --git a/src/cli.py b/src/cli.py
index d12aa69..73172fd 100644
--- a/src/cli.py
+++ b/src/cli.py
@@ -137,7 +137,7 @@ def _capture_command(commands):
actions = captures.add_subparsers(dest="action", required=True)
area = actions.add_parser("create", help="Plan and download an area with multiple sources")
area.add_argument("--bbox", required=True, nargs=4, type=float, metavar=("S", "W", "N", "E"))
- area.add_argument("--sources", dest="include", nargs="+", choices=capture.SOURCES, help="sources to download (default: all; osm includes terrain)")
+ area.add_argument("--sources", dest="include", nargs="+", choices=capture.SOURCES, help="sources to download (default: streetview satellite osm; osm includes terrain)")
# Planning and confirmation.
planning = area.add_mutually_exclusive_group()
@@ -159,6 +159,9 @@ def _capture_command(commands):
# Terrain resolution.
area.add_argument("--terrain-zoom", type=int, help="terrain zoom, 1–14 (default: 14)")
+ # Google Earth 3D mesh detail.
+ area.add_argument("--mesh-level", type=int, help="3D mesh detail level, 1–22 (default: 21); each level halves the texel size")
+
# Requests, cache, and output shared by all capture sources.
area.add_argument("--delay", type=float, help="pause between requests in seconds (default: 0)")
_cache_options(area)
diff --git a/src/dashboard.py b/src/dashboard.py
index c682a68..002a567 100644
--- a/src/dashboard.py
+++ b/src/dashboard.py
@@ -126,7 +126,7 @@ class Catalog:
def file(self, identity, name):
folder, run, _ = self.get(identity)
- allowed = {"map.osm", "terrain.tif", "satellite.tif", "satellite.png", "manifest.json", "README.txt",
+ allowed = {"map.osm", "terrain.tif", "satellite.tif", "satellite.png", "mesh.glb", "manifest.json", "README.txt",
"streetview/photos.geojson", "streetview/paths.geojson", "streetview/plan.svg",
"satellite/patches.geojson", "satellite/plan.svg"}
allowed.update(item["filename"] for stage in run["stages"] for item in stage["results"]
diff --git a/src/mesh.py b/src/mesh.py
new file mode 100644
index 0000000..fd9b083
--- /dev/null
+++ b/src/mesh.py
@@ -0,0 +1,390 @@
+"""Google Earth 3D meshes: plan octree nodes, then join saved nodes into one glTF binary.
+
+Earth Web streams photogrammetry as an octree of protobuf messages. BulkMetadata
+lists nodes four levels at a time; NodeData holds a node's meshes with JPEG
+textures. A finer node replaces one octant of its parent's mesh. Positions lie
+on a sphere, onto which latitude and longitude map directly.
+Protocol notes: https://github.com/retroplasma/earth-reverse-engineering
+"""
+
+import json
+import math
+import shutil
+import struct
+import sys
+import tempfile
+from array import array
+from collections import deque
+from concurrent.futures import ThreadPoolExecutor
+from itertools import accumulate
+
+from .common import MissingImagery, atomic_path
+from .pbf import fields, unpack
+
+BASE = "https://kh.google.com/rt/earth/"
+LEAF, NODATA, USE_IMAGERY_EPOCH = 4, 8, 16
+JPEG = 1
+WORKERS = 16
+LOWEST, HIGHEST = -1000, 9000 # Heights searched for nodes, in meters from the sphere.
+GLB_LIMIT = 2**32
+BITS = [bytes((byte >> i) & 1 for i in range(8)) for byte in range(256)]
+
+
+def fetch(client, addresses):
+ """Yield responses in order with a few requests in flight; None marks missing data."""
+ def get(address):
+ try:
+ return client.get(address, missing_ok=True)
+ except MissingImagery:
+ return None
+
+ # Keep requests sequential when the user asks for pauses between them.
+ if client.delay:
+ yield from map(get, addresses)
+ return
+ pending = deque()
+ with ThreadPoolExecutor(WORKERS) as pool:
+ try:
+ for address in addresses:
+ pending.append(pool.submit(get, address))
+ if len(pending) > 2 * WORKERS:
+ yield pending.popleft().result()
+ while pending:
+ yield pending.popleft().result()
+ finally:
+ for future in pending:
+ future.cancel()
+
+
+def first(data):
+ """Protobuf fields keeping the first value of repeated ones."""
+ values = {}
+ for number, value in fields(data):
+ values.setdefault(number, value)
+ return values
+
+
+def dot(a, b):
+ return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def frame(lat, lon):
+ """East, north, and up unit vectors."""
+ la, lo = math.radians(lat), math.radians(lon)
+ return ((-math.sin(lo), math.cos(lo), 0.0),
+ (-math.sin(la) * math.cos(lo), -math.sin(la) * math.sin(lo), math.cos(la)),
+ (math.cos(la) * math.cos(lo), math.cos(la) * math.sin(lo), math.sin(la)))
+
+
+def search_box(area, radius):
+ """An oriented box around the rectangle, from below sea level to above the highest peaks."""
+ south, west, north, east = area
+ lat, lon = (south + north) / 2, (west + east) / 2
+ axes = frame(lat, lon)
+ half_east = half_north = drop = 0
+ for y in (south, north, lat, min(max(0, south), north)):
+ for x in (west, east, lon):
+ up = frame(y, x)[2]
+ point = [radius * (a - b) for a, b in zip(up, axes[2])]
+ half_east = max(half_east, abs(dot(point, axes[0])))
+ half_north = max(half_north, abs(dot(point, axes[1])))
+ drop = max(drop, -dot(point, axes[2]))
+ middle = (HIGHEST + LOWEST - drop) / 2
+ center = tuple((radius + middle) * a for a in axes[2])
+ return center, (half_east + 1, half_north + 1, (HIGHEST - LOWEST + drop) / 2), axes
+
+
+def overlaps(a, b):
+ """Separating-axis test for two oriented boxes: (center, half sizes, unit axes)."""
+ (c1, h1, r1), (c2, h2, r2) = a, b
+ d = (c2[0] - c1[0], c2[1] - c1[1], c2[2] - c1[2])
+ axes = [*r1, *r2]
+ for u in r1:
+ for v in r2:
+ w = (u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0])
+ if dot(w, w) > 1e-12:
+ axes.append(w)
+ return all(abs(dot(d, x)) <= sum(h * abs(dot(r, x)) for h, r in zip(h1 + h2, r1 + r2)) for x in axes)
+
+
+def node_box(packed, head, texel):
+ if len(packed) != 15:
+ raise ValueError("Unexpected 3D mesh node bounds.")
+ cx, cy, cz, ex, ey, ez, a0, a1, a2 = struct.unpack("<3h3B3H", packed)
+ a0, a1, a2 = a0 * math.pi / 32768, a1 * math.pi / 65536, a2 * math.pi / 32768
+ c0, s0, c1, s1, c2, s2 = math.cos(a0), math.sin(a0), math.cos(a1), math.sin(a1), math.cos(a2), math.sin(a2)
+ axes = ((c0 * c2 - c1 * s0 * s2, c1 * c0 * s2 + c2 * s0, s2 * s1),
+ (-c0 * s2 - c2 * c1 * s0, c0 * c1 * c2 - s0 * s2, c2 * s1),
+ (s1 * s0, -c0 * s1, c1))
+ center = (head[0] + cx * texel, head[1] + cy * texel, head[2] + cz * texel)
+ return center, (ex * texel, ey * texel, ez * texel), axes
+
+
+def bulk(data, head, epoch):
+ """Yield (path, flags, epoch, bulk epoch, imagery epoch, box) for up to four levels below head."""
+ nodes, center, texels, imagery = [], None, (), None
+ for number, value in fields(data):
+ if number == 1:
+ nodes.append(value)
+ elif number == 2:
+ epoch = dict(fields(value)).get(2, epoch)
+ elif number == 3:
+ center = struct.unpack("<3d", value)
+ elif number == 4:
+ texels = struct.unpack(f"<{len(value) // 4}f", value)
+ elif number == 5:
+ imagery = value
+ for raw in nodes:
+ node = dict(fields(raw))
+ packed = node[1]
+ depth = 1 + (packed & 3)
+ packed >>= 2
+ path = head
+ for _ in range(depth):
+ path += str(packed & 7)
+ packed >>= 3
+ texel = struct.unpack("<f", node[4])[0] if 4 in node else texels[depth - 1]
+ box = node_box(node[3], center, texel) if 3 in node else None
+ yield path, packed, node.get(2, epoch), node.get(5, epoch), node.get(7, imagery), box
+
+
+def plan(client, area, level, progress, *, allow_empty=False):
+ """Nodes with data meeting the rectangle down to level, and the octants their children refine."""
+ planet = dict(fields(client.get(BASE + "PlanetoidMetadata")))
+ root = dict(fields(planet[1]))
+ radius = struct.unpack("<f", planet[2])[0]
+ target = search_box(area, radius)
+ found, existing = [], set()
+ pending, done = [("", root.get(5, root[2]))], 0
+ progress("Finding 3D mesh nodes", done)
+ while pending:
+ batch, pending = pending, []
+ addresses = [f"{BASE}BulkMetadata/pb=!1m2!1s{path}!2u{epoch}" for path, epoch in batch]
+ for (head, epoch), data in zip(batch, fetch(client, addresses)):
+ done += 1
+ progress("Finding 3D mesh nodes", done)
+ if data is None:
+ continue
+ hit = set()
+ for path, flags, node_epoch, bulk_epoch, imagery, box in sorted(bulk(data, head, epoch),
+ key=lambda node: len(node[0])):
+ if not flags & NODATA:
+ existing.add(path)
+ # Parents come first; skip subtrees outside the area.
+ if ((len(path) > len(head) + 1 and path[:-1] not in hit) or len(path) > level
+ or box is None or not overlaps(target, box)):
+ continue
+ hit.add(path)
+ if not flags & NODATA:
+ found.append((path, node_epoch, imagery if flags & USE_IMAGERY_EPOCH else None))
+ if len(path) == len(head) + 4 and len(path) < level and not flags & LEAF:
+ pending.append((path, bulk_epoch))
+ # Children replace their parent's octant, even outside the area where cropping removes them.
+ # Skip parents with every octant replaced: they would add no triangles.
+ nodes = []
+ for path, epoch, imagery in sorted(found):
+ mask = sum(1 << k for k in range(8) if f"{path}{k}" in existing) if len(path) < level else 0
+ if mask != 255:
+ nodes.append([path, epoch, imagery, mask])
+ if not nodes and not allow_empty:
+ raise ValueError("No Google Earth 3D data in this area.")
+ return dict(mode="mesh", level=level, radius=radius, nodes=nodes, results=[])
+
+
+def address(node):
+ path, epoch, imagery, _ = node
+ return (f"{BASE}NodeData/pb=!1m2!1s{path}!2u{epoch}!2e{JPEG}"
+ + ("" if imagery is None else f"!3u{imagery}") + "!4b0")
+
+
+def check(data):
+ """Reject responses that are not a node with a 4 × 4 transform."""
+ if len(first(data).get(1, b"")) != 128:
+ raise ValueError("Unexpected 3D mesh node data.")
+
+
+def words(low, high):
+ """Little-endian 16-bit values from separate low and high byte planes."""
+ joined = bytearray(2 * len(low))
+ joined[0::2], joined[1::2] = low, high
+ values = array("H", joined)
+ if sys.byteorder != "little":
+ values.byteswap()
+ return values
+
+
+def counted(data, name):
+ """Packed integers preceded by their count."""
+ values = unpack(data)
+ if not values or len(values) != values[0] + 1:
+ raise ValueError(f"Unexpected 3D mesh {name}.")
+ return values[1:]
+
+
+def decode(data, mask, axes, radius, inside):
+ """Yield (positions, texture coordinates, triangles, JPEG) per mesh, in local meters.
+
+ Keeps the three base layers, without skirts, octants in mask, or triangles centered outside.
+ """
+ matrix, meshes = None, []
+ for number, value in fields(data):
+ if number == 1:
+ matrix = struct.unpack("<16d", value)
+ elif number == 2:
+ meshes.append(value)
+ if not meshes:
+ return
+ if matrix is None:
+ raise ValueError("Unexpected 3D mesh node data.")
+ # Fold the column-major globe transform into the move to east/north/up around the origin.
+ rows = [[dot(axis, matrix[4 * j:4 * j + 3]) for j in range(4)] for axis in axes]
+ rows[2][3] -= radius
+ (a0, a1, a2, at), (b0, b1, b2, bt), (c0, c1, c2, ct) = rows
+ for raw in meshes:
+ mesh, offsets = {}, b""
+ for number, value in fields(raw):
+ if number == 10:
+ offsets += value # Four floats, packed or not.
+ else:
+ mesh.setdefault(number, value)
+ vertices, uv = mesh.get(1, b""), mesh.get(7, b"")
+ count = len(vertices) // 3
+ if not count or len(vertices) != 3 * count or len(uv) != 4 + 4 * count:
+ raise ValueError("Unexpected 3D mesh vertices.")
+ texture = first(mesh.get(6, b""))
+ if 1 not in texture or texture.get(2, JPEG) != JPEG:
+ raise ValueError("Unexpected 3D mesh texture.")
+
+ xs, ys, zs = ([v & 255 for v in accumulate(vertices[i * count:(i + 1) * count])] for i in range(3))
+ east = [a0 * x + a1 * y + a2 * z + at for x, y, z in zip(xs, ys, zs)]
+ north = [b0 * x + b1 * y + b2 * z + bt for x, y, z in zip(xs, ys, zs)]
+ up = [c0 * x + c1 * y + c2 * z + ct for x, y, z in zip(xs, ys, zs)]
+ u_mod, v_mod = 1 + uv[0] + (uv[1] << 8), 1 + uv[2] + (uv[3] << 8)
+ planes = [uv[4 + i * count:4 + (i + 1) * count] for i in range(4)]
+ if len(offsets) == 16:
+ u_offset, v_offset, u_scale, v_scale = struct.unpack("<4f", offsets)
+ else:
+ u_offset, v_offset, u_scale, v_scale = 0.5, 0.5, 1 / u_mod, 1 / v_mod
+ us = [(u % u_mod + u_offset) * u_scale for u in accumulate(words(planes[0], planes[2]))]
+ vs = [(v % v_mod + v_offset) * v_scale for v in accumulate(words(planes[1], planes[3]))]
+
+ # A zero index adds the next new vertex; others count back from the newest.
+ strip, zeros = [], 0
+ for value in counted(mesh.get(3, b""), "indices"):
+ strip.append(zeros - value)
+ if not value:
+ zeros += 1
+ if zeros > count or (strip and min(strip) < 0):
+ raise ValueError("Unexpected 3D mesh indices.")
+ # Runs cycle through eight octants per layer; trailing positions belong to no drawn layer.
+ runs = counted(mesh.get(8, b""), "octants")
+ keep = b"".join((b"\1" if j < 24 and not mask >> (j & 7) & 1 else b"\0") * size
+ for j, size in enumerate(runs)).ljust(len(strip), b"\0")
+ skirts = b"".join(BITS[byte] for byte in mesh.get(13, b"")).ljust(len(strip), b"\0")
+ triangles = []
+ for t in range(len(strip) - 2):
+ if not keep[t + 2] or skirts[t]:
+ continue
+ a, b, c = strip[t], strip[t + 1], strip[t + 2]
+ if a != b != c != a and inside((east[a] + east[b] + east[c]) / 3, (north[a] + north[b] + north[c]) / 3,
+ (up[a] + up[b] + up[c]) / 3):
+ triangles += (a, c, b) if t & 1 else (a, b, c)
+ if not triangles:
+ continue
+ used = list(dict.fromkeys(triangles))
+ index = {v: i for i, v in enumerate(used)}
+ # glTF is Y-up: x east, y up, z south.
+ positions = array("f", [value for v in used for value in (east[v], up[v], -north[v])])
+ texcoords = array("f", [value for v in used for value in (us[v], vs[v])])
+ indices = array("H" if len(used) <= 65536 else "I", [index[v] for v in triangles])
+ yield positions, texcoords, indices, texture[1]
+
+
+def crop(area, axes, radius):
+ """A test for local east/north/up points inside the rectangle's latitudes and longitudes."""
+ south, west, north, east = (math.radians(value) for value in area)
+ (ex, ey, ez), (nx, ny, nz), (ux, uy, uz) = axes
+ low, high = math.sin(south), math.sin(north)
+ west_x, west_y, east_x, east_y = -math.sin(west), math.cos(west), -math.sin(east), math.cos(east)
+
+ def inside(e, n, u):
+ r = radius + u
+ x, y, z = ex * e + nx * n + ux * r, ey * e + ny * n + uy * r, ez * e + nz * n + uz * r
+ length = math.sqrt(x * x + y * y + z * z)
+ return low * length <= z <= high * length and x * west_x + y * west_y >= 0 >= x * east_x + y * east_y
+
+ return inside
+
+
+def export(path, folder, stage, area, progress):
+ """Join saved nodes into one glTF binary in a local east/north/up frame around the center."""
+ nodes, results = stage["nodes"], stage["results"]
+ radius = stage["radius"]
+ lat, lon = (area[0] + area[2]) / 2, (area[1] + area[3]) / 2
+ axes = frame(lat, lon)
+ inside = crop(area, axes, radius)
+ # Keep parent octants whose child was unavailable, so gaps stay covered.
+ missing = {node[0] for node, result in zip(nodes, results) if result.get("status") == "skipped"}
+ saved = [(node, result["filename"]) for node, result in zip(nodes, results) if "filename" in result]
+ gltf = dict(
+ asset=dict(version="2.0", generator="Aleph", copyright="© Google",
+ extras=dict(latitude=lat, longitude=lon, radius=radius, bounds=list(area),
+ frame="meters east (x), up (y), and south (z) of the center at sea level")),
+ scene=0, scenes=[dict(nodes=[])], nodes=[], meshes=[], materials=[], textures=[], images=[],
+ accessors=[], bufferViews=[], samplers=[dict(magFilter=9729, minFilter=9987, wrapS=33071, wrapT=33071)],
+ extensionsUsed=["KHR_materials_unlit"],
+ )
+ progress("Building mesh.glb", 0, len(saved))
+ with tempfile.TemporaryFile(dir=folder) as spool:
+ def view(data, target=None):
+ if sys.byteorder != "little" and isinstance(data, array):
+ data = array(data.typecode, data)
+ data.byteswap()
+ data = bytes(data)
+ gltf["bufferViews"].append(dict(buffer=0, byteOffset=spool.tell(), byteLength=len(data),
+ **({"target": target} if target else {})))
+ spool.write(data + b"\0" * (-len(data) % 4))
+ if spool.tell() >= GLB_LIMIT:
+ raise ValueError("The 3D mesh exceeds the 4 GiB glTF limit. Use a smaller area or lower mesh level.")
+ return len(gltf["bufferViews"]) - 1
+
+ for done, (node, filename) in enumerate(saved, 1):
+ mask = node[3] & ~sum(1 << k for k in range(8) if f"{node[0]}{k}" in missing)
+ data = (folder / filename).read_bytes()
+ for part, (positions, texcoords, indices, jpeg) in enumerate(decode(data, mask, axes, radius, inside)):
+ i, k = len(gltf["meshes"]), len(gltf["accessors"])
+ name = node[0] if not part else f"{node[0]}-{part}"
+ gltf["accessors"] += [
+ dict(bufferView=view(positions, 34962), componentType=5126, count=len(positions) // 3,
+ type="VEC3", min=[min(positions[j::3]) for j in range(3)],
+ max=[max(positions[j::3]) for j in range(3)]),
+ dict(bufferView=view(texcoords, 34962), componentType=5126, count=len(texcoords) // 2,
+ type="VEC2"),
+ dict(bufferView=view(indices, 34963), componentType=5123 if indices.typecode == "H" else 5125,
+ count=len(indices), type="SCALAR"),
+ ]
+ gltf["images"].append(dict(bufferView=view(jpeg), mimeType="image/jpeg"))
+ gltf["textures"].append(dict(source=i, sampler=0))
+ gltf["materials"].append(dict(name=name, doubleSided=True, extensions={"KHR_materials_unlit": {}},
+ pbrMetallicRoughness=dict(baseColorTexture=dict(index=i),
+ metallicFactor=0, roughnessFactor=1)))
+ gltf["meshes"].append(dict(name=name, primitives=[dict(
+ attributes=dict(POSITION=k, TEXCOORD_0=k + 1), indices=k + 2, material=i)]))
+ gltf["nodes"].append(dict(name=name, mesh=i))
+ gltf["scenes"][0]["nodes"].append(i)
+ progress("Building mesh.glb", done, len(saved))
+ if not gltf["meshes"]:
+ return
+ size = spool.tell()
+ gltf["buffers"] = [dict(byteLength=size)]
+ header = json.dumps(gltf, ensure_ascii=False, separators=(",", ":")).encode()
+ header += b" " * (-len(header) % 4)
+ total = 28 + len(header) + size
+ if total >= GLB_LIMIT:
+ raise ValueError("The 3D mesh exceeds the 4 GiB glTF limit. Use a smaller area or lower mesh level.")
+ with atomic_path(path) as temporary, temporary.open("wb") as output:
+ output.write(struct.pack("<III", 0x46546C67, 2, total))
+ output.write(struct.pack("<II", len(header), 0x4E4F534A) + header)
+ output.write(struct.pack("<II", size, 0x004E4942))
+ spool.seek(0)
+ shutil.copyfileobj(spool, output)
diff --git a/tests/test_mesh.py b/tests/test_mesh.py
new file mode 100644
index 0000000..6163049
--- /dev/null
+++ b/tests/test_mesh.py
@@ -0,0 +1,144 @@
+"""Decode synthetic Google Earth nodes and download them through the capture engine."""
+
+import json
+import struct
+import time
+import unittest
+from array import array
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest.mock import Mock
+
+from src import capture, mesh
+from src.common import MissingImagery, write_bytes
+
+RADIUS = 6371010.0
+AREA = (-1e-4, -1e-4, 1e-4, 1e-4) # About 22 m square around latitude 0, longitude 0.
+
+
+def varint(value):
+ out = bytearray()
+ while True:
+ out.append((value & 127) | (128 if value > 127 else 0))
+ value >>= 7
+ if not value:
+ return bytes(out)
+
+
+def field(number, value):
+ if isinstance(value, int):
+ return varint(number << 3) + varint(value)
+ return varint(number << 3 | 2) + varint(len(value)) + value
+
+
+def counted(values):
+ return b"".join(map(varint, [len(values), *values]))
+
+
+def deltas(values):
+ return bytes((b - a) & 255 for a, b in zip([0, *values], values))
+
+
+def node(vertices=(), strip=(), runs=(), skirts=b"", jpeg=b""):
+ """Vertex x, y, z map to meters east, north, and up, offset by 100 m horizontally."""
+ matrix = struct.pack("<16d", 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, RADIUS, -100, -100, 1)
+ data = field(1, matrix)
+ if not vertices:
+ return data
+ xs, ys, zs = zip(*[(e + 100, n + 100, u) for e, n, u in vertices])
+ us, vs = [10 * i for i in range(len(vertices))], [5 * i for i in range(len(vertices))]
+ zeros, indices = 0, []
+ for index in strip:
+ indices.append(0 if index == zeros else zeros - index)
+ zeros += index == zeros
+ texture = field(1, jpeg) + field(2, mesh.JPEG)
+ return data + field(2, b"".join([
+ field(1, deltas(xs) + deltas(ys) + deltas(zs)),
+ field(3, counted(indices)),
+ field(6, texture),
+ field(7, b"\xff\0\xff\0" + deltas(us) + deltas(vs) + bytes(len(us)) + bytes(len(vs))),
+ field(8, counted(runs)),
+ field(13, skirts),
+ ]))
+
+
+def read_glb(path):
+ data = Path(path).read_bytes()
+ size = struct.unpack("<I", data[12:16])[0]
+ gltf, body = json.loads(data[20:20 + size]), data[28 + size:]
+
+ def view(index, kind):
+ v = gltf["bufferViews"][index]
+ return array(kind, body[v["byteOffset"]:v["byteOffset"] + v["byteLength"]])
+
+ return gltf, view
+
+
+class MeshTests(unittest.TestCase):
+ def setUp(self):
+ temporary = TemporaryDirectory()
+ self.addCleanup(temporary.cleanup)
+ self.folder = Path(temporary.name)
+
+ def test_export_drops_refined_octants_skirts_upper_layers_and_outside_triangles(self):
+ vertices = [(0, 0, 1), (2, 0, 0), (0, 2, 0), (2, 2, 0), (4, 0, 0), (4, 2, 0), (0, 4, 0), (60, 60, 0), (-60, -60, 0)]
+ # Triangles: 0 kept, 1 skirt, 2–3 degenerate, 4 octant refined by "01", 5 octant of the
+ # unavailable "02" (kept, odd so flipped), 6 centered outside, 7 in the fourth layer.
+ strip = [0, 1, 2, 3, 3, 4, 5, 6, 7, 8]
+ runs = [6, 1, 1, 0, 0, 0, 0, 0, 1] + [0] * 15 + [1]
+ write_bytes(self.folder / "0.bin", node(vertices, strip, runs, skirts=bytes([0b10]), jpeg=b"jpeg-0"))
+ write_bytes(self.folder / "01.bin", node())
+ stage = dict(radius=RADIUS, nodes=[["0", 1, None, 0b110], ["01", 1, None, 0], ["02", 1, None, 0]],
+ results=[dict(filename="0.bin"), dict(filename="01.bin"), dict(status="skipped")])
+ mesh.export(self.folder / "mesh.glb", self.folder, stage, AREA, Mock())
+
+ gltf, view = read_glb(self.folder / "mesh.glb")
+ self.assertEqual([m["name"] for m in gltf["meshes"]], ["0"])
+ position, uv, indices = (gltf["accessors"][i]["bufferView"] for i in range(3))
+ self.assertEqual(list(view(indices, "H")), [0, 1, 2, 3, 4, 5])
+ # Vertices 0, 1, 2, 4, 6, 5 as x east, y up, z south.
+ self.assertEqual(list(view(position, "f")), [0, 1, 0, 2, 0, 0, 0, 0, -2, 4, 0, 0, 0, 0, -4, 4, 0, -2])
+ self.assertEqual(list(view(uv, "f"))[6:8], [40.5 / 256, 20.5 / 256])
+ self.assertEqual(view(gltf["images"][0]["bufferView"], "B").tobytes(), b"jpeg-0")
+
+ def test_parallel_download_keeps_node_order_across_interrupt_and_resume(self):
+ nodes = [[f"0{i:02d}", 1, None, 0] for i in range(20)]
+ run = dict(format="aleph-python", version=capture.FORMAT_VERSION, bounds=list(AREA),
+ options=capture.settings({"include": ["mesh"]}), started_at="", state="planned",
+ stages=[dict(mode="mesh", level=21, radius=RADIUS, nodes=nodes, results=[])])
+
+ def payload(path):
+ return node() + field(4, path.encode())
+
+ def get(address, interrupt=None, **_):
+ path = address.split("!1s")[1].split("!")[0]
+ time.sleep(0.02 if int(path) % 2 else 0) # Finish out of order.
+ if path == interrupt:
+ raise KeyboardInterrupt()
+ if path == "005":
+ raise MissingImagery("Gone.")
+ return payload(path)
+
+ client = Mock(delay=0)
+ client.get.side_effect = lambda address, **kwargs: get(address, "012", **kwargs)
+ with self.assertRaises(KeyboardInterrupt):
+ capture.download(run, self.folder, client, Mock())
+
+ saved = capture.load(self.folder)
+ results = saved["stages"][0]["results"]
+ self.assertEqual((saved["state"], len(results)), ("stopped", 12))
+ self.assertEqual(results[5]["status"], "skipped")
+ for node_, result in zip(nodes, results):
+ if "filename" in result:
+ self.assertEqual((self.folder / result["filename"]).read_bytes(), payload(node_[0]))
+
+ client.get.reset_mock(side_effect=True)
+ client.get.side_effect = get
+ capture.download(saved, self.folder, client, Mock())
+ requested = sorted(call.args[0].split("!1s")[1].split("!")[0] for call in client.get.call_args_list)
+ self.assertEqual(requested, [node_[0] for node_ in nodes[12:]])
+ self.assertEqual(capture.load(self.folder)["state"], "complete")
+
+
+if __name__ == "__main__":
+ unittest.main()