openusd 1.0.0

data/lib/openusd/attribute_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # An authored attribute in a Layer.
+  class AttributeSpec
+    # Sentinel distinguishing an absent default from an authored value block.
+    UNAUTHORED = Object.new.freeze
+    # Valid attribute variability values.
+    VARIABILITIES = %i[varying uniform].freeze
+
+    attr_reader :name, :type_name, :time_samples, :connections, :metadata, :variability, :default
+    attr_accessor :custom
+
+    def initialize(name, type_name, default: UNAUTHORED, variability: :varying, custom: false, metadata: {})
+      @name = validate_name(name)
+      @type_name = String(type_name).dup.freeze
+      self.variability = variability
+      @custom = custom == true
+      @metadata = metadata.dup
+      @connections = []
+      @connections_authored = false
+      @time_samples = {}
+      @time_samples_authored = false
+      @default_authored = false
+      set(default) unless default.equal?(UNAUTHORED)
+    end
+
+    def type_name=(value)
+      normalized = String(value).dup.freeze
+      Types.validate!(normalized, @default) if default_authored? && !@default.nil?
+      @time_samples.each_value { |sample| Types.validate!(normalized, sample) unless sample.nil? }
+      @type_name = normalized
+    end
+
+    def variability=(value)
+      normalized = value.to_sym
+      raise OpenUSD::TypeError, "invalid variability: #{value.inspect}" unless VARIABILITIES.include?(normalized)
+
+      @variability = normalized
+    end
+
+    # Whether a default opinion, including a value block, is authored.
+    def default_authored?
+      @default_authored
+    end
+
+    # Whether a timeSamples dictionary, including an empty one, is authored.
+    def time_samples_authored?
+      @time_samples_authored
+    end
+
+    # Whether connections, including an empty list, are authored.
+    def connections_authored?
+      @connections_authored
+    end
+
+    # Set a default or time-sampled value.
+    def set(value, time: nil)
+      normalized = value.nil? ? nil : Types.coerce(type_name, value)
+      return set_time_sample(time, normalized) unless time.nil?
+
+      @default = normalized
+      @default_authored = true
+      normalized
+    end
+
+    # Remove the default opinion.
+    def clear_default
+      @default = nil
+      @default_authored = false
+      self
+    end
+
+    # Replace time samples, normalizing their keys and values.
+    def time_samples=(samples)
+      @time_samples = samples.each_with_object({}) do |(time, value), result|
+        result[Float(time)] = value.nil? ? nil : Types.coerce(type_name, value)
+      end.sort.to_h
+      @time_samples_authored = true
+    rescue ArgumentError, ::TypeError
+      raise OpenUSD::TypeError, "time sample keys must be numeric"
+    end
+
+    # Replace all connection paths.
+    def connections=(paths)
+      @connections = Array(paths).map { |path| Path.parse(path) }
+      @connections_authored = true
+    end
+
+    # @return [Hash] semantic representation used for equality
+    def to_h
+      {
+        name: name, type_name: type_name, default: default,
+        default_authored: default_authored?, time_samples: time_samples,
+        time_samples_authored: time_samples_authored?,
+        variability: variability, custom: custom, connections: connections,
+        connections_authored: connections_authored?,
+        metadata: metadata
+      }
+    end
+
+    private
+
+    def validate_name(value)
+      name = String(value)
+      return name.dup.freeze if Path::PROPERTY_NAME.match?(name)
+
+      raise PathError, "invalid attribute name: #{name.inspect}"
+    end
+
+    def set_time_sample(time, value)
+      @time_samples[Float(time)] = value
+      @time_samples = @time_samples.sort.to_h
+      @time_samples_authored = true
+      value
+    rescue ArgumentError, ::TypeError
+      raise OpenUSD::TypeError, "time must be numeric"
+    end
+  end
+end

