openusd 1.0.0

data/lib/openusd/layer.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # A single authored USD layer.
+  class Layer
+    attr_reader :identifier, :root_prims, :metadata
+
+    class << self
+      # Create an empty layer.
+      # @return [Layer]
+      def create(identifier)
+        new(identifier)
+      end
+
+      # Open a USDA, USD, or USDZ layer.
+      # @return [Layer]
+      def open(path)
+        if path.to_s.match?(/\.usdz\[[^\]]+\]\z/i)
+          require_relative "format/usdz/reader"
+          return Format::Usdz::Reader.read_uri(path.to_s)
+        end
+
+        expanded = File.expand_path(path)
+        Format::Registry.reader_for(expanded).read(expanded)
+      rescue Errno::ENOENT
+        raise CompositionError, "layer not found: #{expanded}"
+      end
+    end
+
+    def initialize(identifier = nil, metadata: {}, root_prims: [])
+      @identifier = identifier&.to_s
+      @metadata = metadata.dup
+      @root_prims = []
+      @root_prim_index = {}
+      root_prims.each { |prim| add_root_prim(prim) }
+    end
+
+    def identifier=(value)
+      @identifier = value&.to_s
+    end
+
+    def add_root_prim(prim)
+      raise OpenUSD::TypeError, "root prim must be a PrimSpec" unless prim.is_a?(PrimSpec)
+      raise PathError, "duplicate root prim: #{prim.name}" if @root_prim_index.key?(prim.name)
+
+      prim.parent = nil
+      root_prims << prim
+      @root_prim_index[prim.name] = prim
+      prim
+    end
+
+    # Remove and return a root prim by name.
+    # @return [PrimSpec, nil]
+    def remove_root_prim(name)
+      prim = root_prim_named(name)
+      root_prims.delete(prim)
+      @root_prim_index.delete(name.to_s)
+      prim
+    end
+
+    # @return [PrimSpec, nil] root prim with the requested name
+    def root_prim_named(name)
+      @root_prim_index[name.to_s]
+    end
+
+    def prim_at(path)
+      parsed = Path.parse(path)
+      raise PathError, "prim path required" if parsed.property?
+      return nil unless parsed.absolute?
+      return nil if parsed.to_s == "/"
+
+      names = parsed.to_s.delete_prefix("/").split("/")
+      names.drop(1).reduce(root_prim_named(names.first)) { |prim, name| prim&.child_named(name) }
+    end
+
+    # Traverse authored specs depth-first.
+    # @return [Enumerator, Layer]
+    def each_prim(&block)
+      return enum_for(__method__) unless block
+
+      root_prims.each do |prim|
+        yield prim
+        prim.each_descendant(&block)
+      end
+    end
+
+    # @return [Array<String>] authored sublayer asset paths
+    def sub_layer_paths
+      value = metadata["subLayers"]
+      value = value.value if value.is_a?(ListOp)
+      Array(value).map { |path| path.is_a?(AssetPath) ? path.path : path.to_s }
+    end
+
+    # @return [PrimSpec, nil] authored default prim
+    def default_prim
+      name = metadata["defaultPrim"]
+      name = name.to_s if name
+      root_prim_named(name)
+    end
+
+    def save
+      raise Error, "in-memory layer has no identifier" unless identifier
+
+      export(identifier)
+    end
+
+    # Export using the format selected by the destination extension.
+    # @return [Layer]
+    def export(path)
+      Format::Registry.writer_for(path).write(self, path)
+      self
+    end
+
+    # @return [String] deterministic USDA representation
+    def to_usda
+      require_relative "format/usda/writer"
+      Format::Usda::Writer.new.write_to_string(self)
+    end
+
+    # Compare authored semantic content, ignoring identifiers.
+    def ==(other)
+      other.is_a?(self.class) && metadata == other.metadata &&
+        root_prims.map(&:to_h) == other.root_prims.map(&:to_h)
+    end
+  end
+end

