blendiff 0.2.0__tar.gz

blendiff-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# PyPI / Hatch
+.hatch/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Blender
+blendiff.zip
+*.blend1
+*.blend2
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/

blendiff-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishrut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blendiff-0.2.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: blendiff
+Version: 0.2.0
+Summary: Semantic diff, snapshot history, and assisted merge for Blender .blend files
+Project-URL: Homepage, https://github.com/Vishrut2403/blendiff
+Project-URL: Repository, https://github.com/Vishrut2403/blendiff
+Project-URL: Bug Tracker, https://github.com/Vishrut2403/blendiff/issues
+Author: Vishrut
+License: MIT
+License-File: LICENSE
+Keywords: 3d,addon,blender,diff,pipeline,vfx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# BlenDiff
+
+**Semantic diff, snapshot history, and assisted merge for Blender `.blend` files.**
+
+BlenDiff compares two `.blend` file states using Blender's Python API — not binary diffing — and provides a full assisted merge system. It ships as both a Blender addon and a pip-installable pure-Python library for headless/CI use.
+
+---
+
+## Features
+
+- **Snapshot history** — named, timestamped snapshots stored in a human-readable `.blendiff` JSON sidecar next to your `.blend` file
+- **Object & collection diffing** — detects added, removed, and modified objects with per-property change tracking (transform, visibility, collection membership)
+- **Material node graph diffing** — per-node, per-socket comparison including image names, input values, and rewired links
+- **Render settings diffing** — engine, resolution, sampling, output format, color management, Cycles and EEVEE sub-settings
+- **Three-way merge** — conflict detection and per-property resolution (Use A / Use B / Use Base) with a Blender UI
+- **Annotated HTML export** — self-contained dark-themed report with per-entry annotation textareas and JSON round-trip
+- **Headless CLI** — run diffs in CI without launching Blender
+
+---
+
+## Installation
+
+### As a pip library (no Blender required)
+
+```bash
+pip install blendiff
+```
+
+### As a Blender addon
+
+Download the latest `blendiff.zip` from [Releases](https://github.com/Vishrut2403/blendiff/releases) and install via **Edit → Preferences → Add-ons → Install**.
+
+---
+
+## CLI Usage
+
+```bash
+# List snapshots in a sidecar file
+blendiff list scene.blendiff
+
+# Compare two snapshots
+blendiff compare scene.blendiff "Before rigging" "After rigging"
+
+# Fail CI if any changes exist
+blendiff latest scene.blendiff --fail-on-changes
+
+# Export an HTML report
+blendiff compare scene.blendiff "v1" "v2" --output report.html
+```
+
+---
+
+## Python API
+
+```python
+from blendiff.storage.sidecar import SidecarManager
+from blendiff.diff_engine.diff_engine import DiffEngine
+
+mgr = SidecarManager("scene.blendiff")
+snaps = {s.label: s for s in mgr.list_snapshots()}
+
+engine = DiffEngine()
+result = engine.compare(snaps["v1"].data, snaps["v2"].data)
+
+# Render settings diff
+print(result.render_diff.summary())
+
+# Object diffs
+for diff in result.object_diffs:
+    print(diff.name, diff.kind)
+    for change in diff.changes:
+        print(" ", change.property_path, change.old_value, "→", change.new_value)
+```
+
+---
+
+## Architecture
+
+```
+blendiff/
+├── data_model/      # Dataclasses — SceneDiff, RenderDiff, MergeProposal, …
+├── diff_engine/     # Pure comparison logic — no bpy
+├── serializer/      # mathutils → JSON-safe types
+├── storage/         # .blendiff sidecar CRUD
+├── export/          # Self-contained HTML report generation
+├── cli/             # Headless CLI + importable Python API
+├── extractor/       # bpy readers (Blender-only)
+└── ui/              # Blender panels and operators (Blender-only)
+```
+
+The extractor is the **only** bpy-touching module. Everything downstream is pure Python and fully testable without Blender.
+
+---
+
+## Running Tests
+
+```bash
+pip install blendiff[dev]
+pytest tests/ -v
+```
+
+224+ tests, all passing without a Blender installation.
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/diff.yml
+- name: Check for scene changes
+  run: blendiff latest scene.blendiff --fail-on-changes
+```
+
+See `docs/ci_example.yml` for a full GitHub Actions workflow template.
+
+---
+
+## License
+
+MIT

blendiff-0.2.0/README.md

@@ -0,0 +1,120 @@
+# BlenDiff
+
+**Semantic diff, snapshot history, and assisted merge for Blender `.blend` files.**
+
+BlenDiff compares two `.blend` file states using Blender's Python API — not binary diffing — and provides a full assisted merge system. It ships as both a Blender addon and a pip-installable pure-Python library for headless/CI use.
+
+---
+
+## Features
+
+- **Snapshot history** — named, timestamped snapshots stored in a human-readable `.blendiff` JSON sidecar next to your `.blend` file
+- **Object & collection diffing** — detects added, removed, and modified objects with per-property change tracking (transform, visibility, collection membership)
+- **Material node graph diffing** — per-node, per-socket comparison including image names, input values, and rewired links
+- **Render settings diffing** — engine, resolution, sampling, output format, color management, Cycles and EEVEE sub-settings
+- **Three-way merge** — conflict detection and per-property resolution (Use A / Use B / Use Base) with a Blender UI
+- **Annotated HTML export** — self-contained dark-themed report with per-entry annotation textareas and JSON round-trip
+- **Headless CLI** — run diffs in CI without launching Blender
+
+---
+
+## Installation
+
+### As a pip library (no Blender required)
+
+```bash
+pip install blendiff
+```
+
+### As a Blender addon
+
+Download the latest `blendiff.zip` from [Releases](https://github.com/Vishrut2403/blendiff/releases) and install via **Edit → Preferences → Add-ons → Install**.
+
+---
+
+## CLI Usage
+
+```bash
+# List snapshots in a sidecar file
+blendiff list scene.blendiff
+
+# Compare two snapshots
+blendiff compare scene.blendiff "Before rigging" "After rigging"
+
+# Fail CI if any changes exist
+blendiff latest scene.blendiff --fail-on-changes
+
+# Export an HTML report
+blendiff compare scene.blendiff "v1" "v2" --output report.html
+```
+
+---
+
+## Python API
+
+```python
+from blendiff.storage.sidecar import SidecarManager
+from blendiff.diff_engine.diff_engine import DiffEngine
+
+mgr = SidecarManager("scene.blendiff")
+snaps = {s.label: s for s in mgr.list_snapshots()}
+
+engine = DiffEngine()
+result = engine.compare(snaps["v1"].data, snaps["v2"].data)
+
+# Render settings diff
+print(result.render_diff.summary())
+
+# Object diffs
+for diff in result.object_diffs:
+    print(diff.name, diff.kind)
+    for change in diff.changes:
+        print(" ", change.property_path, change.old_value, "→", change.new_value)
+```
+
+---
+
+## Architecture
+
+```
+blendiff/
+├── data_model/      # Dataclasses — SceneDiff, RenderDiff, MergeProposal, …
+├── diff_engine/     # Pure comparison logic — no bpy
+├── serializer/      # mathutils → JSON-safe types
+├── storage/         # .blendiff sidecar CRUD
+├── export/          # Self-contained HTML report generation
+├── cli/             # Headless CLI + importable Python API
+├── extractor/       # bpy readers (Blender-only)
+└── ui/              # Blender panels and operators (Blender-only)
+```
+
+The extractor is the **only** bpy-touching module. Everything downstream is pure Python and fully testable without Blender.
+
+---
+
+## Running Tests
+
+```bash
+pip install blendiff[dev]
+pytest tests/ -v
+```
+
+224+ tests, all passing without a Blender installation.
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/diff.yml
+- name: Check for scene changes
+  run: blendiff latest scene.blendiff --fail-on-changes
+```
+
+See `docs/ci_example.yml` for a full GitHub Actions workflow template.
+
+---
+
+## License
+
+MIT

blendiff-0.2.0/blendiff/__init__.py

@@ -0,0 +1,40 @@
+"""
+BlenDiff — semantic diff, snapshot history, and assisted merge for .blend files.
+
+When imported outside Blender (e.g. via pip), only the pure-Python core is
+available: data_model, diff_engine, serializer, storage, export, cli.
+
+When imported inside Blender, the full addon registers its UI panels and
+operators on top of the core.
+"""
+
+__version__ = "0.2.0"
+
+bl_info = {
+	"name":        "BlenDiff",
+	"author":      "Vishrut",
+	"version":     (0, 2, 0),
+	"blender":     (3, 6, 0),
+	"location":    "3D Viewport > Sidebar > BlenDiff",
+	"description": "Semantic scene diff, snapshot history, and assisted merge for .blend files",
+	"category":    "Scene",
+}
+
+try:
+	import bpy
+	_IN_BLENDER = True
+except ModuleNotFoundError:
+	_IN_BLENDER = False
+
+if _IN_BLENDER:
+	from .ui import panels, operators, merge_panel
+
+	def register() -> None:
+		operators.register()
+		panels.register()
+		merge_panel.register()
+
+	def unregister() -> None:
+		merge_panel.unregister()
+		panels.unregister()
+		operators.unregister()

blendiff-0.2.0/blendiff/cli/__init__.py

@@ -0,0 +1,6 @@
+from .api import (
+	list_snapshots,
+	compare_snapshots,
+	compare_snapshots_by_label,
+	compare_latest_two,
+)

blendiff-0.2.0/blendiff/cli/__main__.py

@@ -0,0 +1,214 @@
+"""
+blendiff.cli.__main__
+~~~~~~~~~~~~~~~~~~~~~~
+Entry point for:  python -m blendiff.cli <command> [args]
+
+Commands
+--------
+  list     <sidecar>                        List all snapshots in a sidecar
+  compare  <sidecar> <label_a> <label_b>   Diff two snapshots by label
+  latest   <sidecar>                        Diff the two most recent snapshots
+
+Global flags
+------------
+  --output <path>      Write HTML report to this path (default: print JSON)
+  --json               Print result as JSON to stdout
+  --fail-on-changes    Exit with code 1 if any changes detected (for CI gates)
+  --quiet              Suppress all output except errors
+
+Exit codes
+----------
+  0  — success, no changes (or changes detected but --fail-on-changes not set)
+  1  — changes detected and --fail-on-changes is set
+  2  — error (file not found, snapshot not found, parse failure, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def _build_parser() -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser(
+		prog="python -m blendiff.cli",
+		description="BlenDiff headless CLI — diff Blender scene snapshots without opening Blender.",
+	)
+
+	sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+	sub.required = True
+
+	# ── list ──────────────────────────────────────────────────────────────
+	p_list = sub.add_parser("list", help="List all snapshots in a .blendiff sidecar")
+	p_list.add_argument("sidecar", help="Path to the .blendiff file")
+	p_list.add_argument("--json", dest="as_json", action="store_true",
+						help="Output as JSON")
+
+	# ── compare ───────────────────────────────────────────────────────────
+	p_compare = sub.add_parser(
+		"compare",
+		help="Diff two snapshots by label (most recent match used if duplicates exist)",
+	)
+	p_compare.add_argument("sidecar", help="Path to the .blendiff file")
+	p_compare.add_argument("label_a", help="Label of the base snapshot (before)")
+	p_compare.add_argument("label_b", help="Label of the target snapshot (after)")
+	p_compare.add_argument("--output", metavar="PATH",
+						   help="Write HTML report to this path")
+	p_compare.add_argument("--json", dest="as_json", action="store_true",
+						   help="Print result as JSON to stdout")
+	p_compare.add_argument("--fail-on-changes", action="store_true",
+						   help="Exit with code 1 if changes are detected")
+	p_compare.add_argument("--quiet", action="store_true",
+						   help="Suppress output except errors")
+
+	# ── latest ────────────────────────────────────────────────────────────
+	p_latest = sub.add_parser(
+		"latest",
+		help="Diff the two most recent snapshots",
+	)
+	p_latest.add_argument("sidecar", help="Path to the .blendiff file")
+	p_latest.add_argument("--output", metavar="PATH",
+						  help="Write HTML report to this path")
+	p_latest.add_argument("--json", dest="as_json", action="store_true",
+						  help="Print result as JSON to stdout")
+	p_latest.add_argument("--fail-on-changes", action="store_true",
+						  help="Exit with code 1 if changes are detected")
+	p_latest.add_argument("--quiet", action="store_true",
+						  help="Suppress output except errors")
+
+	return parser
+
+
+def _cmd_list(args) -> int:
+	from .api import list_snapshots
+
+	try:
+		snapshots = list_snapshots(args.sidecar)
+	except FileNotFoundError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+
+	if args.as_json:
+		print(json.dumps(snapshots, indent=2))
+		return 0
+
+	if not snapshots:
+		print("No snapshots found.")
+		return 0
+
+	print(f"{'#':<4} {'Label':<30} {'Timestamp':<22} {'ID'}")
+	print("-" * 80)
+	for i, s in enumerate(snapshots, 1):
+		print(f"{i:<4} {s['label']:<30} {s['timestamp_display']:<22} {s['id'][:8]}")
+
+	return 0
+
+
+def _cmd_compare(args, use_latest: bool = False) -> int:
+	from .api import compare_snapshots_by_label, compare_latest_two
+	from ..export.html_exporter import export_to_file, build_output_path
+
+	quiet = getattr(args, "quiet", False)
+
+	try:
+		if use_latest:
+			result = compare_latest_two(args.sidecar)
+		else:
+			result = compare_snapshots_by_label(
+				args.sidecar, args.label_a, args.label_b
+			)
+	except FileNotFoundError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+	except ValueError as e:
+		print(f"Error: {e}", file=sys.stderr)
+		return 2
+
+	# JSON output
+	if getattr(args, "as_json", False):
+		print(json.dumps(result, indent=2, default=str))
+
+	# HTML output
+	elif getattr(args, "output", None):
+		output_path = args.output
+		snapshot_label = (
+			f"{result['snapshot_a']['label']} → {result['snapshot_b']['label']}"
+		)
+		export_to_file(
+			result=result,
+			snapshot_label=snapshot_label,
+			blend_filepath=args.sidecar,
+			output_path=output_path,
+		)
+		if not quiet:
+			print(f"HTML report written to: {output_path}")
+
+	# Default: human-readable summary
+	else:
+		if not quiet:
+			snap_a = result["snapshot_a"]
+			snap_b = result["snapshot_b"]
+			print(f"\nBlenDiff — comparing snapshots")
+			print(f"  Before : '{snap_a['label']}' ({snap_a['timestamp']})")
+			print(f"  After  : '{snap_b['label']}' ({snap_b['timestamp']})")
+			print(f"\n  {result['summary']}\n")
+
+			added = result["added_objects"]
+			removed = result["removed_objects"]
+			modified = result["modified_objects"]
+			col_diffs = result["collection_diffs"]
+
+			if added:
+				print(f"  Added objects ({len(added)}):")
+				for name in added:
+					print(f"    + {name}")
+
+			if removed:
+				print(f"  Removed objects ({len(removed)}):")
+				for name in removed:
+					print(f"    - {name}")
+
+			if modified:
+				print(f"  Modified objects ({len(modified)}):")
+				for obj in modified:
+					print(f"    ~ {obj['name']}")
+					for c in obj["changes"]:
+						print(f"        {c['property_path']}")
+						print(f"          {c['old_value']}  →  {c['new_value']}")
+
+			if col_diffs:
+				print(f"  Collection changes ({len(col_diffs)}):")
+				for cd in col_diffs:
+					print(f"    {cd['kind'].capitalize()}: {cd['path']}")
+
+			if not result["has_changes"]:
+				print("  No changes detected.")
+
+			print()
+
+	# Exit code
+	if getattr(args, "fail_on_changes", False) and result["has_changes"]:
+		return 1
+
+	return 0
+
+
+def main(argv=None) -> int:
+	parser = _build_parser()
+	args = parser.parse_args(argv)
+
+	if args.command == "list":
+		return _cmd_list(args)
+	elif args.command == "compare":
+		return _cmd_compare(args, use_latest=False)
+	elif args.command == "latest":
+		return _cmd_compare(args, use_latest=True)
+
+	parser.print_help()
+	return 2
+
+
+if __name__ == "__main__":
+	sys.exit(main())