Skip to main content

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

pip install vcti-usd-schema-model

In requirements.txt

vcti-usd-schema-model>=0.3.0

In pyproject.toml dependencies

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

Quick Start

Validate a stage

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

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:

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

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

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
Walk through the fixtures scenario by scenario docs/patterns.md
Navigate and understand the source docs/source-guide.md
Add a type, a property, a check or a fixture docs/extending.md

Metadata

Release files for vcti-usd-schema-model 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-usd-schema-model 0.3.0
File Size Uploaded Provenance Actions
vcti_usd_schema_model-0.3.0.tar.gz 80.9 kB With provenance Details for vcti_usd_schema_model-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-usd-schema-model 0.3.0
File Interpreter ABI Platform Actions
vcti_usd_schema_model-0.3.0-py3-none-any.whl Python 3 none any Details for vcti_usd_schema_model-0.3.0-py3-none-any.whl

Total release size: 156.2 kB

Release files / vcti_usd_schema_model-0.3.0.tar.gz

Download URL vcti_usd_schema_model-0.3.0.tar.gz
Size 80.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e4744a8579bb4f3cedcd0d4c6308f7c7f338f3895bf195544e61e6d011dbba5a
BLAKE2b-256 checksum
How to use checksums
327f398a6957e5f7768d56d7d02881da5ea4bc02a758b76568303387f2051e9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / vcti_usd_schema_model-0.3.0-py3-none-any.whl

Download URL vcti_usd_schema_model-0.3.0-py3-none-any.whl
Size 75.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
adac394b14f94850043dfab65edfe7585963de51f2d292d76e85130e8135a0ee
BLAKE2b-256 checksum
How to use checksums
e7a251ae23e81da0d3dbad3c462e101df88e92628c737abf71beec54cb25aa50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for vcti-usd-schema-model 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_usd_schema_model-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page