md2 1.0.0

data/lib/md2/command.rb

@@ -0,0 +1,63 @@
+# This class is instantiated from the C extension. You shouldn't have to instantiate it directly.
+#
+# GL Commands are an optimization technique employed by MD2 files to improve render time. The
+# MD2 file contains a span of bytes equal to the MD2::Header#gl_command_count. Those bytes in
+# turn have the following format:
+#
+#   1. How many bytes follow for a single GL command. This is an integer, so the data need to be
+#      cast into an integer in order to be processed.
+#
+#      This byte also indicates the render method for this GL command: if it's positive,
+#      this is a triangle strip; if it's negative, a triangle fan. If zero, this byte
+#      represents the end of the command list. Terminating bytes are silently omitted
+#      by this Ruby library.
+#   2. The horizontal texture coordinate. This is a float, so the data needs to be cast into a
+#      float to be processed.
+#   3. The vertical texture coordinate. This is a float, so the data needs to be cast into a
+#      float to be processed.
+#   4. The vertex index to be rendered. This is an integer, so the data needs to be cast into
+#      an integer to be processed.
+#
+# As the data are cast into the necessary types, the boundaries of any given command structure
+# must be adjusted to match. I was not able to find a way to do this using pure Ruby, so the
+# bulk of the above algorithm is implemented in this gem's C extension.
+#
+# This class is only instantiated after the fact, with the data already deserialized.
+#
+class MD2::Command
+  # A data structure containing a single #texture_s, #texture_t and #vertex_index.
+  class Segment
+    attr_reader :texture_s, :texture_t, :vertex_index
+    def initialize(s, t, index)
+      @texture_s, @texture_t, @vertex_index = s, t, index
+    end
+  end
+  
+  # The type of command. This is equal to either :triangle_strip or :triangle_fan.
+  attr_reader :type
+  
+  # an array of segments, each an instance of MD2::Command::Segment. Segments contain the vertex and texture data
+  # for this command.
+  attr_reader :segments
+  
+  # Arguments are expected to be a single array with the following content:
+  #   [ (:triangle_strip|:triangle_fan), *elements ]
+  #
+  # The remainder of the elements are expected to appear in this order:
+  #   (s_coord, t_coord, vert_index)
+  #
+  # So, the elements are expected to be in groups of 3: the s and t texture coordinates (which are Floats),
+  # and the vertex index (which is a Fixnum).
+  #
+  # The array of args is expected to be a single, flat array -- the data should not be nested
+  # into other arrays.
+  #
+  def initialize(args)
+    @type = args.shift
+    @segments = []
+    
+    0.step(args.length-1, 3) do |index|
+      @segments << MD2::Command::Segment.new(args[index], args[index+1], args[index+2])
+    end
+  end
+end

data/lib/md2/errors.rb

@@ -0,0 +1,13 @@
+module MD2::Errors
+  # Not raised directly: this is a superclass for all other MD2 errors.
+  class Error < ::StandardError
+  end
+  
+  # Raised when the specified file is invalid: for instance, when it is not an MD2 file.
+  class InvalidFile < Error
+  end
+  
+  # Raised when the file format version specified in the header is not what was expected.
+  class InvalidVersion < Error
+  end
+end

data/lib/md2/frame.rb

@@ -0,0 +1,61 @@
+class MD2::Frame
+  # Float[3] containing X, Y, Z scale values
+  attr_reader :scale
+  
+  # Float[3] containing X, Y, Z translations
+  attr_reader :translation
+  
+  # The name of this frame (string)
+  attr_reader :name
+  
+  # The vertices for this frame.
+  attr_reader :vertices
+  
+  # The indices of the normal vectors.
+  attr_reader :normal_indices
+  
+  def reduce
+    {        
+      :name => name,
+      :translation => @translation,
+      :scale => @scale,
+      :vertices => packed_vertices,
+      :normal_indices => normal_indices.flatten
+    }
+  end
+  
+  def initialize(frame_data)
+    @scale = []
+    @translation = []
+    @vertices = []
+    @normal_indices = []
+    
+    # 3 floats (scale), 3 floats (transl), 16 bytes (name), and variable num of unsigned chars (vertices)
+    frame_data = frame_data.unpack("f3f3a16C*")
+    3.times { @scale << frame_data.shift }
+    3.times { @translation << frame_data.shift }
+    @name = frame_data.shift.strip
+    while !frame_data.empty?
+      packed_vertex = MD2::Vertex.new(frame_data.shift, frame_data.shift, frame_data.shift)
+      @vertices << unpack_vertex_data(packed_vertex)
+      @normal_indices << frame_data.shift
+    end
+  end
+  
+  private
+  def packed_vertices
+    vertices.collect do |vert|
+      [ ((vert[0] - @translation[0]) / @scale[0]).to_i,
+        ((vert[1] - @translation[1]) / @scale[1]).to_i,
+        ((vert[2] - @translation[2]) / @scale[2]).to_i ]
+    end.flatten
+  end
+  
+  def unpack_vertex_data(packed_vertex)
+    3.times do |i|
+      packed_vertex[i] = (packed_vertex[i] * @scale[i]) + @translation[i]
+    end
+    
+    packed_vertex
+  end
+end