data/lib/openusd/cli.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module OpenUSD
+  # Command-line interface used by the `openusd` executable.
+  class CLI
+    # Supported subcommand names.
+    COMMANDS = %w[cat tree zip].freeze
+
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # Run a command and return a process exit status.
+    # @param arguments [Array<String>]
+    # @return [Integer]
+    def run(arguments)
+      argv = arguments.dup
+      command = argv.shift
+      return print_help(0) if command.nil? || %w[-h --help help].include?(command)
+      return print_version if %w[-v --version version].include?(command)
+      return unknown_command(command) unless COMMANDS.include?(command)
+
+      send("run_#{command}", argv)
+      0
+    rescue OptionParser::ParseError, ArgumentError, OpenUSD::Error, SystemCallError => e
+      @stderr.puts("openusd: #{e.message}")
+      1
+    end
+
+    private
+
+    def run_cat(argv)
+      output = nil
+      show_help = false
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: openusd cat [options] FILE"
+        options.on("-o", "--output PATH", "Write formatted USDA to PATH") { |path| output = path }
+        options.on("-h", "--help", "Show this help") { show_help = true }
+      end
+      parser.parse!(argv)
+      return @stdout.puts(parser) if show_help
+
+      input = required_argument(argv, parser)
+      ensure_no_arguments!(argv, parser)
+      text = Layer.open(input).to_usda
+      output ? File.binwrite(output, text) : @stdout.write(text)
+    end
+
+    def run_tree(argv)
+      show_help = false
+      parser = OptionParser.new
+      parser.banner = "Usage: openusd tree FILE"
+      parser.on("-h", "--help", "Show this help") { show_help = true }
+      parser.parse!(argv)
+      return @stdout.puts(parser) if show_help
+
+      input = required_argument(argv, parser)
+      ensure_no_arguments!(argv, parser)
+      Stage.open(input).traverse do |prim|
+        depth = prim.path.to_s.count("/") - 1
+        type = prim.type_name ? " <#{prim.type_name}>" : ""
+        @stdout.puts("#{"  " * depth}#{prim.name}#{type}")
+      end
+    end
+
+    def run_zip(argv)
+      show_help = false
+      parser = OptionParser.new
+      parser.banner = "Usage: openusd zip OUTPUT.usdz ROOT.usd[a|c] [ASSET ...]"
+      parser.on("-h", "--help", "Show this help") { show_help = true }
+      parser.parse!(argv)
+      return @stdout.puts(parser) if show_help
+
+      output = required_argument(argv, parser)
+      root = required_argument(argv, parser)
+      Format::Usdz::Writer.pack(output, root: root, assets: argv)
+      @stdout.puts(output)
+    end
+
+    def required_argument(argv, parser)
+      argv.shift || raise(OptionParser::MissingArgument, parser.banner)
+    end
+
+    def ensure_no_arguments!(argv, parser)
+      raise OptionParser::InvalidArgument, "#{parser.banner}: #{argv.join(" ")}" unless argv.empty?
+    end
+
+    def print_help(status)
+      @stdout.puts <<~HELP
+        Usage: openusd COMMAND [options]
+
+        Commands:
+          cat FILE                    Parse and format a USDA or USDZ root layer
+          tree FILE                   Print the composed prim hierarchy
+          zip OUTPUT ROOT [ASSET...]  Create an aligned, uncompressed USDZ package
+
+        Run `openusd COMMAND --help` for command-specific options.
+      HELP
+      status
+    end
+
+    def print_version
+      @stdout.puts("openusd #{VERSION}")
+      0
+    end
+
+    def unknown_command(command)
+      @stderr.puts("openusd: unknown command #{command.inspect}")
+      print_help(1)
+    end
+  end
+end

