Metadata-Version: 2.4
Name: vcti-mesh-schema
Version: 1.0.0
Summary: Mesh schema and accessors for structured-array mesh blocks in DataNode trees
Author: Visual Collaboration Technologies Inc.
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: vcti-tree>=2.0.0
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

# vcti-mesh-schema

Mesh schema and accessors for structured-array mesh blocks in DataNode trees.

## Overview

`vcti-mesh-schema` defines what a **mesh subtree** looks like: a DataNode
subtree whose children carry one structured numpy array per block — a
`node` block with point coordinates (`x, y` for 2-D meshes, `x, y, z` for
3-D), and cell blocks (`edge`, `triangle`, `tetrahedron`, ...) with
integer `node_index*` connectivity fields. It is the shared contract that
lets mesh readers (fileloader plugins such as `vcti-fileloader-slim`) and
mesh writers (`vcti-tree-exporter-mesh`) interoperate without depending
on each other. There is deliberately no container class — just the
vocabulary, and free functions that extract coordinate/connectivity
matrices, locate blocks in a tree, and validate conformance.

## Installation

```bash
pip install vcti-mesh-schema
```

### In `requirements.txt`

```
vcti-mesh-schema>=1.0.0
```

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-mesh-schema>=1.0.0",
]
```

---

## Quick Start

Work with a block array directly (any structured array with schema fields):

```python
import numpy as np
from vcti.mesh.schema import attribute_fields, connectivity, coordinates

node = np.array(
    [(0.0, 0.0, 0.0, 10), (1.0, 0.0, 0.0, 11), (1.0, 1.0, 0.0, 12)],
    dtype=[("x", "<f8"), ("y", "<f8"), ("z", "<f8"), ("uid", "<i4")],
)
triangle = np.array(
    [(0, 1, 2, 7)],
    dtype=[("node_index0", "<u4"), ("node_index1", "<u4"),
           ("node_index2", "<u4"), ("uid", "<i4")],
)

coordinates(node)            # (3, 3) float64 matrix — (N, 2) for a 2-D mesh
connectivity(triangle)       # (1, 3) int64 matrix, zero-based indices
attribute_fields(node.dtype) # ("uid",) — the per-entity fields
dimension(node.dtype)        # 3 (a block with only x, y fields gives 2)
```

Work with a mesh subtree produced by a loader:

```python
from vcti.mesh.schema import load_mesh_blocks, validate_mesh_subtree

validate_mesh_subtree(tree, mesh_root)          # raises MeshSchemaError subclass
blocks = load_mesh_blocks(tree, mesh_root)      # {"node": ..., "triangle": ...}
xyz = coordinates(blocks["node"])
```

Blocks may be lazy (`LazyDataNode`-style payloads); `load_mesh_blocks`
materialises them through the payload's own `load()`.

---

## API surface

| Name | Kind | Purpose |
|------|------|---------|
| `NODE_BLOCK`, `COORDINATE_FIELDS`, `CONNECTIVITY_PREFIX`, `UID_FIELD` | constants | Schema vocabulary |
| `CELL_NODE_COUNTS` | mapping | Canonical cell types → nodes per cell |
| `dimension(dtype)` | function | Mesh dimension: 2 or 3 |
| `coordinates(block)` | function | `(N, d)` float64 matrix from a point block |
| `connectivity(block)` | function | `(M, k)` int64 matrix from a cell block |
| `connectivity_fields(dtype)` / `attribute_fields(dtype)` | function | Field classification |
| `block_array(payload)` | function | Duck-typed (lazy-aware) array access |
| `find_mesh_blocks(tree, root)` | function | Block handles by name |
| `load_mesh_blocks(tree, root)` | function | Block arrays by name |
| `validate_mesh_subtree(tree, root)` | function | Schema conformance check |
| `MeshSchemaError` | exception | Base; `BlockNotFoundError`, `BlockFormatError`, `ConnectivityError` |

See [docs/schema.md](docs/schema.md) for the normative schema and
[docs/design.md](docs/design.md) for the rationale and boundaries.

---

## Dependencies

- [vcti-tree](https://pypi.org/project/vcti-tree/) — the tree protocols the accessors walk.
- [numpy](https://numpy.org/) — structured-array block access.