data/lib/md2/header.rb

@@ -0,0 +1,37 @@
+class MD2::Header
+  # The length of an MD2 header is fixed.
+  LENGTH = 68
+  
+  # The magic number that all MD2 headers start with. This is equal to "IDP2" in bytes.
+  MD2_IDENT = ((?2.ord<<24) + (?P.ord<<16) + (?D.ord<<8) + ?I.ord) # we use #ord because of Ruby 1.9
+  
+  # The MD2 file format version. This is always 8.
+  MD2_VERSION = 8
+  
+  attr_reader :skin_width, :skin_height, :frame_size, :skin_count, :vertex_count,
+              :texture_coord_count, :triangle_count, :gl_command_count, :frame_count,
+              :skin_name_offset, :texture_coord_offset, :triangle_offset, :frame_data_offset,
+              :gl_command_offset, :eof_offset
+  
+  def initialize(file)
+    header = file.sysread(LENGTH).unpack("i17")
+    raise MD2::Errors::InvalidFile, "Header identifier did not match" unless header.shift == MD2_IDENT
+    raise MD2::Errors::InvalidVersion, "File format version mismatch" unless header.shift == MD2_VERSION
+    
+    @skin_width           = header.shift
+    @skin_height          = header.shift
+    @frame_size           = header.shift
+    @skin_count           = header.shift
+    @vertex_count         = header.shift
+    @texture_coord_count  = header.shift
+    @triangle_count       = header.shift
+    @gl_command_count     = header.shift
+    @frame_count          = header.shift
+    @skin_name_offset     = header.shift
+    @texture_coord_offset = header.shift
+    @triangle_offset      = header.shift
+    @frame_data_offset    = header.shift
+    @gl_command_offset    = header.shift
+    @eof_offset           = header.shift
+  end
+end

data/lib/md2/normals.rb

