rgltf 1.0.0

data/lib/rgltf/validation/root_asset_extensions.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Validation
+    class RootAssetExtensions < Rule
+      ROOT_ARRAYS = %w[accessors animations buffers bufferViews cameras images materials meshes nodes
+                       samplers scenes skins textures extensionsUsed extensionsRequired].freeze
+
+      def validate
+        validate_root_arrays
+        validate_asset
+        validate_extensions
+        validate_extension_shapes(@json)
+        reference('scenes', @json['scene'], 'scene') if @json.key?('scene')
+      end
+
+      private
+
+      def validate_root_arrays
+        ROOT_ARRAYS.each do |key|
+          next unless @json.key?(key)
+
+          if @json[key].is_a?(Array)
+            error(:empty_root_collection, key, 'must not be empty when present') if @json[key].empty?
+            next
+          end
+
+          error(:invalid_type, key, 'must be an array')
+        end
+        return unless @json.key?('extensions') && !@json['extensions'].is_a?(Hash)
+
+        error(:invalid_type, 'extensions',
+              'must be an object')
+      end
+
+      def validate_asset
+        unless @json.key?('asset')
+          error(:asset_missing, 'asset', 'is required')
+          return
+        end
+        asset = object(@json['asset'], 'asset')
+        version = asset['version']
+        unless version.is_a?(String) && version.match?(/\A2\.\d+\z/)
+          error(:invalid_asset_version, 'asset/version', 'must identify glTF 2.x')
+        end
+        min = asset['minVersion']
+        %w[copyright generator].each do |key|
+          error(:invalid_type, "asset/#{key}", 'must be a string') if asset.key?(key) && !asset[key].is_a?(String)
+        end
+        return if min.nil?
+
+        unless min.is_a?(String) && min.match?(/\A2\.\d+\z/)
+          error(:invalid_min_version, 'asset/minVersion', 'must identify glTF 2.x')
+          return
+        end
+        return unless version.is_a?(String) && version.match?(/\A2\.\d+\z/)
+
+        comparison = min.split('.').map(&:to_i) <=> version.split('.').map(&:to_i)
+        return if comparison && comparison <= 0
+
+        error(:invalid_min_version, 'asset/minVersion', 'must not exceed asset version')
+      end
+
+      def validate_extensions
+        used = string_set('extensionsUsed')
+        required = string_set('extensionsRequired')
+        (required - used).each do |name|
+          error(:required_extension_not_used, 'extensionsRequired', "#{name} must also appear in extensionsUsed")
+        end
+        collect_extension_names(@json).uniq.each do |name|
+          unless used.include?(name)
+            warning(:undeclared_extension, 'extensionsUsed',
+                    "#{name} is used but not declared")
+          end
+        end
+        registry = context.document&.extension_registry
+        return unless registry
+
+        required.reject { |name| registry.known?(name) }.each do |name|
+          warning(:unsupported_required_extension, 'extensionsRequired', "#{name} is not registered")
+        end
+      end
+
+      def string_set(key)
+        values = array(key)
+        values.each_with_index do |value, index|
+          error(:invalid_extension_name, "#{key}/#{index}", 'must be a string') unless value.is_a?(String)
+        end
+        duplicates = values.select { |value| values.count(value) > 1 }.uniq
+        duplicates.each { |value| error(:duplicate_extension, key, "contains duplicate #{value.inspect}") }
+        values.grep(String)
+      end
+
+      def collect_extension_names(value, names = [])
+        case value
+        when Hash
+          names.concat(value['extensions'].keys.grep(String)) if value['extensions'].is_a?(Hash)
+          value.each_value { |child| collect_extension_names(child, names) }
+        when Array
+          value.each { |child| collect_extension_names(child, names) }
+        end
+        names
+      end
+
+      def validate_extension_shapes(value, path = '')
+        case value
+        when Hash
+          extensions = value['extensions']
+          if value.key?('extensions') && !extensions.is_a?(Hash)
+            error(:invalid_extensions, join(path, 'extensions'), 'must be an object')
+          elsif extensions
+            extensions.each do |name, payload|
+              unless name.is_a?(String) && !name.empty?
+                error(:invalid_extension_name, join(path, 'extensions'),
+                      'extension names must be non-empty strings')
+              end
+              unless payload.is_a?(Hash)
+                error(:invalid_extension_payload, join(path, "extensions/#{name}"),
+                      'must be an object')
+              end
+            end
+          end
+          value.each { |key, child| validate_extension_shapes(child, join(path, key)) }
+        when Array
+          value.each_with_index { |child, index| validate_extension_shapes(child, join(path, index)) }
+        end
+      end
+
+      def join(path, segment)
+        path.empty? ? segment.to_s : "#{path}/#{segment}"
+      end
+    end
+  end
+end

