gobbo 2.0.0__py3-none-any.whl

gobbo/PRD.md

@@ -0,0 +1,65 @@
+# Gobbo Datum SDK Product Requirements Document (PRD)
+
+## Document Information
+- **Version**: 1.0
+- **Date**: November 25, 2025
+- **Author**: Grok AI (Synthesized from Conversation Specifications)
+- **Status**: Draft for MVP Deployment
+- **Purpose**: This PRD defines the requirements for the Gobbo Datum SDK, an open-source Python tool that acts as "the one datum to rule them all." It converts coordinates from systems like ECEF, LLA, UTM, MGRS, and data formats like LAS (LiDAR), GeoJSON, SRTM GeoTIFF into Gobbo's binary octree paths for alignment, overlap, diff, and fusion. Gobbo is strictly positioning-only: A 1 million km ECEF geo-locked octree with binary subdivision (8 children per level) nested recursively to infinity, using 0-7 labels in concatenated paths (no decimals, base-8 int compression for memory/speed). No data storage, no timestamps, no payloads, no AI analysis, no uploads/downloads, no database integrations—pure mathematical positioning for deterministic, reproducible spatial operations.
+
+## Executive Summary
+Gobbo Datum is the universal voxel translator that unifies any spatial data source into a single, precise framework. By hashing points into compact paths (e.g., "703" as base-8 int 451), it enables seamless alignment and operations across formats without reprojection pains. Built for users to say "This is better because it's in Gobbo," the SDK is a lightweight CLI/package with commands like `gobbo convert las scan.las --depth 20 --out gobbo.vox` and `gobbo-diff a.vox b.vox`. Pure Python (no dependencies), Apache-2.0 licensed OSS for GitHub launch. MVP deploys as pip-installable package, targeting geospatial/robotics devs. Monetize pro features like cloud API ($49/mo). Quick win: Virality through demos fusing drone LAS with SRTM diffs.
+
+## Problem Statement
+Geospatial and robotics users waste hours aligning disparate data (e.g., LiDAR LAS from surveys vs. GeoJSON boundaries vs. SRTM rasters), with errors from datum mismatches (5-10m in UTM) or fixed precision (1cm in SLAM). Existing datums like ECEF are point-based (no volumes), while standards like WGS84 lack infinite scaling. Gobbo solves this by providing a universal volumetric datum: Hash any input to aligned cubes, enabling instant overlap/diff/fuse with bounded errors (cube size halves precision).
+
+## Target Audience and Personas
+- **Primary Segments**: Geospatial analysts (surveying/mining), robotics engineers (precision tasks), AR devs (overlays), environmental scientists (change detection).
+- **Persona 1**: "Jordan Lee," 32, geospatial analyst at a mid-size surveying firm ($10-50M revenue). JTBD: Fuse drone LAS with historical SRTM for volume changes; Pain: 2-4hr reprojection per project; Gain: Gobbo aligns in seconds with verifiable precision.
+- **Persona 2**: "Alex Rivera," 28, robotics dev at a med-tech startup. JTBD: Calibrate robot arms to sub-mm using sensor data; Pain: Sensor drift consumes 30min/shift; Gain: Gobbo's auto-depth bounds errors, reducing rework 10-15%.
+
+## Key Features and Requirements
+### Core Positioning Engine
+- Req 1.1: gobbo_path: Input ECEF XYZ (km), output base-8 int path, depth. Use LBF IDs (label = 4*[x>=half] + 2*[y>=half] + 1*[z>=half]), shift to positive (add 500k km/axis).
+- Req 1.2: gobbo_to_ecef: Inverse path to center/min/max bounds. Round-trip for validation.
+- Req 1.3: Dynamic depth: error_threshold param auto-computes depth (while size > threshold*2).
+- Req 1.4: Error handling: Validate bounds/depth, log GobboError.
+
+### Multi-System Converters
+- Req 2.1: gobbo_from_any(system, coords, depth/error_threshold): Handle 'ecef', 'lla', 'utm', 'mgrs'. Formulas as discussed (pure math; simplified ellipsoid for MVP).
+- Req 2.2: Alt/hemisphere support for LLA/UTM/MGRS.
+
+### Format Parsers
+- Req 3.1: gobbo_convert --in file --format las/geojson/tiff --depth/error_threshold --out vox.json
+- Req 3.2: LAS: Parse points (loop over binary; no laspy—use struct for header/points).
+- Req 3.3: GeoJSON: Parse features (points/polygons/lines to ECEF; --solid fills volumes).
+- Req 3.4: SRTM GeoTIFF: Parse raster (loop over pixels; elev as alt, grid to points).
+- Req 3.5: Output .vox: JSON array of {path_int, depth} per voxel (compact, loadable).
+
+### Spatial Ops Suite
+- Req 4.1: gobbo_overlap(path1, depth1, path2, depth2): Ratio 0-1 (intersect vol / vol1).
+- Req 4.2: gobbo_diff(vox1, vox2): Volume change (km³) + ratio.
+- Req 4.3: gobbo_fuse(vox1, vox2, cutoff=0.7): Merge if overlap > cutoff; output combined .vox (average if conflicting).
+- Req 4.4: gobbo_distance(path1, depth1, path2, depth2): Euclidean km between centers.
+
+### CLI Interface
+- Req 5.1: argparse for convert/overlap/diff/fuse/distance.
+- Req 5.2: Logging: Info for ops, errors for failures.
+- Req 5.3: --out json/csv for .vox (array of paths).
+
+## Non-Functional Requirements
+- **Performance**: O(depth) per op (<1ms/query); <5s for 100K points.
+- **Memory**: Base-8 ints (8 bytes/path); grid loads in RAM only.
+- **Security**: Offline-only; no network.
+- **Compatibility**: Python 3.6+; pure math.
+- **Testing**: Unit tests for each func (e.g., assert paths for known coords).
+- **Docs**: README.md with examples, install guide, contribution notes.
+- **License**: Apache-2.0 for OSS.
+
+## Deployment and Iteration
+- **MVP Launch**: GitHub repo; pip / PyPI via `pyproject.toml` (`python -m build`).
+- **Versions**: v0.1.0 (core/converters), v0.2.0 (parsers), v1.0 (ops suite).
+- **Monetization**: Free OSS; pro: $49/mo cloud API, plugins.
+- **Validation**: GitHub metrics (stars/downloads); user surveys in README.
+
+This PRD is complete, self-contained—feed to AI for code, demos, or expansions.

