Metadata-Version: 2.4
Name: vcti-usd-schema-report
Version: 0.1.0
Summary: Codeless OpenUSD schema for the VCollab report model, the slides of a report 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 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 and the deck.

The stage keeps two 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. Renaming, reordering or moving an item
touches its name or the nodes, never its path. A slide the deck does not
reach is a view kept while working.

This package ships that schema as a codeless USD plugin, the declarations
it is generated from, three fixture reports that each exercise one group of
contracts, authoring helpers that make the changes the viewer protocol's
deck actions call for, and the validator a server-built stage must pass
unchanged. It is a sibling of `vcti-usd-schema-delivery`, which describes a
model. The schema is a candidate, and a slide's content, the capture of the
screen, is not designed yet: a slide today is a name and the user's
attributes.

## 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 delivery 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 anything they create, because allocating
it is the server's rule, and return the item's path, its identity from then
on.

```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()
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))  # []
```

### 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(path)` | A stage holding an empty report |
| `add_slide`, `add_section`, `duplicate_slide`, `duplicate_section` | New items, optionally placed in the deck |
| `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 |
| `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 three 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` | Anchor for one report, at `/Report` |
| `VctSlide` | `string vct:name`; `attr:*` | One slide, under `/Report/slides` |
| `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 |

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

---

## 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-delivery`.

---

## 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 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) |
