rgltf 1.0.0

data/lib/rgltf/writer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Writer
+    def initialize(document, validate: true)
+      @document = document
+      @validate = validate
+      return unless validate
+
+      result = Validator.validate(document)
+      return if result.errors.empty?
+
+      raise ValidationError, result.errors.map { |issue| "#{issue.path}: #{issue.message}" }.join('; ')
+    end
+
+    def to_glb
+      json, binary = serialized_payload
+      json.fetch('buffers', []).each { |buffer| buffer.delete('uri') }
+      GLB.write(JSON.generate(json), binary.empty? ? nil : binary)
+    end
+
+    def write_glb(path)
+      File.binwrite(path, to_glb)
+      path
+    rescue Errno::EACCES, Errno::ENOENT => e
+      raise MissingResourceError, e.message
+    end
+
+    def write_gltf(path, embed: false)
+      json, binary = serialized_payload
+      unless binary.empty?
+        if embed
+          json.fetch('buffers').first['uri'] = data_uri(binary)
+        else
+          extension = File.extname(path)
+          basename = File.basename(path, extension)
+          bin_path = File.join(File.dirname(path), "#{basename}.bin")
+          File.binwrite(bin_path, binary)
+          json.fetch('buffers').first['uri'] = File.basename(bin_path)
+        end
+      end
+      File.write(path, JSON.pretty_generate(json) << "\n")
+      path
+    rescue Errno::EACCES, Errno::ENOENT => e
+      raise MissingResourceError, e.message
+    end
+
+    private
+
+    def serialized_payload
+      copies = {}
+      json = deep_copy(@document.raw_json, copies)
+      owners = property_owners
+      ExtensionSerializer.new(@document, copies).apply!(owners)
+      DefaultOmitter.apply!(owners, copies)
+      binary = BufferMerger.new(@document).merge!(json)
+      validate_serialized!(json) if @validate
+      [json, binary]
+    end
+
+    def property_owners
+      roots = [@document.asset, *@document.class::COLLECTIONS.keys.flat_map do |key|
+        @document.public_send(key == 'bufferViews' ? :buffer_views : key)
+      end]
+      roots.flat_map { |owner| collect_owners(owner) }
+    end
+
+    def collect_owners(owner)
+      [owner, *owner.nested_properties.flat_map { |child| collect_owners(child) }]
+    end
+
+    def deep_copy(value, copies)
+      copy = case value
+             when Hash then value.to_h { |key, child| [key, deep_copy(child, copies)] }
+             when Array then value.map { |child| deep_copy(child, copies) }
+             when String then value.dup
+             else value
+             end
+      copies[value.object_id] = copy if value.is_a?(Hash)
+      copy
+    end
+
+    def data_uri(binary)
+      "data:application/octet-stream;base64,#{[binary].pack('m0')}"
+    end
+
+    def validate_serialized!(json)
+      result = Validator.validate(json)
+      return if result.errors.empty?
+
+      message = result.errors.map { |issue| "#{issue.path}: #{issue.message}" }.join('; ')
+      raise ValidationError, message
+    end
+  end
+end

