openusd 1.0.0

data/lib/openusd/format/usda/writer.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  module Format
+    module Usda
+      # Deterministic USDA serializer.
+      class Writer
+        # Indentation used for nested USDA constructs.
+        INDENT = " " * 4
+
+        class << self
+          # Serialize a layer to a filesystem path.
+          # @return [String] destination path
+          def write(layer, path)
+            File.binwrite(path, new.write_to_string(layer))
+            path
+          end
+        end
+
+        # Serialize a layer to USDA text.
+        # @return [String]
+        def write_to_string(layer)
+          @lines = ["#usda 1.0"]
+          write_metadata_block(layer.metadata, 0, layer_comment: true) unless layer.metadata.empty?
+          layer.root_prims.each do |prim|
+            line
+            write_prim(prim, 0)
+          end
+          "#{@lines.join("\n")}\n"
+        ensure
+          @lines = nil
+        end
+
+        private
+
+        def write_prim(prim, depth)
+          declaration = "#{prim.specifier}#{type_declaration(prim.type_name)} #{quote(prim.name)}"
+          metadata = prim.metadata.dup
+          write_references_metadata(metadata, prim) if prim.references_authored?
+          append(declaration, depth)
+          write_metadata_block(metadata, depth) unless metadata.empty?
+          append("{", depth)
+          write_prim_contents(prim, depth + 1)
+          append("}", depth)
+        end
+
+        def write_prim_contents(prim, depth)
+          ordered_properties(prim).each { |property| write_property(property, depth) }
+          write_variants(prim, depth)
+          prim.children.each do |child|
+            line
+            write_prim(child, depth)
+          end
+        end
+
+        def ordered_properties(prim)
+          prim.properties.sort_by do |property|
+            if property.is_a?(RelationshipSpec)
+              2
+            elsif property.variability == :uniform
+              0
+            else
+              1
+            end
+          end
+        end
+
+        def write_property(property, depth)
+          if property.is_a?(RelationshipSpec)
+            write_relationship(property, depth)
+          else
+            write_attribute(property, depth)
+          end
+        end
+
+        def write_attribute(attribute, depth)
+          prefix = attribute_prefix(attribute)
+          wrote_declaration = false
+          if attribute.default_authored?
+            write_property_line("#{prefix} = #{format_value(attribute.default, attribute.type_name, depth)}",
+                                attribute.metadata, depth)
+            wrote_declaration = true
+          elsif !attribute.metadata.empty?
+            write_property_line(prefix, attribute.metadata, depth)
+            wrote_declaration = true
+          end
+          write_time_samples(attribute, prefix, depth) if attribute.time_samples_authored?
+          write_connections(attribute, prefix, depth) if attribute.connections_authored?
+          authored = wrote_declaration || attribute.time_samples_authored? || attribute.connections_authored?
+          write_property_line(prefix, attribute.metadata, depth) unless authored
+        end
+
+        def write_time_samples(attribute, prefix, depth)
+          append("#{prefix}.timeSamples = {", depth)
+          attribute.time_samples.each do |time, value|
+            formatted = format_value(value, attribute.type_name, depth + 1)
+            append("#{format_number(time)}: #{formatted},", depth + 1)
+          end
+          append("}", depth)
+        end
+
+        def write_connections(attribute, prefix, depth)
+          value = attribute.connections.length == 1 ? attribute.connections.first : attribute.connections
+          append("#{prefix}.connect = #{format_value(value, nil, depth)}", depth)
+        end
+
+        def write_relationship(relationship, depth)
+          prefix = relationship.custom ? "custom rel #{relationship.name}" : "rel #{relationship.name}"
+          value = relationship.targets.length == 1 ? relationship.targets.first : relationship.targets
+          text = if relationship.targets_authored?
+                   "#{prefix} = #{format_value(value, nil, depth)}"
+                 else
+                   prefix
+                 end
+          write_property_line(text, relationship.metadata, depth)
+        end
+
+        def write_property_line(text, metadata, depth)
+          if metadata.empty?
+            append(text, depth)
+          else
+            append("#{text} (", depth)
+            write_metadata_entries(metadata, depth + 1)
+            append(")", depth)
+          end
+        end
+
+        def write_metadata_block(metadata, depth, layer_comment: false)
+          append("(", depth)
+          write_metadata_entries(metadata, depth + 1, layer_comment: layer_comment)
+          append(")", depth)
+        end
+
+        def write_metadata_entries(metadata, depth, layer_comment: false)
+          metadata.each do |key, value|
+            if layer_comment && key == "comment" && value.is_a?(String)
+              append(quote(value), depth)
+              next
+            end
+
+            operation, unwrapped = unwrap_list_op(value)
+            prefix = operation ? "#{operation} " : ""
+            write_metadata_entry("#{prefix}#{key}", unwrapped, depth)
+          end
+        end
+
+        def write_metadata_entry(key, value, depth)
+          if value.is_a?(Hash)
+            append("#{key} = {", depth)
+            write_dictionary(value, depth + 1)
+            append("}", depth)
+          else
+            append("#{key} = #{format_value(value, nil, depth)}", depth)
+          end
+        end
+
+        def write_dictionary(dictionary, depth)
+          dictionary.each do |key, value|
+            type_name = infer_type(value)
+            if value.is_a?(Hash)
+              append("dictionary #{key} = {", depth)
+              write_dictionary(value, depth + 1)
+              append("}", depth)
+            else
+              append("#{type_name} #{key} = #{format_value(value, type_name, depth)}", depth)
+            end
+          end
+        end
+
+        def write_variants(prim, depth)
+          prim.variant_sets.each do |name, choices|
+            line
+            append("variantSet #{quote(name)} = {", depth)
+            choices.each do |choice, variant|
+              append("#{quote(choice)} {", depth + 1)
+              variant.properties.each { |property| write_property(property, depth + 2) }
+              variant.children.each { |child| write_prim(child, depth + 2) }
+              append("}", depth + 1)
+            end
+            append("}", depth)
+          end
+        end
+
+        def format_value(value, expected_type, depth)
+          return "None" if value.nil?
+          return format_reference(value) if value.is_a?(Reference)
+          return format_asset(value) if value.is_a?(AssetPath)
+          return "<#{value}>" if value.is_a?(Path)
+          return quote(value) if value.is_a?(String)
+          return value ? "true" : "false" if [true, false].include?(value)
+          return format_number(value) if value.is_a?(Numeric)
+          return format_array(value, expected_type, depth) if value.is_a?(Array)
+          return format_inline_dictionary(value, depth) if value.is_a?(Hash)
+
+          value.to_s
+        end
+
+        def format_array(values, expected_type, depth)
+          scalar_value = expected_type && !Types.array?(expected_type)
+          vector = scalar_value && Types::VECTOR_TYPES.key?(Types.base_type(expected_type))
+          matrix = scalar_value && Types::MATRIX_TYPES.key?(Types.base_type(expected_type))
+          opening, closing = vector || matrix ? ["(", ")"] : ["[", "]"]
+          element_type = Types.array?(expected_type.to_s) ? Types.base_type(expected_type) : nil
+          contents = if matrix
+                       values.map { |row| format_array(row, "double4", depth) }.join(", ")
+                     else
+                       values.map { |value| format_value(value, element_type, depth) }.join(", ")
+                     end
+          "#{opening}#{contents}#{closing}"
+        end
+
+        def format_inline_dictionary(dictionary, depth)
+          return "{}" if dictionary.empty?
+
+          parts = dictionary.map { |key, value| "#{key}: #{format_value(value, nil, depth + 1)}" }
+          "{ #{parts.join(", ")} }"
+        end
+
+        def format_reference(reference)
+          return "<#{reference.prim_path}>" if reference.internal?
+
+          asset = format_asset(reference.asset_path)
+          reference.prim_path ? "#{asset}<#{reference.prim_path}>" : asset
+        end
+
+        def format_asset(asset)
+          delimiter = asset.path.include?("@") ? "@@@" : "@"
+          "#{delimiter}#{asset.path}#{delimiter}"
+        end
+
+        def format_number(number)
+          return "nan" if number.respond_to?(:nan?) && number.nan?
+          return number.negative? ? "-inf" : "inf" if number.respond_to?(:infinite?) && number.infinite?
+          return number.to_s unless number.is_a?(Float)
+
+          number.to_s
+        end
+
+        def infer_type(value)
+          return "bool" if [true, false].include?(value)
+          return "int" if value.is_a?(Integer)
+          return "double" if value.is_a?(Float)
+          return "asset" if value.is_a?(AssetPath)
+          return "token" if value.is_a?(Token)
+          return "string" if value.is_a?(String)
+
+          "string"
+        end
+
+        def quote(value)
+          escaped = value.to_s.gsub("\\", "\\\\").gsub("\"", "\\\"")
+                         .gsub("\n", "\\n").gsub("\r", "\\r").gsub("\t", "\\t")
+          "\"#{escaped}\""
+        end
+
+        def type_declaration(type_name)
+          type_name.nil? || type_name.empty? ? "" : " #{type_name}"
+        end
+
+        def attribute_prefix(attribute)
+          qualifiers = []
+          qualifiers << "custom" if attribute.custom
+          qualifiers << "uniform" if attribute.variability == :uniform
+          [*qualifiers, attribute.type_name, attribute.name].join(" ")
+        end
+
+        def reference_value(references)
+          references.length == 1 ? references.first : references
+        end
+
+        def write_references_metadata(metadata, prim)
+          value = reference_value(prim.references)
+          value = ListOp.new(prim.reference_list_op, value) if prim.reference_list_op
+          metadata["references"] = value
+        end
+
+        def unwrap_list_op(value)
+          return [value.operation, value.value] if value.is_a?(ListOp)
+
+          [nil, value]
+        end
+
+        def append(text, depth)
+          @lines << "#{INDENT * depth}#{text}"
+        end
+
+        def line
+          @lines << ""
+        end
+      end
+
+      Format::Registry.register("usda", reader: Reader, writer: Writer)
+      Format::Registry.register("usd", reader: Reader, writer: Writer)
+    end
+  end
+end

