python-gdb 0.1.0__cp312-abi3-win_amd64.whl

pygdb/registry.py

@@ -0,0 +1,104 @@
+"""
+Best-effort extraction of coordinate-system (map projection) names from a
+`.gdb` file's REG/IPJ "reserved/administrative" blob region.
+
+[CONFIRMED] present and real on every one of 3 independent agencies this
+project has files from; [UNKNOWN] full binary framing beyond the specific
+name marker decoded here. See docs/spec.md sections 8-9 and
+docs/provenance/notes.md sections 6.7-6.8 for the full derivation --
+including the important caveat that REG/IPJ content is **not universal**:
+several real files (mostly ones apparently never interactively opened in
+Oasis montaj) have none at all, which is a real, patterned absence, not a
+bug in this scan.
+
+Administrative blobs (holding REG/IPJ metadata rather than real survey
+channel data) are addressed via the same blob_index formula as ordinary
+data (gdb_reader.BlobHeader.line_channel), but with an out-of-range
+line_slot -- one past every real line this file's own line table
+(gdb_reader.read_lines) actually has. This project's original prototype
+(docs/provenance/scripts/reg_ipj_full_scan.py) used a hardcoded line_slot
+threshold (700) tuned to its own sample corpus; this module instead
+derives the threshold from each file's real line count, so it isn't
+tied to one corpus's line-numbering conventions.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+from typing import List, Optional
+
+from .gdb_reader import GDBParseWarning, check_magic, header_fields, iter_blobs, read_lines
+
+
+def _warn(msg: str) -> None:
+    warnings.warn(msg, GDBParseWarning, stacklevel=3)
+
+# The confirmed micro-pattern for how a working projected-CRS name is
+# introduced inside an IPJ-tagged administrative blob (docs/spec.md
+# section 8): the 4-byte tag " JPI" (a space plus the tail of the literal
+# string "IPJ" read across an alignment boundary), an int32 count (always
+# seen as 1), then a NUL-terminated name string.
+_IPJ_NAME_RE = re.compile(rb" JPI\x01\x00\x00\x00([\x20-\x7e]+)\x00")
+
+# How many bytes of each candidate administrative blob to read looking for
+# the IPJ name marker. [GUESS] -- generous relative to the marker's own
+# size, matches the original prototype script.
+_PROBE_SIZE = 2000
+
+
+def find_coordinate_systems(path: str, max_real_line_slot: Optional[int] = None) -> List[str]:
+    """
+    Scan `path` for coordinate-system (map projection) names.
+
+    Returns a de-duplicated, order-of-discovery list of name strings (e.g.
+    `"WGS 84 / UTM zone 54S"`), or an empty list if none were found --
+    which is expected and normal for a real file with no REG/IPJ content
+    at all (docs/spec.md section 9), not necessarily a sign of a problem.
+
+    `max_real_line_slot` is the highest physical line-table slot index
+    that corresponds to a real survey line -- blobs whose `line_slot`
+    (decoded via `BlobHeader.line_channel`) is beyond this are treated as
+    "administrative" and probed for IPJ content. If not given, it's
+    derived by calling `read_lines(path)` (an extra table scan) and using
+    the highest slot index found there; pass it explicitly if you already
+    have that file's `read_lines()` result to avoid repeating the scan.
+
+    Fails gracefully like the rest of this package: a bad magic or
+    truncated header returns `[]` with a `GDBParseWarning` rather than
+    raising.
+    """
+    with open(path, "rb") as f:
+        header = f.read(128)
+    if not check_magic(header):
+        _warn(f"{path}: does not start with the expected '!CBD' magic -- "
+              f"no coordinate systems")
+        return []
+    fields = header_fields(header)
+    chans_max = fields["chans_max"]
+    if chans_max is None:
+        _warn(f"{path}: header too short to read chans_max -- "
+              f"no coordinate systems")
+        return []
+
+    if max_real_line_slot is None:
+        lines = read_lines(path)
+        max_real_line_slot = max((line.index for line in lines), default=-1)
+
+    names: List[str] = []
+    seen = set()
+    with open(path, "rb") as f:
+        for blob in iter_blobs(path):
+            line_slot, _channel_slot = blob.line_channel(chans_max)
+            if line_slot <= max_real_line_slot:
+                continue  # a real survey line's data, not administrative metadata
+            f.seek(blob.offset)
+            chunk = f.read(_PROBE_SIZE)
+            m = _IPJ_NAME_RE.search(chunk)
+            if not m:
+                continue
+            name = m.group(1).decode("ascii", errors="replace")
+            if name not in seen:
+                seen.add(name)
+                names.append(name)
+    return names

python_gdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: python-gdb
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=2.2
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: xarray ; extra == 'dev'
+Requires-Dist: zensical ; extra == 'docs'
+Requires-Dist: xarray ; extra == 'xarray'
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: xarray
+License-File: LICENSE
+Summary: A clean-room Python reader for Geosoft .gdb database and .grd grid files
+Author-email: Joseph Capriotti <josephrcapriotti@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# pygdb
+
+A clean-room Python reader for Geosoft's proprietary `.gdb` ("Geosoft
+Database") binary format and the sibling `.grd` grid format.
+
+> [!IMPORTANT]
+> This project has **no affiliation with, and is not endorsed,
+> sponsored, or certified by, Geosoft Inc., Seequent, Bentley Systems,
+> or any of their successors.** "Geosoft" and "Oasis montaj" are
+> trademarks of their respective owners. This is an independent,
+> third-party implementation produced entirely by clean-room means —
+> see [Provenance](docs/provenance/index.md) for the full research
+> trail.
+
+It was built using only publicly available information: vendor-published
+open-source code and documentation, independent third-party format
+readers, one openly-specified independent successor format (`.geoh5`,
+read via the third-party `geoh5py` library), and byte-level analysis of
+real, publicly downloaded `.gdb` files. No Geosoft software of any kind
+(the `geosoft`/`gxapi`/`gxpy` compiled package, Oasis montaj, Geosoft
+Desktop, or the free Geosoft Viewer) was installed, imported, or
+executed at any point in producing it.
+
+Reading only — writing or mutating `.gdb`/`.grd` files is out of scope.
+
+## Installation
+
+```sh
+pip install python-gdb
+```
+
+The distribution is named `python-gdb` on PyPI (`pygdb` was already
+registered there for an unrelated project), but the importable package
+is `pygdb`. On a platform/Python version this project publishes a
+prebuilt wheel for, that automatically includes the optional Rust
+accelerator (see below) -- nothing extra to install or configure.
+Elsewhere, `pip` falls back to building from source, which needs a Rust
+toolchain. `numpy` is the one required dependency (used to return
+correctly-shaped arrays -- see Quick start below); everything else is
+optional.
+
+## Quick start
+
+```python
+from pygdb import GDB
+
+db = GDB("example.gdb")
+
+db.compression           # CompressionInfo(code=0, name='DB_COMP_NONE', ...)
+db.coordinate_systems     # ['NAD83 / UTM zone 11N', 'WGS 84'] (best-effort, may be [])
+
+db.line_names[:5]         # ['L1000', 'L1001', 'L1010', 'L1020', 'L1030']
+db.channels_on_line("L1000")   # channels that actually have data on this line
+db.read("L1000", "Easting")    # random access by (line name, channel name)
+                                # -> ndarray, shape (n_rows,) for a scalar
+                                #    channel, (n_rows, array_width) for a
+                                #    VA/array channel (docs/spec.md section 5)
+```
+
+See [the docs](docs/index.md) for the lower-level, slot-index-based
+functions `GDB` is built on.
+
+`db.to_xarray("L1000")` exports one line to an `xarray.Dataset`
+(`pip install python-gdb[xarray]`, an optional dependency) — see
+[the docs](docs/index.md#exporting-to-xarray) for how VA/array channels
+and duplicate channel names come through.
+
+## Optional Rust-accelerated backend
+
+The pure-Python code in `pygdb/` is always the reference implementation
+and always fully correct and usable on its own — nothing here depends
+on Rust. This package is built with [`maturin`](https://www.maturin.rs/)
+so that an optional Rust extension (`pygdb._native`, source under
+[`rust/`](rust/)) rides along and is used automatically when present:
+it accelerates the two real CPU-bound hot paths profiling found in this
+reader — LZRW1 decompression and fixed-width string decoding — roughly
+3-6x on real files, measured against this project's own sample corpus.
+`pygdb/lzrw1.py`/`pygdb/gdb_reader.py` detect it at import time and fall
+back to plain Python transparently if it isn't there.
+
+Building it yourself (e.g. for local development, or a platform without
+a published wheel) needs a Rust toolchain:
+
+```sh
+pip install -e ".[dev]"   # compiles pygdb._native as part of the install
+```
+
+or, for a release-optimized build without an editable install:
+
+```sh
+pip install maturin
+maturin build --release --manifest-path rust/Cargo.toml
+```
+
+See [`rust/src/lib.rs`](rust/src/lib.rs) for what's implemented (and,
+just as importantly, what was tried and deliberately left out after
+being benchmarked as not worth it — a parallel batch decoder and a
+memory-mapped-file I/O path, both documented there with real numbers),
+and [`.github/workflows/wheels.yml`](.github/workflows/wheels.yml) for
+the released wheel matrix: an `abi3` wheel per platform covering every
+non-free-threaded CPython ≥3.12, an `abi3.abi3t` wheel per platform
+(PEP 803) covering both the GIL-enabled and free-threaded builds of
+CPython ≥3.15 with a single wheel, and one version-specific wheel per
+platform for 3.14's free-threaded build (`3.14t` has no stable-ABI
+option — `abi3t` only exists from 3.15 onward).
+
+## Documentation
+
+Full documentation — the format specification, usage, contributing
+guide, and research provenance — lives under [`docs/`](docs/index.md)
+and is built with [Zensical](https://zensical.org/). To view it
+locally:
+
+```sh
+pip install -e ".[docs]"
+zensical serve
+```
+
+- [`docs/spec.md`](docs/spec.md) — the living reference specification
+  for the `.gdb`/`.grd` on-disk format, with a confidence rating
+  (confirmed / likely / guess / unknown) on every field. Updated as
+  more real example files are tested against it.
+- [`docs/contributing.md`](docs/contributing.md) — how to report bugs
+  (reproducible example files welcome) and this project's hard
+  boundary on reverse engineering.
+- [`docs/provenance/`](docs/provenance/index.md) — the original
+  research log and write-up this implementation was derived from.
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Most of the suite is synthetic-fixture unit tests (`tests/test_*.py`,
+minus `test_integration_samples.py`) that build minimal `.gdb`/`.grd`
+byte layouts by hand — no sample data required, safe to run anywhere
+including CI. `tests/test_integration_samples.py` additionally
+cross-checks the reader against real files in a local, gitignored
+`samples/` directory when present, and skips (not fails) when it's
+absent.
+
+## Sample data
+
+Real `.gdb`/`.grd` sample files used during development are **not**
+committed to this repository or otherwise redistributed — we don't
+necessarily have redistribution rights for them. See
+[`docs/provenance/notes.md`](docs/provenance/notes.md) for exact
+provenance (source URL/DOI/portal, size) for every sample used, so they
+can be re-downloaded independently.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Joseph Capriotti.
+

python_gdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pygdb/__init__.py,sha256=0srdABOKNkLpKi0CJFa0vpGaLL8_kc17U2afcTVzRDM,1637
+pygdb/_native.pyd,sha256=T3mim3jz-dDqoO9wpsJILUBf75sRQQ3YtDh6VLU6PNM,186368
+pygdb/gdb.py,sha256=MDM5zcTNSdobFlSFEC1AqW0hTDKBmTC8_AUewML8xZM,29436
+pygdb/gdb_reader.py,sha256=nwYpNdurB9oPmLh0kF_BGl0yqnyzjOc0sYNvOCCy4fs,65656
+pygdb/grd_reader.py,sha256=pabp9vVW1v-leM9rfZowzV2DGn70AboSoQKV4Zeprzs,11655
+pygdb/lzrw1.py,sha256=Hjne6ClmgXNyHGsN0Oel2c_yLLgE_uoAML9D3DUHVPk,14612
+pygdb/registry.py,sha256=74cLbC9k9dpWYN0sOKBwUENymhu8LrtbuoIOdVrQhVs,4637
+python_gdb-0.1.0.dist-info/METADATA,sha256=j9hTn_rLwIBsYVibUUm-vY1XJ5t2YjpBkO2X0eCSqVY,7635
+python_gdb-0.1.0.dist-info/WHEEL,sha256=rjikdQI6uHLAgYXPVkr7bTnnX2G_U4MjYuRag5dSWZs,96
+python_gdb-0.1.0.dist-info/licenses/LICENSE,sha256=PKGLyWd7bIQHdkI3zmIF0jpKUlD01tpRdmvNQ7hAlTI,1094
+python_gdb-0.1.0.dist-info/sboms/pygdb-native.cyclonedx.json,sha256=DhLZJaU5Rimv09TbQKSWDEOURFmTplXLsxvAUbgzTIE,17316
+python_gdb-0.1.0.dist-info/RECORD,,

python_gdb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp312-abi3-win_amd64

python_gdb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Capriotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.