ncarnate 2.0.0__tar.gz

ncarnate-2.0.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

ncarnate-2.0.0/.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: [ErickShepherd] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: ErickShepherd # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: ['paypal.me/ErickEShepherd', 'https://cash.app/$ErickShepherd', 'https://venmo.com/ErickShepherd', 'https://erickshepherd.com/pay/bitcoin/'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

ncarnate-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+# No system HDF libraries are installed anywhere in this workflow on
+# purpose: the netCDF4 wheels bundle libhdf5/libnetcdf, and the pyhdf
+# >= 0.11.6 manylinux wheels bundle libhdf4 (verified against PyPI
+# 2026-07-08 for cp310-cp313). Platforms without a pyhdf wheel (e.g.
+# linux-aarch64) need a system libhdf4 for the sdist build instead.
+
+jobs:
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: python -m pip install ruff
+      - name: Run ruff
+        run: ruff check .
+
+  test:
+    name: pytest (${{ matrix.os }} py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # Smoke the self-contained-wheel install story (pyhdf + netCDF4 +
+        # pyproj, no system HDF libs) on macOS too. Windows is deliberately
+        # excluded: pyhdf's Windows wheel ships no HDF4 runtime, so the
+        # HDF4 path can't import from PyPI wheels there (README documents
+        # the conda-forge / WSL route). The netCDF path works on Windows.
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with test extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+      - name: Run tests (offline; raw-granule marks self-skip)
+        run: python -m pytest -q
+
+  build:
+    name: build + twine check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install build twine
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*

ncarnate-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+# Publishes the package via PyPI Trusted Publishing (OIDC) — no API token is
+# stored anywhere (not in the repo, not in GitHub secrets). PyPI verifies the
+# workflow's short-lived OIDC identity instead.
+#
+# Two ways to run:
+#   * A published GitHub Release  -> builds and publishes to PyPI.
+#   * Manual "Run workflow"       -> choose testpypi (dry run) or pypi.
+#
+# The publish jobs run in protected GitHub Environments (`pypi` / `testpypi`).
+# Add yourself as a required reviewer on each (repo Settings -> Environments)
+# so every upload pauses for your one-click approval before it leaves.
+
+on:
+  release:
+    types: [released]  # full releases only — pre-releases never auto-publish
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true  # re-dispatching a dry run for an existing version won't fail
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0

ncarnate-2.0.0/.gitignore

@@ -0,0 +1,21 @@
+# Python build/runtime artifacts.
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments.
+venv/
+.venv/
+
+# Tooling caches.
+.pytest_cache/
+.ruff_cache/
+
+# Local scratch.
+tmp/
+
+# Audit orchestration sidecars (ephemeral analysis).
+docs/audits/*.run.log
+docs/audits/*.audit-state.json

ncarnate-2.0.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [2.0.0] - 2026-07-08
+
+A ground-up rebuild of the 2020 utility, renamed from
+`netcdf_recompressor` to **ncarnate**. Everything below is breaking
+relative to the notional 1.x behavior; there are no downstream users
+(1.x was never published).
+
+### Fixed
+
+- The CLI recompresses again: a debugging `raise ValueError` committed
+  in 2020 made the shipped tool process nothing.
+- Variables carrying `_FillValue` no longer crash the copy (`fill_value`
+  is declared at variable creation, as netCDF4 requires).
+- Packed-integer data is no longer silently re-quantized through float:
+  values are copied raw (`set_auto_maskandscale(False)`), with
+  `scale_factor`/`add_offset`/`_FillValue` re-declared, never applied.
+- Overwrite is safe: output is written to a temp file, verified
+  value-for-value against the source, and only then atomically moved
+  into place. A failed run never destroys the source.
+- `-V`/`--version` works without a path; errors exit non-zero with
+  clear messages instead of vanishing into a log file.
+
+### Added
+
+- **HDF4/HDF-EOS2 ingest** (read-only; output is always netCDF4):
+  SDS payloads convert bit-identically, one netCDF4 group per EOS
+  structure, EOS metadata preserved verbatim, hostile names sanitized
+  with originals recorded in companion attributes.
+- **CF geolocation reconstruction** for HDF-EOS2: GCTP
+  polar-stereographic, geographic, and Lambert-azimuthal (EASE-Grid)
+  grids become CF grid mappings + `x`/`y` + 2-D `lat`/`lon`; swath
+  geolocation is CF-attached; dimension-mapped geolocation (5 km →
+  1 km) is interpolated through ECEF space with fill propagation.
+  `--no-geolocation` converts payload-only. Unsupported constructs fail
+  loud with named errors.
+- File-type dispatch by magic bytes (netCDF3 / netCDF4-HDF5 / HDF4),
+  independent of file extension.
+- pytest suite (66 tests) pinning the fidelity contract over committed
+  fixtures trimmed from real granules, plus the geolocation verification
+  lattice (four of the design's five checks; the `eos2dump` external
+  reference is unimplemented — the same-granule THG reference covers
+  that grid); CI across CPython 3.10–3.13.
+- Modern packaging: hatchling `pyproject.toml`, console entry point
+  `ncarnate`, single-sourced version, `LICENSE` file.
+
+### Changed
+
+- Project renamed to `ncarnate`; import package `ncarnate`; CLI
+  `ncarnate`.
+- Python 3.10+ (was 3.7).
+- Logging goes to stderr only when the CLI runs — importing the library
+  no longer creates log files as a side effect.
+
+### Removed
+
+- `setup.py`, `MANIFEST.in`, `version.json` (and its malformed
+  `"1.0.0."` version string), committed `__pycache__`, and the stray
+  `LOG_FILE`.
+
+## [1.0.0] - 2020-05-28
+
+Initial private version (`netcdf_recompressor`), never published:
+a single-purpose netCDF4/HDF5 recompression script with a `setup.py`
+package skeleton.

ncarnate-2.0.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "ncarnate"
+abstract: >-
+  Reincarnate legacy scientific data as modern netCDF4: losslessly
+  recompress netCDF/HDF5 files and convert HDF4/HDF-EOS2 granules to
+  CF-annotated netCDF4 with reconstructed grid and swath geolocation.
+type: software
+authors:
+  - family-names: "Shepherd"
+    given-names: "Erick"
+    email: "Contact@ErickShepherd.com"
+version: "2.0.0"
+date-released: "2026-07-08"
+license: MIT
+repository-code: "https://github.com/ErickShepherd/ncarnate"
+url: "https://github.com/ErickShepherd/ncarnate"
+keywords:
+  - netCDF
+  - HDF4
+  - HDF-EOS2
+  - compression
+  - CF conventions
+  - atmospheric science
+  - remote sensing

ncarnate-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Erick Edward Shepherd
+
+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.

ncarnate-2.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: ncarnate
+Version: 2.0.0
+Summary: Losslessly rewrite netCDF4/HDF5 files with different compression settings.
+Project-URL: Homepage, https://github.com/ErickShepherd/ncarnate
+Project-URL: Source, https://github.com/ErickShepherd/ncarnate
+Project-URL: Bug Tracker, https://github.com/ErickShepherd/ncarnate/issues
+Author-email: Erick Shepherd <Contact@ErickShepherd.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HDF-EOS2,HDF4,HDF5,atmospheric science,compression,netCDF,netCDF4,recompression
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: netcdf4>=1.6
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyhdf>=0.11.6
+Requires-Dist: pyproj>=3.6
+Requires-Dist: tqdm>=4.66
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/x-rst
+
+ncarnate
+========
+
+|ci| |license| |python|
+
+.. |ci| image:: https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml
+   :alt: CI status
+
+.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg
+   :target: https://github.com/ErickShepherd/ncarnate/blob/master/LICENSE
+   :alt: MIT License
+
+.. |python| image:: https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg
+   :target: https://pypi.org/project/ncarnate/
+   :alt: Python 3.10-3.13
+
+Reincarnate legacy scientific data as modern netCDF4.
+
+ncarnate reads netCDF3, netCDF4/HDF5, and HDF4/HDF-EOS2 files and writes
+recompressed, CF-annotated netCDF4. It does two jobs:
+
+- **Recompress** netCDF/HDF5 files — change the compression level,
+  shuffle filter, or storage layout without changing a single stored
+  value.
+- **Convert** HDF4 and HDF-EOS2 granules (AMSR-E, MODIS, and kin) to
+  netCDF4, reconstructing the CF coordinates that modern tools (xarray,
+  QGIS, Panoply) need: grid projections become CF grid mappings with
+  1-D ``x``/``y`` and 2-D ``lat``/``lon`` coordinates, swath geolocation
+  is attached as CF coordinates, and dimension-mapped (e.g. 5 km → 1 km)
+  geolocation is interpolated through ECEF space.
+
+The fidelity contract
+---------------------
+
+Converting or recompressing a file changes *storage*, never *science
+data*:
+
+- Every variable's stored values are preserved **bit-identically** —
+  packed integers stay packed; ``scale_factor``/``add_offset``/
+  ``_FillValue`` are carried across as declarations, never applied.
+- Every dimension (including unlimited-ness), attribute (including its
+  type), and group survives. HDF-EOS2 ``StructMetadata`` is preserved
+  verbatim; names netCDF cannot hold are sanitized with the original
+  recorded in a companion attribute.
+- Geolocation reconstruction is strictly **additive**: the original
+  information always rides along, so the conversion never becomes the
+  only copy of the truth.
+- Every output is **verified against the source value-for-value before
+  it replaces anything**. A source file is never destroyed by a failed
+  run, and HDF4 sources are never replaced at all.
+- Unsupported constructs (user-defined netCDF types, unverified GCTP
+  projections, exotic swath layouts) **fail loud** with a named error
+  rather than guessing — a wrong coordinate is worse than a refused
+  conversion. ``--no-geolocation`` converts the raw payload anyway.
+
+The details, the guarantee boundary, and how the test suite pins each
+clause live in ``docs/fidelity-notes.md``.
+
+Installation
+------------
+
+.. code-block:: console
+
+   pip install ncarnate
+
+On **Linux (x86_64)** and **macOS (arm64)**, every dependency — including
+``pyhdf`` — installs as a self-contained binary wheel with no system
+libraries required (the ``pyhdf`` wheels there bundle the HDF4 C
+library). On platforms without a repaired ``pyhdf`` wheel (e.g. Linux
+aarch64), building from sdist requires the system HDF4 library first
+(Debian/Ubuntu: ``apt install libhdf4-dev``).
+
+**Windows:** the netCDF/HDF5 *recompression* path works from PyPI wheels
+out of the box, but the HDF4/HDF-EOS2 *conversion* path does **not** —
+``pyhdf``'s Windows wheel ships no HDF4 runtime, so ``import pyhdf`` fails
+with a DLL-load error. For HDF4 support on Windows, install
+``pyhdf`` from **conda-forge** first (``conda install -c conda-forge
+pyhdf``), which provides a properly linked build with the HDF4 runtime,
+then ``pip install ncarnate`` into that same environment — or use **WSL**
+and follow the Linux instructions.
+
+Command line usage
+------------------
+
+.. code-block:: console
+
+   # Recompress a netCDF4 file in place (verified before replacement).
+   ncarnate observations.nc --complevel 9
+
+   # Keep the original; write observations_recompressed.nc beside it.
+   ncarnate --no-overwrite observations.nc
+
+   # Convert an HDF-EOS2 granule -> granule.nc with CF geolocation.
+   ncarnate AMSR_E_L3_SeaIce12km_B02_20020619.hdf
+
+   # Convert the raw SDS payload only (unsupported-projection escape hatch).
+   ncarnate --no-geolocation granule.hdf
+
+   # Recurse over a directory tree.
+   ncarnate -r /data/archive
+
+Exit codes: ``0`` success, ``1`` one or more files failed, ``2`` bad
+input paths or arguments.
+
+Library usage
+-------------
+
+.. code-block:: python
+
+   from ncarnate import recompress
+
+   # Lossless recompression; returns the output path.
+   recompress("observations.nc", complevel=9)
+
+   # HDF-EOS2 conversion; the .hdf source is never replaced.
+   recompress("granule.hdf", dst="granule.nc")
+
+Example
+-------
+
+The AMSR-E daily 12.5 km sea-ice granule this project grew up around:
+
+===============================================  ==========  ===========
+File                                             Input       Output
+===============================================  ==========  ===========
+netCDF4 recompression (``--complevel 9``)        42.6 MB     19.9 MB
+HDF-EOS2 → netCDF4 (+ reconstructed lat/lon)     60.2 MB     35.5 MB
+===============================================  ==========  ===========
+
+Both outputs re-read bit-identically to their sources; the conversion
+additionally carries CF ``polar_stereographic`` grid mappings and
+coordinates for both hemispheric grids. The northern grid's
+reconstructed latitudes/longitudes agree with The HDF Group's
+independent conversion of the same granule to within 10\ :sup:`-5`
+degrees (about a metre), the tolerance the test suite enforces.
+
+Supported inputs
+----------------
+
+- **netCDF4 / HDF5** and **netCDF3** — recompressed via the netCDF4
+  library.
+- **HDF4 / HDF-EOS2** — read via the pyhdf SD API. GRID structures with
+  GCTP polar-stereographic, geographic, and Lambert-azimuthal
+  (EASE-Grid) projections; SWATH structures with direct or
+  dimension-mapped geolocation. Output is always netCDF4 — HDF4 is
+  never written.
+
+Development
+-----------
+
+.. code-block:: console
+
+   pip install -e ".[test]"
+   ruff check .
+   pytest
+
+The test suite runs entirely offline against small committed fixtures
+trimmed from real granules (provenance sidecars included); cross-checks
+against the raw multi-MB granules self-skip where the local granule
+store is absent.
+
+License
+-------
+
+MIT — see ``LICENSE``.

ncarnate-2.0.0/README.rst

@@ -0,0 +1,166 @@
+ncarnate
+========
+
+|ci| |license| |python|
+
+.. |ci| image:: https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/ErickShepherd/ncarnate/actions/workflows/ci.yml
+   :alt: CI status
+
+.. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg
+   :target: https://github.com/ErickShepherd/ncarnate/blob/master/LICENSE
+   :alt: MIT License
+
+.. |python| image:: https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg
+   :target: https://pypi.org/project/ncarnate/
+   :alt: Python 3.10-3.13
+
+Reincarnate legacy scientific data as modern netCDF4.
+
+ncarnate reads netCDF3, netCDF4/HDF5, and HDF4/HDF-EOS2 files and writes
+recompressed, CF-annotated netCDF4. It does two jobs:
+
+- **Recompress** netCDF/HDF5 files — change the compression level,
+  shuffle filter, or storage layout without changing a single stored
+  value.
+- **Convert** HDF4 and HDF-EOS2 granules (AMSR-E, MODIS, and kin) to
+  netCDF4, reconstructing the CF coordinates that modern tools (xarray,
+  QGIS, Panoply) need: grid projections become CF grid mappings with
+  1-D ``x``/``y`` and 2-D ``lat``/``lon`` coordinates, swath geolocation
+  is attached as CF coordinates, and dimension-mapped (e.g. 5 km → 1 km)
+  geolocation is interpolated through ECEF space.
+
+The fidelity contract
+---------------------
+
+Converting or recompressing a file changes *storage*, never *science
+data*:
+
+- Every variable's stored values are preserved **bit-identically** —
+  packed integers stay packed; ``scale_factor``/``add_offset``/
+  ``_FillValue`` are carried across as declarations, never applied.
+- Every dimension (including unlimited-ness), attribute (including its
+  type), and group survives. HDF-EOS2 ``StructMetadata`` is preserved
+  verbatim; names netCDF cannot hold are sanitized with the original
+  recorded in a companion attribute.
+- Geolocation reconstruction is strictly **additive**: the original
+  information always rides along, so the conversion never becomes the
+  only copy of the truth.
+- Every output is **verified against the source value-for-value before
+  it replaces anything**. A source file is never destroyed by a failed
+  run, and HDF4 sources are never replaced at all.
+- Unsupported constructs (user-defined netCDF types, unverified GCTP
+  projections, exotic swath layouts) **fail loud** with a named error
+  rather than guessing — a wrong coordinate is worse than a refused
+  conversion. ``--no-geolocation`` converts the raw payload anyway.
+
+The details, the guarantee boundary, and how the test suite pins each
+clause live in ``docs/fidelity-notes.md``.
+
+Installation
+------------
+
+.. code-block:: console
+
+   pip install ncarnate
+
+On **Linux (x86_64)** and **macOS (arm64)**, every dependency — including
+``pyhdf`` — installs as a self-contained binary wheel with no system
+libraries required (the ``pyhdf`` wheels there bundle the HDF4 C
+library). On platforms without a repaired ``pyhdf`` wheel (e.g. Linux
+aarch64), building from sdist requires the system HDF4 library first
+(Debian/Ubuntu: ``apt install libhdf4-dev``).
+
+**Windows:** the netCDF/HDF5 *recompression* path works from PyPI wheels
+out of the box, but the HDF4/HDF-EOS2 *conversion* path does **not** —
+``pyhdf``'s Windows wheel ships no HDF4 runtime, so ``import pyhdf`` fails
+with a DLL-load error. For HDF4 support on Windows, install
+``pyhdf`` from **conda-forge** first (``conda install -c conda-forge
+pyhdf``), which provides a properly linked build with the HDF4 runtime,
+then ``pip install ncarnate`` into that same environment — or use **WSL**
+and follow the Linux instructions.
+
+Command line usage
+------------------
+
+.. code-block:: console
+
+   # Recompress a netCDF4 file in place (verified before replacement).
+   ncarnate observations.nc --complevel 9
+
+   # Keep the original; write observations_recompressed.nc beside it.
+   ncarnate --no-overwrite observations.nc
+
+   # Convert an HDF-EOS2 granule -> granule.nc with CF geolocation.
+   ncarnate AMSR_E_L3_SeaIce12km_B02_20020619.hdf
+
+   # Convert the raw SDS payload only (unsupported-projection escape hatch).
+   ncarnate --no-geolocation granule.hdf
+
+   # Recurse over a directory tree.
+   ncarnate -r /data/archive
+
+Exit codes: ``0`` success, ``1`` one or more files failed, ``2`` bad
+input paths or arguments.
+
+Library usage
+-------------
+
+.. code-block:: python
+
+   from ncarnate import recompress
+
+   # Lossless recompression; returns the output path.
+   recompress("observations.nc", complevel=9)
+
+   # HDF-EOS2 conversion; the .hdf source is never replaced.
+   recompress("granule.hdf", dst="granule.nc")
+
+Example
+-------
+
+The AMSR-E daily 12.5 km sea-ice granule this project grew up around:
+
+===============================================  ==========  ===========
+File                                             Input       Output
+===============================================  ==========  ===========
+netCDF4 recompression (``--complevel 9``)        42.6 MB     19.9 MB
+HDF-EOS2 → netCDF4 (+ reconstructed lat/lon)     60.2 MB     35.5 MB
+===============================================  ==========  ===========
+
+Both outputs re-read bit-identically to their sources; the conversion
+additionally carries CF ``polar_stereographic`` grid mappings and
+coordinates for both hemispheric grids. The northern grid's
+reconstructed latitudes/longitudes agree with The HDF Group's
+independent conversion of the same granule to within 10\ :sup:`-5`
+degrees (about a metre), the tolerance the test suite enforces.
+
+Supported inputs
+----------------
+
+- **netCDF4 / HDF5** and **netCDF3** — recompressed via the netCDF4
+  library.
+- **HDF4 / HDF-EOS2** — read via the pyhdf SD API. GRID structures with
+  GCTP polar-stereographic, geographic, and Lambert-azimuthal
+  (EASE-Grid) projections; SWATH structures with direct or
+  dimension-mapped geolocation. Output is always netCDF4 — HDF4 is
+  never written.
+
+Development
+-----------
+
+.. code-block:: console
+
+   pip install -e ".[test]"
+   ruff check .
+   pytest
+
+The test suite runs entirely offline against small committed fixtures
+trimmed from real granules (provenance sidecars included); cross-checks
+against the raw multi-MB granules self-skip where the local granule
+store is absent.
+
+License
+-------
+
+MIT — see ``LICENSE``.