mirror of https://github.com/lighttransport/tinyusdz.git synced 2026-01-18 01:11:17 +01:00

Files

Syoyo Fujita f85b4664d3 Implement USD Layer diff functionality and usddiff command-line tool

## Features Added

### Core diff-and-compare implementation:
- Complete rewrite of src/tydra/diff-and-compare.cc with full diff algorithm
- Hierarchical PrimSpec comparison (added/deleted/modified primitives)
- Property comparison for attributes and relationships
- Recursive traversal with depth limits for security
- Memory-safe implementation using standard containers

### Text and JSON output formats:
- DiffToText(): Unix diff-style output with +/- symbols
- DiffToJSON(): Structured JSON format for programmatic use
- Proper JSON escaping and formatting
- Sorted output for consistent results

### usddiff command-line tool:
- Full-featured CLI application in examples/usddiff/
- Support for --json and --help options
- USD file loading with error handling
- Support for all USD formats (.usd, .usda, .usdc, .usdz)
- Comprehensive documentation and usage examples

## Implementation Details

- Path-based diff organization using USD scene graph paths
- Efficient O(n log n) sorting for consistent output
- Configurable depth limits (default: 1M levels) for security
- Proper error handling and input validation
- CMake integration with TinyUSDZ build system

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-21 03:21:43 +09:00

3.4 KiB

Raw Permalink Blame History

usddiff - USD Layer Diff Tool

A command-line tool for computing and displaying differences between USD (Universal Scene Description) files.

Description

usddiff compares two USD files and reports differences in their structure, including:

Added, deleted, and modified primitive specifications (PrimSpecs)
Changes in primitive properties (attributes and relationships)
Hierarchical differences in the USD scene graph

The tool supports both human-readable text output (similar to Unix diff) and structured JSON output for programmatic use.

Usage

# Basic text diff
usddiff file1.usd file2.usd

# JSON output
usddiff --json scene1.usda scene2.usda

# Show help
usddiff --help

Command Line Options

--json - Output differences in JSON format instead of text
--help, -h - Display help information

Supported File Formats

.usd - USD (any format)
.usda - USD ASCII format
.usdc - USD Crate (binary) format
.usdz - USD ZIP archive format

Output Formats

Text Output (Default)

Similar to Unix diff command with USD-specific annotations:

--- old_scene.usd
+++ new_scene.usd
- /RootPrim/DeletedChild (PrimSpec deleted)
+ /RootPrim/NewChild (PrimSpec added)
~ /RootPrim/ModifiedChild (PrimSpec modified)
- /RootPrim/SomePrim.deletedAttribute (Property deleted)
+ /RootPrim/SomePrim.newAttribute (Property added)
~ /RootPrim/SomePrim.modifiedAttribute (Property modified)

JSON Output

Structured format suitable for programmatic processing:

{
  "comparison": {
    "left": "old_scene.usd",
    "right": "new_scene.usd"
  },
  "primspec_diffs": {
    "/RootPrim": {
      "added": ["NewChild"],
      "deleted": ["DeletedChild"],
      "modified": ["ModifiedChild"]
    }
  },
  "property_diffs": {
    "/RootPrim/SomePrim": {
      "added": ["newAttribute"],
      "deleted": ["deletedAttribute"],
      "modified": ["modifiedAttribute"]
    }
  }
}

Examples

Compare Two Scene Files

usddiff models/scene_v1.usd models/scene_v2.usd

Export Differences as JSON

usddiff --json old_model.usda new_model.usda > changes.json

Using with Kitchen Set Example

# Compare different Kitchen Set configurations
usddiff models/Kitchen_set/Kitchen_set.usd models/Kitchen_set/Kitchen_set_instanced.usd

Building

The usddiff tool is built automatically when examples are enabled:

mkdir build && cd build
cmake -DTINYUSDZ_BUILD_EXAMPLES=ON ..
make usddiff

The executable will be created in build/examples/usddiff/usddiff.

Implementation Details

Uses TinyUSDZ's Layer abstraction for efficient USD file processing
Implements recursive diff algorithm with configurable depth limits
Memory-safe implementation with proper error handling
Supports all USD file formats through TinyUSDZ's unified loader

Limitations

Currently compares USD structure at the Layer level
Property value comparison is basic (presence/absence, not deep value diff)
Does not perform composition-aware diffing (compares pre-composition layers)

Future Enhancements

Deep value comparison for properties
Composition-aware diffing
Visual diff output (HTML format)
Performance optimization for large scene graphs
Selective diffing (specific paths or property types)

3.4 KiB Raw Permalink Blame History