data/lib/openusd/metadata_view.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Hash-compatible composed metadata that authors mutations through a callback.
+  class MetadataView < Hash
+    def initialize(values, writer:)
+      super()
+      values.each { |key, value| store(key.to_s, value) }
+      @writer = writer
+    end
+
+    # Author a metadata value through the owning view.
+    def []=(key, value)
+      normalized = key.to_s
+      @writer.call(:set, normalized, value)
+      store(normalized, value)
+    end
+
+    # Delete an authored metadata value.
+    def delete(key)
+      normalized = key.to_s
+      @writer.call(:delete, normalized, nil)
+      super(normalized)
+    end
+  end
+end

data/lib/openusd/path.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Immutable SdfPath-like value object for prim and property paths.
+  class Path
+    include Comparable
+
+    # Reusable USD identifier fragment.
+    IDENTIFIER = /[\p{L}_][\p{L}\p{N}_]*/u
+    # Validation expression for prim names.
+    PRIM_NAME = /\A#{IDENTIFIER}\z/u
+    # Validation expression for namespaced property names.
+    PROPERTY_NAME = /\A#{IDENTIFIER}(?::#{IDENTIFIER})*\z/u
+
+    attr_reader :property_name
+
+    class << self
+      # Parse a path string.
+      # @param value [String, Path]
+      # @return [Path]
+      # @raise [PathError] if the path is malformed
+      def parse(value)
+        return value if value.is_a?(self)
+
+        new(String(value))
+      rescue ArgumentError, TypeError
+        raise PathError, "path must be a string or Path"
+      end
+    end
+
+    def initialize(value)
+      @value = value.dup.freeze
+      @property_name = split_property
+      validate!
+      freeze
+    end
+
+    # Whether this path begins at the pseudo-root.
+    def absolute?
+      @value.start_with?("/")
+    end
+
+    # Whether this identifies a property rather than a prim.
+    def property?
+      !property_name.nil?
+    end
+
+    # Return the prim portion of this path.
+    # @return [Path]
+    def prim_path
+      return self unless property?
+
+      self.class.parse(@value.delete_suffix(".#{property_name}"))
+    end
+
+    # Return the namespace parent, or nil when no parent exists.
+    # @return [Path, nil]
+    def parent
+      return prim_path if property?
+      return nil if @value == "/"
+
+      separator = @value.rindex("/")
+      return nil unless separator
+      return self.class.parse("/") if separator.zero?
+
+      self.class.parse(@value[0...separator])
+    end
+
+    # Append a child prim name.
+    # @param name [String]
+    # @return [Path]
+    def child(name)
+      raise PathError, "a property path cannot have prim children" if property?
+
+      child_name = String(name)
+      raise PathError, "invalid prim name: #{child_name.inspect}" unless PRIM_NAME.match?(child_name)
+
+      separator = @value == "/" ? "" : "/"
+      self.class.parse("#{@value}#{separator}#{child_name}")
+    rescue ArgumentError, TypeError
+      raise PathError, "child name must be a string"
+    end
+
+    # Append a property name.
+    # @param name [String]
+    # @return [Path]
+    def property(name)
+      raise PathError, "a property path cannot have another property" if property?
+
+      property = String(name)
+      raise PathError, "invalid property name: #{property.inspect}" unless PROPERTY_NAME.match?(property)
+
+      self.class.parse("#{@value}.#{property}")
+    rescue ArgumentError, TypeError
+      raise PathError, "property name must be a string"
+    end
+
+    # Compare paths by their canonical string form.
+    def <=>(other)
+      @value <=> self.class.parse(other).to_s
+    rescue PathError
+      nil
+    end
+
+    def eql?(other)
+      other.is_a?(self.class) && @value == other.to_s
+    end
+    alias == eql?
+
+    # @return [Integer] value hash compatible with {#eql?}
+    def hash
+      @value.hash
+    end
+
+    # @return [String] canonical path text
+    def to_s
+      @value
+    end
+
+    # @return [String] developer representation
+    def inspect
+      "#<#{self.class} #{@value.inspect}>"
+    end
+
+    private
+
+    def split_property
+      index = @value.index(".")
+      return unless index
+
+      @value[(index + 1)..]
+    end
+
+    def validate!
+      raise PathError, "path cannot be empty" if @value.empty?
+      return if @value == "/"
+
+      validate_prim_path!
+      return unless property?
+      raise PathError, "property path requires a prim" if raw_prim_path.empty?
+      raise PathError, "invalid property name: #{property_name.inspect}" unless PROPERTY_NAME.match?(property_name)
+    end
+
+    def validate_prim_path!
+      prim = raw_prim_path
+      raise PathError, "path cannot end with /" if prim.end_with?("/")
+      raise PathError, "path cannot contain an empty component" if prim.include?("//")
+
+      components = prim.delete_prefix("/").split("/")
+      invalid = components.find { |part| !PRIM_NAME.match?(part) }
+      raise PathError, "invalid prim name: #{invalid.inspect}" if invalid
+    end
+
+    def raw_prim_path
+      property? ? @value[0...@value.index(".")] : @value
+    end
+  end
+end

