vcti-usd-schema-model 0.2.0__tar.gz

vcti_usd_schema_model-0.2.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_usd_schema_model-0.2.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: vcti-usd-schema-model
+Version: 0.2.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.2.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-usd-schema-model>=0.2.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) |

vcti_usd_schema_model-0.2.0/README.md

@@ -0,0 +1,200 @@
+# 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.2.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-usd-schema-model>=0.2.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) |

vcti_usd_schema_model-0.2.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-usd-schema-model"
+version = "0.2.0"
+description = "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"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    # The shipped plugin was generated by usdGenSchema 26.11; a new major is
+    # admitted only after the plugin is regenerated and checked against it.
+    "usd-core>=26.11,<27",
+]
+
+[project.urls]
+Repository = "https://github.com/vcollab/vcti-python-usd-schema-model"
+Changelog = "https://github.com/vcollab/vcti-python-usd-schema-model/blob/main/CHANGELOG.md"
+
+[project.scripts]
+vcti-usd-model-validate = "vcti.usd.schema.model.cli:main"
+
+# Every schema package of the family names its plugin directory here, and
+# each one's register_plugin() registers them all; see registry.py.
+[project.entry-points."vcti.usd.schema"]
+model = "vcti.usd.schema.model.registry:PLUGIN_DIR"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.usd.schema.model", "vcti.usd.schema.model.*"]
+
+[tool.setuptools.package-data]
+"vcti.usd.schema.model" = [
+    "py.typed",
+    "plugin/*.json",
+    "plugin/*.usda",
+    "stages/*.usda",
+    "stages/payloads/*.usda",
+    "stages/buffers/*.bin",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+# usdGenSchema, which regenerates the plugin, renders its output with jinja2.
+schema = ["jinja2"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.usd.schema.model --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+# usd-core ships no type information, so its modules are untyped here.
+[[tool.mypy.overrides]]
+module = ["pxr.*"]
+ignore_missing_imports = true
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "^\\s*\\.\\.\\.\\s*$",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_usd_schema_model-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_usd_schema_model-0.2.0/src/vcti/usd/schema/model/__init__.py

@@ -0,0 +1,85 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.usd.schema.model: the OpenUSD schema for the VCollab model.
+
+The model is the stage the VCollab server builds for one model and
+projects into the viewer protocol. This package ships that schema as a
+codeless USD plugin, the declarations it is generated from, nine fixture
+stages that exercise its contracts, the authoring helpers that reproduce the
+CAE fixtures, and the validator a server-built stage must pass.
+
+Typical use::
+
+    from vcti.usd.schema.model import open_fixture, validate
+
+    stage = open_fixture("static_structural")
+    assert validate(stage) == []
+"""
+
+from importlib.metadata import version
+
+from .builder import build_fixtures
+from .declarations import normalize_plugin_info, render_schema, write_schema
+from .fixtures import (
+    BUILT_FIXTURE_NAMES,
+    FIXTURE_NAMES,
+    STAGES_DIR,
+    fixture_path,
+    fixture_paths,
+    open_fixture,
+    open_stage,
+)
+from .registry import ENTRY_POINT_GROUP, PLUGIN_DIR, is_registered, plugin_dirs, register_plugin
+from .validator import validate, validate_file
+from .vocabulary import (
+    COMPONENT_ORDER,
+    ELEMENT_TYPES,
+    FAMILY_WIDTH,
+    FIDELITIES,
+    GEOMETRY_ARRAYS,
+    LIBRARY_NAME,
+    MAPPINGS,
+    MODEL_KINDS,
+    PRECISIONS,
+    PRIMITIVE_TOKEN,
+    PRIMITIVES,
+    SCHEMA_VERSION,
+    SOURCE_ASSOCIATIONS,
+)
+
+__version__ = version("vcti-usd-schema-model")
+
+__all__ = [
+    "BUILT_FIXTURE_NAMES",
+    "COMPONENT_ORDER",
+    "ELEMENT_TYPES",
+    "ENTRY_POINT_GROUP",
+    "FAMILY_WIDTH",
+    "FIDELITIES",
+    "FIXTURE_NAMES",
+    "GEOMETRY_ARRAYS",
+    "LIBRARY_NAME",
+    "MAPPINGS",
+    "MODEL_KINDS",
+    "PLUGIN_DIR",
+    "PRECISIONS",
+    "PRIMITIVES",
+    "PRIMITIVE_TOKEN",
+    "SCHEMA_VERSION",
+    "SOURCE_ASSOCIATIONS",
+    "STAGES_DIR",
+    "__version__",
+    "build_fixtures",
+    "fixture_path",
+    "fixture_paths",
+    "is_registered",
+    "normalize_plugin_info",
+    "open_fixture",
+    "open_stage",
+    "plugin_dirs",
+    "register_plugin",
+    "render_schema",
+    "validate",
+    "validate_file",
+    "write_schema",
+]