data/lib/rgltf/validation/scenes_nodes.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Validation
+    class ScenesNodes < Rule
+      def validate
+        validate_scenes
+        validate_nodes
+        validate_hierarchy
+      end
+
+      private
+
+      def validate_scenes
+        array('scenes').each_with_index do |raw, scene_index|
+          scene = object(raw, "scenes/#{scene_index}")
+          nodes = scene.fetch('nodes', [])
+          unless nodes.is_a?(Array)
+            error(:invalid_type, "scenes/#{scene_index}/nodes", 'must be an array')
+            next
+          end
+          validate_unique(nodes, "scenes/#{scene_index}/nodes", :duplicate_scene_node)
+          nodes.each_with_index do |node, index|
+            reference('nodes', node, "scenes/#{scene_index}/nodes/#{index}", required: true)
+          end
+        end
+      end
+
+      def validate_nodes
+        array('nodes').each_with_index do |raw, node_index|
+          node = object(raw, "nodes/#{node_index}")
+          path = "nodes/#{node_index}"
+          validate_transform(node, path)
+          %w[mesh skin camera].each do |key|
+            reference((key == 'mesh' ? 'meshes' : "#{key}s").to_s, node[key], "#{path}/#{key}") if node.key?(key)
+          end
+          if node.key?('skin') && !node.key?('mesh')
+            warning(:skin_without_mesh, "#{path}/skin",
+                    'skin has no effect without a mesh on the same node')
+          end
+          validate_children(node.fetch('children', []), node_index, path)
+          validate_node_weights(node, path)
+        end
+      end
+
+      def validate_transform(node, path)
+        trs = %w[translation rotation scale].any? { |key| node.key?(key) }
+        error(:matrix_trs_conflict, path, 'cannot define both matrix and TRS') if node.key?('matrix') && trs
+        context.numeric_array(node['matrix'], 16, "#{path}/matrix") if node.key?('matrix')
+        context.numeric_array(node['translation'], 3, "#{path}/translation") if node.key?('translation')
+        context.numeric_array(node['scale'], 3, "#{path}/scale") if node.key?('scale')
+        return unless node.key?('rotation') && context.numeric_array(node['rotation'], 4, "#{path}/rotation")
+
+        magnitude = Math.sqrt(node['rotation'].sum { |value| value * value })
+        return if (magnitude - 1.0).abs <= 1e-3
+
+        error(:rotation_not_normalized, "#{path}/rotation",
+              'quaternion must have unit length')
+      end
+
+      def validate_children(children, node_index, path)
+        unless children.is_a?(Array)
+          error(:invalid_type, "#{path}/children", 'must be an array')
+          return
+        end
+        validate_unique(children, "#{path}/children", :duplicate_child)
+        children.each_with_index do |child, index|
+          reference('nodes', child, "#{path}/children/#{index}", required: true)
+          if child == node_index
+            error(:node_self_reference, "#{path}/children/#{index}",
+                  'node cannot be its own child')
+          end
+        end
+      end
+
+      def validate_node_weights(node, path)
+        return unless node.key?('weights')
+
+        weights = node['weights']
+        unless weights.is_a?(Array) && weights.all? { |weight| finite?(weight) }
+          error(:invalid_node_weights, "#{path}/weights", 'must be an array of finite numbers')
+          return
+        end
+        mesh = array('meshes')[node['mesh']] if node['mesh'].is_a?(Integer)
+        targets = mesh&.dig('primitives', 0, 'targets')
+        return unless targets.is_a?(Array) && weights.length != targets.length
+
+        error(:node_weights_count_mismatch, "#{path}/weights", 'count must equal morph target count')
+      end
+
+      def validate_hierarchy
+        parents = Hash.new { |hash, key| hash[key] = [] }
+        array('nodes').each_with_index do |node, parent|
+          next unless node.is_a?(Hash) && node['children'].is_a?(Array)
+
+          node['children'].grep(Integer).each do |child|
+            parents[child] << parent if child.between?(0, array('nodes').length - 1)
+          end
+        end
+        parents.each do |child, values|
+          error(:node_multiple_parents, "nodes/#{child}", 'node has more than one parent') if values.uniq.length > 1
+        end
+        array('scenes').each_with_index do |scene, scene_index|
+          next unless scene.is_a?(Hash) && scene['nodes'].is_a?(Array)
+
+          scene['nodes'].each_with_index do |root, root_index|
+            next unless root.is_a?(Integer) && parents[root].any?
+
+            error(:scene_node_has_parent, "scenes/#{scene_index}/nodes/#{root_index}",
+                  'scene root node must not have a parent')
+          end
+        end
+        visiting = {}
+        visited = {}
+        array('nodes').each_index { |index| visit(index, visiting, visited) }
+      end
+
+      def visit(index, visiting, visited)
+        return if visited[index]
+
+        if visiting[index]
+          error(:node_cycle, "nodes/#{index}/children", 'node hierarchy contains a cycle')
+          return
+        end
+        visiting[index] = true
+        node = array('nodes')[index]
+        children = node.is_a?(Hash) && node['children'].is_a?(Array) ? node['children'] : []
+        children.grep(Integer).each do |child|
+          visit(child, visiting, visited) if child.between?(0, array('nodes').length - 1)
+        end
+        visiting.delete(index)
+        visited[index] = true
+      end
+
+      def validate_unique(values, path, code)
+        duplicates = values.select { |value| values.count(value) > 1 }.uniq
+        duplicates.each { |value| error(code, path, "contains duplicate #{value.inspect}") }
+      end
+    end
+  end
+end