data/lib/openusd/prim.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Composed prim view on a Stage.
+  class Prim
+    attr_reader :stage, :path
+
+    def initialize(stage, path)
+      @stage = stage
+      @path = Path.parse(path)
+    end
+
+    # @return [String] final path component
+    def name
+      path.to_s.split("/").last
+    end
+
+    # @return [String, nil] strongest authored type name
+    def type_name
+      opinions.filter_map(&:type_name).find { |value| !value.empty? }
+    end
+
+    # Author a type name in the edit target.
+    def type_name=(value)
+      stage.set_prim_type(path, value)
+    end
+
+    # @return [Prim, PseudoRoot, nil] composed namespace parent
+    def parent
+      parent_path = path.parent
+      return stage.pseudo_root if parent_path&.to_s == "/"
+      return unless parent_path
+
+      stage.prim_at(parent_path)
+    end
+
+    # @return [Array<Prim>] active direct children
+    def children
+      stage.child_paths(path).filter_map { |child_path| stage.prim_at(child_path) }
+    end
+
+    # @return [Attribute, nil] composed attribute by name
+    def attribute(name)
+      properties = property_opinions(name)
+      return unless properties.first.is_a?(AttributeSpec)
+
+      Attribute.new(self, name)
+    end
+
+    # Create or return an attribute in the edit target.
+    # @return [Attribute]
+    def create_attribute(name, type_name)
+      stage.author_attribute(path, name, type_name)
+      Attribute.new(self, name)
+    end
+
+    # @return [Relationship, nil] composed relationship by name
+    def relationship(name)
+      properties = property_opinions(name)
+      return unless properties.first.is_a?(RelationshipSpec)
+
+      Relationship.new(self, name)
+    end
+
+    # Create or return a relationship in the edit target.
+    # @return [Relationship]
+    def create_relationship(name)
+      stage.author_relationship(path, name)
+      Relationship.new(self, name)
+    end
+
+    def active?
+      authored = opinions.find { |opinion| opinion.metadata.key?("active") }
+      authored ? authored.metadata["active"] != false : true
+    end
+
+    # @return [MetadataView] composed, writable metadata
+    def metadata
+      values = opinions.reverse_each.with_object({}) { |opinion, result| result.merge!(opinion.metadata) }
+      MetadataView.new(values, writer: method(:write_metadata))
+    end
+
+    # @return [Hash] composed variant-set definitions
+    def variant_sets
+      opinions.reverse_each.with_object({}) do |opinion, result|
+        result.merge!(opinion.variant_sets) if opinion.respond_to?(:variant_sets)
+      end
+    end
+
+    # Author a variant selection.
+    # @return [Prim]
+    def set_variant_selection(set_name, choice)
+      stage.set_variant_selection(path, set_name, choice)
+      self
+    end
+
+    # @api private
+    # @return [Array<AttributeSpec, RelationshipSpec>]
+    def property_opinions(name)
+      opinions.filter_map { |opinion| opinion.property_named(name) }
+    end
+
+    protected
+
+    # Return all composed opinions for this prim.
+    # @api private
+    def opinions
+      stage.opinions_for(path)
+    end
+
+    private
+
+    def write_metadata(operation, key, value)
+      stage.author_prim_metadata(path, operation, key, value)
+    end
+  end
+
+  # Synthetic root for a Stage's root prims.
+  class PseudoRoot
+    attr_reader :stage
+
+    def initialize(stage)
+      @stage = stage
+    end
+
+    # @return [Path] pseudo-root path
+    def path
+      Path.parse("/")
+    end
+
+    # @return [String] empty pseudo-root name
+    def name
+      ""
+    end
+
+    # @return [nil]
+    def type_name
+      nil
+    end
+
+    # @return [nil]
+    def parent
+      nil
+    end
+
+    # @return [Array<Prim>] active root prims
+    def children
+      stage.root_paths.filter_map { |root_path| stage.prim_at(root_path) }
+    end
+  end
+end