data/lib/rgltf.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'rgltf/version'
+require_relative 'rgltf/errors'
+require_relative 'rgltf/glb'
+require_relative 'rgltf/extension'
+require_relative 'rgltf/buffer_resolver'
+require_relative 'rgltf/accessor_reader'
+require_relative 'rgltf/properties'
+require_relative 'rgltf/document'
+require_relative 'rgltf/extensions/khr_materials_unlit'
+require_relative 'rgltf/extensions/khr_texture_transform'
+require_relative 'rgltf/extensions/khr_lights_punctual'
+require_relative 'rgltf/extensions/khr_materials_emissive_strength'
+require_relative 'rgltf/validator'
+require_relative 'rgltf/writer/default_omitter'
+require_relative 'rgltf/writer/extension_serializer'
+require_relative 'rgltf/writer/buffer_merger'
+require_relative 'rgltf/writer'
+require_relative 'rgltf/builder'
+
+module Rgltf
+  class << self
+    def load(source, base_dir: nil, **options)
+      data, inferred_base_dir, inferred_format = read_source(source)
+      base_dir ||= inferred_base_dir
+
+      if inferred_format == :glb
+        raise FormatError, 'not a GLB (bad magic)' unless glb?(data)
+
+        load_glb(data, base_dir:, **options)
+      elsif glb?(data)
+        load_glb(data, base_dir:, **options)
+      else
+        load_json(data, base_dir:, **options)
+      end
+    rescue Errno::ENOENT, Errno::EACCES => e
+      raise MissingResourceError, e.message
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise FormatError, "could not load glTF: #{e.message}"
+    end
+
+    def load_glb(data, base_dir: nil, **options)
+      json, bin = GLB.read(binary_string(data))
+      load_json(json, base_dir:, glb_bin: bin, **options)
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise FormatError, "could not load GLB: #{e.message}"
+    end
+
+    def load_json(json, base_dir: nil, buffers: nil, glb_bin: nil, lazy: true,
+                  extensions: default_extensions, validate: false,
+                  strict_extensions: true)
+      parsed = json.is_a?(Hash) ? deep_copy(json) : JSON.parse(string_data(json))
+      validate_before_build!(parsed, supplied_buffers: buffers) if validate
+      Document.new(
+        parsed,
+        base_dir:,
+        supplied_buffers: buffers,
+        glb_bin:,
+        lazy:,
+        extension_registry: extensions,
+        validate:,
+        strict_extensions:
+      )
+    rescue JSON::ParserError => e
+      raise FormatError, "invalid glTF JSON: #{e.message}"
+    rescue FormatError => e
+      raise ValidationError, e.message if validate
+
+      raise
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise FormatError, "could not load glTF JSON: #{e.message}"
+    end
+
+    private
+
+    def read_source(source)
+      return [source.read, nil, nil] if source.respond_to?(:read)
+
+      value = string_data(source)
+      stripped = value.lstrip
+      return [value, nil, nil] if glb?(value.b) || stripped.start_with?('{', '[')
+
+      format = :glb if File.extname(value).casecmp?('.glb')
+      [File.binread(value), File.dirname(File.expand_path(value)), format]
+    end
+
+    def string_data(value)
+      return value.to_str if value.respond_to?(:to_str)
+
+      raise ArgumentError, 'expected a path, String, or IO-like object'
+    end
+
+    def binary_string(value)
+      string_data(value).b
+    end
+
+    def glb?(data)
+      data.bytesize >= 4 && data.byteslice(0, 4).unpack1('L<') == GLB::MAGIC
+    end
+
+    def deep_copy(value)
+      Marshal.load(Marshal.dump(value))
+    end
+
+    def validate_before_build!(json, supplied_buffers: nil)
+      result = Validator.validate(json)
+      errors = filter_supplied_buffer_errors(result.errors, supplied_buffers)
+      return if errors.empty?
+
+      message = errors.map { |issue| "#{issue.path}: #{issue.message}" }.join('; ')
+      raise ValidationError, message
+    end
+
+    def filter_supplied_buffer_errors(errors, supplied_buffers)
+      return errors unless supplied_buffers
+
+      resolver = BufferResolver.new(base_dir: nil, supplied_buffers:)
+      errors.reject do |issue|
+        match = %r{\Abuffers/(\d+)\z}.match(issue.path) if issue.code == :missing_buffer
+        match && resolver.send(:supplied?, match[1].to_i)
+      end
+    end
+  end
+end