@@ -0,0 +1,81 @@
+class MD2
+  # For your convenience: NORMALS is an array of arrays which contain X, Y and Z float values.
+  #
+  # This is the same for every MD2 file, and is referenced by the normal indices within the model data.
+  #
+  # You can get this data with simply:
+  #
+  #   MD2::Normals[index]
+  #
+  # or you can use its longer variant:
+  #
+  #   MD2::Normals::NORMALS[index].
+  #
+  class Normals
+    class << self
+      delegate :[], :[]=, :to => :_normals
+    
+      def _normals #:nodoc:
+        MD2::Normals::NORMALS
+      end 
+    end
+  
+
+    NORMALS = [
+      [-0.525731,  0.000000,  0.850651], [-0.442863,  0.238856,  0.864188], [-0.295242,  0.000000,  0.955423], 
+      [-0.309017,  0.500000,  0.809017], [-0.162460,  0.262866,  0.951056], [ 0.000000,  0.000000,  1.000000], 
+      [ 0.000000,  0.850651,  0.525731], [-0.147621,  0.716567,  0.681718], [ 0.147621,  0.716567,  0.681718], 
+      [ 0.000000,  0.525731,  0.850651], [ 0.309017,  0.500000,  0.809017], [ 0.525731,  0.000000,  0.850651], 
+      [ 0.295242,  0.000000,  0.955423], [ 0.442863,  0.238856,  0.864188], [ 0.162460,  0.262866,  0.951056], 
+      [-0.681718,  0.147621,  0.716567], [-0.809017,  0.309017,  0.500000], [-0.587785,  0.425325,  0.688191], 
+      [-0.850651,  0.525731,  0.000000], [-0.864188,  0.442863,  0.238856], [-0.716567,  0.681718,  0.147621], 
+      [-0.688191,  0.587785,  0.425325], [-0.500000,  0.809017,  0.309017], [-0.238856,  0.864188,  0.442863], 
+      [-0.425325,  0.688191,  0.587785], [-0.716567,  0.681718, -0.147621], [-0.500000,  0.809017, -0.309017], 
+      [-0.525731,  0.850651,  0.000000], [ 0.000000,  0.850651, -0.525731], [-0.238856,  0.864188, -0.442863], 
+      [ 0.000000,  0.955423, -0.295242], [-0.262866,  0.951056, -0.162460], [ 0.000000,  1.000000,  0.000000], 
+      [ 0.000000,  0.955423,  0.295242], [-0.262866,  0.951056,  0.162460], [ 0.238856,  0.864188,  0.442863], 
+      [ 0.262866,  0.951056,  0.162460], [ 0.500000,  0.809017,  0.309017], [ 0.238856,  0.864188, -0.442863], 
+      [ 0.262866,  0.951056, -0.162460], [ 0.500000,  0.809017, -0.309017], [ 0.850651,  0.525731,  0.000000], 
+      [ 0.716567,  0.681718,  0.147621], [ 0.716567,  0.681718, -0.147621], [ 0.525731,  0.850651,  0.000000], 
+      [ 0.425325,  0.688191,  0.587785], [ 0.864188,  0.442863,  0.238856], [ 0.688191,  0.587785,  0.425325], 
+      [ 0.809017,  0.309017,  0.500000], [ 0.681718,  0.147621,  0.716567], [ 0.587785,  0.425325,  0.688191], 
+      [ 0.955423,  0.295242,  0.000000], [ 1.000000,  0.000000,  0.000000], [ 0.951056,  0.162460,  0.262866], 
+      [ 0.850651, -0.525731,  0.000000], [ 0.955423, -0.295242,  0.000000], [ 0.864188, -0.442863,  0.238856], 
+      [ 0.951056, -0.162460,  0.262866], [ 0.809017, -0.309017,  0.500000], [ 0.681718, -0.147621,  0.716567], 
+      [ 0.850651,  0.000000,  0.525731], [ 0.864188,  0.442863, -0.238856], [ 0.809017,  0.309017, -0.500000], 
+      [ 0.951056,  0.162460, -0.262866], [ 0.525731,  0.000000, -0.850651], [ 0.681718,  0.147621, -0.716567], 
+      [ 0.681718, -0.147621, -0.716567], [ 0.850651,  0.000000, -0.525731], [ 0.809017, -0.309017, -0.500000], 
+      [ 0.864188, -0.442863, -0.238856], [ 0.951056, -0.162460, -0.262866], [ 0.147621,  0.716567, -0.681718], 
+      [ 0.309017,  0.500000, -0.809017], [ 0.425325,  0.688191, -0.587785], [ 0.442863,  0.238856, -0.864188],
+      [ 0.587785,  0.425325, -0.688191], [ 0.688191,  0.587785, -0.425325], [-0.147621,  0.716567, -0.681718], 
+      [-0.309017,  0.500000, -0.809017], [ 0.000000,  0.525731, -0.850651], [-0.525731,  0.000000, -0.850651], 
+      [-0.442863,  0.238856, -0.864188], [-0.295242,  0.000000, -0.955423], [-0.162460,  0.262866, -0.951056], 
+      [ 0.000000,  0.000000, -1.000000], [ 0.295242,  0.000000, -0.955423], [ 0.162460,  0.262866, -0.951056], 
+      [-0.442863, -0.238856, -0.864188], [-0.309017, -0.500000, -0.809017], [-0.162460, -0.262866, -0.951056], 
+      [ 0.000000, -0.850651, -0.525731], [-0.147621, -0.716567, -0.681718], [ 0.147621, -0.716567, -0.681718], 
+      [ 0.000000, -0.525731, -0.850651], [ 0.309017, -0.500000, -0.809017], [ 0.442863, -0.238856, -0.864188], 
+      [ 0.162460, -0.262866, -0.951056], [ 0.238856, -0.864188, -0.442863], [ 0.500000, -0.809017, -0.309017], 
+      [ 0.425325, -0.688191, -0.587785], [ 0.716567, -0.681718, -0.147621], [ 0.688191, -0.587785, -0.425325], 
+      [ 0.587785, -0.425325, -0.688191], [ 0.000000, -0.955423, -0.295242], [ 0.000000, -1.000000,  0.000000], 
+      [ 0.262866, -0.951056, -0.162460], [ 0.000000, -0.850651,  0.525731], [ 0.000000, -0.955423,  0.295242], 
+      [ 0.238856, -0.864188,  0.442863], [ 0.262866, -0.951056,  0.162460], [ 0.500000, -0.809017,  0.309017], 
+      [ 0.716567, -0.681718,  0.147621], [ 0.525731, -0.850651,  0.000000], [-0.238856, -0.864188, -0.442863], 
+      [-0.500000, -0.809017, -0.309017], [-0.262866, -0.951056, -0.162460], [-0.850651, -0.525731,  0.000000], 
+      [-0.716567, -0.681718, -0.147621], [-0.716567, -0.681718,  0.147621], [-0.525731, -0.850651,  0.000000], 
+      [-0.500000, -0.809017,  0.309017], [-0.238856, -0.864188,  0.442863], [-0.262866, -0.951056,  0.162460], 
+      [-0.864188, -0.442863,  0.238856], [-0.809017, -0.309017,  0.500000], [-0.688191, -0.587785,  0.425325], 
+      [-0.681718, -0.147621,  0.716567], [-0.442863, -0.238856,  0.864188], [-0.587785, -0.425325,  0.688191], 
+      [-0.309017, -0.500000,  0.809017], [-0.147621, -0.716567,  0.681718], [-0.425325, -0.688191,  0.587785], 
+      [-0.162460, -0.262866,  0.951056], [ 0.442863, -0.238856,  0.864188], [ 0.162460, -0.262866,  0.951056], 
+      [ 0.309017, -0.500000,  0.809017], [ 0.147621, -0.716567,  0.681718], [ 0.000000, -0.525731,  0.850651], 
+      [ 0.425325, -0.688191,  0.587785], [ 0.587785, -0.425325,  0.688191], [ 0.688191, -0.587785,  0.425325], 
+      [-0.955423,  0.295242,  0.000000], [-0.951056,  0.162460,  0.262866], [-1.000000,  0.000000,  0.000000], 
+      [-0.850651,  0.000000,  0.525731], [-0.955423, -0.295242,  0.000000], [-0.951056, -0.162460,  0.262866], 
+      [-0.864188,  0.442863, -0.238856], [-0.951056,  0.162460, -0.262866], [-0.809017,  0.309017, -0.500000], 
+      [-0.864188, -0.442863, -0.238856], [-0.951056, -0.162460, -0.262866], [-0.809017, -0.309017, -0.500000], 
+      [-0.681718,  0.147621, -0.716567], [-0.681718, -0.147621, -0.716567], [-0.850651,  0.000000, -0.525731], 
+      [-0.688191,  0.587785, -0.425325], [-0.587785,  0.425325, -0.688191], [-0.425325,  0.688191, -0.587785], 
+      [-0.425325, -0.688191, -0.587785], [-0.587785, -0.425325, -0.688191], [-0.688191, -0.587785, -0.425325]
+    ].collect { |c| c.freeze }.freeze
+  end
+end