data/lib/openusd/format/usdz/reader.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "zlib"
+
+module OpenUSD
+  module Format
+    # USDZ package format support.
+    module Usdz
+      # Reads and validates the constrained ZIP representation used by USDZ.
+      class Reader
+        # Validated package entry.
+        Entry = Data.define(:name, :data, :data_offset)
+        # Virtual identifier for an entry inside a package.
+        PACKAGE_URI = /\A(.+\.usdz)\[([^\]]+)\]\z/i
+        # ZIP local-file-header signature.
+        LOCAL_SIGNATURE = 0x04034B50
+        # ZIP central-directory-entry signature.
+        CENTRAL_SIGNATURE = 0x02014B50
+        # ZIP end-of-central-directory signature.
+        END_SIGNATURE = 0x06054B50
+
+        class << self
+          # Read the default layer from a package.
+          # @return [Layer]
+          def read(path)
+            package = new(path)
+            root = package.entries.first
+            raise PackageError, "USDZ package is empty" unless root
+
+            parse_layer(package.path, root)
+          end
+
+          # Read a layer identified by a virtual package URI.
+          # @return [Layer]
+          def read_uri(uri)
+            package_path, entry_name = parse_uri(uri)
+            package = new(package_path)
+            entry = package.entry(entry_name)
+            raise PackageError, "package entry not found: #{entry_name}" unless entry
+
+            parse_layer(package.path, entry)
+          end
+
+          # Split a virtual package URI.
+          # @return [Array(String, String)] package path and entry name
+          def parse_uri(uri)
+            match = PACKAGE_URI.match(uri.to_s)
+            raise PackageError, "invalid package URI: #{uri}" unless match
+
+            [File.expand_path(match[1]), match[2]]
+          end
+
+          # Parse a validated package entry as USDA.
+          # @return [Layer]
+          def parse_layer(package_path, root)
+            extension = File.extname(root.name).downcase
+            raise NotSupportedError, "USDC root layers are not supported" if extension == ".usdc"
+            raise PackageError, "first USDZ entry must be a native USD layer" unless %w[.usd .usda].include?(extension)
+
+            layer = Format::Usda::Parser.parse(root.data.dup.force_encoding(Encoding::UTF_8),
+                                               file: "#{package_path}[#{root.name}]")
+            layer.identifier = "#{File.expand_path(package_path)}[#{root.name}]"
+            layer
+          end
+
+          # Extract a validated package.
+          # @return [Array<String>] extracted entry names
+          def unpack(path, destination:)
+            new(path).extract(destination)
+          end
+        end
+
+        attr_reader :path
+
+        def initialize(path)
+          @path = File.expand_path(path)
+          @archive = File.binread(@path)
+          @entries = nil
+        rescue Errno::ENOENT
+          raise PackageError, "package not found: #{path}"
+        end
+
+        # @return [Array<Entry>] validated entries in archive order
+        def entries
+          @entries ||= parse_entries.freeze
+        end
+
+        # Find an entry by its exact package path.
+        # @return [Entry, nil]
+        def entry(name)
+          entries.find { |candidate| candidate.name == name.to_s }
+        end
+
+        # Securely extract all entries below a destination.
+        # @return [Array<String>] extracted entry names
+        def extract(destination)
+          root = File.expand_path(destination)
+          entries.each do |entry|
+            output = File.expand_path(entry.name, root)
+            unless output.start_with?("#{root}#{File::SEPARATOR}")
+              raise PackageError, "unsafe package entry: #{entry.name.inspect}"
+            end
+
+            FileUtils.mkdir_p(File.dirname(output))
+            File.binwrite(output, entry.data)
+          end
+          entries.map(&:name)
+        end
+
+        private
+
+        def parse_entries
+          count, central_offset = end_directory
+          offset = central_offset
+          Array.new(count) do
+            entry, offset = parse_central_entry(offset)
+            entry
+          end
+        end
+
+        def end_directory
+          signature = [END_SIGNATURE].pack("V")
+          offset = @archive.rindex(signature, [@archive.bytesize - 22, 0].max)
+          raise PackageError, "missing ZIP end-of-directory record" unless offset
+
+          fields = bytes(offset, 22).unpack("VvvvvVVv")
+          _signature, disk, central_disk, disk_count, total_count, size, central_offset, comment_size = fields
+          unsupported = disk != 0 || central_disk != 0 || disk_count != total_count || comment_size != 0
+          raise PackageError, "multi-disk and commented ZIP files are not supported" if unsupported
+          raise PackageError, "invalid central directory bounds" if central_offset + size > offset
+
+          [total_count, central_offset]
+        end
+
+        def parse_central_entry(offset)
+          fields = bytes(offset, 46).unpack("VvvvvvvVVVvvvvvVV")
+          signature, _made, _needed, flags, method, _time, _date, crc, compressed_size,
+            size, name_size, extra_size, comment_size, _disk, _internal, _external, local_offset = fields
+          raise PackageError, "invalid central directory entry" unless signature == CENTRAL_SIGNATURE
+
+          validate_storage!(flags, method, compressed_size, size)
+
+          name = bytes(offset + 46, name_size).force_encoding(Encoding::UTF_8)
+          validate_name!(name)
+          data, data_offset = read_local_entry(local_offset, name, size, crc)
+          next_offset = offset + 46 + name_size + extra_size + comment_size
+          [Entry.new(name.freeze, data.freeze, data_offset), next_offset]
+        end
+
+        def read_local_entry(offset, expected_name, size, expected_crc)
+          fields = bytes(offset, 30).unpack("VvvvvvVVVvv")
+          signature, _needed, flags, method, _time, _date, crc, compressed_size,
+            local_size, name_size, extra_size = fields
+          raise PackageError, "invalid local ZIP header" unless signature == LOCAL_SIGNATURE
+
+          validate_storage!(flags, method, compressed_size, local_size)
+          raise PackageError, "central and local sizes differ" unless size == local_size
+
+          name = bytes(offset + 30, name_size).force_encoding(Encoding::UTF_8)
+          raise PackageError, "central and local names differ" unless name == expected_name
+
+          data_offset = offset + 30 + name_size + extra_size
+          raise PackageError, "USDZ entry is not 64-byte aligned" unless (data_offset % 64).zero?
+
+          data = bytes(data_offset, size)
+          actual_crc = Zlib.crc32(data)
+          raise PackageError, "CRC mismatch for #{name}" unless crc == expected_crc && crc == actual_crc
+
+          [data, data_offset]
+        end
+
+        def validate_storage!(flags, method, compressed_size, size)
+          raise PackageError, "encrypted ZIP entries are not supported" unless flags.nobits?(1)
+          raise PackageError, "USDZ entries must be uncompressed" unless method.zero? && compressed_size == size
+        end
+
+        def validate_name!(name)
+          parts = name.tr("\\", "/").split("/")
+          invalid = name.empty? || name.start_with?("/", "\\") || parts.include?("..")
+          raise PackageError, "unsafe package entry: #{name.inspect}" if invalid
+        end
+
+        def bytes(offset, length)
+          value = @archive.byteslice(offset, length)
+          raise PackageError, "truncated ZIP structure" unless value&.bytesize == length
+
+          value
+        end
+      end
+
+      Format::Registry.register("usdz", reader: Reader)
+    end
+  end
+end