data/lib/rgltf/validation/skins.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Rgltf
+  module Validation
+    class Skins < Rule
+      def validate
+        array('skins').each_with_index { |raw, index| validate_skin(object(raw, "skins/#{index}"), index) }
+        validate_skinned_meshes
+      end
+
+      private
+
+      def validate_skin(skin, index)
+        path = "skins/#{index}"
+        joints = skin['joints']
+        unless joints.is_a?(Array) && !joints.empty?
+          error(:skin_joints_missing, "#{path}/joints", 'must be a non-empty array')
+          joints = []
+        end
+        duplicates = joints.select { |joint| joints.count(joint) > 1 }.uniq
+        duplicates.each do |joint|
+          error(:duplicate_skin_joint, "#{path}/joints", "contains duplicate #{joint.inspect}")
+        end
+        joints.each_with_index do |joint, position|
+          reference('nodes', joint, "#{path}/joints/#{position}", required: true)
+        end
+        reference('nodes', skin['skeleton'], "#{path}/skeleton") if skin.key?('skeleton')
+        validate_skeleton(skin['skeleton'], joints, path) if skin['skeleton'].is_a?(Integer)
+        return unless skin.key?('inverseBindMatrices')
+
+        validate_inverse_bind_matrices(skin['inverseBindMatrices'], joints.length,
+                                       path)
+      end
+
+      def validate_inverse_bind_matrices(index, joint_count, path)
+        return unless reference('accessors', index, "#{path}/inverseBindMatrices", required: true)
+
+        accessor = array('accessors')[index]
+        return unless accessor.is_a?(Hash)
+
+        valid = accessor['componentType'] == 5126 && accessor['type'] == 'MAT4' && !accessor.fetch('normalized', false)
+        unless valid
+          error(:invalid_inverse_bind_matrices, "#{path}/inverseBindMatrices",
+                'must be a non-normalized MAT4 FLOAT accessor')
+        end
+        return unless accessor['count'].is_a?(Integer) && accessor['count'] < joint_count
+
+        error(:inverse_bind_count_mismatch, "#{path}/inverseBindMatrices", 'count must be at least joint count')
+      end
+
+      def validate_skeleton(skeleton, joints, path)
+        return unless skeleton.between?(0, array('nodes').length - 1)
+
+        descendants = collect_descendants(skeleton, {})
+        joints.grep(Integer).each do |joint|
+          unless descendants[joint]
+            error(:joint_outside_skeleton, "#{path}/joints",
+                  "joint #{joint} is not below skeleton")
+          end
+        end
+      end
+
+      def collect_descendants(index, found)
+        return found if found[index]
+
+        found[index] = true
+        node = array('nodes')[index]
+        children = node.is_a?(Hash) && node['children'].is_a?(Array) ? node['children'] : []
+        children.grep(Integer).each do |child|
+          collect_descendants(child, found) if child.between?(0, array('nodes').length - 1)
+        end
+        found
+      end
+
+      def validate_skinned_meshes
+        array('nodes').each_with_index do |node, node_index|
+          next unless node.is_a?(Hash) && node.key?('skin') && node['mesh'].is_a?(Integer)
+
+          mesh = array('meshes')[node['mesh']]
+          next unless mesh.is_a?(Hash) && mesh['primitives'].is_a?(Array)
+
+          mesh['primitives'].each_with_index do |primitive, primitive_index|
+            attributes = primitive.is_a?(Hash) ? primitive['attributes'] : nil
+            next if attributes.is_a?(Hash) && attributes.key?('JOINTS_0') && attributes.key?('WEIGHTS_0')
+
+            error(:skinned_primitive_attributes_missing,
+                  "nodes/#{node_index}/mesh/primitives/#{primitive_index}/attributes",
+                  'skinned primitives must define JOINTS_0 and WEIGHTS_0')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgltf/validator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'validation/context'
+require_relative 'validation/root_asset_extensions'
+require_relative 'validation/buffers'
+require_relative 'validation/accessors'
+require_relative 'validation/images_materials'
+require_relative 'validation/meshes'
+require_relative 'validation/scenes_nodes'
+require_relative 'validation/skins'
+require_relative 'validation/animations'
+require_relative 'validation/cameras'
+
+module Rgltf
+  class Validator
+    Issue = Struct.new(:code, :path, :message, keyword_init: true)
+    Result = Struct.new(:errors, :warnings, keyword_init: true) do
+      def valid?
+        errors.empty?
+      end
+    end
+
+    RULES = [
+      Validation::RootAssetExtensions,
+      Validation::Buffers,
+      Validation::Accessors,
+      Validation::ImagesMaterials,
+      Validation::Meshes,
+      Validation::ScenesNodes,
+      Validation::Skins,
+      Validation::Animations,
+      Validation::Cameras
+    ].freeze
+
+    class << self
+      def validate(value)
+        document = value if value.respond_to?(:raw_json)
+        json = document ? document.raw_json : value
+        context = Validation::Context.new(json, document:)
+        RULES.each { |rule| run_rule(rule, context) }
+        Result.new(errors: context.errors.freeze, warnings: context.warnings.freeze)
+      end
+
+      private
+
+      def run_rule(rule, context)
+        rule.new(context).validate
+      rescue StandardError => e
+        context.error(:validation_rule_failure, '', "#{rule.name.split('::').last} could not validate: #{e.message}")
+      end
+    end
+  end
+end

