openusd 1.0.0

data/lib/openusd/relationship_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # An authored relationship in a Layer.
+  class RelationshipSpec
+    # Sentinel distinguishing no target opinion from an authored empty list.
+    UNAUTHORED = Object.new.freeze
+
+    attr_reader :name, :targets, :metadata
+    attr_accessor :custom
+
+    def initialize(name, targets: UNAUTHORED, custom: false, metadata: {})
+      @name = validate_name(name)
+      @custom = custom == true
+      @metadata = metadata.dup
+      @targets = []
+      @targets_authored = false
+      self.targets = targets unless targets.equal?(UNAUTHORED)
+    end
+
+    def targets=(paths)
+      @targets = Array(paths).map { |path| Path.parse(path) }
+      @targets_authored = true
+    end
+
+    # Whether targets, including an empty list, are authored.
+    def targets_authored?
+      @targets_authored
+    end
+
+    # Add a target unless it is already present.
+    # @return [Path]
+    def add_target(path)
+      target = Path.parse(path)
+      @targets << target unless @targets.include?(target)
+      @targets_authored = true
+      target
+    end
+
+    # @return [Hash] semantic representation used for equality
+    def to_h
+      {
+        name: name, targets: targets, targets_authored: targets_authored?,
+        custom: custom, metadata: metadata
+      }
+    end
+
+    private
+
+    def validate_name(value)
+      name = String(value)
+      return name.dup.freeze if Path::PROPERTY_NAME.match?(name)
+
+      raise PathError, "invalid relationship name: #{name.inspect}"
+    end
+  end
+end

data/lib/openusd/schema/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Typed convenience wrappers for commonly authored prim schemas.
+  module Schema
+    # Base for typed convenience wrappers around Stage prims.
+    class Base
+      class << self
+        attr_reader :type_name
+
+        # Declare the prim type represented by a wrapper.
+        # @api private
+        def schema_type(name)
+          @type_name = name.freeze
+        end
+
+        # Define and wrap a prim.
+        # @return [Base]
+        def define(stage, path)
+          new(stage.define_prim(path, type_name))
+        end
+
+        # Wrap a prim only when its type matches.
+        # @return [Base, nil]
+        def get(stage, path)
+          prim = stage.prim_at(path)
+          return unless prim&.type_name == type_name
+
+          new(prim)
+        end
+      end
+
+      attr_reader :prim
+
+      def initialize(prim)
+        @prim = prim
+      end
+
+      # @return [Stage] owning stage
+      def stage
+        prim.stage
+      end
+
+      # @return [Path] wrapped prim path
+      def path
+        prim.path
+      end
+
+      private
+
+      def get(name)
+        prim.attribute(name)&.get
+      end
+
+      def set(name, type_name, value)
+        prim.create_attribute(name, type_name).set(value)
+        self
+      end
+    end
+  end
+end

data/lib/openusd/schema/camera.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Schema
+    # Convenience API for common Camera attributes.
+    class Camera < Base
+      schema_type "Camera"
+
+      # @return [Float, nil] focal length in tenths of a scene unit
+      def focal_length
+        get("focalLength")
+      end
+
+      # Author the focal length.
+      def focal_length=(value)
+        set("focalLength", "float", value)
+      end
+
+      # @return [Array<Float>, nil] near and far clipping distances
+      def clipping_range
+        get("clippingRange")
+      end
+
+      # Author near and far clipping distances.
+      def clipping_range=(value)
+        set("clippingRange", "float2", value)
+      end
+    end
+  end
+end

data/lib/openusd/schema/material.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Schema
+    # Convenience API for Material prims.
+    class Material < Base
+      schema_type "Material"
+
+      # Bind this material to another prim.
+      # @return [Material]
+      def bind(geometry_prim)
+        geometry_prim.create_relationship("material:binding").set_targets([path])
+        self
+      end
+    end
+  end
+end