data/lib/openusd/format/usdz/writer.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "zlib"
+
+module OpenUSD
+  module Format
+    module Usdz
+      # Writes uncompressed, 64-byte-aligned USDZ packages.
+      module Writer
+        # ZIP local-file-header signature.
+        LOCAL_SIGNATURE = 0x04034B50
+        # ZIP central-directory-entry signature.
+        CENTRAL_SIGNATURE = 0x02014B50
+        # ZIP end-of-central-directory signature.
+        END_SIGNATURE = 0x06054B50
+        # OpenUSD alignment extra-field identifier.
+        ALIGNMENT_EXTRA_ID = 0x1986
+        # Largest value representable by non-ZIP64 records.
+        UINT32_MAX = (2**32) - 1
+
+        module_function
+
+        # Package one in-memory layer as a USDZ file.
+        # @return [String] destination path
+        def write(layer, path)
+          root_name = "#{File.basename(path, File.extname(path))}.usda"
+          write_entries(path, [[root_name, layer.to_usda]])
+          path
+        end
+
+        # Package a root USD file and additional assets.
+        # @return [String] destination path
+        def pack(path, root:, assets: [])
+          root_path = File.expand_path(root)
+          validate_root!(root_path)
+          entries = [[File.basename(root_path), File.binread(root_path)]]
+          entries.concat(Array(assets).map { |asset| asset_entry(asset) })
+          write_entries(path, entries)
+          path
+        rescue Errno::ENOENT => e
+          raise PackageError, "package input not found: #{e.message}"
+        end
+
+        # Write preloaded `[name, bytes]` entries.
+        # @return [Integer] bytes written
+        def write_entries(path, entries)
+          validate_entries!(entries)
+          archive = String.new(encoding: Encoding::BINARY)
+          central_records = entries.map { |name, data| write_local_entry(archive, name, data.b) }
+          central_offset = archive.bytesize
+          central_records.each { |record| archive << central_header(record) }
+          central_size = archive.bytesize - central_offset
+          archive << end_record(entries.length, central_size, central_offset)
+          File.binwrite(path, archive)
+        end
+
+        def write_local_entry(archive, name, data)
+          name = name.encode(Encoding::UTF_8)
+          flags = name.ascii_only? ? 0 : (1 << 11)
+          crc = Zlib.crc32(data)
+          local_offset = archive.bytesize
+          extra = alignment_extra(local_offset + 30 + name.bytesize)
+          header = [
+            LOCAL_SIGNATURE, 10, flags, 0, 0, 0, crc,
+            data.bytesize, data.bytesize, name.bytesize, extra.bytesize
+          ].pack("VvvvvvVVVvv")
+          archive << header << name.b << extra << data
+          {
+            name: name, flags: flags, crc: crc, size: data.bytesize,
+            local_offset: local_offset
+          }
+        end
+        private_class_method :write_local_entry
+
+        def alignment_extra(base_offset)
+          extra_size = (-base_offset) % 64
+          extra_size += 64 if extra_size.positive? && extra_size < 4
+          return "".b if extra_size.zero?
+
+          [ALIGNMENT_EXTRA_ID, extra_size - 4].pack("vv") + ("\0".b * (extra_size - 4))
+        end
+        private_class_method :alignment_extra
+
+        def central_header(record)
+          name = record.fetch(:name)
+          [
+            CENTRAL_SIGNATURE, 20, 10, record.fetch(:flags), 0, 0, 0,
+            record.fetch(:crc), record.fetch(:size), record.fetch(:size),
+            name.bytesize, 0, 0, 0, 0, 0, record.fetch(:local_offset)
+          ].pack("VvvvvvvVVVvvvvvVV") + name.b
+        end
+        private_class_method :central_header
+
+        def end_record(count, central_size, central_offset)
+          [END_SIGNATURE, 0, 0, count, count, central_size, central_offset, 0].pack("VvvvvVVv")
+        end
+        private_class_method :end_record
+
+        def asset_entry(asset)
+          source, authored_name = asset.is_a?(Hash) ? asset.values_at(:source, :path) : [asset, asset]
+          source = File.expand_path(source)
+          name = Pathname.new(authored_name.to_s).absolute? ? File.basename(authored_name) : authored_name.to_s
+          [normalize_entry_name(name), File.binread(source)]
+        end
+        private_class_method :asset_entry
+
+        def validate_root!(path)
+          extension = File.extname(path).downcase
+          return if %w[.usd .usda .usdc].include?(extension)
+
+          raise PackageError, "USDZ root must be a .usd, .usda, or .usdc file"
+        end
+        private_class_method :validate_root!
+
+        def validate_entries!(entries)
+          raise PackageError, "USDZ package requires a root layer" if entries.empty?
+          raise PackageError, "too many ZIP entries" if entries.length > 65_535
+
+          names = entries.map do |name, data|
+            normalized = normalize_entry_name(name)
+            raise PackageError, "ZIP64 packages are not supported" if data.bytesize > UINT32_MAX
+
+            normalized
+          end
+          raise PackageError, "duplicate package entry" unless names.uniq.length == names.length
+        end
+        private_class_method :validate_entries!
+
+        def normalize_entry_name(name)
+          normalized = name.to_s.tr("\\", "/").delete_prefix("./")
+          parts = normalized.split("/")
+          invalid = normalized.empty? || normalized.start_with?("/") || parts.include?("..")
+          raise PackageError, "unsafe package entry: #{name.inspect}" if invalid
+          raise PackageError, "package entry name is too long" if normalized.bytesize > 65_535
+
+          normalized
+        end
+        private_class_method :normalize_entry_name
+      end
+
+      Format::Registry.register("usdz", writer: Writer)
+    end
+  end
+end