Metadata-Version: 2.4
Name: vcti-usd-schema-model
Version: 0.3.0
Summary: Codeless OpenUSD schema for the VCollab model, the stage the server builds for one model and projects into the viewer protocol: schema source, generated plugin, synthetic fixtures and a validator
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-usd-schema-model
Project-URL: Changelog, https://github.com/vcollab/vcti-python-usd-schema-model/blob/main/CHANGELOG.md
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: usd-core<27,>=26.11
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"
Provides-Extra: schema
Requires-Dist: jinja2; extra == "schema"
Dynamic: license-file

# VCollab USD Model Schema

Codeless OpenUSD schema for the VCollab model, the stage the server builds for one model and projects into the viewer protocol: schema source, generated plugin, synthetic fixtures and a validator

## Overview

The model is the USD stage the VCollab server composes for one
model once its readers and operators have run. It holds everything a viewer
needs and nothing it has to compute, in three parts. **Definitions** describe
the objects a client understands: the logical assembly, meshes, named
representations, fields, frames, materials and histories. **Bindings** say
which arrays serve which combination: the points of one mesh, or the stress
values for those points at one frame. **Arrays** hold flat typed tuples
behind a small header, inline or in an external buffer file. Bindings and
the arrays they name are built on request, when a client asks for them. The
browser never receives USD; a packaging step projects the stage into the
viewer protocol, which names what the stage holds by prim path.

This package ships that schema as a codeless USD plugin, the declarations it
is generated from, nine fixture stages that each exercise one group of
contracts, the authoring helpers that reproduce the CAE fixtures, and the
validator a server-built stage must pass unchanged. The fixtures are
deliberately small and synthetic: they illustrate the contracts, not
engineering results.

## Installation

```bash
pip install vcti-usd-schema-model
```

### In `requirements.txt`

```
vcti-usd-schema-model>=0.3.0
```

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-usd-schema-model>=0.3.0",
]
```

---

## Quick Start

### Validate a stage

```python
from vcti.usd.schema.model import open_fixture, validate

stage = open_fixture("static_structural")
errors = validate(stage)
print(errors)  # [] for a conforming stage
```

`open_fixture` and `open_stage` register the plugin first. Any failure is one
string, prefixed by the prim it concerns.

### Open your own stage with the plugin registered

```python
from pxr import Usd

from vcti.usd.schema.model import fixture_path, register_plugin

register_plugin()
stage = Usd.Stage.Open(str(fixture_path("transient_cfd")))
model = stage.GetPrimAtPath("/Model")
print(model.GetTypeName(), model.GetAttribute("vct:schemaVersion").Get())
```

Registration is explicit and idempotent. Without it, every `Vct` prim is an
untyped prim with authored properties, and the validator reports each one.
It also registers every installed sibling schema, such as
`vcti-usd-schema-report`: USD only knows the plugins registered before it
first looks up a typed prim, so a process that opens stages itself calls
`register_plugin()` before the first one.

### Author a stage

The builder module is the smallest API that writes a conforming stage. A
one-mesh model with a single load case and one field:

```python
from pathlib import Path

from vcti.usd.schema.model import open_stage, validate
from vcti.usd.schema.model.builder import (
    L_POINTS,
    L_TRIANGLES,
    add_array,
    add_field,
    add_frame,
    add_frame_group,
    add_index_data,
    add_mesh,
    add_occurrence,
    add_points_data,
    bind_field,
    finish,
    flat,
    new_model_stage,
    vector_values,
)

stage = new_model_stage(Path("bracket.usda"), "run://example")
mesh = add_mesh(stage, "bracket", L_POINTS)
points = add_array(stage, "points", "float32", 3, flat(L_POINTS))
normals = add_array(stage, "normals", "float32", 3, flat([(0, 0, 1)] * 6))
triangles = add_array(stage, "triangles", "int32", 3, L_TRIANGLES)
data = add_points_data(stage, "bracketPoints", mesh, points, normals, extent=L_POINTS)
add_index_data(stage, "bracketSurface", mesh, data, triangles, "surface")
add_occurrence(stage, "bracket", mesh)
add_frame_group(stage, "loadCases", "loadCase", "static")
frame = add_frame(stage, "loadCases/tension", 0)
displacement = add_field(stage, "displacement", "vector", "m", "displacement", "deformation")
values = add_array(stage, "u_tension", "float32", 3, vector_values(L_POINTS, 0.001))
bind_field(stage, "u_tension", data, displacement, values, frame, ranges=True)
finish(stage)

print(validate(open_stage("bracket.usda")))
```

### From the command line

```bash
vcti-usd-model-validate model.usda other.usda
```

One line per stage, `PASS` or `FAIL`, each failure indented beneath it, and
a non-zero exit status when any stage fails or cannot be opened.

### Rebuild the fixtures

```python
from pathlib import Path

from vcti.usd.schema.model import build_fixtures

written = build_fixtures(Path("stages"))
print([p.name for p in written])
```

The eight CAE fixtures are written with the authoring helpers. The shipped
copies are authored by hand so they can carry comments; the tests assert the
two compose to the same prims and values.

---

## Key API

| Name | What it does |
|---|---|
| `register_plugin()` | Register the shipped codeless plugin, and every installed sibling schema's, with this process, once |
| `open_stage(path)`, `open_fixture(name)` | Open with the plugin registered |
| `validate(stage)`, `validate_file(path)` | Every contract the schema states, as a list of messages |
| `fixture_path(name)`, `fixture_paths()`, `FIXTURE_NAMES` | The nine shipped stages |
| `build_fixtures(dir)` | Write the eight CAE fixtures, payloads and buffer |
| `render_schema()`, `write_schema(path)` | The `schema.usda` text, from the declarations |
| `SCHEMA_VERSION`, `FAMILY_WIDTH`, `ELEMENT_TYPES`, … | The closed vocabularies |

The fixtures, in reading order:

| Fixture | Scenario | Contracts it exercises |
|---|---|---|
| `cad_assembly` | A knuckle assembly | Occurrences, placements, shared geometry, incremental detail, part attributes |
| `higher_order` | A plate of quadratic triangles | Array composition: refinement extends points with complete indices, growth extends both; fields compose too |
| `static_structural` | One bracket, three load cases | Normals, source ids, a material, frames, bindings with ranges, provenance, a constant field |
| `modal` | Three bracket modes | Mode-indexed results, one mode per frame |
| `prestressed_modal` | Modes about two thermal conditions | Nested frame groups, inheritance down the tree, shared arrays across frames |
| `multiphysics` | Thermal, structural and modal branches | Data at some field and frame combinations only, reference conditions on frames and groups |
| `transient_cfd` | Flow on two skin patches | Physical time, histories, atoms, element death, payloads, a located array |
| `kinematic` | A crank and slider | History-only rigid-body motion, arrays shared across meshes |
| `nonlinear_mesh_change` | A rigid tool and a remeshed workpiece | Per-occurrence mesh selection across a topology change |

---

## Dependencies

- `usd-core` 26.11 or later within the 26 series, the OpenUSD Python
  distribution. Wheels exist for every Python the package supports. The
  shipped plugin was generated by that version's `usdGenSchema`, so a new
  major is admitted only after regeneration.
- `jinja2`, in the `schema` extra, only to regenerate the plugin.

---

## Documentation

| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Understand the model and the decisions behind it | [docs/design.md](docs/design.md) |
| Walk through the fixtures scenario by scenario | [docs/patterns.md](docs/patterns.md) |
| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
| Add a type, a property, a check or a fixture | [docs/extending.md](docs/extending.md) |
