openusd 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18f311892663fd11d0b18ef824c6ad9b62265b06b4699f9c2e591f0d40024813
+  data.tar.gz: 565f39580b706c5fa4f0486ac256784fe8a9069a783ce052526b0463ffcc363f
+SHA512:
+  metadata.gz: '082ed57cb32bc359f49a9de3c5b5723f0b914de8bdf68932981fd26436b12451e21692546f12d1551d1a656e7fffb8e59db5274362c380869efd709034591257'
+  data.tar.gz: e78c9b71ee3d6a99cb27070a3cd1b53b31aee1804285d943f302993355f4537f96bc6feea33d5ee7c371af93a25200134d68b0e321a1a8fe78b0196957ba3893

data/.rubocop.yml

@@ -0,0 +1,47 @@
+AllCops:
+  CacheRootDirectory: tmp/rubocop_cache
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+    - "tmp/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "openusd.gemspec"
+
+Metrics/ClassLength:
+  Max: 260
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ParameterLists:
+  Max: 6
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Metrics/ModuleLength:
+  Max: 220
+
+Naming/AccessorMethodName:
+  Exclude:
+    - "lib/openusd/relationship.rb"
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--output-dir doc
+--protected
+-
+README.md

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,163 @@
+# openusd
+
+`openusd` is a Pure Ruby library for reading, composing, editing, and writing
+OpenUSD ASCII (`.usda`) and package (`.usdz`) assets. It requires Ruby 3.2 or
+newer and has no runtime gem or native-library dependencies.
+
+Version 1.0 focuses on pipeline automation, validation, conversion, and scene
+generation. It supports sublayers and references, but it is not a replacement
+for the complete C++ OpenUSD composition engine.
+
+## Installation
+
+Add the gem to your bundle:
+
+```bash
+bundle add openusd
+```
+
+Or install it directly:
+
+```bash
+gem install openusd
+```
+
+## Create and save a stage
+
+```ruby
+require "openusd"
+
+stage = OpenUSD::Stage.create("scene.usda")
+stage.define_prim("/World", "Xform")
+cube = stage.define_prim("/World/Cube", "Cube")
+cube.create_attribute("size", "double").set(2.0)
+cube.create_attribute("xformOp:translate", "double3").set([0, 1, 0])
+cube.create_relationship("target").set_targets(["/World"])
+
+stage.root_layer.metadata.merge!(
+  "defaultPrim" => "World",
+  "metersPerUnit" => 1.0,
+  "upAxis" => "Y"
+)
+stage.save
+```
+
+## Open and traverse a composed stage
+
+```ruby
+stage = OpenUSD::Stage.open("scene.usda")
+
+stage.traverse do |prim|
+  puts "#{prim.path} <#{prim.type_name}>"
+end
+
+size = stage.prim_at("/World/Cube").attribute("size").get
+```
+
+`Stage.open(path, missing_assets: :warn)` warns and skips unresolved sublayers
+or references. The default policy, `:error`, raises
+`OpenUSD::CompositionError`; `:ignore` silently skips them.
+
+## Time samples and metadata
+
+```ruby
+prim = stage.prim_at("/World/Cube")
+attribute = prim.create_attribute("animatedSize", "double")
+attribute.set(1.0, time: 0)
+attribute.set(3.0, time: 24)
+
+attribute.get(time: 12) # => 2.0
+prim.metadata["kind"] = "component"
+attribute.metadata["documentation"] = "Animated cube size"
+```
+
+## Schema helpers
+
+```ruby
+xform = OpenUSD::Schema::Xform.define(stage, "/World/Model")
+xform.translate = [0, 2, 0]
+xform.scale = [2, 2, 2]
+
+mesh = OpenUSD::Schema::Mesh.define(stage, "/World/Model/Mesh")
+mesh.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
+mesh.face_vertex_counts = [3]
+mesh.face_vertex_indices = [0, 1, 2]
+```
+
+## USDZ
+
+Package an existing root layer and its assets:
+
+```ruby
+OpenUSD::Format::Usdz::Writer.pack(
+  "scene.usdz",
+  root: "scene.usda",
+  assets: ["textures/albedo.png"]
+)
+```
+
+Every entry is stored without compression and begins at a 64-byte boundary.
+The reader validates bounds, CRC values, alignment, encryption/compression
+flags, and extraction paths.
+
+```ruby
+stage = OpenUSD::Stage.open("scene.usdz")
+OpenUSD::Format::Usdz::Reader.unpack("scene.usdz", destination: "unpacked")
+```
+
+## Command line
+
+```text
+openusd cat scene.usda
+openusd cat --output formatted.usda scene.usda
+openusd tree scene.usdz
+openusd zip scene.usdz scene.usda textures/albedo.png
+```
+
+The repository includes a reproducible
+[CLI smoke-test procedure](docs/CLI_SMOKE_TEST.md) covering all three
+subcommands and official validation of their outputs.
+
+## Supported scope
+
+Version 1.0 supports:
+
+- USDA layer metadata, prims, typed attributes, relationships, time samples,
+  dictionaries, connections, references, and variant selections
+- deterministic USDA output and semantic round trips
+- root layer → authored sublayers → references composition strength
+- stored ZIP32 USDZ packages with internal USDA references
+- Xform, Mesh, Camera, Material, and Scope conveniences
+
+Version 1.0 does not support USDC (Crate), payloads, inherits, specializes, full
+list-edit semantics, Hydra/imaging, or concurrent writes to one Stage. Separate
+stages and concurrent read-only access are safe as long as application code
+does not mutate their underlying Layers.
+
+Unknown USDA value types and metadata are retained where the parser can
+represent their syntax, which allows newer authored data to survive a
+parse/write round trip.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+bundle exec rake lint
+bundle exec rake doc
+bundle exec rake compatibility # requires usdchecker and usdcat on PATH
+bundle exec rake golden:update  # intentionally refresh exact writer baselines
+bundle exec rake bench
+```
+
+The compatibility task validates generated USDA and USDZ files with the
+official `usdchecker`, then parses every golden USDA output with `usdcat`.
+In CI, where the `usd-core` wheel does not install those executables, the task
+uses the equivalent official `UsdValidation` and `Sdf` Python APIs.
+The benchmark defaults to 100,000 generated prims and a 1,000,000-vertex Mesh,
+reports elapsed time and resident-memory growth, and enforces a five-second
+100,000-Prim budget. Set `PRIMS`, `VERTICES`, or `PRIM_BUDGET` to adjust it.
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "fileutils"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "tmpdir"
+require "yard"
+require "yard/rake/yardoc_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new(:lint)
+
+YARD::Rake::YardocTask.new(:doc) do |task|
+  task.files = ["lib/**/*.rb", "exe/openusd"]
+end
+
+desc "Run the USDA parser benchmark"
+task :bench do
+  ruby "-Ilib", "benchmark/parser.rb"
+end
+
+namespace :golden do
+  desc "Regenerate deterministic USDA golden files"
+  task :update do
+    require_relative "lib/openusd"
+
+    source_root = File.expand_path("spec/fixtures", __dir__)
+    destination = File.join(source_root, "golden")
+    FileUtils.mkdir_p(destination)
+    Dir[File.join(source_root, "{,upstream/}*.usda")].each do |source|
+      name = source.delete_prefix("#{source_root}/").tr("/", "__")
+      File.binwrite(File.join(destination, name), OpenUSD::Layer.open(source).to_usda)
+    end
+  end
+end
+
+module CompatibilityTask
+  extend Rake::DSL
+
+  module_function
+
+  def write_assets(directory)
+    usda_path = File.join(directory, "scene.usda")
+    usdz_path = File.join(directory, "scene.usdz")
+    stage = OpenUSD::Stage.create(usda_path)
+    stage.define_prim("/World", "Xform")
+    mesh = OpenUSD::Schema::Mesh.define(stage, "/World/Mesh")
+    mesh.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
+    mesh.face_vertex_counts = [3]
+    mesh.face_vertex_indices = [0, 1, 2]
+    mesh.extent = [[0, 0, 0], [1, 1, 0]]
+    stage.root_layer.metadata.merge!(
+      "defaultPrim" => "World", "metersPerUnit" => 1.0, "upAxis" => "Y"
+    )
+    stage.save
+    stage.export(usdz_path)
+    [usda_path, usdz_path]
+  end
+
+  def validate(assets)
+    python = ENV.fetch("USD_CORE_PYTHON", nil)
+    return validate_with_python(python, assets) if python
+
+    assets.each { |path| sh ENV.fetch("USDCHECKER", "usdchecker"), path }
+    usdcat = ENV.fetch("USDCAT", "usdcat")
+    golden_paths.each { |path| sh usdcat, path, out: File::NULL }
+  end
+
+  def validate_with_python(python, assets)
+    validator = File.expand_path("spec/support/usd_core_check.py", __dir__)
+    sh python, validator, "validate", *assets
+    sh python, validator, "parse", *golden_paths
+  end
+
+  def golden_paths
+    Dir[File.expand_path("spec/fixtures/golden/*.usda", __dir__)]
+  end
+end
+
+desc "Validate generated USDA and USDZ with the official usdchecker"
+task :compatibility do
+  require_relative "lib/openusd"
+
+  Dir.mktmpdir("openusd-compatibility") do |directory|
+    CompatibilityTask.validate(CompatibilityTask.write_assets(directory))
+  end
+end
+
+task default: %i[spec lint]

data/benchmark/RESULTS.md

@@ -0,0 +1,16 @@
+# Parser benchmark results
+
+The benchmark is generated in memory and can be reproduced with:
+
+```bash
+bundle exec rake bench
+```
+
+## 2026-07-28
+
+- Environment: Ruby 4.0.0, arm64 Darwin 25.3.0
+- 100,000 Prim layer: 1.351 seconds, resident memory +147.1 MiB
+- 1,000,000-vertex Mesh: 2.093 seconds, resident memory +208.5 MiB
+
+Resident-memory growth is sampled immediately before and after each parse.
+Results vary by Ruby version, allocator, hardware, and concurrent system load.

data/benchmark/parser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "openusd"
+
+def resident_megabytes
+  if File.file?("/proc/self/status")
+    kilobytes = File.read("/proc/self/status")[/^VmRSS:\s+(\d+)/, 1]
+    return kilobytes.to_i / 1024.0 if kilobytes
+  end
+
+  output = IO.popen(["ps", "-o", "rss=", "-p", Process.pid.to_s], &:read)
+  Integer(output, 10) / 1024.0
+rescue Errno::ENOENT, ArgumentError
+  nil
+end
+
+def measure(label)
+  GC.start
+  memory_before = resident_megabytes
+  started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  result = yield
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+  memory_after = resident_megabytes
+  memory = memory_before && memory_after ? format(", RSS +%.1f MiB", memory_after - memory_before) : ""
+  puts "#{label} in #{format("%.3f", elapsed)} seconds#{memory}"
+  [result, elapsed]
+end
+
+def run_prim_benchmark
+  prim_count = Integer(ENV.fetch("PRIMS", "100000"))
+  body = String.new(capacity: prim_count * 22)
+  prim_count.times { |index| body << "def Xform \"P#{index}\" {}\n" }
+  source = "#usda 1.0\n#{body}"
+
+  layer, elapsed = measure("Parsed #{prim_count} prims") { OpenUSD::Format::Usda::Parser.parse(source) }
+  raise "prim benchmark parsed the wrong count" unless layer.root_prims.length == prim_count
+
+  budget = Float(ENV.fetch("PRIM_BUDGET", "5"))
+  raise "prim benchmark exceeded #{budget} seconds" if elapsed > budget
+end
+
+def run_mesh_benchmark
+  vertex_count = Integer(ENV.fetch("VERTICES", "1000000"))
+  points = "(0, 0, 0)," * vertex_count
+  source = "#usda 1.0\ndef Mesh \"Mesh\" { point3f[] points = [#{points}] }"
+  layer, = measure("Parsed #{vertex_count} Mesh vertices") { OpenUSD::Format::Usda::Parser.parse(source) }
+  parsed_points = layer.prim_at("/Mesh").property_named("points").default
+  raise "mesh benchmark parsed the wrong vertex count" unless parsed_points.length == vertex_count
+end
+
+run_prim_benchmark
+GC.start
+run_mesh_benchmark

data/docs/CLI_SMOKE_TEST.md

@@ -0,0 +1,29 @@
+# CLI smoke test
+
+Run these commands from the repository root after `bundle install`.
+
+```bash
+work_dir="$(mktemp -d)"
+
+bundle exec exe/openusd cat \
+  --output "$work_dir/formatted.usda" \
+  spec/fixtures/layer_metadata.usda
+
+bundle exec exe/openusd tree spec/fixtures/nested_prims.usda
+
+bundle exec exe/openusd zip \
+  "$work_dir/scene.usdz" \
+  spec/fixtures/layer_metadata.usda
+
+usdchecker "$work_dir/formatted.usda"
+usdchecker "$work_dir/scene.usdz"
+```
+
+Expected results:
+
+- `cat` exits successfully and writes a deterministic USDA layer.
+- `tree` prints `World`, its `Geometry` child, and the nested `Cube`.
+- `zip` exits successfully and creates an uncompressed, aligned USDZ package.
+- Both `usdchecker` commands report `Success!`.
+
+The temporary directory can be deleted after inspection.

data/exe/openusd

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "openusd"
+
+exit OpenUSD::CLI.new.run(ARGV)

data/lib/openusd/asset_resolver.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module OpenUSD
+  # Resolves authored asset paths relative to their containing layer.
+  class AssetResolver
+    # Supported unresolved-asset behaviors.
+    MISSING_POLICIES = %i[error warn ignore].freeze
+
+    attr_reader :search_paths, :missing_assets
+
+    def initialize(search_paths: [], missing_assets: :error)
+      @search_paths = search_paths.map { |path| File.expand_path(path) }.freeze
+      @missing_assets = missing_assets.to_sym
+      return if MISSING_POLICIES.include?(@missing_assets)
+
+      raise ArgumentError, "invalid missing-assets policy: #{missing_assets.inspect}"
+    end
+
+    # Resolve an asset path, optionally anchored to a layer identifier.
+    # @return [String, nil]
+    def resolve(asset_path, anchor: nil)
+      authored = asset_path.is_a?(AssetPath) ? asset_path.path : asset_path.to_s
+      return resolve_package_asset(authored, anchor) if package_uri?(anchor)
+      return File.expand_path(anchor) if authored.empty? && anchor
+
+      resolved = candidates(authored, anchor).find { |candidate| File.file?(candidate) }
+      return resolved if resolved
+
+      missing(authored, anchor)
+    end
+
+    private
+
+    def package_uri?(value)
+      value&.match?(/\A.+\.usdz\[[^\]]+\]\z/i)
+    end
+
+    def resolve_package_asset(authored, anchor)
+      package, entry_name = Format::Usdz::Reader.parse_uri(anchor)
+      normalized = File.expand_path(authored, "/#{File.dirname(entry_name)}").delete_prefix("/")
+      unsafe = normalized.start_with?("../") || authored.start_with?("/")
+      return missing(authored, anchor) if unsafe
+
+      return "#{package}[#{normalized}]" if Format::Usdz::Reader.new(package).entry(normalized)
+
+      missing(authored, anchor)
+    end
+
+    def candidates(authored, anchor)
+      return [File.expand_path(authored)] if Pathname.new(authored).absolute?
+
+      roots = []
+      roots << File.dirname(File.expand_path(anchor)) if anchor && !anchor.start_with?("anonymous:")
+      roots.concat(search_paths)
+      roots << Dir.pwd if roots.empty?
+      roots.uniq.map { |root| File.expand_path(authored, root) }
+    end
+
+    def missing(authored, anchor)
+      message = "asset not found: #{authored.inspect}"
+      message += " (relative to #{anchor})" if anchor
+      raise CompositionError, message if missing_assets == :error
+
+      warn(message) if missing_assets == :warn
+      nil
+    end
+  end
+end

data/lib/openusd/attribute.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module OpenUSD
+  # Composed attribute view on a Stage.
+  class Attribute
+    attr_reader :prim, :name
+
+    def initialize(prim, name)
+      @prim = prim
+      @name = name.to_s
+    end
+
+    # @return [String, nil] strongest authored USD type name
+    def type_name
+      opinions.first&.type_name
+    end
+
+    # Get the default or a time-sampled value.
+    # @param time [Numeric, nil]
+    # @return [Object, nil]
+    def get(time: nil)
+      return default_value if time.nil?
+
+      sampled_value(Float(time))
+    rescue ArgumentError, ::TypeError
+      raise OpenUSD::TypeError, "time must be numeric"
+    end
+
+    # Author a default or time-sampled value in the edit target.
+    # @return [Object] input value
+    def set(value, time: nil)
+      authored_spec.set(value, time: time)
+      prim.stage.invalidate!
+      value
+    end
+
+    # @return [Hash{Float => Object}] composed samples in time order
+    def time_samples
+      opinions.find(&:time_samples_authored?)&.time_samples || {}
+    end
+
+    # @return [Array<Path>] strongest authored connections
+    def connections
+      opinions.find(&:connections_authored?)&.connections || []
+    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(AttributeSpec)
+    end
+
+    def default_value
+      opinions.find(&:default_authored?)&.default
+    end
+
+    def sampled_value(time)
+      opinion = opinions.find(&:time_samples_authored?)
+      return default_value unless opinion
+
+      samples = opinion.time_samples
+      return default_value if samples.empty?
+      return samples[time] if samples.key?(time)
+
+      interpolate_samples(samples, time)
+    end
+
+    def interpolate_samples(samples, time)
+      times = samples.keys
+      return samples[times.first] if time <= times.first
+      return samples[times.last] if time >= times.last
+
+      upper = times.find { |sample_time| sample_time > time }
+      lower = times[times.index(upper) - 1]
+      interpolate(samples[lower], samples[upper], (time - lower) / (upper - lower))
+    end
+
+    def interpolate(left, right, alpha)
+      return left + ((right - left) * alpha) if left.is_a?(Numeric) && right.is_a?(Numeric)
+      if left.is_a?(Array) && right.is_a?(Array) && left.length == right.length
+        return left.zip(right).map { |a, b| interpolate(a, b, alpha) }
+      end
+
+      left
+    end
+
+    def authored_spec
+      prim.stage.author_attribute(prim.path, name, type_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