Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript

M2: Satellite — XYZ tile engine with provenance, Leaflet capture UI

OsintMeThat1e1423a19d48
diff --git a/frontend/src/tools/PostComposer.svelte b/frontend/src/tools/PostComposer.svelte
index 4127cb0..77bd79d 100644
--- a/frontend/src/tools/PostComposer.svelte
+++ b/frontend/src/tools/PostComposer.svelte
@@ -6,8 +6,8 @@
<div class="tool-body">
<div class="empty" style="height: 100%">
<div class="empty-icon"><Icon name="post" size={40} /></div>
- <h3>PostComposer</h3>
- <p>Coming in this milestone.</p>
+ <h3>Post Composer</h3>
+ <p>Coming in the next milestone.</p>
</div>
</div>
</div>
diff --git a/frontend/src/tools/ProofComposer.svelte b/frontend/src/tools/ProofComposer.svelte
index 3142d23..f261e7f 100644
--- a/frontend/src/tools/ProofComposer.svelte
+++ b/frontend/src/tools/ProofComposer.svelte
@@ -6,8 +6,8 @@
<div class="tool-body">
<div class="empty" style="height: 100%">
<div class="empty-icon"><Icon name="proof" size={40} /></div>
- <h3>ProofComposer</h3>
- <p>Coming in this milestone.</p>
+ <h3>Proof Composer</h3>
+ <p>Coming in the next milestone.</p>
</div>
</div>
</div>
diff --git a/frontend/src/tools/Satellite.svelte b/frontend/src/tools/Satellite.svelte
index e7da8cb..5473fce 100644
--- a/frontend/src/tools/Satellite.svelte
+++ b/frontend/src/tools/Satellite.svelte
@@ -1,13 +1,440 @@
<script>
+ import { onMount } from 'svelte';
+ import L from 'leaflet';
+ import 'leaflet/dist/leaflet.css';
+ import { api } from '../lib/api.js';
+ import { caseState, uiState, ensureCase, reloadCase, toast } from '../lib/state.svelte.js';
import Icon from '../components/Icon.svelte';
+
+ let mapEl;
+ let map;
+ let tileLayer;
+ let providers = $state([]);
+ let providerId = $state('esri-world-imagery');
+ let coordsText = $state('');
+ let center = $state({ lat: 48.8584, lon: 2.2945, zoom: 16 });
+ let size = $state('1000x700');
+ let crosshair = $state(true);
+ let capturing = $state(false);
+ let captures = $state([]);
+ let capturesFor = $state(null);
+
+ onMount(async () => {
+ providers = await api.get('/api/satellite/providers');
+ map = L.map(mapEl, {
+ center: [center.lat, center.lon],
+ zoom: center.zoom,
+ zoomControl: true,
+ attributionControl: true,
+ });
+ setLayer();
+ map.on('moveend zoomend', () => {
+ const c = map.getCenter();
+ center = { lat: c.lat, lon: c.lng, zoom: map.getZoom() };
+ });
+ return () => map.remove();
+ });
+
+ function setLayer() {
+ const p = providers.find((x) => x.id === providerId);
+ if (!p || !map) return;
+ if (tileLayer) tileLayer.remove();
+ tileLayer = L.tileLayer(p.url, {
+ attribution: p.attribution,
+ maxZoom: p.max_zoom,
+ }).addTo(map);
+ }
+
+ $effect(() => {
+ providerId; // track provider changes
+ setLayer();
+ });
+
+ $effect(() => {
+ const id = caseState.current?.id;
+ if (id !== capturesFor) {
+ capturesFor = id;
+ captures = [];
+ if (id) api.get(`/api/cases/${id}/satellite`).then((r) => (captures = r));
+ }
+ });
+
+ async function goTo() {
+ const text = coordsText.trim();
+ if (!text) return;
+ try {
+ const parsed = await api.post('/api/geo/parse', { text });
+ map.setView([parsed.lat, parsed.lon], Math.max(map.getZoom(), 16));
+ } catch {
+ toast('Could not parse coordinates — try "50.4501, 30.5234" or DMS', 'danger');
+ }
+ }
+
+ async function captureCrop() {
+ if (capturing) return;
+ capturing = true;
+ const [width, height] = size.split('x').map(Number);
+ try {
+ const c = await ensureCase();
+ const result = await api.post(`/api/cases/${c.id}/satellite/capture`, {
+ lat: center.lat,
+ lon: center.lon,
+ zoom: center.zoom,
+ width,
+ height,
+ provider: providerId,
+ crosshair,
+ });
+ captures = [result, ...captures];
+ await reloadCase();
+ toast(
+ result.tiles_missing
+ ? `Captured with ${result.tiles_missing} missing tile(s) — no imagery there`
+ : 'Satellite crop captured & filed',
+ result.tiles_missing ? 'warn' : 'ok'
+ );
+ } catch (e) {
+ toast(`Capture failed: ${e.message}`, 'danger', 6000);
+ } finally {
+ capturing = false;
+ }
+ }
+
+ async function removeCapture(item) {
+ await api.del(
+ `/api/cases/${caseState.current.id}/satellite?path=${encodeURIComponent(item.path)}`
+ );
+ captures = captures.filter((c) => c.path !== item.path);
+ }
+
+ function sendToComposer(item) {
+ if (!uiState.composeQueue.includes(item.path)) uiState.composeQueue.push(item.path);
+ uiState.tool = 'proof';
+ }
+
+ function fmt(value) {
+ return value.toFixed(5);
+ }
+
+ async function copyCoords() {
+ await navigator.clipboard.writeText(`${fmt(center.lat)}, ${fmt(center.lon)}`);
+ toast('Coordinates copied', 'ok', 1600);
+ }
</script>
<div class="tool">
- <div class="tool-body">
- <div class="empty" style="height: 100%">
- <div class="empty-icon"><Icon name="satellite" size={40} /></div>
- <h3>Satellite</h3>
- <p>Coming in this milestone.</p>
+ <div class="tool-header">
+ <h2>Satellite</h2>
+ <span class="sub">pan to a point, capture a sourced imagery crop</span>
+ <div class="spacer"></div>
+ <form
+ class="go-form"
+ onsubmit={(e) => {
+ e.preventDefault();
+ goTo();
+ }}
+ >
+ <input
+ class="input"
+ placeholder={'50.4501, 30.5234 · 48°51\'29"N 2°17\'40"E'}
+ bind:value={coordsText}
+ />
+ <button type="submit" class="btn" disabled={!coordsText.trim()}>
+ <Icon name="search" size={15} /> Go
+ </button>
+ </form>
+ </div>
+
+ <div class="body">
+ <div class="map-wrap">
+ <div class="map" bind:this={mapEl}></div>
+ <div class="crosshair-overlay" class:hidden={!crosshair} aria-hidden="true">
+ <svg width="46" height="46" viewBox="0 0 46 46">
+ <g stroke="#000" stroke-width="4" opacity="0.55">
+ <line x1="1" y1="23" x2="16" y2="23" /><line x1="30" y1="23" x2="45" y2="23" />
+ <line x1="23" y1="1" x2="23" y2="16" /><line x1="23" y1="30" x2="23" y2="45" />
+ </g>
+ <g stroke="#fff" stroke-width="2">
+ <line x1="1" y1="23" x2="16" y2="23" /><line x1="30" y1="23" x2="45" y2="23" />
+ <line x1="23" y1="1" x2="23" y2="16" /><line x1="23" y1="30" x2="23" y2="45" />
+ <circle cx="23" cy="23" r="2.5" fill="none" />
+ </g>
+ </svg>
+ </div>
+
+ <div class="hud card">
+ <button class="hud-coords mono" onclick={copyCoords} title="Copy coordinates">
+ <Icon name="crosshair" size={13} />
+ {fmt(center.lat)}, {fmt(center.lon)}
+ <span class="z">z{center.zoom}</span>
+ <Icon name="copy" size={12} />
+ </button>
+ </div>
+
+ <div class="capture-bar card">
+ <select class="select" bind:value={providerId} title="Imagery provider">
+ {#each providers as p (p.id)}
+ <option value={p.id} disabled={p.needs_key}>
+ {p.label}{p.needs_key ? ' (needs API key)' : ''}
+ </option>
+ {/each}
+ </select>
+ <select class="select" bind:value={size} title="Crop size">
+ <option value="800x600">800 × 600</option>
+ <option value="1000x700">1000 × 700</option>
+ <option value="1280x800">1280 × 800</option>
+ <option value="1000x1000">1000 × 1000</option>
+ </select>
+ <label class="check">
+ <input type="checkbox" bind:checked={crosshair} /> crosshair
+ </label>
+ <button class="btn btn-primary" onclick={captureCrop} disabled={capturing}>
+ {#if capturing}
+ <span class="spinner"></span> Capturing…
+ {:else}
+ <Icon name="satellite" size={15} /> Capture
+ {/if}
+ </button>
+ </div>
</div>
+
+ <aside class="captures">
+ <div class="cap-head">
+ <span class="label" style="margin:0">Captures</span>
+ <span class="count">{captures.length}</span>
+ </div>
+ {#if !captures.length}
+ <div class="none">
+ Captured crops land in the case with full provenance: provider, zoom, date,
+ attribution.
+ </div>
+ {:else}
+ <div class="cap-list">
+ {#each captures as item (item.path)}
+ <div class="cap card fade-up">
+ <img
+ src={`/files/${caseState.current.id}/${item.path}`}
+ alt={item.filename}
+ loading="lazy"
+ />
+ <div class="cap-meta">
+ <span class="mono coords">{item.lat.toFixed(5)}, {item.lon.toFixed(5)}</span>
+ <span class="prov">z{item.zoom} · {item.provider_label} · {item.fetched_at?.slice(0, 10)}</span>
+ </div>
+ <div class="cap-actions">
+ <button
+ class="btn btn-ghost btn-sm"
+ title="Send to Proof Composer"
+ onclick={() => sendToComposer(item)}
+ >
+ <Icon name="proof" size={14} />
+ </button>
+ <a
+ class="btn btn-ghost btn-sm"
+ href={`/files/${caseState.current.id}/${item.path}`}
+ target="_blank"
+ rel="noreferrer"
+ title="Open"
+ >
+ <Icon name="external" size={14} />
+ </a>
+ <button
+ class="btn btn-ghost btn-sm"
+ title="Delete"
+ onclick={() => removeCapture(item)}
+ >
+ <Icon name="trash" size={14} />
+ </button>
+ </div>
+ </div>
+ {/each}
+ </div>
+ {/if}
+ </aside>
</div>
</div>
+
+<style>
+ .spacer {
+ flex: 1;
+ }
+ .go-form {
+ display: flex;
+ gap: 8px;
+ width: min(420px, 36vw);
+ }
+ .body {
+ flex: 1;
+ display: flex;
+ min-height: 0;
+ }
+ .map-wrap {
+ position: relative;
+ flex: 1;
+ min-width: 0;
+ }
+ .map {
+ position: absolute;
+ inset: 0;
+ background: var(--bg-2);
+ }
+ .crosshair-overlay {
+ position: absolute;
+ inset: 0;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ pointer-events: none;
+ z-index: 500;
+ }
+ .crosshair-overlay.hidden {
+ display: none;
+ }
+ .hud {
+ position: absolute;
+ top: 12px;
+ left: 50%;
+ transform: translateX(-50%);
+ z-index: 600;
+ background: rgba(16, 22, 35, 0.88);
+ backdrop-filter: blur(6px);
+ }
+ .hud-coords {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 7px 13px;
+ font-size: var(--fs-sm);
+ color: var(--text-1);
+ }
+ .hud-coords:hover {
+ color: var(--accent);
+ }
+ .z {
+ color: var(--text-3);
+ font-size: var(--fs-xs);
+ }
+ .capture-bar {
+ position: absolute;
+ bottom: 16px;
+ left: 50%;
+ transform: translateX(-50%);
+ z-index: 600;
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 10px 12px;
+ background: rgba(16, 22, 35, 0.92);
+ backdrop-filter: blur(6px);
+ box-shadow: var(--shadow-2);
+ }
+ .capture-bar .select {
+ width: auto;
+ }
+ .check {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ font-size: var(--fs-sm);
+ color: var(--text-2);
+ user-select: none;
+ white-space: nowrap;
+ }
+ .check input {
+ accent-color: var(--accent);
+ }
+ .spinner {
+ width: 13px;
+ height: 13px;
+ border: 2px solid var(--accent-text);
+ border-top-color: transparent;
+ border-radius: 50%;
+ animation: spin 0.7s linear infinite;
+ }
+ @keyframes spin {
+ to {
+ transform: rotate(360deg);
+ }
+ }
+ .captures {
+ width: 300px;
+ flex-shrink: 0;
+ border-left: 1px solid var(--border);
+ background: var(--bg-1);
+ display: flex;
+ flex-direction: column;
+ }
+ .cap-head {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ padding: 14px 14px 8px;
+ }
+ .count {
+ font-size: var(--fs-xs);
+ color: var(--text-3);
+ font-weight: 600;
+ }
+ .none {
+ padding: 8px 14px;
+ font-size: var(--fs-xs);
+ color: var(--text-3);
+ }
+ .cap-list {
+ flex: 1;
+ overflow-y: auto;
+ padding: 6px 12px 12px;
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+ }
+ .cap {
+ overflow: hidden;
+ }
+ .cap img {
+ width: 100%;
+ aspect-ratio: 10 / 7;
+ object-fit: cover;
+ background: var(--bg-2);
+ }
+ .cap-meta {
+ padding: 8px 10px 2px;
+ display: flex;
+ flex-direction: column;
+ }
+ .coords {
+ font-size: var(--fs-xs);
+ color: var(--text-1);
+ }
+ .prov {
+ font-size: var(--fs-xs);
+ color: var(--text-3);
+ }
+ .cap-actions {
+ display: flex;
+ gap: 2px;
+ padding: 4px 6px 6px;
+ }
+
+ /* Leaflet dark-theme adjustments */
+ :global(.leaflet-container) {
+ font-family: var(--font-sans);
+ background: var(--bg-2);
+ }
+ :global(.leaflet-control-attribution) {
+ background: rgba(16, 22, 35, 0.85) !important;
+ color: var(--text-3) !important;
+ font-size: 10px;
+ }
+ :global(.leaflet-control-attribution a) {
+ color: var(--text-2) !important;
+ }
+ :global(.leaflet-bar a) {
+ background: var(--bg-2) !important;
+ color: var(--text-1) !important;
+ border-color: var(--border) !important;
+ }
+ :global(.leaflet-bar a:hover) {
+ background: var(--bg-3) !important;
+ }
+</style>
diff --git a/src/ozimut/api/satellite.py b/src/ozimut/api/satellite.py
new file mode 100644
index 0000000..81f0d5e
--- /dev/null
+++ b/src/ozimut/api/satellite.py
@@ -0,0 +1,128 @@
+"""REST API for the Satellite tool: providers, capture crops, list captures."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from ..engine import geo, tiles
+from .cases import get_case
+
+router = APIRouter(prefix="/api", tags=["satellite"])
+
+
+class CaptureIn(BaseModel):
+ lat: float = Field(ge=-90, le=90)
+ lon: float = Field(ge=-180, le=180)
+ zoom: int = Field(ge=1, le=22)
+ width: int = Field(default=1000, ge=256, le=2048)
+ height: int = Field(default=700, ge=256, le=2048)
+ provider: str = "esri-world-imagery"
+ crosshair: bool = True
+
+
+class ParseIn(BaseModel):
+ text: str
+
+
[email protected]("/satellite/providers")
+def providers() -> list[dict[str, Any]]:
+ return [
+ {
+ "id": p.id,
+ "label": p.label,
+ "url": p.url,
+ "attribution": p.attribution,
+ "max_zoom": p.max_zoom,
+ "needs_key": p.needs_key,
+ }
+ for p in tiles.all_providers()
+ ]
+
+
[email protected]("/geo/parse")
+def parse_coordinates(body: ParseIn) -> dict[str, Any]:
+ coords = geo.parse_coords(body.text)
+ if not coords:
+ raise HTTPException(status_code=422, detail="could not parse coordinates")
+ lat, lon = coords
+ return {
+ "lat": lat,
+ "lon": lon,
+ "dms": geo.to_dms(lat, lon),
+ "plus_code": geo.plus_code(lat, lon),
+ "links": geo.map_links(lat, lon),
+ }
+
+
[email protected]("/cases/{case_id}/satellite/capture")
+def capture(case_id: str, body: CaptureIn) -> dict[str, Any]:
+ case = get_case(case_id)
+ try:
+ provider = tiles.get_provider(body.provider)
+ except KeyError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+ try:
+ image, provenance = tiles.fetch_crop(
+ body.lat, body.lon, body.zoom, body.width, body.height,
+ provider, crosshair=body.crosshair,
+ )
+ except tiles.TileFetchError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ except Exception as exc: # network / provider failure
+ raise HTTPException(status_code=502, detail=f"tile fetch failed: {exc}") from exc
+
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+ name = f"sat_{stamp}_z{provenance['zoom']}_{provider.id}.png"
+ sat_dir = case.subdir("satellite")
+ image.save(sat_dir / name, "PNG")
+ provenance["filename"] = name
+ provenance["plus_code"] = geo.plus_code(body.lat, body.lon)
+ provenance["dms"] = geo.to_dms(body.lat, body.lon)
+ (sat_dir / f"{name}.json").write_text(
+ json.dumps(provenance, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+ )
+
+ # suggest a place entity — analyst confirms or dismisses (spec §3.5)
+ label = f"{body.lat:.5f}, {body.lon:.5f}"
+ if not case.find_entity(attr="coords", value=label):
+ case.add_entity(
+ "place",
+ label,
+ attrs={"coords": label, "lat": body.lat, "lon": body.lon,
+ "plus_code": provenance["plus_code"]},
+ by="satellite",
+ status="suggested",
+ )
+
+ return {"path": f"satellite/{name}", **provenance}
+
+
[email protected]("/cases/{case_id}/satellite")
+def list_captures(case_id: str) -> list[dict[str, Any]]:
+ case = get_case(case_id)
+ sat_dir = case.subdir("satellite")
+ captures = []
+ for sidecar in sorted(sat_dir.glob("*.png.json")):
+ image_name = sidecar.name[: -len(".json")]
+ if not (sat_dir / image_name).exists():
+ continue
+ data = json.loads(sidecar.read_text(encoding="utf-8"))
+ data["path"] = f"satellite/{image_name}"
+ captures.append(data)
+ captures.sort(key=lambda d: d.get("fetched_at") or "", reverse=True)
+ return captures
+
+
[email protected]("/cases/{case_id}/satellite")
+def delete_capture(case_id: str, path: str) -> dict[str, str]:
+ case = get_case(case_id)
+ image = case.resolve_inside(path)
+ image.unlink(missing_ok=True)
+ image.with_name(image.name + ".json").unlink(missing_ok=True)
+ return {"status": "deleted"}
diff --git a/src/ozimut/engine/geo.py b/src/ozimut/engine/geo.py
new file mode 100644
index 0000000..41cf5e2
--- /dev/null
+++ b/src/ozimut/engine/geo.py
@@ -0,0 +1,122 @@
+"""Coordinate utilities: parsing, formats (decimal/DMS/plus code), reverse geocoding."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any
+
+import httpx
+
+from .tiles import USER_AGENT
+
+# -- parsing -------------------------------------------------------------------
+
+_DEC = r"[-+]?\d{1,3}(?:\.\d+)?"
+_DMS = (
+ r"(?P<deg>\d{1,3})\s*[°d]\s*(?:(?P<min>\d{1,2})\s*[’'m]\s*)?"
+ r"(?:(?P<sec>\d{1,2}(?:\.\d+)?)\s*[”\"s]\s*)?(?P<hemi>[NSEW])"
+)
+
+
+def parse_coords(text: str) -> tuple[float, float] | None:
+ """Parse 'lat, lon' in decimal or DMS. Returns (lat, lon) or None."""
+ text = text.strip()
+
+ # decimal: "50.4501, 30.5234" / "50.4501 30.5234"
+ m = re.fullmatch(rf"\s*({_DEC})\s*[,;\s]\s*({_DEC})\s*", text)
+ if m:
+ lat, lon = float(m.group(1)), float(m.group(2))
+ if -90 <= lat <= 90 and -180 <= lon <= 180:
+ return lat, lon
+ return None
+
+ # DMS pair: 50°27'0.4"N 30°31'24.2"E
+ parts = re.findall(_DMS, text, flags=re.IGNORECASE)
+ if len(parts) == 2:
+ values = []
+ for deg, minute, sec, hemi in parts:
+ value = float(deg) + float(minute or 0) / 60 + float(sec or 0) / 3600
+ if hemi.upper() in "SW":
+ value = -value
+ values.append((value, hemi.upper()))
+ lat = next((v for v, h in values if h in "NS"), None)
+ lon = next((v for v, h in values if h in "EW"), None)
+ if lat is not None and lon is not None and -90 <= lat <= 90 and -180 <= lon <= 180:
+ return lat, lon
+ return None
+
+
+# -- formatting ------------------------------------------------------------------
+
+
+def to_dms(lat: float, lon: float) -> str:
+ def fmt(value: float, pos: str, neg: str) -> str:
+ hemi = pos if value >= 0 else neg
+ value = abs(value)
+ deg = int(value)
+ minutes = (value - deg) * 60
+ mins = int(minutes)
+ secs = (minutes - mins) * 60
+ return f"{deg}°{mins:02d}'{secs:04.1f}\"{hemi}"
+
+ return f"{fmt(lat, 'N', 'S')} {fmt(lon, 'E', 'W')}"
+
+
+# -- Open Location Code (plus codes) ----------------------------------------------
+# Standard encoding, full 10-character code + '+'. Public-domain algorithm.
+
+_OLC_ALPHABET = "23456789CFGHJMPQRVWX"
+
+
+def plus_code(lat: float, lon: float) -> str:
+ lat = min(max(lat + 90, 0), 180 - 1e-12)
+ lon = ((lon + 180) % 360 + 360) % 360 # normalize to [0, 360)
+ code = []
+ lat_res, lon_res = 20.0, 20.0
+ for _ in range(5): # 10 chars in 5 pairs
+ lat_digit = int(lat / lat_res)
+ lon_digit = int(lon / lon_res)
+ code.append(_OLC_ALPHABET[lat_digit])
+ code.append(_OLC_ALPHABET[lon_digit])
+ lat -= lat_digit * lat_res
+ lon -= lon_digit * lon_res
+ lat_res /= 20
+ lon_res /= 20
+ return "".join(code[:8]) + "+" + "".join(code[8:])
+
+
+# -- map links (quick-open, spec Coordinates tool preview) --------------------------
+
+
+def map_links(lat: float, lon: float, zoom: int = 17) -> dict[str, str]:
+ return {
+ "google": f"https://www.google.com/maps/@{lat},{lon},{zoom}z",
+ "google_sat": f"https://www.google.com/maps/@{lat},{lon},2000m/data=!3m1!1e3",
+ "osm": f"https://www.openstreetmap.org/?mlat={lat}&mlon={lon}#map={zoom}/{lat}/{lon}",
+ "bing": f"https://www.bing.com/maps?cp={lat}~{lon}&lvl={zoom}&style=h",
+ "yandex": f"https://yandex.com/maps/?ll={lon},{lat}&z={zoom}&l=sat",
+ }
+
+
+# -- reverse geocoding (Nominatim, polite) ------------------------------------------
+
+
+def reverse_geocode(lat: float, lon: float) -> dict[str, Any] | None:
+ """Best-effort place name via Nominatim. Returns None on any failure."""
+ try:
+ response = httpx.get(
+ "https://nominatim.openstreetmap.org/reverse",
+ params={"lat": lat, "lon": lon, "format": "jsonv2", "zoom": 14},
+ headers={"User-Agent": USER_AGENT},
+ timeout=8,
+ )
+ response.raise_for_status()
+ data = response.json()
+ return {
+ "display_name": data.get("display_name"),
+ "address": data.get("address", {}),
+ "attribution": "© OpenStreetMap contributors (Nominatim)",
+ }
+ except Exception:
+ return None
diff --git a/src/ozimut/engine/tiles.py b/src/ozimut/engine/tiles.py
new file mode 100644
index 0000000..4aacdb9
--- /dev/null
+++ b/src/ozimut/engine/tiles.py
@@ -0,0 +1,233 @@
+"""XYZ tile engine: Web Mercator math, provider registry, crop stitching.
+
+Legal-only policy (spec §6 v1 notes): built-in presets are exclusively
+providers whose terms permit this use. More imagery comes from official APIs
+with the user's own key, or custom XYZ templates for legitimate sources,
+configured in settings.json — never from unofficial endpoints of keyed
+services.
+"""
+
+from __future__ import annotations
+
+import math
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+import httpx
+from PIL import Image, ImageDraw
+
+from .. import config
+
+TILE_SIZE = 256
+MAX_TILES_PER_CROP = 64 # hard cap: bounded requests per capture, polite to providers
+USER_AGENT = "Ozimut/0.1 (+local OSINT workbench; single-user)"
+
+
+@dataclass(frozen=True)
+class Provider:
+ id: str
+ label: str
+ url: str # template with {x} {y} {z}, optionally {key}
+ attribution: str
+ max_zoom: int = 19
+ needs_key: bool = False
+ subdomains: tuple[str, ...] = field(default_factory=tuple) # for {s} templates
+
+
+BUILTIN_PROVIDERS: tuple[Provider, ...] = (
+ Provider(
+ id="esri-world-imagery",
+ label="Esri World Imagery",
+ url="https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
+ attribution="Esri, Maxar, Earthstar Geographics, and the GIS User Community",
+ max_zoom=19,
+ ),
+ Provider(
+ id="osm",
+ label="OpenStreetMap (street context)",
+ url="https://tile.openstreetmap.org/{z}/{x}/{y}.png",
+ attribution="© OpenStreetMap contributors",
+ max_zoom=19,
+ ),
+)
+
+
+def all_providers() -> list[Provider]:
+ providers = list(BUILTIN_PROVIDERS)
+ settings = config.load_settings()
+ keys = settings.get("api_keys", {})
+ for entry in settings.get("tile_providers", []):
+ try:
+ url = entry["url"]
+ needs_key = "{key}" in url
+ if needs_key and entry["id"] in keys:
+ url = url.replace("{key}", keys[entry["id"]])
+ needs_key = False
+ providers.append(
+ Provider(
+ id=entry["id"],
+ label=entry.get("label", entry["id"]),
+ url=url,
+ attribution=entry.get("attribution", entry["id"]),
+ max_zoom=int(entry.get("max_zoom", 19)),
+ needs_key=needs_key,
+ )
+ )
+ except (KeyError, TypeError, ValueError):
+ continue # malformed user entry: skip rather than break the app
+ return providers
+
+
+def get_provider(provider_id: str) -> Provider:
+ for provider in all_providers():
+ if provider.id == provider_id:
+ return provider
+ raise KeyError(f"unknown tile provider '{provider_id}'")
+
+
+# -- Web Mercator ------------------------------------------------------------
+
+
+def project(lat: float, lon: float, zoom: int) -> tuple[float, float]:
+ """(lat, lon) → fractional tile coordinates at zoom."""
+ lat = min(max(lat, -85.05112878), 85.05112878)
+ scale = 1 << zoom
+ x = (lon + 180.0) / 360.0 * scale
+ siny = math.sin(math.radians(lat))
+ y = (0.5 - math.log((1 + siny) / (1 - siny)) / (4 * math.pi)) * scale
+ return x, y
+
+
+def unproject(x: float, y: float, zoom: int) -> tuple[float, float]:
+ """Fractional tile coordinates at zoom → (lat, lon)."""
+ scale = 1 << zoom
+ lon = x / scale * 360.0 - 180.0
+ n = math.pi - 2.0 * math.pi * y / scale
+ lat = math.degrees(math.atan(math.sinh(n)))
+ return lat, lon
+
+
+def meters_per_pixel(lat: float, zoom: int) -> float:
+ return 156543.03392 * math.cos(math.radians(lat)) / (1 << zoom)
+
+
+# -- crop fetching -------------------------------------------------------------
+
+
+class TileFetchError(Exception):
+ pass
+
+
+def _default_fetch(client: httpx.Client, url: str) -> Image.Image | None:
+ """Fetch one tile; None for 'no imagery here' (404), raise on other errors."""
+ response = client.get(url)
+ if response.status_code == 404:
+ return None
+ response.raise_for_status()
+ import io
+
+ return Image.open(io.BytesIO(response.content)).convert("RGB")
+
+
+def fetch_crop(
+ lat: float,
+ lon: float,
+ zoom: int,
+ width: int,
+ height: int,
+ provider: Provider,
+ *,
+ crosshair: bool = True,
+ fetch_tile: Callable[[httpx.Client, str], Image.Image | None] | None = None,
+) -> tuple[Image.Image, dict[str, Any]]:
+ """Stitch a width×height crop centered on (lat, lon). Returns (image, provenance).
+
+ Missing tiles become labeled gray placeholders instead of failing the crop.
+ """
+ if provider.needs_key:
+ raise TileFetchError(f"provider '{provider.id}' requires an API key (settings.json)")
+ zoom = min(zoom, provider.max_zoom)
+ width, height = min(width, 2048), min(height, 2048)
+
+ center_x, center_y = project(lat, lon, zoom)
+ center_px, center_py = center_x * TILE_SIZE, center_y * TILE_SIZE
+ left, top = center_px - width / 2, center_py - height / 2
+
+ tile_x0, tile_y0 = int(left // TILE_SIZE), int(top // TILE_SIZE)
+ tile_x1, tile_y1 = int((left + width) // TILE_SIZE), int((top + height) // TILE_SIZE)
+ n_tiles = (tile_x1 - tile_x0 + 1) * (tile_y1 - tile_y0 + 1)
+ if n_tiles > MAX_TILES_PER_CROP:
+ raise TileFetchError(
+ f"crop needs {n_tiles} tiles (max {MAX_TILES_PER_CROP}) — reduce size or zoom"
+ )
+
+ max_index = (1 << zoom) - 1
+ fetch = fetch_tile or _default_fetch
+ canvas = Image.new("RGB", (width, height), (24, 28, 38))
+ missing = 0
+
+ def grab(tx: int, ty: int) -> tuple[int, int, Image.Image | None]:
+ if not (0 <= tx <= max_index and 0 <= ty <= max_index):
+ return tx, ty, None
+ url = provider.url.format(x=tx, y=ty, z=zoom)
+ return tx, ty, fetch(client, url)
+
+ with httpx.Client(
+ headers={"User-Agent": USER_AGENT}, timeout=20, follow_redirects=True
+ ) as client:
+ with ThreadPoolExecutor(max_workers=6) as pool:
+ results = list(
+ pool.map(
+ lambda xy: grab(*xy),
+ [
+ (tx, ty)
+ for ty in range(tile_y0, tile_y1 + 1)
+ for tx in range(tile_x0, tile_x1 + 1)
+ ],
+ )
+ )
+
+ for tx, ty, tile in results:
+ px, py = int(tx * TILE_SIZE - left), int(ty * TILE_SIZE - top)
+ if tile is None:
+ missing += 1
+ continue
+ canvas.paste(tile, (px, py))
+
+ if crosshair:
+ _draw_crosshair(canvas)
+
+ provenance = {
+ "provider": provider.id,
+ "provider_label": provider.label,
+ "attribution": provider.attribution,
+ "lat": lat,
+ "lon": lon,
+ "zoom": zoom,
+ "width": width,
+ "height": height,
+ "meters_per_pixel": round(meters_per_pixel(lat, zoom), 3),
+ "tiles": n_tiles,
+ "tiles_missing": missing,
+ "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+ "crosshair": crosshair,
+ }
+ return canvas, provenance
+
+
+def _draw_crosshair(img: Image.Image) -> None:
+ """Center marker: thin cross with an open middle, white with dark outline."""
+ draw = ImageDraw.Draw(img)
+ cx, cy = img.width // 2, img.height // 2
+ arm, gap = 22, 7
+ for dx, dy, colour in ((1, 1, (0, 0, 0)), (0, 0, (255, 255, 255))):
+ for (x0, y0, x1, y1) in (
+ (cx - arm, cy, cx - gap, cy),
+ (cx + gap, cy, cx + arm, cy),
+ (cx, cy - arm, cx, cy - gap),
+ (cx, cy + gap, cx, cy + arm),
+ ):
+ draw.line((x0 + dx, y0 + dy, x1 + dx, y1 + dy), fill=colour, width=2)
+ draw.ellipse((cx - 2 + dx, cy - 2 + dy, cx + 2 + dx, cy + 2 + dy), outline=colour, width=1)
diff --git a/src/ozimut/server.py b/src/ozimut/server.py
index 961f8c6..f283e66 100644
--- a/src/ozimut/server.py
+++ b/src/ozimut/server.py
@@ -18,10 +18,11 @@ def create_app() -> FastAPI:
app = FastAPI(title="Ozimut", version=__version__, docs_url="/api/docs")
- from .api import cases, files, media
+ from .api import cases, files, media, satellite
app.include_router(cases.router)
app.include_router(media.router)
+ app.include_router(satellite.router)
app.include_router(files.router)
@app.get("/api/health")
diff --git a/tests/test_tiles.py b/tests/test_tiles.py
new file mode 100644
index 0000000..e0985d5
--- /dev/null
+++ b/tests/test_tiles.py
@@ -0,0 +1,85 @@
+"""Tile math and crop stitching (offline: injected fake tile fetcher)."""
+
+import math
+
+from PIL import Image
+
+from ozimut.engine import geo, tiles
+
+
+def test_project_roundtrip():
+ lat, lon = 50.4501, 30.5234
+ for zoom in (3, 10, 17):
+ x, y = tiles.project(lat, lon, zoom)
+ lat2, lon2 = tiles.unproject(x, y, zoom)
+ assert math.isclose(lat, lat2, abs_tol=1e-6)
+ assert math.isclose(lon, lon2, abs_tol=1e-6)
+
+
+def test_project_known_values():
+ # (0,0) is the center of the tile grid
+ x, y = tiles.project(0, 0, 1)
+ assert (x, y) == (1.0, 1.0)
+
+
+def test_fetch_crop_stitches_and_records_provenance():
+ provider = tiles.BUILTIN_PROVIDERS[0]
+ fetched_urls = []
+
+ def fake_fetch(client, url):
+ fetched_urls.append(url)
+ return Image.new("RGB", (256, 256), (10, 120, 10))
+
+ img, prov = tiles.fetch_crop(
+ 48.8584, 2.2945, 17, 640, 480, provider, crosshair=True, fetch_tile=fake_fetch
+ )
+ assert img.size == (640, 480)
+ assert prov["provider"] == "esri-world-imagery"
+ assert prov["attribution"]
+ assert prov["tiles"] == len(fetched_urls)
+ assert prov["tiles_missing"] == 0
+ assert prov["meters_per_pixel"] > 0
+ # crosshair drew white pixels at center
+ assert img.getpixel((320 - 10, 240)) == (255, 255, 255)
+
+
+def test_fetch_crop_missing_tiles_dont_fail():
+ provider = tiles.BUILTIN_PROVIDERS[0]
+
+ img, prov = tiles.fetch_crop(
+ 10.0, 10.0, 15, 512, 512, provider, crosshair=False,
+ fetch_tile=lambda client, url: None,
+ )
+ assert prov["tiles_missing"] == prov["tiles"] > 0
+ assert img.size == (512, 512)
+
+
+def test_fetch_crop_tile_cap():
+ provider = tiles.BUILTIN_PROVIDERS[0]
+ try:
+ tiles.fetch_crop(0, 0, 19, 2048, 2048, provider, fetch_tile=lambda c, u: None)
+ except tiles.TileFetchError as exc:
+ assert "tiles" in str(exc)
+ else: # pragma: no cover
+ raise AssertionError("expected TileFetchError for oversized crop")
+
+
+def test_parse_coords():
+ assert geo.parse_coords("50.4501, 30.5234") == (50.4501, 30.5234)
+ assert geo.parse_coords("50.4501 30.5234") == (50.4501, 30.5234)
+ assert geo.parse_coords("-33.8688, 151.2093") == (-33.8688, 151.2093)
+ lat, lon = geo.parse_coords("""48°51'29.6"N 2°17'40.2"E""")
+ assert abs(lat - 48.85822) < 1e-4
+ assert abs(lon - 2.29450) < 1e-4
+ assert geo.parse_coords("hello world") is None
+ assert geo.parse_coords("91, 0") is None
+
+
+def test_plus_code_known_value():
+ # Google's OLC reference example: 47.365590, 8.524997 → 8FVC9G8F+6X
+ assert geo.plus_code(47.365590, 8.524997) == "8FVC9G8F+6X"
+
+
+def test_dms_format():
+ assert geo.to_dms(48.8584, 2.2945).endswith('E')
+ assert "N" in geo.to_dms(48.8584, 2.2945)