data/lib/openusd/schema/mesh.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Schema
+    # Convenience API for core Mesh topology and point attributes.
+    class Mesh < Base
+      schema_type "Mesh"
+
+      {
+        points: ["points", "point3f[]"],
+        normals: ["normals", "normal3f[]"],
+        face_vertex_counts: ["faceVertexCounts", "int[]"],
+        face_vertex_indices: ["faceVertexIndices", "int[]"],
+        extent: ["extent", "float3[]"]
+      }.each do |method_name, (attribute_name, type_name)|
+        define_method(method_name) { get(attribute_name) }
+        define_method("#{method_name}=") { |value| set(attribute_name, type_name, value) }
+      end
+
+      # @return [Token, nil] authored subdivision scheme
+      def subdivision_scheme
+        get("subdivisionScheme")
+      end
+
+      # Author the subdivision scheme token.
+      def subdivision_scheme=(value)
+        set("subdivisionScheme", "token", value)
+      end
+    end
+  end
+end

data/lib/openusd/schema/scope.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Schema
+    # Convenience wrapper for organizational Scope prims.
+    class Scope < Base
+      schema_type "Scope"
+    end
+  end
+end

data/lib/openusd/schema/xform.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Schema
+    # Convenience API for Xform prims and common transform operations.
+    class Xform < Base
+      schema_type "Xform"
+
+      # @return [Array<Float>, nil] translation operation
+      def translate
+        get("xformOp:translate")
+      end
+
+      # Author the translation operation.
+      def translate=(value)
+        set_operation("xformOp:translate", "double3", value)
+      end
+
+      # @return [Array<Float>, nil] XYZ rotation operation
+      def rotate_xyz
+        get("xformOp:rotateXYZ")
+      end
+
+      # Author the XYZ rotation operation.
+      def rotate_xyz=(value)
+        set_operation("xformOp:rotateXYZ", "float3", value)
+      end
+
+      # @return [Array<Float>, nil] scale operation
+      def scale
+        get("xformOp:scale")
+      end
+
+      # Author the scale operation.
+      def scale=(value)
+        set_operation("xformOp:scale", "float3", value)
+      end
+
+      private
+
+      def set_operation(name, type_name, value)
+        set(name, type_name, value)
+        order = prim.attribute("xformOpOrder")&.get || []
+        prim.create_attribute("xformOpOrder", "token[]").set(order + [name]) unless order.include?(name)
+        value
+      end
+    end
+  end
+end

