gobbo 2.0.0

Gobbo 9D Voxel Datum and STAMP Technology — universal positioning (octree paths), pairwise STAMP / E-STAMP helpers, and optional HTTP client for Secure Envelope APIs. Copyright Gobbo Datum Labs; inventor: Adam Gobbo.

gobbo — Gobbo 9D Voxel Datum + STAMP Technology

Copyright 2026 Gobbo Datum Labs. Gobbo 9D Voxel Datum with STAMP Technology — inventor: Adam Gobbo. Licensed under Apache-2.0; retain LICENSE, NOTICE, ATTRIBUTION.md, and EULA.md when redistributing. See ATTRIBUTION.md for citation text and goodwill rules.

Binding supplemental terms: By downloading, installing, or using this package, you agree to EULA.md (marks, Permitted Gobbo Designations, STAMP / STAMP Format naming). Delaware counsel should finalize before enforcement.

Open source: install from PyPI with pip install gobbo. Source and issues live at github.com/gobbo-datum-labs/gobbo. Writing STAMPs with this SDK is free; reading/querying the hosted Secure Envelope collection remains a paid service on www.secure-envelope.com.

Universal positioning framework for converting spatial data to Gobbo octree paths. "The one datum to rule them all."

Installation

pip install gobbo

import gobbo

That is the only install line and the only import name. The core package is dependency-free standard-library Python.

Optional dependency groups:

pip install "gobbo[geospatial]"   # pyproj, laspy, rasterio, shapely, mpmath, mgrs — UTM/MGRS + file parsers
pip install "gobbo[gnss]"         # NumPy — PPP helpers in gobbo.core.gnss
pip install "gobbo[nav]"          # YOLO / OpenCV — map-scene and nav da3_yolo
pip install "gobbo[http]"         # requests — GobboClient for hosted /api/stamps/*
pip install "gobbo[http-strict]"  # requests + pydantic — typed HTTP responses

Learn it (training course ships in the package)

A complete beginner-to-formal course is bundled inside the wheel:

• gobbo/docs/training/README.md — Lessons 0–8: why Gobbo, the nine dimensions, G-Line / H-Plane / N-Line, depth + Sphere-in-Cube, STAMP Technology, a hands-on first-stamp tutorial, 2TD vs GHN angles, the identity epoch, and collections.
• gobbo/docs/formal/PRIMER.md — faithful condensed formal primer with pointers to the frozen normative specifications.
• gobbo/examples/ — runnable scripts (01_lla_to_voxel.py, 02_create_stamp.py, 03_ghn_and_2td.py).

Locate them after install:

import gobbo, pathlib
print(pathlib.Path(gobbo.__file__).parent / "docs" / "training")

Quick start

import gobbo

# Position → voxel identity (identity epoch v2, exact on every platform)
path_int, depth = gobbo.gobbo_from_lla(40.6413, -73.7781, 4.0, depth=30)
print(gobbo.path_int_to_path_oct(path_int, depth))

# Honest depth from GPS precision (Sphere-in-Cube rule)
d = gobbo.gobbo_depth_for_precision_lla(40.6413, -73.7781, 4.0, 5.0)

# Mint an immutable STAMP fact (stampv:2 content-addressed id + frozen sentence)
stamp = gobbo.create_stamp(
    lat=40.6413, lon=-73.7781, alt=4.0, depth=30,
    temporal=1752444000, assignment="sensor:jfk-roof-1",
    metric="temperature_c", point=22.5, source="quickstart",
)
print(stamp.stamp_id)
print(stamp.sentence)

Features

