vcti-mesh-schema 1.0.0

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

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

pip install vcti-mesh-schema

In requirements.txt

vcti-mesh-schema>=1.0.0

In pyproject.toml dependencies

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

---

Quick Start

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

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:

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 for the normative schema and docs/design.md for the rationale and boundaries.

---

Dependencies

• vcti-tree — the tree protocols the accessors walk.
• numpy — structured-array block access.