data/lib/openusd/prim_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # An authored prim specification in a Layer.
+  class PrimSpec
+    # Valid authored specifier values.
+    SPECIFIERS = %i[def over class].freeze
+    # Sentinel distinguishing no reference opinion from an authored empty list.
+    REFERENCES_UNAUTHORED = Object.new.freeze
+    # Supported reference list-edit operators.
+    REFERENCE_LIST_OPERATIONS = %i[prepend append delete reorder add explicit].freeze
+
+    attr_reader :name, :children, :properties, :metadata, :references, :variant_sets, :specifier,
+                :reference_list_op
+    attr_accessor :type_name, :parent
+
+    def initialize(name, type_name: nil, specifier: :def, metadata: {}, references: REFERENCES_UNAUTHORED,
+                   reference_list_op: :prepend)
+      @name = validate_name(name)
+      @type_name = type_name&.to_s
+      self.specifier = specifier
+      @metadata = metadata.dup
+      @references = []
+      @references_authored = false
+      set_references(references, operation: reference_list_op) unless references.equal?(REFERENCES_UNAUTHORED)
+      @variant_sets = {}
+      @children = []
+      @child_index = {}
+      @properties = []
+      @property_index = {}
+      @parent = nil
+    end
+
+    def specifier=(value)
+      normalized = value.to_sym
+      raise OpenUSD::TypeError, "invalid specifier: #{value.inspect}" unless SPECIFIERS.include?(normalized)
+
+      @specifier = normalized
+    end
+
+    # Absolute path within the containing layer.
+    def path
+      return Path.parse("/#{name}") unless parent
+
+      parent.path.child(name)
+    end
+
+    def add_child(child)
+      raise OpenUSD::TypeError, "child must be a PrimSpec" unless child.is_a?(PrimSpec)
+      raise PathError, "duplicate child prim: #{child.name}" if @child_index.key?(child.name)
+
+      child.parent = self
+      children << child
+      @child_index[child.name] = child
+      child
+    end
+
+    # Remove a direct child by name.
+    # @return [PrimSpec, nil]
+    def remove_child(name)
+      child = child_named(name)
+      return unless child
+
+      children.delete(child)
+      @child_index.delete(name.to_s)
+      child.parent = nil
+      child
+    end
+
+    # @return [PrimSpec, nil] direct child by name
+    def child_named(name)
+      @child_index[name.to_s]
+    end
+
+    def add_property(property)
+      valid = property.is_a?(AttributeSpec) || property.is_a?(RelationshipSpec)
+      raise OpenUSD::TypeError, "property must be an AttributeSpec or RelationshipSpec" unless valid
+      raise PathError, "duplicate property: #{property.name}" if @property_index.key?(property.name)
+
+      properties << property
+      @property_index[property.name] = property
+      property
+    end
+
+    # @return [AttributeSpec, RelationshipSpec, nil] authored property by name
+    def property_named(name)
+      @property_index[name.to_s]
+    end
+
+    # Remove an authored property by name.
+    # @return [AttributeSpec, RelationshipSpec, nil]
+    def remove_property(name)
+      property = property_named(name)
+      properties.delete(property)
+      @property_index.delete(name.to_s)
+      property
+    end
+
+    # Add a reference composition arc.
+    # @return [Reference]
+    def add_reference(asset_path = nil, prim_path = nil)
+      reference = Reference.new(asset_path, prim_path)
+      references << reference
+      @references_authored = true
+      @reference_list_op = :prepend if @reference_list_op.nil?
+      reference
+    end
+
+    # Replace the authored references and list-edit operation.
+    # @return [Array<Reference>]
+    def set_references(values, operation: nil)
+      normalized_operation = operation&.to_sym
+      unless normalized_operation.nil? || REFERENCE_LIST_OPERATIONS.include?(normalized_operation)
+        raise OpenUSD::TypeError, "invalid reference list operation: #{operation.inspect}"
+      end
+
+      @references = Array(values).map { |reference| normalize_reference(reference) }
+      @reference_list_op = normalized_operation
+      @references_authored = true
+      references
+    end
+
+    # Whether a reference opinion, including an empty list, is authored.
+    def references_authored?
+      @references_authored
+    end
+
+    # Traverse authored descendants depth-first.
+    # @return [Enumerator, nil]
+    def each_descendant(&block)
+      return enum_for(__method__) unless block
+
+      children.each do |child|
+        yield child
+        child.each_descendant(&block)
+      end
+    end
+
+    # @return [Hash] semantic representation used for equality
+    def to_h
+      {
+        name: name, type_name: type_name, specifier: specifier,
+        metadata: metadata, references: references, references_authored: references_authored?,
+        reference_list_op: reference_list_op, variant_sets: variant_sets_to_h,
+        properties: semantic_properties(properties), children: children.map(&:to_h)
+      }
+    end
+
+    private
+
+    def validate_name(value)
+      name = String(value)
+      return name.dup.freeze if Path::PRIM_NAME.match?(name)
+
+      raise PathError, "invalid prim name: #{name.inspect}"
+    end
+
+    def normalize_reference(value)
+      return value if value.is_a?(Reference)
+      return Reference.new(*value) if value.is_a?(Array)
+
+      Reference.new(value)
+    end
+
+    def variant_sets_to_h
+      variant_sets.transform_values do |choices|
+        choices.transform_values do |variant|
+          next variant unless variant.respond_to?(:properties)
+
+          { properties: semantic_properties(variant.properties), children: variant.children.map(&:to_h) }
+        end
+      end
+    end
+
+    def semantic_properties(values)
+      values.sort_by(&:name).map(&:to_h)
+    end
+  end
+end

