ernie-renderer 0.2.0.dev43__tar.gz → 0.2.0.dev47__tar.gz

{ernie_renderer-0.2.0.dev43 → ernie_renderer-0.2.0.dev47}/.github/workflows/ci.yml

@@ -134,7 +134,7 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
-      - run: python -m pip install pytest
+      - run: python -m pip install pytest jsonschema
       - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: build-${{ matrix.os }}
@@ -213,8 +213,10 @@ jobs:
           path: coverage
           retention-days: 14
 
-  # The documentation, built strictly so broken links and warnings fail.
+  # The documentation, built strictly so broken links and warnings fail, with the schema reference
+  # pages and the scene files' JSON Schema generated by the Linux build.
   docs:
+    needs: build
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
@@ -222,6 +224,14 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: build-ubuntu-24.04
+      - name: Generate the schema reference
+        run: |
+          tar -xf build-ci.tar
+          build/ci/bin/ernie schema --json-schema docs/schema/ernie-scene.schema.json \
+            --markdown docs/reference
       - run: python -m pip install -r docs/requirements.txt
       - run: mkdocs build --strict
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2

{ernie_renderer-0.2.0.dev43 → ernie_renderer-0.2.0.dev47}/.gitignore

@@ -7,6 +7,9 @@ build/
 dist/
 site/
 .deps/
+# Generated by `ernie schema` before the docs build
+/docs/reference/
+/docs/schema/
 *.egg-info/
 __pycache__/
 .venv/

{ernie_renderer-0.2.0.dev43 → ernie_renderer-0.2.0.dev47}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev43" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev47" CACHE STRING "Pre-release suffix of Ernie's version")
 set(ERNIE_VERSION "${PROJECT_VERSION}${ERNIE_VERSION_SUFFIX}")
 
 option(ERNIE_BUILD_TESTS "Build Ernie's tests" OFF)

