Skip to main content

VCollab USD Report Schema

Codeless OpenUSD schema for the VCollab report model, the slides of a report, what they show and the deck that arranges them: schema source, generated plugin, synthetic fixtures and a validator

Overview

A VCollab report is a set of slides made from one or more models. It is defined by its variables and its workflow, which are stored as JSON; everything else is produced by running the workflow, and the server holds that as a USD stage. This package defines the part of that stage that holds the slides, what they show, and the deck.

The stage keeps three things apart:

  • The list holds every slide and section, flat, each named by a prim path that never changes.
  • The deck is a tree of nodes under /Report/deck that arranges some of them. Each node places one item, nesting is the hierarchy, and the order of a node's children is the order of the deck.
  • The states hold what is shown. A slide names the state it shows, and the report names the state on the screen.

Renaming, moving or updating a slide touches its name, the nodes or which state it names, never its path. A slide the deck does not reach is a view kept while working.

A state is made of small groups, each optional. So far there is one, assembly visibility: which assemblies of the report's models are shown, stored as a flag only where one was set. An assembly with no flag takes its parent's value, and setting a flag removes every flag beneath it.

History is not in the schema. A server may keep each workflow step in a USD layer of its own and undo by removing the last layers; every helper writes to the stage's edit target, so the same helpers work on such a stack.

This package ships that schema as a codeless USD plugin, the declarations it is generated from, four fixture reports that each exercise one group of contracts, authoring helpers that make the changes the viewer protocol's actions call for, and the validator a server-built stage must pass unchanged. It is a sibling of vcti-usd-schema-model, which describes a model. The schema is a candidate. The other groups of a state, such as the camera, the result shown and visibility within a part, are not designed yet.

Installation

pip install vcti-usd-schema-report

In requirements.txt

vcti-usd-schema-report>=0.1.0

In pyproject.toml dependencies

dependencies = [
    "vcti-usd-schema-report>=0.1.0",
]

Quick Start

Validate a stage

from vcti.usd.schema.report import open_fixture, validate

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

open_fixture and open_stage register the plugin first. Any failure is one string: the path of the prim it concerns, then a short stable phrase.

Open your own stage with the plugin registered

from pxr import Usd

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

register_plugin()
stage = Usd.Stage.Open(str(fixture_path("nested_sections")))
report = stage.GetPrimAtPath("/Report")
print(report.GetTypeName(), report.GetAttribute("vct:schemaVersion").Get())

Registration is explicit and idempotent, and it also registers every installed sibling schema, such as the model schema's. 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.

Build and edit a report

The helpers take the prim name of a slide, section or state they create, because allocating it is the server's rule, and return its path, its identity from then on. A new report starts with one state, the default screen.

from vcti.usd.schema.report import (
    DECK_PATH,
    Position,
    add_section,
    add_slide,
    logical_path,
    move_item,
    new_report_stage,
    rename_item,
    validate,
)

stage = new_report_stage("t1")
deck = Position(parent=DECK_PATH)
overview = add_slide(stage, "s1", "Overview", position=deck)
results = add_section(stage, "k1", "Results", position=deck)
stress = add_slide(stage, "s2", "Stress", {"load_case": "LC1"}, Position(parent=results))
kept = add_slide(stage, "s3", "Before the change")  # in the list, not in the deck

rename_item(stage, results, "Findings")
move_item(stage, overview, Position(after=stress))

print(stress, logical_path(stage, stress))  # /Report/slides/s2 /Findings/Stress
print(validate(stage))  # []

Change the screen and save it as a slide

A flag names its assembly by a model the report uses and the assembly's prim path on that model's stage. The models themselves are not on the report's stage.

A state that a slide shows is not written to, so a change to the screen starts with a copy of it. The three slides above show t1.

from vcti.usd.schema.report import (
    add_model,
    fork_state,
    set_visibility,
    state_of,
    update_slide,
    visibility_of,
)

main = add_model(stage, "main", project="p-104", fingerprint="9f2c61")
engine = "/Model/hierarchy/engine"

screen = fork_state(stage, "t2")  # a copy of t1, now on the screen
set_visibility(stage, screen, main, [engine], False, step="step-7")
set_visibility(stage, screen, main, [f"{engine}/bolts"], True, step="step-8")

print(visibility_of(stage, screen, main, f"{engine}/block"))  # False: takes the engine's
print(visibility_of(stage, screen, main, f"{engine}/bolts/m8"))  # True: takes the bolts'
print(visibility_of(stage, screen, main, "/Model/hierarchy/frame"))  # True: nothing set

update_slide(stage, stress)  # the slide now shows the screen; its path is unchanged
print(stress, state_of(stage, stress))  # /Report/slides/s2 /Report/states/t2
print(validate(stage))  # []

Keep a step in a layer of its own

Every helper writes to the stage's edit target. On a stack of layers a helper cannot delete what a layer beneath defines, so it makes it inactive; removing the step's layer then gives back the report as it was.

from pxr import Sdf, Usd

from vcti.usd.schema.report import remove_item

