animora-backend / scene_diff.py
eatanimora's picture
Deploy Animora backend
396ddfa verified
Raw History Blame Contribute Delete
6.23 kB
"""
Scene-graph diff.
Computes a compact, human-readable + machine-readable diff between two
scene-graph snapshots. The diff goes into the LLM context so the model can
react to what just changed instead of re-reading a 50-object graph every
turn.
Two outputs:
diff_text(prev, curr) -> str
Short, prose-style summary suitable for inlining into a system or
user message. ~5–30 lines for typical edits. Truncated at 2 KB.
diff_json(prev, curr) -> dict
Structured per-field changes. Use when downstream consumers need to
reason programmatically (e.g. quality enforcer deciding which checks
apply, telemetry tagging "modifier_added" events).
Design notes:
- Scene graphs are unordered lists of objects keyed by name. We treat the
name as identity. Renames look like (deleted name=A) + (added name=B);
detecting renames properly requires tracking object pointers across
snapshots — deferred until pointer tracking is added to the addon-side
serializer in Phase 3.
- Floating-point compares use a tolerance (1e-5) so jittery snapshots from
Blender's gizmo handler don't flag "modified" every frame.
- The text form is bounded; if too many objects changed (>15) we summarize
("23 objects modified") instead of listing each.
"""
from __future__ import annotations
from typing import Any
_FLOAT_TOL = 1e-5
_MAX_LISTED_CHANGES = 15
_MAX_TEXT_LEN = 2048
def _index_by_name(objs: list[dict]) -> dict[str, dict]:
return {o.get("name", ""): o for o in objs if o.get("name")}
def _floats_changed(a: list | tuple, b: list | tuple) -> bool:
if len(a) != len(b):
return True
return any(abs(float(x) - float(y)) > _FLOAT_TOL for x, y in zip(a, b))
def _object_field_diffs(prev: dict, curr: dict) -> dict[str, Any]:
"""Return the subset of fields that differ between two object dicts."""
diffs: dict[str, Any] = {}
for field in ("type", "visible", "selected"):
if prev.get(field) != curr.get(field):
diffs[field] = {"from": prev.get(field), "to": curr.get(field)}
for field in ("location", "rotation", "scale"):
a, b = prev.get(field) or [], curr.get(field) or []
if _floats_changed(a, b):
diffs[field] = {"from": list(a), "to": list(b)}
pm, cm = prev.get("modifiers", []), curr.get("modifiers", [])
if pm != cm:
diffs["modifiers"] = {"from": pm, "to": cm}
pmat, cmat = prev.get("materials", []), curr.get("materials", [])
if pmat != cmat:
diffs["materials"] = {"from": pmat, "to": cmat}
return diffs
def diff_json(prev: dict[str, Any] | None, curr: dict[str, Any]) -> dict[str, Any]:
"""Structured diff. Always returns the same shape regardless of input."""
result: dict[str, Any] = {
"added": [],
"removed": [],
"modified": [],
"scene": {},
"mode_changed": False,
"frame_changed": False,
"active_object_changed": False,
}
if prev is None:
result["added"] = [o.get("name", "?") for o in curr.get("objects", [])]
result["scene"] = {"name": curr.get("scene_name", "")}
return result
prev_idx = _index_by_name(prev.get("objects", []))
curr_idx = _index_by_name(curr.get("objects", []))
prev_names = set(prev_idx.keys())
curr_names = set(curr_idx.keys())
result["added"] = sorted(curr_names - prev_names)
result["removed"] = sorted(prev_names - curr_names)
for name in sorted(prev_names & curr_names):
diffs = _object_field_diffs(prev_idx[name], curr_idx[name])
if diffs:
result["modified"].append({"name": name, "changes": diffs})
if prev.get("mode") != curr.get("mode"):
result["mode_changed"] = True
result["mode"] = {"from": prev.get("mode"), "to": curr.get("mode")}
if prev.get("frame_current") != curr.get("frame_current"):
result["frame_changed"] = True
result["frame"] = {"from": prev.get("frame_current"), "to": curr.get("frame_current")}
if prev.get("active_object") != curr.get("active_object"):
result["active_object_changed"] = True
result["active_object"] = {"from": prev.get("active_object"), "to": curr.get("active_object")}
return result
def diff_text(prev: dict[str, Any] | None, curr: dict[str, Any]) -> str:
"""Prose-style diff, capped at ~2 KB for LLM context."""
j = diff_json(prev, curr)
lines: list[str] = []
if prev is None:
lines.append(f"Initial snapshot of scene '{j['scene'].get('name', '?')}' with {len(j['added'])} object(s).")
if j["added"]:
lines.append(" Objects: " + ", ".join(j["added"][:_MAX_LISTED_CHANGES]))
if len(j["added"]) > _MAX_LISTED_CHANGES:
lines.append(f" …and {len(j['added']) - _MAX_LISTED_CHANGES} more.")
return "\n".join(lines)[:_MAX_TEXT_LEN]
if j["added"]:
if len(j["added"]) <= _MAX_LISTED_CHANGES:
lines.append(f"Added: {', '.join(j['added'])}")
else:
lines.append(f"Added {len(j['added'])} objects (e.g. {', '.join(j['added'][:5])}…)")
if j["removed"]:
if len(j["removed"]) <= _MAX_LISTED_CHANGES:
lines.append(f"Removed: {', '.join(j['removed'])}")
else:
lines.append(f"Removed {len(j['removed'])} objects (e.g. {', '.join(j['removed'][:5])}…)")
mods = j["modified"]
if mods:
if len(mods) > _MAX_LISTED_CHANGES:
lines.append(f"Modified {len(mods)} objects (showing first {_MAX_LISTED_CHANGES}):")
mods = mods[:_MAX_LISTED_CHANGES]
for entry in mods:
change_names = sorted(entry["changes"].keys())
lines.append(f" {entry['name']}: {', '.join(change_names)}")
if j["mode_changed"]:
lines.append(f"Mode changed: {j['mode']['from']} → {j['mode']['to']}")
if j["frame_changed"]:
lines.append(f"Frame changed: {j['frame']['from']} → {j['frame']['to']}")
if j["active_object_changed"]:
lines.append(f"Active object: {j['active_object']['from']} → {j['active_object']['to']}")
if not lines:
return "No changes since last snapshot."
return ("\n".join(lines))[:_MAX_TEXT_LEN]