data/tasks/sample_assets.rake

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'rake'
+
+namespace :sample_assets do
+  SHA = '2bac6f8c57bf471df0d2a1e8a8ec023c7801dddf'
+  URL = 'https://github.com/KhronosGroup/glTF-Sample-Assets.git'
+  DEFAULT_PATH = File.expand_path('../tmp/gltf-sample-assets', __dir__)
+
+  desc 'Clone and verify the pinned Khronos glTF-Sample-Assets revision'
+  task :fetch do
+    destination = ENV.fetch('GLTF_SAMPLE_ASSETS', DEFAULT_PATH)
+    managed = File.expand_path(destination) == DEFAULT_PATH
+    checkout = SampleAssetsCheckout.new(destination, URL, SHA)
+    managed ? checkout.prepare_managed : checkout.verify_custom
+    puts "glTF-Sample-Assets ready at #{destination} (#{SHA})"
+  end
+
+  desc 'Run the explicit and full pinned sample-asset acceptance suites'
+  task :verify do
+    root = ENV.fetch('GLTF_SAMPLE_ASSETS', nil)
+    abort 'GLTF_SAMPLE_ASSETS must point to a pinned checkout' if root.nil? || root.empty?
+
+    sh({ 'GLTF_SAMPLE_ASSETS' => File.expand_path(root) }, 'bundle', 'exec', 'rspec',
+       'spec/sample_assets_spec.rb', 'spec/sample_assets_full_spec.rb')
+  end
+
+  class SampleAssetsCheckout
+    def initialize(destination, url, sha)
+      @destination = destination
+      @url = url
+      @sha = sha
+    end
+
+    def prepare_managed
+      clone_fresh unless usable_repository?
+      refresh unless commit_available?
+      return checkout if checkout_successful?
+
+      clone_fresh
+      checkout
+    end
+
+    def verify_custom
+      raise "custom sample-assets path is not a git repository: #{@destination}" unless usable_repository?
+
+      dirty = capture('git', '-C', @destination, 'status', '--porcelain').strip
+      raise "custom sample-assets checkout must be clean: #{@destination}" unless dirty.empty?
+
+      actual = capture('git', '-C', @destination, 'rev-parse', 'HEAD').strip
+      raise "custom sample-assets checkout must be at #{@sha}, got #{actual}" unless actual == @sha
+    end
+
+    private
+
+    def usable_repository?
+      return false unless File.directory?(File.join(@destination, '.git'))
+
+      system('git', '-C', @destination, 'rev-parse', '--is-inside-work-tree',
+             out: File::NULL, err: File::NULL)
+    end
+
+    def commit_available?
+      system('git', '-C', @destination, 'cat-file', '-e', "#{@sha}^{commit}",
+             out: File::NULL, err: File::NULL)
+    end
+
+    def refresh
+      remove_stale_locks
+      run 'git', '-C', @destination, 'fetch', '--depth', '1', '--force', 'origin', @sha
+    end
+
+    def checkout
+      run 'git', '-C', @destination, 'checkout', '--detach', '--force', @sha
+      actual = capture('git', '-C', @destination, 'rev-parse', 'HEAD').strip
+      raise "sample-assets revision mismatch: #{actual}" unless actual == @sha
+
+      run 'git', '-C', @destination, 'submodule', 'update', '--init', '--recursive', '--depth', '1'
+    end
+
+    def checkout_successful?
+      remove_stale_locks
+      system('git', '-C', @destination, 'checkout', '--detach', '--force', @sha,
+             out: File::NULL, err: File::NULL)
+    end
+
+    def clone_fresh
+      temporary = "#{@destination}.new-#{Process.pid}"
+      FileUtils.rm_rf(temporary)
+      FileUtils.mkdir_p(File.dirname(@destination))
+      run 'git', 'clone', '--filter=blob:none', '--no-checkout', @url, temporary
+      run 'git', '-C', temporary, 'fetch', '--depth', '1', '--force', 'origin', @sha
+      FileUtils.rm_rf(@destination)
+      FileUtils.mv(temporary, @destination)
+    ensure
+      FileUtils.rm_rf(temporary) if temporary && File.exist?(temporary)
+    end
+
+    def remove_stale_locks
+      Dir[File.join(@destination, '.git', '**', '*.lock')].each { |path| FileUtils.rm_f(path) }
+    end
+
+    def run(*command)
+      raise "command failed: #{command.join(' ')}" unless system(*command)
+    end
+
+    def capture(*command)
+      IO.popen(command, &:read)
+    end
+  end
+end
+
+desc 'Clone and verify the pinned Khronos glTF sample assets'
+task sample_assets: 'sample_assets:fetch'

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: rgltf
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Loads and writes glTF 2.0 and GLB with GPU-ready packed binary accessors.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark/accessors.rb
+- benchmark/compare.rb
+- benchmark/sample_assets.rb
+- examples/README.md
+- examples/build_triangle.rb
+- examples/convert.rb
+- examples/inspect.rb
+- lib/rgltf.rb
+- lib/rgltf/accessor_reader.rb
+- lib/rgltf/buffer_resolver.rb
+- lib/rgltf/builder.rb
+- lib/rgltf/builder/accessor_data.rb
+- lib/rgltf/builder/accessors.rb
+- lib/rgltf/builder/component_builders.rb
+- lib/rgltf/builder/document_properties.rb
+- lib/rgltf/builder/materials.rb
+- lib/rgltf/document.rb
+- lib/rgltf/errors.rb
+- lib/rgltf/extension.rb
+- lib/rgltf/extensions/khr_lights_punctual.rb
+- lib/rgltf/extensions/khr_materials_emissive_strength.rb
+- lib/rgltf/extensions/khr_materials_unlit.rb
+- lib/rgltf/extensions/khr_texture_transform.rb
+- lib/rgltf/glb.rb
+- lib/rgltf/properties.rb
+- lib/rgltf/properties/accessor.rb
+- lib/rgltf/properties/animation.rb
+- lib/rgltf/properties/asset.rb
+- lib/rgltf/properties/base.rb
+- lib/rgltf/properties/buffer.rb
+- lib/rgltf/properties/buffer_view.rb
+- lib/rgltf/properties/camera.rb
+- lib/rgltf/properties/image.rb
+- lib/rgltf/properties/material.rb
+- lib/rgltf/properties/mesh.rb
+- lib/rgltf/properties/node.rb
+- lib/rgltf/properties/sampler.rb
+- lib/rgltf/properties/scene.rb
+- lib/rgltf/properties/skin.rb
+- lib/rgltf/properties/texture.rb
+- lib/rgltf/validation/accessors.rb
+- lib/rgltf/validation/animations.rb
+- lib/rgltf/validation/buffers.rb
+- lib/rgltf/validation/cameras.rb
+- lib/rgltf/validation/context.rb
+- lib/rgltf/validation/images_materials.rb
+- lib/rgltf/validation/meshes.rb
+- lib/rgltf/validation/root_asset_extensions.rb
+- lib/rgltf/validation/scenes_nodes.rb
+- lib/rgltf/validation/skins.rb
+- lib/rgltf/validator.rb
+- lib/rgltf/version.rb
+- lib/rgltf/writer.rb
+- lib/rgltf/writer/buffer_merger.rb
+- lib/rgltf/writer/default_omitter.rb
+- lib/rgltf/writer/extension_serializer.rb
+- tasks/sample_assets.rake
+homepage: https://github.com/ydah/rgltf
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/rgltf
+  source_code_uri: https://github.com/ydah/rgltf
+  changelog_uri: https://github.com/ydah/rgltf/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Pure Ruby glTF 2.0 loader and writer
+test_files: []