gobbo/__init__.py

@@ -0,0 +1,154 @@
+"""
+gobbo — the Gobbo 9D Voxel Datum with STAMP Technology.
+
+Install: ``pip install gobbo``.  Learn: ``gobbo/docs/training/README.md``
+(lessons 0–8 ship inside this package) and ``gobbo/docs/formal/PRIMER.md``.
+
+Copyright 2026 Gobbo Datum Labs. Inventor / original technical authorship: Adam Gobbo.
+Licensed under Apache-2.0; see LICENSE, NOTICE, and ATTRIBUTION.md in the package root.
+"""
+
+__version__ = "2.0.0"
+
+from gobbo.core.gobbo import (
+    GobboError,
+    gobbo_center_ecef_pm,
+    gobbo_depth_for_precision,
+    gobbo_depth_for_precision_lla,
+    gobbo_from_ecef,
+    gobbo_from_ecef_pm,
+    gobbo_from_lla,
+    gobbo_ghn_basis,
+    gobbo_horizon_plane,
+    gobbo_min_max_pm,
+    gobbo_ned_basis,
+    gobbo_radial_vector,
+    gobbo_to_ecef,
+    gobbo_to_ecef_meters,
+    gobbo_to_lla,
+    gobbo_voxel_to_ned,
+    gobbo_voxels_to_ned,
+    path_int_to_path_oct,
+    path_oct_to_path_int,
+)
+from gobbo.core.create_stamp import GobboStampRecord, create_stamp
+from gobbo.core.stamp_canonical import (
+    CanonicalStampInputV2,
+    StampCanonicalV2Error,
+    compute_stamp_id_v2,
+    js_number_string,
+    to_canonical_string_v2,
+)
+from gobbo.core.pairwise_stamp import (
+    EPSILON_M,
+    direction_unit_ecef_or_none,
+    ecef_delta_from_gobbo_az_tilt_distance,
+    euclidean_distance_m,
+    gobbo_azimuth_deg,
+    gobbo_azimuth_tilt_distance_m,
+    gobbo_tilt_deg,
+    linear_point_expected_along_segment,
+    new_pairwise_lines_on_stamp_append,
+    pairwise_line_count,
+    parent_mean_from_eight_children,
+    parent_partial_mean_from_known_children,
+)
+from gobbo.core.stamp_interactions import (
+    build_interaction_row,
+    compute_delta_t_seconds,
+    compute_delta_v,
+    compute_interaction_metrics,
+)
+from gobbo.core.gobbo import gobbo_to_mgrs, gobbo_to_utm
+from gobbo.core.stamp_models import (
+    ALLOWED_FACT_KINDS,
+    DEFAULT_FACT_KIND,
+    FACT_KIND_CORRECTION,
+    FACT_KIND_DERIVED_MEASUREMENT,
+    FACT_KIND_ESTIMATE,
+    FACT_KIND_LABEL,
+    FACT_KIND_RAW_MEASUREMENT,
+    StampFact,
+    StampInteractionRow,
+    StampSpatial,
+)
+from gobbo.core.stamp_sentence import (
+    STAMP_SENTENCE_TEMPLATE,
+    build_gobbo_sentence,
+    build_stamp_sentence,
+)
+from gobbo.core.voxel_traverse import (
+    TraversalStep,
+    VoxelTraverseError,
+    ecef_to_gobbo,
+    path_int_from_grid_cell,
+    traverse_voxels_between_ecef,
+)
+
+__all__ = [
+    "__version__",
+    # Voxel datum core
+    "GobboError",
+    "gobbo_center_ecef_pm",
+    "gobbo_depth_for_precision",
+    "gobbo_depth_for_precision_lla",
+    "gobbo_from_ecef",
+    "gobbo_from_ecef_pm",
+    "gobbo_from_lla",
+    "gobbo_ghn_basis",
+    "gobbo_horizon_plane",
+    "gobbo_min_max_pm",
+    "gobbo_ned_basis",
+    "gobbo_radial_vector",
+    "gobbo_to_ecef",
+    "gobbo_to_ecef_meters",
+    "gobbo_to_lla",
+    "gobbo_voxel_to_ned",
+    "gobbo_voxels_to_ned",
+    "path_int_to_path_oct",
+    "path_oct_to_path_int",
+    # STAMP minting + canonical identity
+    "GobboStampRecord",
+    "create_stamp",
+    "CanonicalStampInputV2",
+    "StampCanonicalV2Error",
+    "compute_stamp_id_v2",
+    "js_number_string",
+    "to_canonical_string_v2",
+    "STAMP_SENTENCE_TEMPLATE",
+    "build_stamp_sentence",
+    "EPSILON_M",
+    "direction_unit_ecef_or_none",
+    "ecef_delta_from_gobbo_az_tilt_distance",
+    "euclidean_distance_m",
+    "gobbo_azimuth_deg",
+    "gobbo_azimuth_tilt_distance_m",
+    "gobbo_tilt_deg",
+    "linear_point_expected_along_segment",
+    "new_pairwise_lines_on_stamp_append",
+    "pairwise_line_count",
+    "parent_mean_from_eight_children",
+    "parent_partial_mean_from_known_children",
+    "gobbo_to_mgrs",
+    "gobbo_to_utm",
+    "ALLOWED_FACT_KINDS",
+    "DEFAULT_FACT_KIND",
+    "FACT_KIND_CORRECTION",
+    "FACT_KIND_DERIVED_MEASUREMENT",
+    "FACT_KIND_ESTIMATE",
+    "FACT_KIND_LABEL",
+    "FACT_KIND_RAW_MEASUREMENT",
+    "StampFact",
+    "StampInteractionRow",
+    "StampSpatial",
+    "build_gobbo_sentence",
+    "build_interaction_row",
+    "compute_delta_t_seconds",
+    "compute_delta_v",
+    "compute_interaction_metrics",
+    "TraversalStep",
+    "VoxelTraverseError",
+    "ecef_to_gobbo",
+    "path_int_from_grid_cell",
+    "traverse_voxels_between_ecef",
+]