data/lib/rgltf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rgltf
+  VERSION = '1.0.0'
+end

data/lib/rgltf/writer/buffer_merger.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Writer
+    class BufferMerger
+      attr_reader :binary, :offsets
+
+      def initialize(document)
+        @document = document
+        @binary = String.new(encoding: Encoding::BINARY)
+        @offsets = []
+      end
+
+      def merge!(json)
+        append_buffers
+        remap_buffer_views!(json)
+        remap_meshopt!(json)
+        replace_buffers!(json)
+        binary
+      end
+
+      private
+
+      def append_buffers
+        @document.buffers.each do |buffer|
+          binary << ("\0" * ((4 - (binary.bytesize % 4)) % 4))
+          offsets << binary.bytesize
+          binary << buffer_payload(buffer)
+        end
+      end
+
+      def buffer_payload(buffer)
+        return "\0" * buffer.byte_length if buffer.send(:meshopt_decode_target?)
+
+        buffer.bytes.byteslice(0, buffer.byte_length)
+      end
+
+      def remap_buffer_views!(json)
+        json.fetch('bufferViews', []).each do |view|
+          source = view.fetch('buffer')
+          view['byteOffset'] = view.fetch('byteOffset', 0) + offsets.fetch(source)
+          view['buffer'] = 0
+          view.delete('byteOffset') if view['byteOffset'].zero?
+        end
+      end
+
+      def remap_meshopt!(json)
+        json.fetch('bufferViews', []).each do |view|
+          meshopt_extensions.each { |name| remap_meshopt_extension!(view.dig('extensions', name)) }
+        end
+      end
+
+      def meshopt_extensions
+        Buffer.const_get(:MESHOPT_EXTENSIONS, false)
+      end
+
+      def remap_meshopt_extension!(meshopt)
+        return unless meshopt.is_a?(Hash) && meshopt['buffer'].is_a?(Integer)
+
+        source = meshopt.fetch('buffer')
+        meshopt['byteOffset'] = meshopt.fetch('byteOffset', 0) + offsets.fetch(source)
+        meshopt['buffer'] = 0
+      end
+
+      def replace_buffers!(json)
+        return json.delete('buffers') if binary.empty?
+
+        json['buffers'] = [{ 'byteLength' => binary.bytesize }]
+      end
+    end
+  end
+end