data/lib/openusd/relationship.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Composed relationship view on a Stage.
+  class Relationship
+    attr_reader :prim, :name
+
+    def initialize(prim, name)
+      @prim = prim
+      @name = name.to_s
+    end
+
+    # @return [Array<Path>] strongest authored targets
+    def targets
+      opinions.find(&:targets_authored?)&.targets || []
+    end
+
+    # Add one target in the edit target.
+    # @return [Relationship]
+    def add_target(path)
+      authored_spec.add_target(path)
+      prim.stage.invalidate!
+      self
+    end
+
+    # Replace targets in the edit target.
+    # @return [Relationship]
+    def set_targets(paths)
+      authored_spec.targets = paths
+      prim.stage.invalidate!
+      self
+    end
+
+    # @return [MetadataView] composed, writable metadata
+    def metadata
+      values = opinions.reverse_each.with_object({}) { |opinion, result| result.merge!(opinion.metadata) }
+      MetadataView.new(values, writer: method(:write_metadata))
+    end
+
+    private
+
+    def opinions
+      prim.property_opinions(name).grep(RelationshipSpec)
+    end
+
+    def authored_spec
+      prim.stage.author_relationship(prim.path, name)
+    end
+
+    def write_metadata(operation, key, value)
+      authored = authored_spec.metadata
+      operation == :set ? authored[key] = value : authored.delete(key)
+      prim.stage.invalidate!
+    end
+  end
+end