data/lib/openusd/stage.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Composed, editable view of one root layer and its composition arcs.
+  class Stage
+    attr_reader :root_layer, :resolver, :pseudo_root, :edit_target
+
+    class << self
+      # Open a composed stage.
+      # @return [Stage]
+      def open(path, missing_assets: :error)
+        expanded = File.expand_path(path)
+        resolver = AssetResolver.new(missing_assets: missing_assets)
+        new(Layer.open(expanded), resolver: resolver)
+      end
+
+      # Create an empty file-backed stage.
+      # @return [Stage]
+      def create(identifier)
+        new(Layer.create(identifier))
+      end
+
+      # Create an anonymous in-memory stage.
+      # @return [Stage]
+      def create_in_memory
+        new(Layer.create("anonymous:#{object_id}:#{Process.clock_gettime(Process::CLOCK_MONOTONIC)}"))
+      end
+    end
+
+    def initialize(root_layer, resolver: AssetResolver.new)
+      @root_layer = root_layer
+      @resolver = resolver
+      @edit_target = root_layer
+      @pseudo_root = PseudoRoot.new(self)
+      @composition = nil
+      @index = nil
+      @layer_cache = {}
+    end
+
+    def edit_target=(layer)
+      raise OpenUSD::TypeError, "edit target must be a Layer" unless layer.is_a?(Layer)
+      raise CompositionError, "edit target is not in this stage's layer stack" unless layer_stack.include?(layer)
+
+      @edit_target = layer
+    end
+
+    # Find an active composed prim.
+    # @return [Prim, PseudoRoot, nil]
+    def prim_at(path)
+      parsed = Path.parse(path)
+      return pseudo_root if parsed.to_s == "/"
+      return nil if parsed.property?
+      return nil unless composed_index.key?(parsed.to_s)
+
+      prim = Prim.new(self, parsed)
+      prim.active? ? prim : nil
+    end
+
+    # @return [Prim, nil] composed default prim
+    def default_prim
+      name = root_layer.metadata["defaultPrim"]
+      prim_at("/#{name}") if name
+    end
+
+    # Define a prim and any missing ancestors in the edit target.
+    # @return [Prim]
+    def define_prim(path, type_name = nil)
+      parsed = validate_prim_path(path)
+      spec = ensure_spec(edit_target, parsed)
+      spec.specifier = :def
+      spec.type_name = type_name.to_s if type_name
+      invalidate!
+      Prim.new(self, parsed)
+    end
+
+    # Remove or deactivate a prim in the edit target.
+    # @return [Stage]
+    def remove_prim(path)
+      parsed = validate_prim_path(path)
+      remove_spec(edit_target, parsed)
+      invalidate!
+      if composed_index.key?(parsed.to_s)
+        blocker = ensure_spec(edit_target, parsed)
+        blocker.specifier = :over
+        blocker.metadata["active"] = false
+      end
+      invalidate!
+      self
+    end
+
+    # Traverse active prims depth-first.
+    # @return [Enumerator, Stage]
+    def traverse
+      return enum_for(__method__) unless block_given?
+
+      walk = lambda do |prim|
+        yield prim
+        prim.children.each { |child| walk.call(child) }
+      end
+      pseudo_root.children.each { |prim| walk.call(prim) }
+      self
+    end
+
+    # Save the root layer to its identifier.
+    # @return [Stage]
+    def save
+      root_layer.save
+      self
+    end
+
+    # Export the root layer by destination extension.
+    # @return [Stage]
+    def export(path)
+      root_layer.export(path)
+      self
+    end
+
+    # Author a variant choice for a prim.
+    # @return [Stage]
+    def set_variant_selection(path, set_name, choice)
+      prim = prim_at(path)
+      raise CompositionError, "prim not found: #{path}" unless prim
+
+      choices = prim.variant_sets[set_name.to_s]
+      raise CompositionError, "variant set not found: #{set_name}" unless choices
+      raise CompositionError, "variant not found: #{choice}" unless choices.key?(choice.to_s)
+
+      spec = ensure_spec(edit_target, Path.parse(path))
+      spec.metadata["variants"] ||= {}
+      spec.metadata["variants"][set_name.to_s] = choice.to_s
+      invalidate!
+      self
+    end
+
+    # @api private
+    # @return [Array<PrimSpec>] strongest-to-weakest opinions
+    def opinions_for(path)
+      composed_index.fetch(Path.parse(path).to_s, [])
+    end
+
+    # @api private
+    # @return [Array<Path>] direct composed child paths
+    def child_paths(path)
+      prefix = "#{Path.parse(path)}/"
+      paths = composed_index.keys.select do |candidate|
+        candidate.start_with?(prefix) && !candidate.delete_prefix(prefix).include?("/")
+      end
+      paths.sort.map { |candidate| Path.parse(candidate) }
+    end
+
+    # @api private
+    # @return [Array<Path>] composed root paths
+    def root_paths
+      composed_index.keys.select { |path| path.count("/") == 1 }.sort.map { |path| Path.parse(path) }
+    end
+
+    # Find or author an attribute spec in the edit target.
+    # @api private
+    def author_attribute(path, name, type_name)
+      spec = ensure_spec(edit_target, Path.parse(path))
+      property = spec.property_named(name)
+      validate_property_kind!(property, AttributeSpec, "#{name} is authored as a relationship")
+      property ||= spec.add_property(AttributeSpec.new(name, type_name || "token"))
+      property.type_name = type_name if type_name
+      invalidate!
+      property
+    end
+
+    # Find or author a relationship spec in the edit target.
+    # @api private
+    def author_relationship(path, name)
+      spec = ensure_spec(edit_target, Path.parse(path))
+      property = spec.property_named(name)
+      validate_property_kind!(property, RelationshipSpec, "#{name} is authored as an attribute")
+      property ||= spec.add_property(RelationshipSpec.new(name))
+      invalidate!
+      property
+    end
+
+    # Author a prim type in the edit target.
+    # @api private
+    def set_prim_type(path, type_name)
+      spec = ensure_spec(edit_target, Path.parse(path))
+      spec.type_name = type_name&.to_s
+      invalidate!
+      type_name
+    end
+
+    # Apply one metadata mutation to an edit-target prim spec.
+    # @api private
+    def author_prim_metadata(path, operation, key, value)
+      metadata = ensure_spec(edit_target, Path.parse(path)).metadata
+      operation == :set ? metadata[key] = value : metadata.delete(key)
+      invalidate!
+    end
+
+    # @return [Array<Layer>] layers participating in composition
+    def layer_stack
+      composed_index
+      @composition.layers
+    end
+
+    # @api private
+    # Invalidate the cached composition index after an edit.
+    def invalidate!
+      @index = nil
+      @composition = nil
+      self
+    end
+
+    private
+
+    def composed_index
+      return @index if @index
+
+      @composition = Composition.new(root_layer, resolver: resolver, layer_cache: @layer_cache)
+      @index = @composition.build
+    end
+
+    def validate_prim_path(path)
+      parsed = Path.parse(path)
+      invalid = !parsed.absolute? || parsed.property? || parsed.to_s == "/"
+      raise PathError, "absolute non-root prim path required" if invalid
+
+      parsed
+    end
+
+    def ensure_spec(layer, path)
+      existing = layer.prim_at(path)
+      return existing if existing
+
+      names = path.to_s.delete_prefix("/").split("/")
+      parent = nil
+      names.each do |name|
+        child = parent ? parent.child_named(name) : layer.root_prim_named(name)
+        unless child
+          child = PrimSpec.new(name, specifier: :over)
+          parent ? parent.add_child(child) : layer.add_root_prim(child)
+        end
+        parent = child
+      end
+      parent
+    end
+
+    def remove_spec(layer, path)
+      spec = layer.prim_at(path)
+      return unless spec
+
+      if spec.parent
+        spec.parent.remove_child(spec.name)
+      else
+        layer.remove_root_prim(spec.name)
+      end
+    end
+
+    def validate_property_kind!(property, expected_class, message)
+      return if property.nil? || property.is_a?(expected_class)
+
+      raise OpenUSD::TypeError, message
+    end
+  end
+end

