Metadata-Version: 2.4
Name: vcti-usd-schema-report
Version: 0.2.0
Summary: 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
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-usd-schema-report
Project-URL: Changelog, https://github.com/vcollab/vcti-python-usd-schema-report/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 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

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

### In `requirements.txt`

```
vcti-usd-schema-report>=0.1.0
```

### In `pyproject.toml` dependencies

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

---

## Quick Start

### Validate a stage

```python
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

```python
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.

```python
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`.

```python
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.

```python
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

```bash
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](docs/patterns.md) |
| Understand the list, the deck, the states, the layer per step and the decisions behind them | [docs/design.md](docs/design.md) |
| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
| Add a type, a property, a check, an action or a fixture | [docs/extending.md](docs/extending.md) |
| See what changed | [CHANGELOG.md](CHANGELOG.md) |