data/lib/rgltf/writer/default_omitter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Writer
+    class DefaultOmitter
+      DEFAULTS = {
+        accessor: { 'byteOffset' => 0, 'normalized' => false },
+        buffer_view: { 'byteOffset' => 0 },
+        primitive: { 'mode' => 4 },
+        sampler: { 'wrapS' => 10_497, 'wrapT' => 10_497 },
+        texture_info: { 'texCoord' => 0 },
+        pbr_metallic_roughness: {
+          'baseColorFactor' => [1.0, 1.0, 1.0, 1.0],
+          'metallicFactor' => 1.0,
+          'roughnessFactor' => 1.0
+        },
+        material: {
+          'emissiveFactor' => [0.0, 0.0, 0.0],
+          'alphaMode' => 'OPAQUE',
+          'alphaCutoff' => 0.5,
+          'doubleSided' => false
+        },
+        node: {
+          'translation' => [0.0, 0.0, 0.0],
+          'rotation' => [0.0, 0.0, 0.0, 1.0],
+          'scale' => [1.0, 1.0, 1.0]
+        },
+        animation_sampler: { 'interpolation' => 'LINEAR' }
+      }.freeze
+
+      def self.apply!(owners, copies)
+        owners.each do |owner|
+          json = copies[owner.source_json.object_id]
+          next unless json
+
+          DEFAULTS.fetch(owner.owner_type, {}).each do |key, default|
+            json.delete(key) if json[key] == default
+          end
+          omit_texture_info_defaults!(owner, json)
+        end
+      end
+
+      def self.omit_texture_info_defaults!(owner, json)
+        json.delete('scale') if owner.is_a?(NormalTextureInfo) && json['scale'] == 1.0
+        json.delete('strength') if owner.is_a?(OcclusionTextureInfo) && json['strength'] == 1.0
+      end
+
+      private_class_method :omit_texture_info_defaults!
+    end
+  end
+end

data/lib/rgltf/writer/extension_serializer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rgltf
+  class Writer
+    class ExtensionSerializer
+      def initialize(document, copies)
+        @document = document
+        @copies = copies
+      end
+
+      def apply!(owners)
+        serialize_extensions!(@copies.fetch(@document.raw_json.object_id), :document, @document.extensions)
+        owners.each do |owner|
+          json = @copies[owner.source_json.object_id]
+          next unless json
+
+          serialize_extensions!(json, owner.owner_type, owner.extensions)
+        end
+      end
+
+      private
+
+      def serialize_extensions!(json, owner_type, extensions)
+        return unless json['extensions']
+
+        extensions.each do |name, object|
+          next unless @document.extension_registry.registered_on?(name, on: owner_type)
+
+          original = json['extensions'][name]
+          serialized = @document.extension_registry.serialize(
+            name, object, on: owner_type, doc: @document
+          )
+          json['extensions'][name] = merge_serialized(original, serialized)
+        end
+      end
+
+      def merge_serialized(original, serialized)
+        if serialized.is_a?(Extension::SerializedProperties)
+          return replace_handled_properties(original, serialized.value, serialized.handled_keys)
+        end
+        return deep_copy(serialized) unless original.is_a?(Hash) && serialized.is_a?(Hash)
+
+        deep_copy(original).merge(deep_copy(serialized))
+      end
+
+      def replace_handled_properties(original, replacement, handled_keys)
+        return deep_copy(replacement) unless original.is_a?(Hash) && replacement.is_a?(Hash)
+
+        output = deep_copy(original)
+        handled_keys.each { |key| output.delete(key) }
+        output.merge!(deep_copy(replacement))
+      end
+
+      def deep_copy(value)
+        case value
+        when Hash then value.to_h { |key, child| [key, deep_copy(child)] }
+        when Array then value.map { |child| deep_copy(child) }
+        when String then value.dup
+        else value
+        end
+      end
+    end
+  end
+end