assimp-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5462e51936b49a449b8092dbc3245eae7470f526941d28adf38edacc724c8d8
+  data.tar.gz: 4198ab6d851dfc478bd72af3db20acec391cb93c0f394ca9c42a01d842796f84
+SHA512:
+  metadata.gz: 7c4fae0a2dc08713fce49dc09b071f69d5ccd8db526af3974082fc7da1ccb111d9ecffbf0c87daf7579578a78267d36784f6242f82ab1812ae7e05907e1b6900
+  data.tar.gz: 26d77fd5e810ffad4d6a17ba50626fd53867c08c4b8f4854dc977f8008f2dcb77ad9277538ede0ea73cbe9a368da34b399c694bdad6c83b3e5ca5ec1635528e5

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,170 @@
+# assimp-ruby
+
+Ruby bindings for [Assimp](https://github.com/assimp/assimp), providing one
+import API for OBJ, FBX, STL, PLY, DAE, 3DS, glTF, and the other formats
+supported by Assimp.
+
+`Assimp.import` copies native scene data into packed Ruby strings and immutable
+Ruby objects, then immediately calls `aiReleaseImport`. Returned scenes do not
+retain pointers or other native resources.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- `ffi` 1.17
+
+Install the gem:
+
+```sh
+bundle add assimp-ruby
+```
+
+Platform gems bundle Assimp 5.4.3 for x86-64 and ARM64 Linux, Intel and Apple
+Silicon macOS, and x64 Windows. The source gem remains available for other
+platforms and searches the system for `assimp`, `libassimp.so.5`, or
+`libassimp.5.dylib`. Set an explicit path when Assimp is installed elsewhere:
+
+```sh
+export ASSIMP_LIBRARY_PATH=/path/to/libassimp.so.5
+```
+
+The major version is checked when the first import runs. Assimp 6.x is rejected
+because its ABI differs from the 5.x ABI.
+
+## Importing
+
+```ruby
+require "assimp"
+
+scene = Assimp.import("model.fbx")
+scene = Assimp.import(
+  "model.obj",
+  process: %i[triangulate gen_smooth_normals flip_uvs]
+)
+
+bytes = File.binread("mesh.stl")
+scene = Assimp.import(bytes, hint: "stl")
+```
+
+Memory and IO inputs require an extension hint. File imports should be used
+when a format needs to resolve external resources such as MTL files or images.
+
+The post-process presets are:
+
+- `:realtime` (default): triangulation, vertex joining, smooth normals,
+  tangents, bone-weight limiting, cache optimization, and primitive sorting
+- `:fast`: triangulation, vertex joining, and generated normals
+- `:none`: no post-processing
+
+Every key in `Assimp::POST_PROCESS` can also be passed in an explicit array.
+
+## Scene data
+
+```ruby
+scene.meshes
+scene.materials
+scene.root
+scene.animations
+scene.textures
+scene.incomplete?
+
+scene.each_mesh_instance do |mesh, world_matrix|
+  # world_matrix is a 16-element, column-major array
+end
+```
+
+Mesh attributes are little-endian packed strings:
+
+- `positions`, `normals`: `f32x3`
+- `tangents`: `f32x4`, including handedness in `w`
+- `uv_sets`: `f32x2`
+- `colors`: `f32x4`
+- `indices`: `u32`
+
+```ruby
+mesh = scene.meshes.first
+positions = mesh.positions.unpack("e*")
+indices = mesh.indices.unpack("L<*")
+mesh.aabb
+mesh.bones
+```
+
+Materials expose normalized common values and retain every native key-value
+property as an escape hatch:
+
+```ruby
+material = scene.materials.first
+material.name
+material.base_color
+material.metallic
+material.roughness
+material.opacity
+material.two_sided?
+
+texture = material.texture(:diffuse)
+texture.path
+texture.embedded_index
+
+material["$clr.diffuse"]
+material["$tex.file", semantic: 1, index: 0]
+```
+
+Animation values use `Assimp::Vec3` and `Assimp::Quat` (`x, y, z, w`):
+
+```ruby
+animation = scene.animations.first
+animation.duration_ticks
+animation.effective_ticks_per_second
+animation.channels.first.rotation_keys
+```
+
+## Embedded images
+
+Compressed embedded images retain their encoded bytes and format hint. Raw
+images retain Assimp's BGRA bytes together with their width and height.
+Applications can pass this neutral data to an image library of their choice.
+
+## Raw mode
+
+For very large files, block-scoped raw access avoids the Ruby copy:
+
+```ruby
+Assimp.open("large.fbx") do |raw|
+  raw.native    # guarded Assimp::Native::Scene view
+  raw.meshes    # guarded non-owning FFI struct views
+end
+```
+
+All top-level raw views raise `Assimp::ReleasedError` when used after the block
+exits. Nested native structs and pointers must not be retained beyond the block.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+
+ASSIMP_LIBRARY_PATH=/path/to/libassimp.so.5 bundle exec rspec
+ASSIMP_LIBRARY_PATH=/path/to/libassimp.so.5 \
+  ASSIMP_STRESS=1 bundle exec rspec spec/stress_spec.rb
+```
+
+The stress suite performs 1,000 imports under `GC.stress`. Test fixtures cover
+OBJ, ASCII and binary STL, PLY, and FBX. Regenerate deterministic text/binary
+fixtures with `bundle exec rake fixtures:generate`. ABI checks verify all
+generated Assimp 5.4 struct layouts against a C compiler.
+
+Build and smoke-test a native platform gem from Assimp 5.4.3:
+
+```sh
+bundle exec rake native:smoke_gem
+```
+
+Set `ASSIMP_SOURCE_DIR` to reuse an Assimp source checkout, or
+`ASSIMP_LIBRARY_PATH` to package an already-built compatible shared library.
+Tagged releases build and verify source plus platform gems for all five
+supported platform/architecture combinations before publishing.
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "rspec/core/rake_task"
+require "shellwords"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :fixtures do
+  desc "Generate deterministic OBJ, STL, and PLY fixtures"
+  task :generate do
+    require_relative "spec/support/fixture_builder"
+    FixtureBuilder.generate
+  end
+
+  desc "Fail if generated fixtures are stale"
+  task :check do
+    require_relative "spec/support/fixture_builder"
+    stale = FixtureBuilder.stale
+    abort "generated fixtures are stale: #{stale.join(", ")}" unless stale.empty?
+  end
+end
+
+namespace :generator do
+  desc "Regenerate Assimp FFI declarations and the native layout probe"
+  task :generate do
+    sh(RbConfig.ruby, File.join(__dir__, "generator", "generate.rb"))
+  end
+
+  desc "Fail if generated FFI declarations are stale"
+  task :check do
+    sh(RbConfig.ruby, File.join(__dir__, "generator", "generate.rb"), "--check")
+  end
+end
+
+namespace :native do
+  desc "Verify every generated FFI struct against the C compiler"
+  task verify_layout: "generator:check" do
+    include_dir = ENV.fetch("ASSIMP_INCLUDE_DIR")
+    config_include_dir = ENV.fetch("ASSIMP_CONFIG_INCLUDE_DIR", include_dir)
+    directory = File.join(__dir__, "tmp", "layout")
+    FileUtils.mkdir_p(directory)
+    executable = File.join(directory, "layout_probe#{RbConfig::CONFIG.fetch("EXEEXT")}")
+    compiler = Shellwords.split(ENV.fetch("CC", RbConfig::CONFIG.fetch("CC")))
+    sh(
+      *compiler,
+      "-std=c11",
+      "-I#{config_include_dir}",
+      "-I#{include_dir}",
+      File.join(__dir__, "generator", "layout_probe.c"),
+      "-o", executable
+    )
+    output, status = Open3.capture2e(executable)
+    raise "layout probe failed:\n#{output}" unless status.success?
+
+    output_path = File.join(directory, "layouts.tsv")
+    File.binwrite(output_path, output)
+    sh(RbConfig.ruby, File.join(__dir__, "generator", "verify_layout.rb"), output_path)
+  end
+end
+
+task spec: "fixtures:check"
+task default: :spec

data/generator/generate.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "ffi/clang"
+require "open3"
+
+class BindingGenerator
+  ROOT = File.expand_path("..", __dir__)
+  RUBY_OUTPUT = File.join(ROOT, "lib", "assimp", "native", "generated.rb")
+  PROBE_OUTPUT = File.join(__dir__, "layout_probe.c")
+  HEADERS = %w[scene.h cimport.h material.h postprocess.h version.h].freeze
+  INTEGER_TYPES = {
+    type_char_u: :char,
+    type_char_s: :char,
+    type_schar: :int8,
+    type_uchar: :uchar,
+    type_short: :int16,
+    type_ushort: :uint16,
+    type_int: :int,
+    type_uint: :uint,
+    type_long: :long,
+    type_ulong: :ulong,
+    type_longlong: :int64,
+    type_ulonglong: :uint64
+  }.freeze
+  CLASS_NAMES = { "aiString" => "StringValue" }.freeze
+  FIELD_NAMES = {
+    ["aiTexture", "achFormatHint"] => "format_hint",
+    ["aiTexture", "pcData"] => "data"
+  }.freeze
+
+  def initialize
+    @include_dir = locate_include_dir
+    @config_include_dir = locate_config_include_dir
+    @translation_units = HEADERS.map { |header| parse(header) }
+    verify_supported_headers!
+  end
+
+  def run(check: false)
+    outputs = { RUBY_OUTPUT => render_ruby, PROBE_OUTPUT => render_probe }
+    if check
+      stale = outputs.filter_map { |path, content| path unless File.binread(path) == content }
+      abort "generated bindings are stale: #{stale.join(", ")}" unless stale.empty?
+      return
+    end
+
+    outputs.each { |path, content| File.binwrite(path, content) }
+  end
+
+  private
+
+  def locate_include_dir
+    explicit = ENV["ASSIMP_INCLUDE_DIR"]
+    candidates = [
+      explicit,
+      pkg_config_include_dir,
+      "/opt/homebrew/include",
+      "/usr/local/include",
+      "/usr/include"
+    ].compact
+    candidates.find { |directory| File.file?(File.join(directory, "assimp", "scene.h")) } ||
+      abort("Assimp headers were not found; set ASSIMP_INCLUDE_DIR")
+  end
+
+  def locate_config_include_dir
+    explicit = ENV["ASSIMP_CONFIG_INCLUDE_DIR"]
+    candidates = [explicit, @include_dir].compact
+    candidates.find { |directory| File.file?(File.join(directory, "assimp", "config.h")) } ||
+      abort("Assimp config.h was not found; set ASSIMP_CONFIG_INCLUDE_DIR")
+  end
+
+  def pkg_config_include_dir
+    output, status = Open3.capture2("pkg-config", "--variable=includedir", "assimp")
+    output.strip if status.success?
+  rescue Errno::ENOENT
+    nil
+  end
+
+  def parse(header)
+    path = File.join(@include_dir, "assimp", header)
+    unit = FFI::Clang::Index.new.parse_translation_unit(
+      path, ["-x", "c", "-I#{@config_include_dir}", "-I#{@include_dir}"]
+    )
+    errors = unit.diagnostics.select { |diagnostic| %i[error fatal].include?(diagnostic.severity) }
+    abort errors.map(&:spelling).join("\n") unless errors.empty?
+
+    unit
+  end
+
+  def declarations(kind)
+    @translation_units.flat_map do |unit|
+      unit.cursor.each.filter_map do |cursor, _parent|
+        next unless cursor.kind == kind
+        next unless cursor.location.file.to_s.start_with?(File.join(@include_dir, "assimp"))
+
+        cursor
+      end
+    end
+  end
+
+  def records
+    declarations(:cursor_struct)
+      .select { |cursor| cursor.definition? && cursor.spelling.start_with?("ai") }
+      .uniq(&:spelling)
+  end
+
+  def enums
+    declarations(:cursor_enum_decl)
+      .select { |cursor| cursor.definition? && cursor.spelling.start_with?("ai") }
+      .uniq(&:spelling)
+  end
+
+  def fields(record)
+    record.each(false).filter_map do |cursor, _parent|
+      cursor if cursor.kind == :cursor_field_decl
+    end
+  end
+
+  def enum_values(enum)
+    enum.each(false).filter_map do |cursor, _parent|
+      [cursor.spelling, cursor.enum_value] if cursor.kind == :cursor_enum_constant_decl
+    end
+  end
+
+  def sorted_records
+    remaining = records.to_h { |record| [record.spelling, record] }
+    sorted = []
+    until remaining.empty?
+      ready = remaining.values.select do |record|
+        record_dependencies(record).none? { |name| remaining.key?(name) }
+      end
+      abort "cyclic struct dependency: #{remaining.keys.join(", ")}" if ready.empty?
+
+      ready.sort_by(&:spelling).each do |record|
+        sorted << record
+        remaining.delete(record.spelling)
+      end
+    end
+    sorted
+  end
+
+  def record_dependencies(record)
+    fields(record).filter_map do |field|
+      type = field.type.canonical
+      type = type.element_type.canonical if type.kind == :type_constant_array
+      record_type_name(type) if type.kind == :type_record && record_type_name(type) != record.spelling
+    end.uniq
+  end
+
+  def verify_supported_headers!
+    record_names = records.map(&:spelling)
+    required_records = %w[aiScene aiMesh aiBone aiNode aiAnimation aiTexture]
+    missing = required_records - record_names
+    abort "incomplete Assimp headers: #{missing.join(", ")}" unless missing.empty?
+
+    quat_key = records.find { |record| record.spelling == "aiQuatKey" }
+    scene = records.find { |record| record.spelling == "aiScene" }
+    unless fields(quat_key).any? { |field| field.spelling == "mInterpolation" } &&
+           fields(scene).any? { |field| field.spelling == "mNumSkeletons" }
+      abort "Assimp 5.4 headers are required to regenerate bindings"
+    end
+  end
+
+  def render_ruby
+    lines = [
+      "# frozen_string_literal: true",
+      "",
+      "# Generated from Assimp 5.4 headers by generator/generate.rb.",
+      "# Do not edit this file directly.",
+      "",
+      "require \"ffi\"",
+      "",
+      "module Assimp",
+      "  module Native"
+    ]
+    sorted_records.each { |record| render_record(lines, record) }
+    render_enums(lines)
+    render_layouts(lines)
+    lines.concat ["  end", "end", ""]
+    lines.join("\n")
+  end
+
+  def render_record(lines, record)
+    lines << ""
+    lines << "    class #{ruby_class_name(record.spelling)} < FFI::Struct"
+    layout = fields(record).flat_map do |field|
+      [":#{ruby_field_name(record.spelling, field.spelling)}", ruby_type(field.type, field: true)]
+    end
+    if layout.empty?
+      lines << "    end"
+      return
+    end
+
+    lines << "      layout #{layout.each_slice(2).map { |pair| pair.join(", ") }.join(",\n             ")}"
+    lines << "    end"
+  end
+
+  def render_enums(lines)
+    lines << ""
+    lines << "    ENUMS = {"
+    enums.sort_by(&:spelling).each do |enum|
+      values = enum_values(enum).map { |name, value| "#{name.inspect} => #{value}" }
+      lines << "      #{enum.spelling.inspect} => { #{values.join(", ")} }.freeze,"
+    end
+    lines << "    }.freeze"
+    lines << ""
+    lines << "    POST_PROCESS = {"
+    post_process = enums.find { |enum| enum.spelling == "aiPostProcessSteps" }
+    enum_values(post_process).each do |name, value|
+      ruby_name = snake_case(name.delete_prefix("aiProcess_"))
+      lines << "      #{ruby_name}: #{format_hex(value & 0xffff_ffff)},"
+    end
+    lines << "    }.freeze"
+  end
+
+  def render_layouts(lines)
+    lines << ""
+    lines << "    HEADER_LAYOUTS = {"
+    sorted_records.each do |record|
+      offsets = fields(record).map do |field|
+        "#{ruby_field_name(record.spelling, field.spelling)}: #{field.offset_of_field / 8}"
+      end
+      lines << "      #{record.spelling.inspect} => [#{record.type.sizeof}, { #{offsets.join(", ")} }.freeze],"
+    end
+    lines << "    }.freeze"
+  end
+
+  def render_probe
+    lines = [
+      "/* Generated from Assimp 5.4 headers by generator/generate.rb. */",
+      "/* Do not edit this file directly. */",
+      "#include <stddef.h>",
+      "#include <stdio.h>",
+      "#include <assimp/cimport.h>",
+      "#include <assimp/scene.h>",
+      "",
+      "int main(void) {"
+    ]
+    sorted_records.each do |record|
+      lines << %(  printf("S\\t#{record.spelling}\\t%zu\\n", sizeof(struct #{record.spelling}));)
+      fields(record).each do |field|
+        ruby_name = ruby_field_name(record.spelling, field.spelling)
+        lines << %(  printf("F\\t#{record.spelling}\\t#{ruby_name}\\t%zu\\n", offsetof(struct #{record.spelling}, #{field.spelling}));)
+      end
+    end
+    lines.concat ["  return 0;", "}", ""]
+    lines.join("\n")
+  end
+
+  def ruby_type(type, field: false)
+    canonical = type.canonical
+    kind = canonical.kind
+    return ":pointer" if kind == :type_pointer
+    return ":float" if kind == :type_float
+    return ":double" if kind == :type_double
+    return ":int" if kind == :type_enum
+    return INTEGER_TYPES.fetch(kind).inspect if INTEGER_TYPES.key?(kind)
+    return "#{ruby_class_name(record_type_name(canonical))}.by_value" if kind == :type_record
+    if kind == :type_constant_array
+      return "[#{ruby_type(canonical.element_type, field: true)}, #{canonical.size}]"
+    end
+
+    abort "unsupported C type: #{type.spelling} (#{kind}, field=#{field})"
+  end
+
+  def ruby_class_name(c_name)
+    CLASS_NAMES.fetch(c_name, c_name.delete_prefix("ai"))
+  end
+
+  def record_type_name(type)
+    type.spelling.delete_prefix("struct ")
+  end
+
+  def ruby_field_name(record_name, field_name)
+    special = FIELD_NAMES[[record_name, field_name]]
+    return special if special
+
+    normalized = field_name.sub(/\Am(?=[A-Z])/, "")
+    snake_case(normalized)
+  end
+
+  def snake_case(name)
+    name
+      .gsub("UV", "Uv")
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .downcase
+  end
+
+  def format_hex(value)
+    return value.to_s if value < 16
+
+    groups = value.to_s(16).reverse.scan(/.{1,4}/).map(&:reverse).reverse
+    "0x#{groups.join("_")}"
+  end
+end
+
+BindingGenerator.new.run(check: ARGV.delete("--check"))