data/lib/md2/triangle.rb

@@ -0,0 +1,9 @@
+class MD2::Triangle
+  attr_reader :vertex_indices, :texcoord_indices
+  
+  def initialize(data)
+    data = data.unpack("s6")
+    @vertex_indices   = [data[0], data[1], data[2]]
+    @texcoord_indices = [data[3], data[4], data[5]]
+  end
+end

data/lib/md2/vertex.rb

@@ -0,0 +1,33 @@
+class MD2::Vertex < Array
+  def initialize(x, y, z)
+    super()
+    raise ArgumentError, "x is nil" if x.nil?
+    raise ArgumentError, "y is nil" if y.nil?
+    raise ArgumentError, "z is nil" if z.nil?
+    self << x << y << z
+  end
+  
+  def x
+    self[0]
+  end
+  
+  def y
+    self[1]
+  end
+  
+  def z
+    self[2]
+  end
+  
+  def x=(x)
+    self[0] = x
+  end
+  
+  def y=(y)
+    self[1] = y
+  end
+  
+  def z=(z)
+    self[2] = z
+  end
+end

data/md2.gemspec

@@ -0,0 +1,117 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{md2}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Colin MacKenzie IV"]
+  s.date = %q{2010-10-28}
+  s.default_executable = %q{md2_to_json}
+  s.description = %q{A Ruby library for loading MD2 3D model files.}
+  s.email = %q{sinisterchipmunk@gmail.com}
+  s.executables = ["md2_to_json"]
+  s.extensions = ["ext/md2/extconf.rb"]
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "bin/md2_to_json",
+     "ext/md2/extconf.rb",
+     "ext/md2/md2.c",
+     "lib/md2.rb",
+     "lib/md2/command.rb",
+     "lib/md2/errors.rb",
+     "lib/md2/frame.rb",
+     "lib/md2/header.rb",
+     "lib/md2/normals.rb",
+     "lib/md2/triangle.rb",
+     "lib/md2/vertex.rb",
+     "md2.gemspec",
+     "spec/lib/md2/frame_spec.rb",
+     "spec/lib/md2/header_spec.rb",
+     "spec/lib/md2_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/crafty/Crafty.BMP",
+     "spec/support/crafty/Crafty.pcx",
+     "spec/support/crafty/Crafty.txt",
+     "spec/support/crafty/Weapon.md2",
+     "spec/support/crafty/Weapon.pcx",
+     "spec/support/crafty/crafty.md2",
+     "spec/support/laalaa/laalaa.md2",
+     "spec/support/laalaa/laalaa24.BMP",
+     "spec/support/laalaa/laalaa8.BMP",
+     "spec/support/ogro/Ogro.txt",
+     "spec/support/ogro/Ogrobase.pcx",
+     "spec/support/ogro/Weapon.md2",
+     "spec/support/ogro/Weapon.pcx",
+     "spec/support/ogro/ogro.md2",
+     "spec/support/ogro/ogro.png",
+     "spec/support/pilot/CC_attribution_licence.txt",
+     "spec/support/pilot/GNU_licence.txt",
+     "spec/support/pilot/Readme.txt",
+     "spec/support/pilot/body.md2",
+     "spec/support/pilot/body.obj",
+     "spec/support/pilot/head.md2",
+     "spec/support/pilot/head.obj",
+     "spec/support/pilot/pilot.md2",
+     "spec/support/pilot/pilot_body.3ds",
+     "spec/support/pilot/pilot_body.jpg",
+     "spec/support/pilot/pilot_body.obj",
+     "spec/support/pilot/pilot_head.3ds",
+     "spec/support/pilot/pilot_head.jpg",
+     "spec/support/pilot/pilot_head.obj",
+     "spec/support/pknight/pknight.BMP",
+     "spec/support/pknight/pknight.PCX",
+     "spec/support/pknight/pknight.md2",
+     "spec/support/pknight/pknight_weapon.PCX",
+     "spec/support/pknight/pknight_weapon.bmp",
+     "spec/support/pknight/pknight_weapon.md2",
+     "spec/support/sodf8/Abarlith.pcx",
+     "spec/support/sodf8/SFOD8.txt",
+     "spec/support/sodf8/Weapon.PCX",
+     "spec/support/sodf8/Weapon.md2",
+     "spec/support/sodf8/sodf8.md2"
+  ]
+  s.homepage = %q{http://thoughtsincomputation.com}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A Ruby library for loading MD2 3D model files.}
+  s.test_files = [
+    "spec/lib/md2/frame_spec.rb",
+     "spec/lib/md2/header_spec.rb",
+     "spec/lib/md2_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sizes>, [">= 1.0"])
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+    else
+      s.add_dependency(%q<sizes>, [">= 1.0"])
+      s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    end
+  else
+    s.add_dependency(%q<sizes>, [">= 1.0"])
+    s.add_dependency(%q<activesupport>, [">= 2.3.5"])
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+  end
+end
+

data/spec/lib/md2/frame_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe MD2 do
+  subject { MD2.new(md2_file("pilot")) }
+  
+  it "should have frames.first.vertices.size == header.vertex_count" do
+    subject.frames.first.vertices.size.should == subject.header.vertex_count
+  end
+  
+  it "should not contain null characters" do
+    subject.frames.first.name.should_not =~ /#{Regexp::escape ?\0.chr}/
+  end
+end

data/spec/lib/md2/header_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe MD2::Header do
+  context "with invalid content" do
+    subject { MD2::Header.new(mock_io("this is invalid "*10)) }
+    
+    it "should raise MD2::Errors::InvalidFile" do
+      proc { subject }.should raise_error(MD2::Errors::InvalidFile)
+    end
+  end
+  
+  context "with valid ID" do
+    context "and invalid version" do
+      subject { MD2::Header.new(mock_io("IDP2" + ("this is invalid"*10))) }
+      
+      it "should raise MD2::Errors::InvalidVersion" do
+        proc { subject }.should raise_error(MD2::Errors::InvalidVersion)
+      end
+    end
+  end
+end