data/lib/openusd/composition.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module OpenUSD
+  # Builds the v1 root/sublayer/reference composition index.
+  class Composition
+    # Internal prim-like opinion for a selected variant.
+    VariantOpinion = Data.define(:properties, :metadata, :type_name) do
+      # Find a property in the selected variant.
+      # @api private
+      def property_named(name)
+        properties.find { |property| property.name == name.to_s }
+      end
+    end
+
+    attr_reader :root_layer, :resolver, :layers, :layer_cache
+
+    def initialize(root_layer, resolver:, layer_cache: {})
+      @root_layer = root_layer
+      @resolver = resolver
+      @layer_cache = layer_cache
+      @layer_cache[layer_key(root_layer)] = root_layer
+      @layers = []
+    end
+
+    # Map absolute prim paths to opinions in strongest-to-weakest order.
+    def build
+      @layers = []
+      compose_layer(root_layer, [])
+    end
+
+    private
+
+    def compose_layer(layer, stack)
+      key = layer_key(layer)
+      cycle!(stack, key) if stack.include?(key)
+      next_stack = stack + [key]
+      layer_stack = collect_layer_stack(layer, next_stack)
+      index = index_layer_stack(layer_stack)
+      compose_references(index, next_stack)
+      index
+    end
+
+    def collect_layer_stack(layer, stack)
+      @layers << layer unless @layers.include?(layer)
+      result = [layer]
+      layer.sub_layer_paths.each do |authored_path|
+        resolved = resolver.resolve(authored_path, anchor: layer.identifier)
+        next unless resolved
+
+        key = File.expand_path(resolved)
+        cycle!(stack, key) if stack.include?(key)
+        child = load_layer(resolved)
+        result.concat(collect_layer_stack(child, stack + [key]))
+      end
+      result
+    end
+
+    def index_layer_stack(layer_stack)
+      index = Hash.new { |hash, key| hash[key] = [] }
+      layer_stack.each do |layer|
+        layer.root_prims.each { |prim| index_prim(index, prim, "/#{prim.name}") }
+      end
+      index
+    end
+
+    def index_prim(index, prim, path)
+      selected_variant_opinions(prim).each { |opinion| index[path] << opinion }
+      index[path] << prim
+      prim.children.each { |child| index_prim(index, child, "#{path}/#{child.name}") }
+      index_variant_children(index, prim, path)
+    end
+
+    def selected_variant_opinions(prim)
+      selections = prim.metadata["variants"]
+      return [] unless selections.is_a?(Hash)
+
+      selections.filter_map do |set_name, choice|
+        variant = prim.variant_sets.dig(set_name.to_s, choice.to_s)
+        VariantOpinion.new(variant.properties, {}, nil) if variant
+      end
+    end
+
+    def index_variant_children(index, prim, path)
+      selections = prim.metadata["variants"]
+      return unless selections.is_a?(Hash)
+
+      selections.each do |set_name, choice|
+        variant = prim.variant_sets.dig(set_name.to_s, choice.to_s)
+        next unless variant
+
+        variant.children.each { |child| index_prim(index, child, "#{path}/#{child.name}") }
+      end
+    end
+
+    def compose_references(index, stack)
+      authored = index.to_a
+      authored.each do |destination, opinions|
+        effective_references(opinions).each do |reference, owner|
+          map_reference(index, destination, owner, reference, stack)
+        end
+      end
+      index
+    end
+
+    def map_reference(index, destination, owner, reference, stack)
+      return map_internal_reference(index, destination, reference) if reference.internal?
+
+      resolved = resolver.resolve(reference.asset_path, anchor: layer_identifier(owner))
+      return unless resolved
+
+      referenced_layer = load_layer(resolved)
+      source_index = compose_layer(referenced_layer, stack)
+      source_root = reference.prim_path || referenced_layer.default_prim&.path
+      raise CompositionError, "reference #{resolved} has no target or defaultPrim" unless source_root
+
+      map_reference_subtree(index, destination, source_index, source_root.to_s)
+    end
+
+    def map_internal_reference(index, destination, reference)
+      source_prefix = reference.prim_path.to_s
+      raise CompositionError, "internal reference cycle detected at #{destination}" if source_prefix == destination
+
+      map_reference_subtree(index, destination, index, source_prefix)
+    end
+
+    def map_reference_subtree(index, destination, source_index, source_prefix)
+      source_index.to_a.each do |source_path, source_opinions|
+        next unless source_path == source_prefix || source_path.start_with?("#{source_prefix}/")
+
+        suffix = source_path.delete_prefix(source_prefix)
+        index["#{destination}#{suffix}"].concat(source_opinions)
+      end
+    end
+
+    def effective_references(opinions)
+      opinions.grep(PrimSpec).reverse_each.with_object([]) do |opinion, result|
+        next unless opinion.references_authored?
+
+        entries = opinion.references.map { |reference| [reference, opinion] }
+        apply_reference_list_op(result, entries, opinion.reference_list_op)
+      end
+    end
+
+    def apply_reference_list_op(result, entries, operation)
+      case operation
+      when :prepend then result.replace(unique_references(entries + result))
+      when :append, :add then result.replace(unique_references(result + entries))
+      when :delete then result.reject! { |reference, _owner| entries.any? { |entry| entry.first == reference } }
+      when :reorder then reorder_references(result, entries)
+      else result.replace(entries)
+      end
+    end
+
+    def unique_references(entries)
+      entries.each_with_object([]) do |entry, result|
+        result << entry unless result.any? { |candidate| candidate.first == entry.first }
+      end
+    end
+
+    def reorder_references(result, entries)
+      ordered = entries.filter_map do |entry|
+        result.find { |candidate| candidate.first == entry.first }
+      end
+      result.replace(ordered + result.reject { |candidate| ordered.include?(candidate) })
+    end
+
+    def layer_identifier(owner)
+      layers.find { |layer| layer.prim_at(owner.path) == owner }&.identifier || root_layer.identifier
+    end
+
+    def load_layer(identifier)
+      key = identifier.match?(/\.usdz\[[^\]]+\]\z/i) ? identifier : File.expand_path(identifier)
+      layer_cache[key] ||= Layer.open(identifier)
+    end
+
+    def layer_key(layer)
+      identifier = layer.identifier
+      return "anonymous:#{layer.object_id}" if identifier.nil? || identifier.start_with?("anonymous:")
+
+      File.expand_path(identifier)
+    end
+
+    def cycle!(stack, key)
+      chain = (stack + [key]).join(" -> ")
+      raise CompositionError, "composition cycle detected: #{chain}"
+    end
+  end
+end