{ernie_renderer-0.2.0.dev43 → ernie_renderer-0.2.0.dev47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev43
+Version: 0.2.0.dev47
 Summary: Efficient Renderer for Natural and Interplanetary Environments: a physically based, spectral Vulkan ray tracer
 Author: Alex Maietta
 License-Expression: BSD-3-Clause

ernie_renderer-0.2.0.dev47/docs/README.md

@@ -0,0 +1,10 @@
+# Docs
+
+The schema reference pages and the scene files' JSON Schema are generated from the schema registry by a build of `ernie`, before the site is built:
+
+```sh
+ernie schema --json-schema docs/schema/ernie-scene.schema.json --markdown docs/reference
+python -m pip install -r docs/requirements.txt
+mkdocs serve # live preview at http://127.0.0.1:8000
+mkdocs build # static site in site/
+```

ernie_renderer-0.2.0.dev47/ernie/app/main.cpp

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file main.cpp
+/// @brief The ernie program.
+#include "ernie/device/vulkan_devices.h"
+#include "ernie/scene/reference.h"
+#include "ernie/util/file.h"
+#include "ernie/util/version.h"
+
+#include <cstdio>
+#include <exception>
+#include <filesystem>
+#include <string_view>
+#include <vector>
+
+namespace {
+
+namespace fs = std::filesystem;
+
+void PrintUsage() {
+    std::puts("Usage: ernie [--version] [--devices] [--help]\n"
+              "       ernie schema [--json-schema FILE] [--markdown DIR] [--usda DIR]\n"
+              "       ernie validate SCENE.json...");
+}
+
+int PrintDevices() {
+    for (const ernie::VulkanDeviceInfo& device : ernie::ListVulkanDevices()) {
+        std::printf("%s (%s, Vulkan %u.%u%s)\n", device.name.c_str(), ernie::ToString(device.type),
+                    device.apiMajor, device.apiMinor, device.rayQuery ? ", ray queries" : "");
+    }
+    return 0;
+}
+
+void Write(const fs::path& path, std::string_view text) {
+    if (path.has_parent_path()) {
+        fs::create_directories(path.parent_path());
+    }
+    ernie::WriteTextFile(path, text);
+}
+
+/// Writes the views of the schema registry that `arguments` ask for.
+int Schema(const std::vector<std::string_view>& arguments) {
+    if (arguments.empty() || arguments.size() % 2 != 0) {
+        PrintUsage();
+        return 2;
+    }
+    for (std::size_t i = 0; i < arguments.size(); i += 2) {
+        const fs::path out(arguments[i + 1]);
+        if (arguments[i] == "--json-schema") {
+            Write(out, ernie::SceneJsonSchema());
+        } else if (arguments[i] == "--markdown") {
+            for (const ernie::SchemaFamily& family : ernie::SchemaFamilies()) {
+                Write(out / (std::string(family.name) + ".md"), ernie::ReferencePage(family));
+            }
+        } else if (arguments[i] == "--usda") {
+            const ernie::UsdSchemaPlugin plugin = ernie::ErnieUsdSchemaPlugin();
+            Write(out / "generatedSchema.usda", plugin.generatedSchema);
+            Write(out / "plugInfo.json", plugin.plugInfo);
+        } else {
+            PrintUsage();
+            return 2;
+        }
+    }
+    return 0;
+}
+
+/// Prints every problem of the scene files; fails if any has one.
+int Validate(const std::vector<std::string_view>& files) {
+    if (files.empty()) {
+        PrintUsage();
+        return 2;
+    }
+    int status = 0;
+    for (const std::string_view file : files) {
+        for (const ernie::SceneProblem& problem :
+             ernie::ValidateScene(ernie::ReadTextFile(fs::path(file)))) {
+            std::printf("%.*s: %s\n", static_cast<int>(file.size()), file.data(),
+                        problem.Message().c_str());
+            status = 1;
+        }
+    }
+    return status;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    const std::string_view option = argc > 1 ? argv[1] : "--help";
+    const std::vector<std::string_view> rest(argv + std::min(argc, 2), argv + argc);
+    try {
+        if (option == "--version") {
+            std::printf("ernie %.*s\n", static_cast<int>(ernie::Version().size()),
+                        ernie::Version().data());
+            return 0;
+        }
+        if (option == "--devices") {
+            return PrintDevices();
+        }
+        if (option == "schema") {
+            return Schema(rest);
+        }
+        if (option == "validate") {
+            return Validate(rest);
+        }
+        PrintUsage();
+        return option == "--help" ? 0 : 2;
+    } catch (const std::exception& error) {
+        std::fprintf(stderr, "ernie: %s\n", error.what());
+        return 1;
+    }
+}

{ernie_renderer-0.2.0.dev43 → ernie_renderer-0.2.0.dev47}/ernie/scene/CMakeLists.txt

@@ -2,13 +2,20 @@
 add_library(
     ernie_scene
     OBJECT
+    animation.cpp
+    edit_history.cpp
     extent_cache.cpp
     holder_index.cpp
     inherit.cpp
+    json.cpp
     path.cpp
+    reference.cpp
     schema.cpp
     scene.cpp
     storage.cpp
+    time_samples.cpp
+    usd_plugin.cpp
+    validate.cpp
     view.cpp
     xform.cpp
     schemas/camera.cpp
@@ -24,4 +31,8 @@ add_library(
     schemas/shade.cpp
     schemas/vol.cpp
 )
-target_link_libraries(ernie_scene PUBLIC ernie_physics ernie_io PRIVATE ernie_build_options)
+target_link_libraries(
+    ernie_scene
+    PUBLIC ernie_physics ernie_io
+    PRIVATE ernie_json ernie_build_options
+)

ernie_renderer-0.2.0.dev47/ernie/scene/animation.cpp

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file animation.cpp
+/// @brief Time-sampled attributes: their sparse samples per prim, and the clock that evaluates
+/// them into the columns.
+#include "ernie/scene/scene.h"
+
+#include <algorithm>
+
+namespace ernie {
+
+void Scene::SetAt(PrimId prim, std::string_view attribute, double time, const Value& value) {
+    TimeSample sample{time, {}, {}};
+    Author(prim, attribute, value, &sample.value);
+    AddSample(prim, attribute, std::move(sample));
+}
+
+void Scene::WriteAt(PrimId prim, std::string_view attribute, double time, Tensor array) {
+    CheckArray(prim, attribute, array);
+    AddSample(prim, attribute, {time, {}, std::move(array)});
+}
+
+void Scene::AddSample(PrimId prim, std::string_view attribute, TimeSample sample) {
+    const AttributeId token = store_.Tokens().Intern(attribute);
+    Animated& animated = animated_[prim.slot];
+    animated.prim = prim;
+    std::vector<TimeSample>& samples = animated.samples[token];
+    // Samples are all values or all arrays: one of the other kind replaces them.
+    if (!samples.empty() && samples.front().tensor.Empty() != sample.tensor.Empty()) {
+        samples.clear();
+    }
+    const auto at = std::ranges::lower_bound(samples, sample.time, {}, &TimeSample::time);
+    if (at != samples.end() && at->time == sample.time) {
+        *at = std::move(sample);
+    } else {
+        samples.insert(at, std::move(sample));
+    }
+    Evaluate(prim, token, samples);
+}
+
+std::span<const TimeSample> Scene::Samples(PrimId prim, std::string_view attribute) const {
+    const auto animated = animated_.find(prim.slot);
+    const std::optional<Token> token = store_.Tokens().Find(attribute);
+    if (animated == animated_.end() || animated->second.prim != prim || !token) {
+        return {};
+    }
+    const auto samples = animated->second.samples.find(*token);
+    return samples == animated->second.samples.end() ? std::span<const TimeSample>()
+                                                     : std::span(samples->second);
+}
+
+std::optional<Value> Scene::GetAt(PrimId prim, std::string_view attribute, double time) const {
+    const std::span<const TimeSample> samples = Samples(prim, attribute);
+    if (samples.empty()) {
+        return Get(prim, attribute);
+    }
+    Value value = ernie::Evaluate(samples, time).value;
+    return value.Empty() ? std::nullopt : std::optional(std::move(value));
+}
+
+bool Scene::ClearSamples(PrimId prim, std::string_view attribute) {
+    const auto animated = animated_.find(prim.slot);
+    const std::optional<Token> token = store_.Tokens().Find(attribute);
+    if (animated == animated_.end() || !token || animated->second.samples.erase(*token) == 0) {
+        return false;
+    }
+    if (animated->second.samples.empty()) {
+        animated_.erase(animated);
+    }
+    return true;
+}
+
+void Scene::SetTime(double timeCode) {
+    time_ = timeCode;
+    for (const auto& [slot, animated] : animated_) {
+        for (const auto& [attribute, samples] : animated.samples) {
+            Evaluate(animated.prim, attribute, samples);
+        }
+    }
+}
+
+void Scene::Evaluate(PrimId prim, AttributeId attribute, std::span<const TimeSample> samples) {
+    const std::string_view name = store_.Tokens().Text(attribute);
+    TimeSample now = ernie::Evaluate(samples, time_);
+    if (!now.tensor.Empty()) {
+        const Tensor* current = Read(prim, name);
+        if (current == nullptr || current->Data() != now.tensor.Data()) {
+            store_.Set(prim, attribute, std::move(now.tensor));
+        }
+    } else if (Get(prim, name) != now.value) {
+        Author(prim, name, now.value);
+    }
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev47/ernie/scene/edit_history.cpp

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file edit_history.cpp
+/// @brief Recording edits as steps of before and after states, and applying them either way.
+#include "ernie/scene/edit_history.h"
+
+#include <stdexcept>
+
+namespace ernie {
+
+void EditHistory::Set(Scene& scene, const Path& path,
+                      std::vector<std::pair<std::string, Value>> edits, bool open) {
+    const PrimId prim = scene.Require(path);
+    Step step{.path = path, .open = open};
+    try {
+        for (auto& [name, value] : edits) {
+            Cell before = Capture(scene, prim, name);
+            scene.Set(prim, name, std::move(value));
+            step.attributes.push_back({name, {std::move(before), Capture(scene, prim, name)}});
+        }
+    } catch (...) {
+        // What applied before the rejected edit stays undoable.
+        if (!step.attributes.empty()) {
+            Push(std::move(step));
+        }
+        throw;
+    }
+    const auto same = [&](const Step& last) {
+        if (last.structural || !last.open || last.path != path ||
+            last.attributes.size() != step.attributes.size()) {
+            return false;
+        }
+        for (std::size_t i = 0; i < last.attributes.size(); ++i) {
+            if (last.attributes[i].first != step.attributes[i].first) {
+                return false;
+            }
+        }
+        return true;
+    };
+    if (open && open_ && next_ == steps_.size() && !steps_.empty() && same(steps_.back())) {
+        for (std::size_t i = 0; i < step.attributes.size(); ++i) {
+            steps_.back().attributes[i].second.second = std::move(step.attributes[i].second.second);
+        }
+        return;
+    }
+    Push(std::move(step));
+}
+
+void EditHistory::Clear(Scene& scene, const Path& path, std::string_view attribute) {
+    const PrimId prim = scene.Require(path);
+    const std::string name(attribute);
+    Cell before = Capture(scene, prim, name);
+    scene.Clear(prim, attribute);
+    Step step{.path = path};
+    step.attributes.push_back({name, {std::move(before), Capture(scene, prim, name)}});
+    Push(std::move(step));
+}
+
+void EditHistory::Define(Scene& scene, const Path& path, std::string_view type) {
+    if (scene.Has(path)) {
+        throw std::invalid_argument("'" + path.String() + "' has a prim already");
+    }
+    scene.Define(path, type);
+    Push({.path = path, .after = Snapshot(scene, path), .structural = true});
+}
+
+bool EditHistory::Remove(Scene& scene, const Path& path) {
+    if (!scene.Has(path)) {
+        return false;
+    }
+    Step step{.path = path, .before = Snapshot(scene, path), .structural = true};
+    scene.Remove(path);
+    Push(std::move(step));
+    return true;
+}
+
+void EditHistory::Add(Scene& scene, const Scene& source, const Path& path) {
+    if (!source.Has(path) || scene.Has(path)) {
+        throw std::invalid_argument("Cannot add '" + path.String() +
+                                    "': the source has no prim there or the scene has one");
+    }
+    Step step{.path = path, .after = Snapshot(source, path), .structural = true};
+    Restore(scene, step.after);
+    Push(std::move(step));
+}
+
+void EditHistory::BeginGroup() {
+    if (groupDepth_++ == 0) {
+        group_ = nextGroup_++;
+    }
+}
+
+void EditHistory::EndGroup() {
+    if (groupDepth_ > 0 && --groupDepth_ == 0) {
+        group_ = 0;
+    }
+}
+
+bool EditHistory::Undo(Scene& scene) {
+    return Move(scene, false);
+}
+
+bool EditHistory::Redo(Scene& scene) {
+    return Move(scene, true);
+}
+
+std::string EditHistory::UndoLabel() const {
+    return CanUndo() ? Label(steps_[next_ - 1]) : std::string();
+}
+
+std::string EditHistory::RedoLabel() const {
+    return CanRedo() ? Label(steps_[next_]) : std::string();
+}
+
+void EditHistory::Reset() {
+    *this = EditHistory();
+}
+
+EditHistory::Cell EditHistory::Capture(const Scene& scene, PrimId prim,
+                                       const std::string& attribute) {
+    Cell cell;
+    const std::span<const TimeSample> samples = scene.Samples(prim, attribute);
+    cell.samples.assign(samples.begin(), samples.end());
+    if (const Tensor* array = scene.Read(prim, attribute)) {
+        cell.array = *array;
+    } else {
+        cell.value = scene.Get(prim, attribute);
+    }
+    return cell;
+}
+
+void EditHistory::Apply(Scene& scene, PrimId prim, const std::string& attribute, const Cell& cell) {
+    if (!cell.samples.empty()) {
+        scene.ClearSamples(prim, attribute);
+        for (const TimeSample& sample : cell.samples) {
+            sample.tensor.Empty() ? scene.SetAt(prim, attribute, sample.time, sample.value)
+                                  : scene.WriteAt(prim, attribute, sample.time, sample.tensor);
+        }
+    } else if (!cell.array.Empty()) {
+        scene.Write(prim, attribute, cell.array);
+    } else if (cell.value) {
+        scene.Set(prim, attribute, *cell.value);
+    } else {
+        scene.Clear(prim, attribute);
+    }
+}
+
+std::vector<EditHistory::PrimSnapshot> EditHistory::Snapshot(const Scene& scene, const Path& path) {
+    std::vector<PrimSnapshot> prims;
+    std::vector<Path> pending{path};
+    while (!pending.empty()) {
+        const Path next = std::move(pending.back());
+        pending.pop_back();
+        const PrimId prim = scene.Require(next);
+        PrimSnapshot& snapshot = prims.emplace_back();
+        snapshot.path = next;
+        snapshot.type = std::string(scene.TypeName(prim));
+        snapshot.apis = scene.AppliedApis(prim);
+        for (const std::string& name : scene.Attributes(next)) {
+            snapshot.attributes.emplace(name, Capture(scene, prim, name));
+        }
+        const std::vector<Path> children = scene.Children(next);
+        pending.insert(pending.end(), children.rbegin(), children.rend());
+    }
+    return prims;
+}
+
+void EditHistory::Restore(Scene& scene, const std::vector<PrimSnapshot>& prims) {
+    for (const PrimSnapshot& snapshot : prims) {
+        const PrimId prim = scene.Define(snapshot.path, snapshot.type);
+        for (const std::string& api : snapshot.apis) {
+            if (!scene.HasApi(prim, api)) {
+                scene.ApplyApi(prim, api);
+            }
+        }
+        for (const auto& [name, cell] : snapshot.attributes) {
+            Apply(scene, prim, name, cell);
+        }
+    }
+}
+
+void EditHistory::Apply(Scene& scene, const Step& step, bool forward) {
+    if (step.structural) {
+        scene.Remove(step.path);
+        Restore(scene, forward ? step.after : step.before);
+        return;
+    }
+    // Edits of a prim removed since are skipped.
+    const std::optional<PrimId> prim = scene.Find(step.path);
+    if (!prim) {
+        return;
+    }
+    for (std::size_t i = 0; i < step.attributes.size(); ++i) {
+        const auto& [name, states] = step.attributes[forward ? i : step.attributes.size() - 1 - i];
+        Apply(scene, *prim, name, forward ? states.second : states.first);
+    }
+}
+
+void EditHistory::Push(Step step) {
+    steps_.resize(next_);
+    step.group = groupDepth_ > 0 ? group_ : 0;
+    open_ = step.open;
+    steps_.push_back(std::move(step));
+    next_ = steps_.size();
+}
+
+bool EditHistory::Move(Scene& scene, bool forward) {
+    open_ = false;
+    if (forward ? !CanRedo() : !CanUndo()) {
+        return false;
+    }
+    const std::uint64_t group = steps_[forward ? next_ : next_ - 1].group;
+    do {
+        if (forward) {
+            Apply(scene, steps_[next_++], true);
+        } else {
+            Apply(scene, steps_[--next_], false);
+        }
+    } while (group != 0 && (forward ? CanRedo() && steps_[next_].group == group
+                                    : CanUndo() && steps_[next_ - 1].group == group));
+    return true;
+}
+
+std::string EditHistory::Label(const Step& step) {
+    if (step.structural) {
+        return (step.before.empty()  ? "Add "
+                : step.after.empty() ? "Remove "
+                                     : "Change ") +
+               step.path.String();
+    }
+    std::string label = step.path.String();
+    for (const auto& [name, states] : step.attributes) {
+        label += " " + name;
+    }
+    return label;
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev47/ernie/scene/edit_history.h

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file edit_history.h
+/// @brief Undo and redo of scene edits, for the viewer.
+///
+/// References:
+/// - E. Gamma, R. Helm, R. Johnson and J. Vlissides, "Design Patterns", the Command pattern,
+///   Addison-Wesley, 1994.
+#pragma once
+
+#include "ernie/scene/scene.h"
+
+#include <cstddef>
+#include <cstdint>
+#include <map>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace ernie {
+
+/// @brief Undo and redo for the edits made through it: attributes set or cleared, prims defined,
+/// removed with their descendants, or copied in. Each step records what it changes, so `Undo`
+/// puts it back and `Redo` does it again.
+///
+/// Continuous edits, as dragging a slider or a gizmo, merge into one step: an `open` edit of the
+/// same attributes as the last step updates it until `Close`. Edits between `BeginGroup` and
+/// `EndGroup` undo and redo together. Edits made to the scene directly are not recorded.
+class EditHistory {
+  public:
+    /// @brief Sets attributes of a prim as one step, dropping the undone steps. With `open`, merges
+    /// into the last step if that is an open edit of the same attributes.
+    /// @throws std::invalid_argument as `Scene::Set`.
+    void Set(Scene& scene, const Path& path, std::vector<std::pair<std::string, Value>> edits,
+             bool open = false);
+    void Set(Scene& scene, const Path& path, std::string_view attribute, Value value,
+             bool open = false) {
+        Set(scene, path, {{std::string(attribute), std::move(value)}}, open);
+    }
+    /// @brief Unauthors an attribute, back to its fallback.
+    void Clear(Scene& scene, const Path& path, std::string_view attribute);
+    /// @brief Defines a new prim; undoing removes it.
+    /// @throws std::invalid_argument as `Scene::Define`, or if a prim is there already.
+    void Define(Scene& scene, const Path& path, std::string_view type);
+    /// @brief Removes a prim and its descendants; undoing restores them, sharing their arrays.
+    /// @return Whether there was a prim.
+    bool Remove(Scene& scene, const Path& path);
+    /// @brief Copies a prim of `source` and its descendants to the same path of `scene`, as for
+    /// prims authored in a scratch scene first; undoing removes them.
+    /// @throws std::invalid_argument if `source` has no prim at `path` or `scene` has one.
+    void Add(Scene& scene, const Scene& source, const Path& path);
+
+    /// Groups the edits until `EndGroup` into one step. Groups nest; the outermost counts.
+    void BeginGroup();
+    void EndGroup();
+    /// Ends the open step, so the next edit starts a new one.
+    void Close() {
+        open_ = false;
+    }
+
+    bool CanUndo() const {
+        return next_ > 0;
+    }
+    bool CanRedo() const {
+        return next_ < steps_.size();
+    }
+    /// @brief Undoes the last step or group; edits of prims removed since are skipped.
+    /// @return Whether there was one.
+    bool Undo(Scene& scene);
+    bool Redo(Scene& scene);
+    /// @return What `Undo` or `Redo` would do, as "/World/Cube xformOp:translate".
+    std::string UndoLabel() const;
+    std::string RedoLabel() const;
+    /// Forgets every step, as when the viewer switches scenes.
+    void Reset();
+    /// @return The steps recorded, a group's edits each counted.
+    std::size_t Size() const {
+        return steps_.size();
+    }
+
+  private:
+    /// One attribute's authored state: unset, a value, an array or time samples.
+    struct Cell {
+        std::optional<Value> value;
+        Tensor array;
+        std::vector<TimeSample> samples;
+    };
+    /// One prim of a subtree, enough to define it again.
+    struct PrimSnapshot {
+        Path path;
+        std::string type;
+        std::vector<std::string> apis;
+        std::map<std::string, Cell> attributes;
+    };
+    struct Step {
+        Path path;
+        /// Attribute steps: each attribute's state before and after.
+        std::vector<std::pair<std::string, std::pair<Cell, Cell>>> attributes;
+        /// Structure steps: the subtree at `path` before and after, parents first; empty for none.
+        std::vector<PrimSnapshot> before;
+        std::vector<PrimSnapshot> after;
+        bool structural = false;
+        bool open = false;
+        /// Steps of one non-zero group undo together.
+        std::uint64_t group = 0;
+    };
+
+    static Cell Capture(const Scene& scene, PrimId prim, const std::string& attribute);
+    static void Apply(Scene& scene, PrimId prim, const std::string& attribute, const Cell& cell);
+    static std::vector<PrimSnapshot> Snapshot(const Scene& scene, const Path& path);
+    static void Restore(Scene& scene, const std::vector<PrimSnapshot>& prims);
+    static void Apply(Scene& scene, const Step& step, bool forward);
+    void Push(Step step);
+    bool Move(Scene& scene, bool forward);
+    static std::string Label(const Step& step);
+
+    std::vector<Step> steps_;
+    /// Steps before it are done; from it on, undone.
+    std::size_t next_ = 0;
+    bool open_ = false;
+    int groupDepth_ = 0;
+    std::uint64_t group_ = 0;
+    std::uint64_t nextGroup_ = 1;
+};
+
+}  // namespace ernie