Metadata-Version: 2.4
Name: vcti-tree-exporter-npz
Version: 2.0.0
Summary: NPZ exporter plugin for vcti-tree-exporter: writes a vcti tree to a single .npz archive (arrays under path-keyed entries, hierarchy and attributes in an embedded JSON manifest).
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/vcollab/vcti-python-tree-exporter-npz
Project-URL: Repository, https://github.com/vcollab/vcti-python-tree-exporter-npz
Project-URL: Changelog, https://github.com/vcollab/vcti-python-tree-exporter-npz/blob/main/CHANGELOG.md
Keywords: tree,export,npz,numpy,serialization,exporter,plugin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vcti-tree-exporter>=2.0.0
Requires-Dist: vcti-tree>=2.0.0
Requires-Dist: vcti-datanode>=2.0.0
Requires-Dist: numpy>=1.24
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# NPZ Tree Exporter

NPZ exporter plugin for [`vcti-tree-exporter`](https://github.com/vcollab/vcti-python-tree-exporter): writes a vcti tree to a single `.npz` archive.

`NpzExporter` serializes any [`vcti-tree`](https://github.com/vcollab/vcti-python-tree)
tree whose node payloads are
[`vcti-datanode`](https://github.com/vcollab/vcti-python-datanode) `DataNode`s
to one NumPy `.npz` archive, and ships a `get_exporter_descriptor()` factory so
a consumer registers it in a catalog and resolves it by id (`"npz"`) or by
attribute lookup.

NPZ preserves array **dtype and shape natively**, so it suits complete numeric
simulation data — the heavy arrays JSON and CSV handle poorly.

## Tree → NPZ mapping

The archive is self-contained:

- each data leaf's array is stored under a **path key** built from node names,
  e.g. `model/materials/material_0`, so the flat NPZ namespace still reads as the
  tree (duplicate paths are de-collided with a `~N` suffix);
- the hierarchy, each node's `attributes`, and the array key of every data node
  are stored as one JSON **manifest** under the reserved key `__manifest__`.

```python
import numpy as np, json
archive = np.load("model.npz")
manifest = json.loads(str(archive["__manifest__"]))   # the tree structure + attributes
array = archive["model/materials/material_0"]          # a leaf's array, native dtype
```

A node may carry both an array and children. Attribute values are JSON-encoded
into the manifest (bytes decoded, numpy scalars/arrays converted) with a `str()`
fallback. The export is one-way — there is no matching importer.

## Usage

```python
from pathlib import Path
from vcti.tree.exporter.core import build_registry, get_exporter
from vcti.tree.exporter.npz import get_exporter_descriptor

registry = build_registry([get_exporter_descriptor()])   # plus any other format plugins
get_exporter(registry, "npz").export(tree, Path("model.npz"), overwrite=True)
```

Or use the exporter directly:

```python
from vcti.tree.exporter.npz import NpzExporter
NpzExporter().export(tree, Path("model.npz"))
```

## Dependencies

- [vcti-tree-exporter](https://github.com/vcollab/vcti-python-tree-exporter) — the `Exporter` protocol and the `ExporterDescriptor` catalog.
- [vcti-tree](https://github.com/vcollab/vcti-python-tree) / [vcti-datanode](https://github.com/vcollab/vcti-python-datanode) — the tree and payload types.
- numpy — the `.npz` backend.