data/lib/openusd/types.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Registry and validation for built-in USD value types.
+  module Types
+    # Integer ranges enforced when authoring.
+    INTEGER_RANGES = {
+      "int" => (-(2**31)...(2**31)),
+      "uint" => (0...(2**32)),
+      "int64" => (-(2**63)...(2**63)),
+      "uint64" => (0...(2**64))
+    }.freeze
+    # Floating-point scalar type names.
+    FLOAT_TYPES = %w[half float double].freeze
+    # Vector and quaternion type names mapped to component counts.
+    VECTOR_TYPES = {
+      "float2" => 2, "float3" => 3, "float4" => 4,
+      "double2" => 2, "double3" => 3, "double4" => 4,
+      "half2" => 2, "half3" => 3, "half4" => 4,
+      "int2" => 2, "int3" => 3, "int4" => 4,
+      "point3f" => 3, "normal3f" => 3, "color3f" => 3,
+      "color4f" => 4, "texCoord2f" => 2, "texCoord3f" => 3,
+      "quatf" => 4, "quatd" => 4, "quath" => 4
+    }.freeze
+    # Matrix type names mapped to dimensions.
+    MATRIX_TYPES = { "matrix2d" => 2, "matrix3d" => 3, "matrix4d" => 4 }.freeze
+    # Built-in scalar type names.
+    SCALAR_TYPES = %w[bool int uint int64 uint64 half float double string token asset].freeze
+    # Internal dispatch table for scalar normalization.
+    SIMPLE_COERCERS = {
+      "bool" => :coerce_bool,
+      "half" => :coerce_float,
+      "float" => :coerce_float,
+      "double" => :coerce_float,
+      "string" => :coerce_string,
+      "token" => :coerce_token,
+      "asset" => :coerce_asset
+    }.freeze
+
+    module_function
+
+    # Whether the registry recognizes a type name.
+    def known?(type_name)
+      name = base_type(type_name)
+      SCALAR_TYPES.include?(name) || VECTOR_TYPES.key?(name) || MATRIX_TYPES.key?(name)
+    end
+
+    # Whether the type is an array type.
+    def array?(type_name)
+      String(type_name).end_with?("[]")
+    end
+
+    # Remove the array suffix from a type name.
+    def base_type(type_name)
+      String(type_name).delete_suffix("[]")
+    end
+
+    # Validate and normalize a Ruby value for a USD type.
+    # Unknown types are intentionally preserved for forward compatibility.
+    def coerce(type_name, value)
+      name = String(type_name)
+      return coerce_array(base_type(name), value) if array?(name)
+      return value unless known?(name)
+
+      coerce_scalar(name, value)
+    rescue OpenUSD::TypeError
+      raise
+    rescue StandardError
+      invalid!(name, value)
+    end
+
+    # Validate a Ruby value and return its normalized representation.
+    def validate!(type_name, value)
+      coerce(type_name, value)
+    end
+
+    def coerce_array(type_name, value)
+      invalid!("#{type_name}[]", value) unless value.is_a?(Array)
+
+      value.map { |element| coerce_scalar(type_name, element) }.freeze
+    end
+    private_class_method :coerce_array
+
+    def coerce_scalar(type_name, value)
+      coercer = SIMPLE_COERCERS[type_name]
+      return send(coercer, value) if coercer
+      return coerce_integer(type_name, value) if INTEGER_RANGES.key?(type_name)
+      return coerce_vector(type_name, value) if VECTOR_TYPES.key?(type_name)
+      return coerce_matrix(type_name, value) if MATRIX_TYPES.key?(type_name)
+      return value unless known?(type_name)
+
+      invalid!(type_name, value)
+    end
+    private_class_method :coerce_scalar
+
+    def coerce_bool(value)
+      return value if [true, false].include?(value)
+
+      invalid!("bool", value)
+    end
+    private_class_method :coerce_bool
+
+    def coerce_integer(type_name, value)
+      range = INTEGER_RANGES.fetch(type_name)
+      return value if value.is_a?(Integer) && range.cover?(value)
+
+      invalid!(type_name, value)
+    end
+    private_class_method :coerce_integer
+
+    def coerce_float(value)
+      return value.to_f if value.is_a?(Numeric)
+
+      invalid!("floating-point", value)
+    end
+    private_class_method :coerce_float
+
+    def coerce_string(value)
+      return value.dup.freeze if value.instance_of?(String)
+
+      invalid!("string", value)
+    end
+    private_class_method :coerce_string
+
+    def coerce_token(value)
+      return Token.new(value) if value.is_a?(String)
+
+      invalid!("token", value)
+    end
+    private_class_method :coerce_token
+
+    def coerce_asset(value)
+      return value if value.is_a?(AssetPath)
+      return AssetPath.new(value) if value.is_a?(String)
+
+      invalid!("asset", value)
+    end
+    private_class_method :coerce_asset
+
+    def coerce_vector(type_name, value)
+      size = VECTOR_TYPES.fetch(type_name)
+      invalid!(type_name, value) unless value.is_a?(Array) && value.length == size
+
+      scalar = type_name.start_with?("int") ? "int" : "double"
+      value.map { |element| coerce_scalar(scalar, element) }.freeze
+    end
+    private_class_method :coerce_vector
+
+    def coerce_matrix(type_name, value)
+      size = MATRIX_TYPES.fetch(type_name)
+      invalid!(type_name, value) unless matrix_shape?(value, size)
+
+      value.map { |row| row.map { |element| coerce_float(element) }.freeze }.freeze
+    end
+    private_class_method :coerce_matrix
+
+    def matrix_shape?(value, size)
+      value.is_a?(Array) && value.length == size &&
+        value.all? { |row| row.is_a?(Array) && row.length == size }
+    end
+    private_class_method :matrix_shape?
+
+    def invalid!(type_name, value)
+      raise OpenUSD::TypeError, "#{value.inspect} is not a valid #{type_name} value"
+    end
+    private_class_method :invalid!
+  end
+end