base = stage.GetRootLayer()
root, step = Sdf.Layer.CreateAnonymous(), Sdf.Layer.CreateAnonymous()
root.subLayerPaths = [step.identifier, base.identifier]
stacked = Usd.Stage.Open(root)
stacked.SetEditTarget(Usd.EditTarget(step))

remove_item(stacked, kept)
print(bool(stacked.GetPrimAtPath(kept).IsActive()), validate(stacked))  # False []

root.subLayerPaths = [base.identifier]  # undo
print(bool(stacked.GetPrimAtPath(kept).IsActive()), validate(stacked))  # True []

From the command line

vcti-usd-report-validate report.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.


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
new_report_stage(first, path) A stage holding an empty report, with its first state
add_slide, add_section, duplicate_slide, duplicate_section New items, optionally placed in the deck. A slide shows the current state
rename_item, move_item, remove_item, set_attributes Changes to an item or to where it is
Position(parent=…), Position(after=…), Position(before=…) Where an item goes in the deck
add_state(stage, name), fork_state(stage, name) A new state on the screen: the default one, or a copy of the current one
current_state(stage), set_current(stage, state), state_of(stage, slide) The state on the screen, and the state a slide shows
update_slide(stage, slide), show_slide(stage, slide) Save the screen to a slide; put a slide on the screen
add_model(stage, variable, project, fingerprint) A model the report uses
set_visibility(stage, state, model, assemblies, visible, step) Show or hide assemblies in a state, with everything beneath them
visibility_of(stage, state, model, assembly) Whether an assembly is shown in a state
visibility_flags(stage, state, model) One model's flags in a state, in one pass
node_of(stage, item), logical_path(stage, item) An item's node, and the path rules look it up by
fixture_path(name), fixture_paths(), FIXTURE_NAMES, build_fixtures(dir) The four shipped reports, and writing them again
render_schema(), write_schema(path) The schema.usda text, from the declarations
SCHEMA_VERSION, REPORT_PATH, DECK_PATH, ITEM_TYPES, … The fixed names

The types:

Type Properties Purpose
VctReport uniform string vct:schemaVersion; rel vct:current Anchor for one report, at /Report; names the state on the screen
VctState none What is shown, under /Report/states, as a set of optional groups
VctSlide string vct:name; attr:*; rel vct:state One slide, under /Report/slides: a name and the state it shows
VctSection string vct:name; attr:* One section, under /Report/sections
VctDeck none The hierarchy's fixed root, /Report/deck
VctDeckNode rel vct:item Places one slide or section in the deck
VctReportModel string vct:project; string vct:fingerprint One model the report uses, under /Report/models
VctVisibility none One state's assembly flags, at <state>/visibility
VctAssemblyVisibility rel vct:model; string vct:assembly; bool vct:visible; string vct:step The flag set on one assembly

The fixtures, in reading order:

Fixture Scenario Contracts it exercises
results_deck Three slides, one section The list beside the hierarchy, a slide outside the deck, a user attribute, three slides showing one state
nested_sections Sections inside sections Depth and order, an empty section, a section outside the deck, repeated names, scalar attribute types
working_views Two slides, nothing arranged An empty deck; the scopes and the deck are always present
assembly_visibility Four states over two models Sparse flags, a part shown inside a hidden assembly, one path in two models, a flag equal to the one it inherits, a state with no groups, a screen that no slide shows

Dependencies

  • usd-core 26.11 or later within the 26 series, the OpenUSD Python distribution. 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.

It does not depend on vcti-usd-schema-model.


Documentation

If you want to… Read
Get started using the package Quick Start above
Build, edit and read a report, fixture by fixture docs/patterns.md
Understand the list, the deck, the states, the layer per step and the decisions behind them docs/design.md
Navigate and understand the source docs/source-guide.md
Add a type, a property, a check, an action or a fixture docs/extending.md
See what changed CHANGELOG.md

Metadata

Release files for vcti-usd-schema-report 0.2.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-report 0.2.0
File Size Uploaded Provenance Actions
vcti_usd_schema_report-0.2.0.tar.gz 72.5 kB With provenance Details for vcti_usd_schema_report-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 116.5 kB

Release files / vcti_usd_schema_report-0.2.0.tar.gz

Download URL vcti_usd_schema_report-0.2.0.tar.gz
Size 72.5 kB
Tags Source
SHA-256 checksum
How to use checksums
2ee7d7aaf68ca067ed13620a7fd515019e2901124f40c8bac8f58a1f99e4db57
BLAKE2b-256 checksum
How to use checksums
1a8cd9b3f9165c46b47769da08baaef8b045ace5a86e934a2860b389b0878084
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_report-0.2.0-py3-none-any.whl

Download URL vcti_usd_schema_report-0.2.0-py3-none-any.whl
Size 44.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a2b09d6f4a095b21bbb33e86e1f0e969695cbe2a580128fb98f02db318d1547
BLAKE2b-256 checksum
How to use checksums
0fabe08c0648f847ae1922c0606d873cc6d75f45bc16b2e42fb34f7f2c92ddb3
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-report 0.2.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_report-0.2.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