gobbo/core/cli.py

@@ -0,0 +1,347 @@
+import argparse
+from dataclasses import asdict
+from gobbo import __version__
+from gobbo.core.gobbo import (
+    gobbo_from_ecef, gobbo_from_lla, gobbo_from_utm, gobbo_from_mgrs,
+    gobbo_from_las, gobbo_from_geojson, gobbo_from_srtm,
+    gobbo_overlap, gobbo_diff, gobbo_fuse, gobbo_distance, GobboError, gobbo_radial_vector,
+    gobbo_ned_basis, gobbo_horizon_plane, gobbo_voxel_to_ned, gobbo_voxels_to_ned, gobbo_to_nmea_ggga
+)
+from gobbo.core.gnss import gobbo_ppp_fuse
+from gobbo.core.stamp_interactions import build_interaction_row
+from gobbo.core.stamp_models import StampFact, StampSpatial
+from gobbo.core.stamp_sentence import build_gobbo_sentence
+import json
+import sys
+
+def main():
+    parser = argparse.ArgumentParser(description='Gobbo Datum CLI - Universal Positioning Converter')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    # Convert from coords
+    convert = subparsers.add_parser('convert', help='Convert coordinates to Gobbo path')
+    convert.add_argument('system', choices=['ecef', 'lla', 'utm', 'mgrs'], help='Coordinate system')
+    convert.add_argument('coords', nargs='+', help='Coordinates (e.g., x y z for ecef)')
+    convert.add_argument('--depth', type=int, default=10, help='Recursion depth')
+    convert.add_argument('--error_threshold', type=float, help='Error threshold for auto-depth (km)')
+    convert.add_argument('--alt', type=float, default=0, help='Altitude for lla/utm/mgrs')
+    convert.add_argument('--hemisphere', default='N', help='Hemisphere for utm (N/S)')
+
+    # Convert from file
+    convert_file = subparsers.add_parser('convert-file', help='Convert file to Gobbo voxels')
+    convert_file.add_argument('format', choices=['las', 'geojson', 'hgt'], help='Input format')
+    convert_file.add_argument('in_file', help='Input file path')
+    convert_file.add_argument('--depth', type=int, default=10, help='Recursion depth')
+    convert_file.add_argument('--error_threshold', type=float, help='Error threshold (km)')
+    convert_file.add_argument('--solid', action='store_true', help='Fill solids for GeoJSON')
+    convert_file.add_argument('--out', help='Output JSON file')
+
+    # Overlap
+    overlap = subparsers.add_parser('overlap', help='Compute voxel overlap ratio')
+    overlap.add_argument('path1', type=int, help='Path int 1')
+    overlap.add_argument('depth1', type=int, help='Depth 1')
+    overlap.add_argument('path2', type=int, help='Path int 2')
+    overlap.add_argument('depth2', type=int, help='Depth 2')
+
+    # Diff
+    diff = subparsers.add_parser('diff', help='Compute volume diff between voxel sets')
+    diff.add_argument('vox1', help='.vox file1')
+    diff.add_argument('vox2', help='.vox file2')
+
+    # Fuse
+    fuse = subparsers.add_parser('fuse', help='Fuse voxel sets')
+    fuse.add_argument('vox1', help='.vox file1')
+    fuse.add_argument('vox2', help='.vox file2')
+    fuse.add_argument('--cutoff', type=float, default=0.7, help='Overlap cutoff')
+    fuse.add_argument('--out', help='Output JSON file')
+
+    # Distance
+    distance = subparsers.add_parser('distance', help='Compute distance between voxel centers')
+    distance.add_argument('path1', type=int, help='Path int 1')
+    distance.add_argument('depth1', type=int, help='Depth 1')
+    distance.add_argument('path2', type=int, help='Path int 2')
+    distance.add_argument('depth2', type=int, help='Depth 2')
+
+    # Radial vector
+    radial = subparsers.add_parser('radial', help='Compute radial vector')
+    radial.add_argument('path', type=int, help='Path int')
+    radial.add_argument('depth', type=int, help='Depth')
+
+    # NED basis
+    ned = subparsers.add_parser('ned', help='Compute NED basis')
+    ned.add_argument('path', type=int, help='Path int')
+    ned.add_argument('depth', type=int, help='Depth')
+
+    # Horizon plane
+    horizon = subparsers.add_parser('horizon', help='Compute horizon plane')
+    horizon.add_argument('path', type=int, help='Path int')
+    horizon.add_argument('depth', type=int, help='Depth')
+
+    # Voxel to NED
+    voxel_ned = subparsers.add_parser('voxel-ned', help='Convert voxel to NED relative to ref')
+    voxel_ned.add_argument('ref_path', type=int, help='Ref path int')
+    voxel_ned.add_argument('ref_depth', type=int, help='Ref depth')
+    voxel_ned.add_argument('target_path', type=int, help='Target path int')
+    voxel_ned.add_argument('target_depth', type=int, help='Target depth')
+
+    # Voxels to NED
+    voxels_ned = subparsers.add_parser('voxels-ned', help='Batch convert voxels to NED')
+    voxels_ned.add_argument('ref_path', type=int, help='Ref path int')
+    voxels_ned.add_argument('ref_depth', type=int, help='Ref depth')
+    voxels_ned.add_argument('targets', nargs='+', help='Target path:depth pairs, e.g., 123:10 456:15')
+
+    # NMEA
+    nmea = subparsers.add_parser('nmea', help='Generate NMEA GGA from voxel')
+    nmea.add_argument('path', type=int, help='Path int')
+    nmea.add_argument('depth', type=int, help='Depth')
+    nmea.add_argument('--utc_time', default='123456.00', help='UTC time')
+    nmea.add_argument('--hdop', type=float, default=1.0, help='HDOP')
+    nmea.add_argument('--fix_quality', type=int, default=1, help='Fix quality')
+    nmea.add_argument('--num_sat', type=int, default=8, help='Num satellites')
+    nmea.add_argument('--age', type=float, default=1.0, help='Age')
+    nmea.add_argument('--station_id', type=int, default=0, help='Station ID')
+
+    # PPP-refine
+    ppp = subparsers.add_parser('ppp-refine', help='Refine voxels via PPP baseline')
+    ppp.add_argument('vox1', help='.vox file1')
+    ppp.add_argument('--vox2', help='.vox file2 (optional, defaults to vox1)')
+    ppp.add_argument('obs', help='RINEX obs file1')
+    ppp.add_argument('--obs2', help='RINEX obs file2 (optional, defaults to obs)')
+    ppp.add_argument('--out', default='refined.vox', help='Output JSON file')
+
+    # Map-scene
+    map_scene_parser = subparsers.add_parser('map-scene', help='Map image to labeled Gobbo voxels')
+    map_scene_parser.add_argument('image', help='RGB image file')
+    map_scene_parser.add_argument('--gps', nargs=3, type=float, help='LLA: lat lon alt')
+    map_scene_parser.add_argument('--depth', type=int, default=40, help='Voxel depth')
+    map_scene_parser.add_argument('--out', default='voxels.json', help='Output JSON')
+
+    # STAMP sentence builder
+    stamp_sentence = subparsers.add_parser(
+        'stamp-sentence',
+        help='Build canonical STAMP sentence from fields',
+    )
+    stamp_sentence.add_argument('--path-int', type=int, required=True, help='STAMP spatial pathInt')
+    stamp_sentence.add_argument('--depth', type=int, required=True, help='STAMP depth')
+    stamp_sentence.add_argument('--path-oct', help='Optional canonical pathOct')
+    stamp_sentence.add_argument('--temporal', required=True, help='ISO timestamp for the STAMP')
+    stamp_sentence.add_argument('--assignment', required=True, help='Assignment field')
+    stamp_sentence.add_argument('--metric', required=True, help='Metric field')
+    stamp_sentence.add_argument('--point', type=float, help='Numeric point value')
+    stamp_sentence.add_argument('--point-value', help='Non-numeric point value fallback')
+    stamp_sentence.add_argument('--stamp-id', help='Optional stable STAMP identifier')
+    stamp_sentence.add_argument(
+        '--fact-kind',
+        default='raw_measurement',
+        help='Fact kind (B.12): raw_measurement | derived_measurement | estimate | label | correction',
+    )
+
+    # STAMP interaction row calculator
+    stamp_interaction = subparsers.add_parser(
+        'stamp-interaction',
+        help='Compute deterministic interaction row between two STAMP facts',
+    )
+    stamp_interaction.add_argument('--anchor-path-int', type=int, required=True, help='Anchor pathInt')
+    stamp_interaction.add_argument('--anchor-depth', type=int, required=True, help='Anchor depth')
+    stamp_interaction.add_argument('--anchor-path-oct', help='Optional anchor pathOct')
+    stamp_interaction.add_argument('--anchor-time', required=True, help='Anchor timestamp (ISO)')
+    stamp_interaction.add_argument('--anchor-assignment', required=True, help='Anchor assignment')
+    stamp_interaction.add_argument('--anchor-metric', required=True, help='Anchor metric')
+    stamp_interaction.add_argument('--anchor-point', type=float, help='Anchor numeric point')
+    stamp_interaction.add_argument('--anchor-point-value', help='Anchor non-numeric point value')
+    stamp_interaction.add_argument('--anchor-stamp-id', help='Anchor stamp identifier')
+    stamp_interaction.add_argument(
+        '--anchor-ecef-m',
+        nargs=3,
+        type=float,
+        required=True,
+        metavar=('X', 'Y', 'Z'),
+        help='Anchor ECEF coordinates in meters',
+    )
+    stamp_interaction.add_argument('--neighbor-path-int', type=int, required=True, help='Neighbor pathInt')
+    stamp_interaction.add_argument('--neighbor-depth', type=int, required=True, help='Neighbor depth')
+    stamp_interaction.add_argument('--neighbor-path-oct', help='Optional neighbor pathOct')
+    stamp_interaction.add_argument('--neighbor-time', required=True, help='Neighbor timestamp (ISO)')
+    stamp_interaction.add_argument('--neighbor-assignment', required=True, help='Neighbor assignment')
+    stamp_interaction.add_argument('--neighbor-metric', required=True, help='Neighbor metric')
+    stamp_interaction.add_argument('--neighbor-point', type=float, help='Neighbor numeric point')
+    stamp_interaction.add_argument('--neighbor-point-value', help='Neighbor non-numeric point value')
+    stamp_interaction.add_argument('--neighbor-stamp-id', help='Neighbor stamp identifier')
+    stamp_interaction.add_argument(
+        '--neighbor-ecef-m',
+        nargs=3,
+        type=float,
+        required=True,
+        metavar=('X', 'Y', 'Z'),
+        help='Neighbor ECEF coordinates in meters',
+    )
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == 'convert':
+            if args.system == 'ecef':
+                x, y, z = map(float, args.coords[:3])
+                path, depth = gobbo_from_ecef(x, y, z, args.depth, args.error_threshold)
+            elif args.system == 'lla':
+                lat, lon = map(float, args.coords[:2])
+                path, depth = gobbo_from_lla(lat, lon, args.alt, args.depth, args.error_threshold)
+            elif args.system == 'utm':
+                zone = int(args.coords[0])
+                easting, northing = map(float, args.coords[1:3])
+                path, depth = gobbo_from_utm(zone, easting, northing, args.hemisphere, args.alt, args.depth, args.error_threshold)
+            elif args.system == 'mgrs':
+                mgrs_str = args.coords[0]
+                path, depth = gobbo_from_mgrs(mgrs_str, args.alt, args.depth, args.error_threshold)
+            print(f"Path: {path}, Depth: {depth}")
+
+        elif args.command == 'convert-file':
+            if args.format == 'las':
+                voxels = gobbo_from_las(args.in_file, args.depth, args.error_threshold)
+            elif args.format == 'geojson':
+                voxels = gobbo_from_geojson(args.in_file, args.depth, args.error_threshold, args.solid)
+            elif args.format == 'hgt':
+                voxels = gobbo_from_srtm(args.in_file, args.depth, args.error_threshold)
+            if args.out:
+                with open(args.out, 'w') as f:
+                    json.dump(voxels, f)
+                print(f"Output written to {args.out}")
+            else:
+                print(json.dumps(voxels[:10]))  # Sample
+
+        elif args.command == 'overlap':
+            ratio = gobbo_overlap(args.path1, args.depth1, args.path2, args.depth2)
+            print(f"Overlap ratio: {ratio}")
+
+        elif args.command == 'diff':
+            with open(args.vox1, 'r') as f1, open(args.vox2, 'r') as f2:
+                v1 = json.load(f1)
+                v2 = json.load(f2)
+            change, ratio = gobbo_diff(v1, v2)
+            print(f"Volume change: {change} km³, Ratio: {ratio}")
+
+        elif args.command == 'fuse':
+            with open(args.vox1, 'r') as f1, open(args.vox2, 'r') as f2:
+                v1 = json.load(f1)
+                v2 = json.load(f2)
+            fused = gobbo_fuse(v1, v2, args.cutoff)
+            if args.out:
+                with open(args.out, 'w') as f:
+                    json.dump(fused, f)
+                print(f"Fused output to {args.out}")
+            else:
+                print(json.dumps(fused[:10]))
+
+        elif args.command == 'distance':
+            dist = gobbo_distance(args.path1, args.depth1, args.path2, args.depth2)
+            print(f"Distance: {dist} km")
+
+        elif args.command == 'radial':
+            vec = gobbo_radial_vector(args.path, args.depth)
+            print(vec)
+
+        elif args.command == 'ned':
+            north, east, down = gobbo_ned_basis(args.path, args.depth)
+            print(f"North: {north}\nEast: {east}\nDown: {down}")
+
+        elif args.command == 'horizon':
+            normal, point = gobbo_horizon_plane(args.path, args.depth)
+            print(f"Normal: {normal}\nPoint: {point}")
+
+        elif args.command == 'voxel-ned':
+            n, e, d = gobbo_voxel_to_ned(args.ref_path, args.ref_depth, args.target_path, args.target_depth)
+            print(f"N: {n}, E: {e}, D: {d}")
+
+        elif args.command == 'voxels-ned':
+            targets = [tuple(map(int, t.split(':'))) for t in args.targets]
+            neds = gobbo_voxels_to_ned(args.ref_path, args.ref_depth, targets)
+            print(json.dumps(neds))
+
+        elif args.command == 'nmea':
+            sentence = gobbo_to_nmea_ggga(args.path, args.depth, args.utc_time, args.hdop, args.fix_quality, args.num_sat, args.age, args.station_id)
+            print(sentence)
+
+        elif args.command == 'ppp-refine':
+            with open(args.vox1, 'r') as f1:
+                v1 = json.load(f1)
+            v2 = json.load(open(args.vox2, 'r')) if args.vox2 else v1
+            obs2 = args.obs2 if args.obs2 else args.obs
+            fused = gobbo_ppp_fuse(v1, v2, args.obs, obs2)
+            with open(args.out, 'w') as f:
+                json.dump(fused, f)
+            print(f"Refined voxels written to {args.out}")
+
+        elif args.command == 'map-scene':
+            import cv2
+            from gobbo.nav.da3_yolo import scene_map
+
+            rgb = cv2.imread(args.image)
+            if rgb is None:
+                print("Error: Invalid image file")
+                sys.exit(1)
+            voxels = scene_map(rgb, gps_lla=args.gps, depth=args.depth)
+            with open(args.out, 'w') as f:
+                json.dump(voxels, f)
+            print(f"Mapped {len(voxels)} voxels to {args.out}")
+
+        elif args.command == 'stamp-sentence':
+            stamp = StampFact(
+                spatial=StampSpatial(path_int=args.path_int, depth=args.depth, path_oct=args.path_oct),
+                temporal=args.temporal,
+                assignment=args.assignment,
+                metric=args.metric,
+                point=args.point,
+                point_value=args.point_value,
+                stamp_id=args.stamp_id,
+                fact_kind=args.fact_kind,
+            )
+            print(build_gobbo_sentence(stamp))
+
+        elif args.command == 'stamp-interaction':
+            anchor = StampFact(
+                spatial=StampSpatial(
+                    path_int=args.anchor_path_int,
+                    depth=args.anchor_depth,
+                    path_oct=args.anchor_path_oct,
+                ),
+                temporal=args.anchor_time,
+                assignment=args.anchor_assignment,
+                metric=args.anchor_metric,
+                point=args.anchor_point,
+                point_value=args.anchor_point_value,
+                stamp_id=args.anchor_stamp_id,
+            )
+            neighbor = StampFact(
+                spatial=StampSpatial(
+                    path_int=args.neighbor_path_int,
+                    depth=args.neighbor_depth,
+                    path_oct=args.neighbor_path_oct,
+                ),
+                temporal=args.neighbor_time,
+                assignment=args.neighbor_assignment,
+                metric=args.neighbor_metric,
+                point=args.neighbor_point,
+                point_value=args.neighbor_point_value,
+                stamp_id=args.neighbor_stamp_id,
+            )
+            row = build_interaction_row(
+                anchor=anchor,
+                neighbor=neighbor,
+                anchor_ecef_m=tuple(args.anchor_ecef_m),
+                neighbor_ecef_m=tuple(args.neighbor_ecef_m),
+            )
+            print(json.dumps(asdict(row), ensure_ascii=True))
+
+    except GobboError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+    except ValueError as e:
+        print(f"Input error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

gobbo/core/constants.py

@@ -0,0 +1,57 @@
+"""
+Frozen ``gobbo:v1`` constants — single Python source (parity with ``lib/gobbo.ts`` / ``lib/datum-conformance.ts``).
+
+Importing this module asserts SHA-256 of the pipe-delimited fingerprint matches ``DATUM_PARAMS_HASH``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+# WGS-84 ellipsoid (meters)
+WGS84_A = 6378137.0
+WGS84_B = 6356752.314245
+
+# Root cube (meters) — frozen
+ROOT_METERS = 1_000_000_000.0
+CENTER_METERS = ROOT_METERS / 2.0
+
+# Legacy ``gobbo.py`` octree fold uses ECEF expressed in **kilometers** after ``/ 1000``.
+ROOT_KM = ROOT_METERS / 1000.0
+CENTER_KM = CENTER_METERS / 1000.0
+
+MILLIMETER_FACTOR = 1000
+MAX_HIGH_DEPTH = 60
+CONTAINMENT_MARGIN_FACTOR = 0.15
+
+DATUM_ID = "gobbo:v1"
+
+# Must match ``lib/stamp-canonical.ts`` / ``docs/GOBBO_DATUM_V1_FROZEN_CONSTANTS.md``
+DATUM_PARAMS_HASH = "4314894cc5878ba496064f57444fc74b2dcb950a59c30939c00824ddb49a5e3e"
+
+
+def _gobbo_v1_datum_params_fingerprint() -> str:
+    return "|".join(
+        [
+            "6378137.0",
+            "6356752.314245",
+            f"{ROOT_METERS:.1f}",
+            f"{CENTER_METERS:.1f}",
+            str(MAX_HIGH_DEPTH),
+            str(MILLIMETER_FACTOR),
+            str(CONTAINMENT_MARGIN_FACTOR),
+        ]
+    )
+
+
+_computed = hashlib.sha256(_gobbo_v1_datum_params_fingerprint().encode("utf-8")).hexdigest()
+if _computed != DATUM_PARAMS_HASH:
+    raise RuntimeError(
+        f"gobbo:v1 frozen-constant drift: expected datum_params_hash {DATUM_PARAMS_HASH}, "
+        f"computed {_computed}. Fingerprint was: {_gobbo_v1_datum_params_fingerprint()}"
+    )
+
+
+def assert_gobbo_v1_datum_params_conformant() -> None:
+    """No-op at runtime; module import already validated. For explicit tests."""
+    return None