• Convert ECEF, LLA, UTM, MGRS to Gobbo paths; decode paths back to centers/bounds (LBF lattice doctrine).
• Exact identity core (gobbo.core.gobbo_exact): BigInt fixed-point WGS-84 transform, picometer voxel grid, deterministic trig — bit-identical voxel identity across Python / TypeScript / Kotlin / Swift (identity epoch v2).
• STAMP minting (gobbo.create_stamp) with the frozen stampv:2 canonical serialization and SHA-256 stamp_id.
• GHN frame (gobbo.gobbo_ghn_basis): G-Line / H-Plane / N-Line local NED basis at any voxel center.
• Pairwise STAMP interaction math: line counts C(n,2), Gobbo Azimuth / Tilt / distance (2TD) from ECEF deltas, linear E-STAMP along a segment, 1/8 parent mean and partial-n mean over children (see docs/PAIRWISE_LINES_AND_ENRICHMENTS.md).
• Parse LAS, GeoJSON, SRTM to voxel lists when the geospatial extra is installed.
• Spatial ops: overlap, diff, fuse, distance.
• CLI entry point: gobbo (see gobbo/core/cli.py).

HTTP client (Secure Envelope STAMP API)

For calling a deployed API (/api/stamps/push, by-voxel, E-STAMP routes), install the http extra and use gobbo.http_client.GobboClient:

from gobbo.http_client import GobboClient

client = GobboClient(
    "https://your-deployment.example",
    bearer_token="...",  # optional for public routes
    api_key="...",       # optional if the server enables x-api-key
)
rows = client.get_stamps_by_voxel(path_int="123", depth=23)

Strict response parsing (Pydantic):

from gobbo.http_client import GobboClient
from gobbo.stamp_http_models import parse_by_voxel_response

client = GobboClient("https://example.com", bearer_token="…")
data = client.get_stamps_by_voxel(path_int="1", depth=10)
typed = parse_by_voxel_response(data)

TypeScript equivalents: npm gobbo-stamp-sdk (HTTP) and gobbo-datum-ts-sdk (canonical path_int / STAMP math). Method parity is checked in CI (scripts/sdk-http-surface.json, npm run check:sdk-parity).

Deterministic STAMP utilities

fact_kind (B.12) must be one of: raw_measurement, derived_measurement, estimate, label, correction — same as the hosted API schema. Defaults use raw_measurement.

• gobbo.core.stamp_models — StampSpatial, StampFact, StampInteractionRow, FACT_KIND_* literals
• gobbo.core.stamp_sentence — frozen canonical sentence builder (At {voxel}@{depth} at {timeIso}, {assignment}'s {metric} of {value}.)
• gobbo.core.stamp_canonical — frozen stampv:2 serialization + compute_stamp_id_v2
• gobbo.core.stamp_interactions — compute_delta_t_seconds, compute_delta_v, compute_interaction_metrics, build_interaction_row

CLI access for non-developers:

gobbo stamp-sentence --path-int 123 --depth 10 --temporal "2026-04-12T10:11:12Z" --assignment "sensor.alpha" --metric "temperature_c" --point 23.5

Tests and conformance

Golden-vector conformance (identity epoch v2 + stampv:2) and the full test suite:

python3 -m unittest discover -s tests

TypeScript parity checks require the geospatial extra (pip install "gobbo[geospatial]").

Documentation in this bundle

Path	Contents
gobbo/docs/training/	Lessons 0–8 — full beginner-to-formal course
gobbo/docs/formal/PRIMER.md	Formal primer → frozen specs bridge
gobbo/examples/	Runnable training example scripts
docs/PAIRWISE_LINES_AND_ENRICHMENTS.md	Pairwise lines, §7 encoding, E-STAMP linear model, parent/child means
gobbo/PRD.md	Product requirements (historical MVP scope)
gobbo/core/gobbo.py	Octree path generation, converters, spatial ops
gobbo/core/gobbo_exact.py	Exact fixed-point identity core (epoch v2)
gobbo/core/requirements.txt	Optional geospatial stack

License and attribution

• License: Apache-2.0 (LICENSE)
• Required attribution notices: NOTICE
• Branding/trademark usage guidance: TRADEMARKS.md
• Suggested software citation metadata: CITATION.cff

The Apache-2.0 license keeps the SDK open source and broadly adoptable, while NOTICE and TRADEMARKS.md preserve clear attribution to Gobbo Datum and Gobbo Datum Labs and protect against misleading branding.

Pro download

Subscribers can also download this SDK from the Secure Envelope dashboard (authenticated Download ZIP). The archive matches the tracked content/sdk/gobbo-datum-sdk tree in the product repository.