data/lib/openusd/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Base class for errors raised by this library.
+  class Error < StandardError; end
+
+  # Raised when USDA text cannot be parsed.
+  class ParseError < Error
+    attr_reader :file, :line, :column
+
+    def initialize(message, file: nil, line: nil, column: nil)
+      @file = file
+      @line = line
+      @column = column
+      super(location ? "#{location}: #{message}" : message)
+    end
+
+    private
+
+    def location
+      return unless line && column
+
+      [file, line, column].compact.join(":")
+    end
+  end
+
+  # Raised when a Ruby value does not conform to a USD value type.
+  class TypeError < Error; end
+
+  # Raised when an Sdf-style path is malformed or invalid for an operation.
+  class PathError < Error; end
+
+  # Raised when layers cannot be composed.
+  class CompositionError < Error; end
+
+  # Raised when a USDZ package is malformed or violates package constraints.
+  class PackageError < Error; end
+
+  # Raised for recognized operations that are outside this implementation.
+  class NotSupportedError < Error; end
+end

data/lib/openusd/format/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # File-format adapters and the extension registry.
+  module Format
+    # Extension-based registry for layer and package formats.
+    module Registry
+      # Registered reader/writer pair.
+      Entry = Data.define(:reader, :writer)
+      @entries = {}
+
+      module_function
+
+      # Register one or both adapters for an extension.
+      def register(extension, reader: nil, writer: nil)
+        key = normalize(extension)
+        current = @entries[key]
+        @entries[key] = Entry.new(
+          reader: reader || current&.reader,
+          writer: writer || current&.writer
+        )
+      end
+
+      # @return [Entry] adapter pair for a path or extension
+      def fetch(path_or_extension)
+        extension = File.extname(path_or_extension.to_s)
+        key = normalize(extension.empty? ? path_or_extension : extension)
+        @entries.fetch(key) { raise NotSupportedError, "unsupported file format: #{key}" }
+      end
+
+      # @return [#read] reader adapter for a path
+      def reader_for(path)
+        fetch(path).reader || raise(NotSupportedError, "reading #{File.extname(path)} is not supported")
+      end
+
+      # @return [#write] writer adapter for a path
+      def writer_for(path)
+        fetch(path).writer || raise(NotSupportedError, "writing #{File.extname(path)} is not supported")
+      end
+
+      # @return [Array<String>] registered extensions without leading dots
+      def extensions
+        @entries.keys.freeze
+      end
+
+      def normalize(extension)
+        extension.to_s.downcase.delete_prefix(".")
+      end
+      private_class_method :normalize
+    end
+  end
+end