ply 0.9

data/.autotest

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+# Autotest.add_hook :initialize do |at|
+#   at.extra_files << "../some/external/dependency.rb"
+#
+#   at.libs << ":../some/external"
+#
+#   at.add_exception 'vendor'
+#
+#   at.add_mapping(/dependency.rb/) do |f, _|
+#     at.files_matching(/test_.*rb$/)
+#   end
+#
+#   %w(TestA TestB).each do |klass|
+#     at.extra_class_map[klass] = "test/test_misc.rb"
+#   end
+# end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/History.txt

@@ -0,0 +1,3 @@
+=== 0.9.0 / 2013-02-04
+
+* Initial release

data/LICENSE.txt

@@ -0,0 +1,28 @@
+== LICENSE:
+
+(The BSD 2-clause License)
+
+ Copyright (c) 2013 Jim Wise
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

data/Manifest.txt

@@ -0,0 +1,15 @@
+.autotest
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+README.rdoc
+Rakefile
+bin/ply2ascii
+examples/cube_ascii.ply
+examples/cube_binary_big_endian.ply
+examples/cube_binary_little_endian.ply
+examples/examples.rb
+lib/ply.rb
+test/test_ply.rb
+test/test_ply2ascii.rb

data/README.rdoc

@@ -0,0 +1,227 @@
+= ply
+
+https://github.com/jimwise/ply
+
+Author::    Jim Wise  (mailto:jwise@draga.com)
+Copyright:: Copyright (c) 2013 Jim Wise
+License::   2-clause BSD-Style (see LICENSE.txt)
+
+== DESCRIPTION:
+
+Ply is a ruby gem for reading Stanford PLY-format 3D model files.
+
+The PLY file format is a flexible format for storing semi-structured binary data,
+and is often used to stored polygonalized 3D models generated with range
+scanning hardware.  You can find some examples of the format at the the
+{Stanford 3D Scanning Repository}[http://graphics.stanford.edu/data/3Dscanrep/].
+ 
+Ply provides a simple API for quick access to the data in a PLY file
+(including examining the structure of a particular file's content), and
+an almost-as-simple event-driven API which can be used to process extremely
+large ply files in a streaming fashion, without needing to keep the full
+dataset represented in the file in memory.  Ply handles all three types of
+PLY files (ascii, binary-big-endian and binary-little-endian).
+
+If you don't have any Stanford PLY files on hand, you probably don't need
+this gem, but if you're curious, the PLY file format, described at
+Wikipedia[http://en.wikipedia.org/wiki/PLY_(file_format)]
+
+
+== REQUIREMENTS:
+
+Ply currently requires Ruby 1.9.3 -- if you have a need to run Ply with Ruby
+1.8.7, drop me an email[mailto:jwise@draga.com], and I'll look into
+backporting it.  Ply has no other dependencies.
+
+== INSTALL:
+
+   $ gem install ply
+
+== SYNOPSIS: 
+ 
+=== How to Use This Gem
+
+To get started, include this gem using
+
+    require 'ply'
+
+This gem provides the Ply module.  This module provides a single class,
+Ply::PlyFile, which can be used directly to parse a PLY file into memory, or
+subclassed to take advantage of Ply's event-driven API for handling large
+PLY files.
+
+=== The Simple API
+
+To parse a PLY file into memory, simply instantiate the Ply::PlyFile class,
+passing either the name of the PLY file or an IO object open on a PLY file 
+to Ply::PlyFile.new.  Thus this:
+
+    pf = Ply::PlyFile.new "horse.ply"
+
+and this:
+
+    pf = Ply::PlyFile.new File.new("horse.ply")
+
+do the same thing.
+
+The PLY file is parsed at construction time, and provides the following
+read-only accessors:
+
+Ply::PlyFile#version::
+  The version of the PLY format used in this file, as a String -- at this
+  time the only defined PLY version is 1.0.
+
+Ply::PlyFile#format::
+  The format of this PLY file as a String-- one of +ascii+,
+  +binary_big_endian+, or +binary_little_endian+.
+
+Ply::PlyFile#elements::
+  The structure of the data in this PLY file, as an array of Hashes, in the
+  order the elements will appear in the file.  Each Hash contains the
+  following keys:
+
+  :name::  the name of this element type
+
+  :count:: the number of elements of this type in this PLY file
+
+  :properties::
+    an array of Hashes describing the properties of this element
+    type.  Each Hash in the +:properties+ array contains the following keys:
+
+    :name::   the name of this property of the current element
+
+    :type::
+      the type of this property (an integral or floating point type, as
+      defined in the PLY file format, or +list+.  If the current property is
+      of type +list+ (a PLY array type), its property Hash also contains the
+      following keys:
+
+     :index_type::
+        the type of the index of this list
+
+     :element_type::
+        the type of the elements in this list
+
+If you are using the Ply::PlyFile class directly (as opposed to subclassing
+it in order to use Ply's event-driven API for handling large PLY files), an
+additional read-only accessor is available
+  
+Ply::PlyFile#data::
+
+  The actual data in this file, in the structure defined by the return value
+  of Ply::PlyFile#elements, as a Hash of Arrays of Hashes.  This data is returned
+  as a Hash keyed by the name of each element type in the file (as a
+  String), and containing an array of Hashes for each element type in the
+  file, keyed by the property names of that element, as Strings.
+
+  That's not as complicated as it sounds!  If the file +horse.ply+ defines a
+  +vertex+ element, with properties +x+, +y+, and +z+, then
+
+      pf = Ply::PlyFile.new "horse.ply"
+      verts = pf.data["vertex"]
+
+  will return an array of all vertices in the file, and
+
+      verts[0]["x"]
+
+  will give you the value of the +x+ property of the first +vertex+ element
+  in the file, as an Integer, Float, or Array, depending on the declared
+  type of that property in the PLY file.
+
+=== The Event-Driven API
+
+The above API is easy to use, but has the disadvantage that the entire data
+stored in the PLY file must be able to fit in memory, in order to be
+returned by Ply::PlyFile::data.  For this reason, a simple event-driven API
+for handling PLY data is also provided.  To make use of this, simply
+subclass the class Ply::PlyFile, and provide your own version of the method
+Ply::PlyFile#element_callback.  When a new object of your subclass is
+constructed from a PLY file, your implementation of this method will be
+called once for each element in the file, and passed two arguments:
+
+* The type of the current element, in the same format as a member of the
+  array returned by Ply::PlyFile::elements
+
+* The current element, in the same format as the members of the arrays
+  returned by Ply::PlyFile::data
+
+Note that if your subclass provides a #initialize method, it is your
+responsibility to ensure that PlyFile
+
+As an example, the following code defines a subclass of PlyFile which merely
+*counts* the elements of each type present in PLY file, without reading them
+all into memory at the same time:
+
+    class PlyFileCounter < Ply::PlyFile
+      attr_reader :counts
+
+      def initialize f
+        @counts = {}
+        super f
+      end
+
+      def element_callback e, v
+        @counts[e[:name]] ||= 0
+        @counts[e[:name]] = @counts[e[:name]] + 1
+      end
+    end
+
+    p = PlyFileCounter.new "horse.ply"
+    puts "There are #{p.counts["vertex"]} vertices in the file."
+
+=== Example Files
+
+In addition to the large models in the {Stanford 3D Scanning
+Repository}[http://graphics.stanford.edu/data/3Dscanrep/], the +examples/+
+subdirectory of this gem includes a simple triangulated cube model in all
+three PLY file formats, as well as a script to generate these three files
+which you may modify for your own purposes.
+
+=== ply2ascii
+
+Finally, this gem includes a simple script, +ply2ascii+, which can be used
+to parse any of the three PLY file formats containing a triangulated scene
+with vertices in an element named +vertex+ with (at least) scalar properties
++x+, +y+, and +z+, and faces in an elemnt named +face+ containing a list
+property +vertex_indices+, and produce a simple ASCII dump of the described
+scene in two files.
+
+Run +ply2ascii+ with no arguments for (a little) more information.
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== LICENSE:
+
+(The BSD 2-clause License)
+
+ Copyright (c) 2013 Jim Wise
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

data/README.txt

@@ -0,0 +1,227 @@
+= ply
+
+https://github.com/jimwise/ply
+
+Author::    Jim Wise  (mailto:jwise@draga.com)
+Copyright:: Copyright (c) 2013 Jim Wise
+License::   2-clause BSD-Style (see LICENSE.txt)
+
+== DESCRIPTION:
+
+Ply is a ruby gem for reading Stanford PLY-format 3D model files.
+
+The PLY file format is a flexible format for storing semi-structured binary data,
+and is often used to stored polygonalized 3D models generated with range
+scanning hardware.  You can find some examples of the format at the the
+{Stanford 3D Scanning Repository}[http://graphics.stanford.edu/data/3Dscanrep/].
+ 
+Ply provides a simple API for quick access to the data in a PLY file
+(including examining the structure of a particular file's content), and
+an almost-as-simple event-driven API which can be used to process extremely
+large ply files in a streaming fashion, without needing to keep the full
+dataset represented in the file in memory.  Ply handles all three types of
+PLY files (ascii, binary-big-endian and binary-little-endian).
+
+If you don't have any Stanford PLY files on hand, you probably don't need
+this gem, but if you're curious, the PLY file format, described at
+Wikipedia[http://en.wikipedia.org/wiki/PLY_(file_format)]
+
+
+== REQUIREMENTS:
+
+Ply currently requires Ruby 1.9.3 -- if you have a need to run Ply with Ruby
+1.8.7, drop me an email[mailto:jwise@draga.com], and I'll look into
+backporting it.  Ply has no other dependencies.
+
+== INSTALL:
+
+   $ gem install ply
+
+== SYNOPSIS: 
+ 
+=== How to Use This Gem
+
+To get started, include this gem using
+
+    require 'ply'
+
+This gem provides the Ply module.  This module provides a single class,
+Ply::PlyFile, which can be used directly to parse a PLY file into memory, or
+subclassed to take advantage of Ply's event-driven API for handling large
+PLY files.
+
+=== The Simple API
+
+To parse a PLY file into memory, simply instantiate the Ply::PlyFile class,
+passing either the name of the PLY file or an IO object open on a PLY file 
+to Ply::PlyFile.new.  Thus this:
+
+    pf = Ply::PlyFile.new "horse.ply"
+
+and this:
+
+    pf = Ply::PlyFile.new File.new("horse.ply")
+
+do the same thing.
+
+The PLY file is parsed at construction time, and provides the following
+read-only accessors:
+
+Ply::PlyFile#version::
+  The version of the PLY format used in this file, as a String -- at this
+  time the only defined PLY version is 1.0.
+
+Ply::PlyFile#format::
+  The format of this PLY file as a String-- one of +ascii+,
+  +binary_big_endian+, or +binary_little_endian+.
+
+Ply::PlyFile#elements::
+  The structure of the data in this PLY file, as an array of Hashes, in the
+  order the elements will appear in the file.  Each Hash contains the
+  following keys:
+
+  :name::  the name of this element type
+
+  :count:: the number of elements of this type in this PLY file
+
+  :properties::
+    an array of Hashes describing the properties of this element
+    type.  Each Hash in the +:properties+ array contains the following keys:
+
+    :name::   the name of this property of the current element
+
+    :type::
+      the type of this property (an integral or floating point type, as
+      defined in the PLY file format, or +list+.  If the current property is
+      of type +list+ (a PLY array type), its property Hash also contains the
+      following keys:
+
+     :index_type::
+        the type of the index of this list
+
+     :element_type::
+        the type of the elements in this list
+
+If you are using the Ply::PlyFile class directly (as opposed to subclassing
+it in order to use Ply's event-driven API for handling large PLY files), an
+additional read-only accessor is available
+  
+Ply::PlyFile#data::
+
+  The actual data in this file, in the structure defined by the return value
+  of Ply::PlyFile#elements, as a Hash of Arrays of Hashes.  This data is returned
+  as a Hash keyed by the name of each element type in the file (as a
+  String), and containing an array of Hashes for each element type in the
+  file, keyed by the property names of that element, as Strings.
+
+  That's not as complicated as it sounds!  If the file +horse.ply+ defines a
+  +vertex+ element, with properties +x+, +y+, and +z+, then
+
+      pf = Ply::PlyFile.new "horse.ply"
+      verts = pf.data["vertex"]
+
+  will return an array of all vertices in the file, and
+
+      verts[0]["x"]
+
+  will give you the value of the +x+ property of the first +vertex+ element
+  in the file, as an Integer, Float, or Array, depending on the declared
+  type of that property in the PLY file.
+
+=== The Event-Driven API
+
+The above API is easy to use, but has the disadvantage that the entire data
+stored in the PLY file must be able to fit in memory, in order to be
+returned by Ply::PlyFile::data.  For this reason, a simple event-driven API
+for handling PLY data is also provided.  To make use of this, simply
+subclass the class Ply::PlyFile, and provide your own version of the method
+Ply::PlyFile#element_callback.  When a new object of your subclass is
+constructed from a PLY file, your implementation of this method will be
+called once for each element in the file, and passed two arguments:
+
+* The type of the current element, in the same format as a member of the
+  array returned by Ply::PlyFile::elements
+
+* The current element, in the same format as the members of the arrays
+  returned by Ply::PlyFile::data
+
+Note that if your subclass provides a #initialize method, it is your
+responsibility to ensure that PlyFile
+
+As an example, the following code defines a subclass of PlyFile which merely
+*counts* the elements of each type present in PLY file, without reading them
+all into memory at the same time:
+
+    class PlyFileCounter < Ply::PlyFile
+      attr_reader :counts
+
+      def initialize f
+        @counts = {}
+        super f
+      end
+
+      def element_callback e, v
+        @counts[e[:name]] ||= 0
+        @counts[e[:name]] = @counts[e[:name]] + 1
+      end
+    end
+
+    p = PlyFileCounter.new "horse.ply"
+    puts "There are #{p.counts["vertex"]} vertices in the file."
+
+=== Example Files
+
+In addition to the large models in the {Stanford 3D Scanning
+Repository}[http://graphics.stanford.edu/data/3Dscanrep/], the +examples/+
+subdirectory of this gem includes a simple triangulated cube model in all
+three PLY file formats, as well as a script to generate these three files
+which you may modify for your own purposes.
+
+=== ply2ascii
+
+Finally, this gem includes a simple script, +ply2ascii+, which can be used
+to parse any of the three PLY file formats containing a triangulated scene
+with vertices in an element named +vertex+ with (at least) scalar properties
++x+, +y+, and +z+, and faces in an elemnt named +face+ containing a list
+property +vertex_indices+, and produce a simple ASCII dump of the described
+scene in two files.
+
+Run +ply2ascii+ with no arguments for (a little) more information.
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== LICENSE:
+
+(The BSD 2-clause License)
+
+ Copyright (c) 2013 Jim Wise
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,8 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'ply' do
+  developer('Jim Wise', 'jwise@draga.com')
+end

data/bin/ply2ascii

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+require 'ply'
+
+USAGE = "usage: #{$0} <ply file> ..."
+HELP = <<EOL
+This utility translates ply files with vertex and triangle information
+into simple ASCII files.
+
+Each plyfile specified on the command line is read, and corresponding
+triangle and vertex files are created in the current directory.
+EOL
+
+class Ply2Ascii < Ply::PlyFile
+  def initialize infile, outname
+    @verts = File.new("vertices_#{outname}.ascii", "w")
+    @verts.puts("# written by ply.rb")
+    @tris = File.new("triangles_#{outname}.ascii", "w")
+    @tris.puts("# written by ply.rb")
+    super infile
+  end
+
+  def element_callback elt, val
+    case elt[:name]
+    when "vertex"
+      @verts.puts "#{val["x"]} #{val["y"]} #{val["z"]}"
+    when "face"
+      @tris.puts val["vertex_indices"].join " "
+    else
+      puts "skipping unknown element type #{elt[:name]}"
+    end
+  end
+end
+
+if ARGV.size == 0
+  puts USAGE
+  puts HELP
+end
+
+ARGV.each do |fname|
+  begin
+    outname = File.basename(fname, ".ply")
+    Ply2Ascii.new(fname, outname)
+  rescue Ply::BadFile => bf
+    puts "#{fname}: #{bf}"
+  end
+end
+
+# -*- ruby -*-

data/examples/cube_ascii.ply

@@ -0,0 +1,30 @@
+ply
+format ascii 1.0
+comment simple triangulated cube example
+element vertex 8
+property float32 x
+property float32 y
+property float32 z
+element face 12
+property list uint8 uint32 vertex_indices
+end_header
+0.0 0.0 0.0
+0.0 1.0 0.0
+1.0 0.0 0.0
+1.0 1.0 0.0
+0.0 0.0 1.0
+0.0 1.0 1.0
+1.0 0.0 1.0
+1.0 1.0 1.0
+3 0 1 3
+3 1 3 2
+3 0 1 5
+3 0 5 4
+3 4 0 2
+3 4 2 6
+3 2 3 7
+3 2 7 6
+3 4 5 7
+3 4 7 6
+3 1 5 7
+3 1 7 3

data/examples/examples.rb

@@ -0,0 +1,100 @@
+#!/usr/local/bin/ruby
+
+#       6---------7
+#      /:        /|
+#     / :       / |
+#    /  :      /  |
+#   2---------3   |
+#   |   4.....|...5
+#   |  '      |  /
+#   | '       | /
+#   |'        |/
+#   0---------1
+#
+#  Y Z
+#  |/
+#  *-X
+
+Cube_vertices = [
+  [0.0, 0.0, 0.0],
+  [0.0, 1.0, 0.0],
+  [1.0, 0.0, 0.0],
+  [1.0, 1.0, 0.0],
+  [0.0, 0.0, 1.0],
+  [0.0, 1.0, 1.0],
+  [1.0, 0.0, 1.0],
+  [1.0, 1.0, 1.0]
+]
+
+Cube_faces = [
+  [0, 1, 3],
+  [1, 3, 2],
+
+  [0, 1, 5],
+  [0, 5, 4],
+
+  [4, 0, 2],
+  [4, 2, 6],
+
+  [2, 3, 7],
+  [2, 7, 6],
+
+  [4, 5, 7],
+  [4, 7, 6],
+
+  [1, 5, 7],
+  [1, 7, 3]
+]
+
+def header f, format
+  f.puts "ply"
+  f.puts "format #{format} 1.0"
+  f.puts "comment simple triangulated cube example"
+  f.puts "element vertex 8"
+  f.puts "property float32 x"
+  f.puts "property float32 y"
+  f.puts "property float32 z"
+  f.puts "element face 12"
+  f.puts "property list uint8 uint32 vertex_indices"
+  f.puts "end_header"
+end
+
+def ascii_cube fname
+  f = File.new(fname, "w")
+  header f, "ascii"
+  Cube_vertices.each do |vert|
+    f.puts vert.map{|p| p.to_s}.join(" ")
+  end
+  Cube_faces.each do |face|
+    f.print "#{face.size} "
+    f.puts face.map{|p| p.to_s}.join(" ")
+  end
+end
+
+def bin_be_cube fname
+  f = File.new(fname, "w")
+  header f, "binary_big_endian"
+  Cube_vertices.each do |vert|
+    f.write vert.pack("g*")
+  end
+  Cube_faces.each do |face|
+    f.write [ face.size ].pack("C")
+    f.write face.pack("L>*")
+  end
+end
+
+def bin_le_cube fname
+  f = File.new(fname, "w")
+  header f, "binary_little_endian"
+  Cube_vertices.each do |vert|
+    f.write vert.pack("e*")
+  end
+  Cube_faces.each do |face|
+    f.write [ face.size ].pack("C")
+    f.write face.pack("L<*")
+  end
+end
+
+ascii_cube "cube_ascii.ply"
+bin_be_cube "cube_binary_big_endian.ply"
+bin_le_cube "cube_binary_little_endian.ply"

data/lib/ply.rb

@@ -0,0 +1,188 @@
+# ply.rb
+
+# Copyright (c) 2013 Jim Wise
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions
+#  are met:
+#
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+#  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+#  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+#  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+#  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+
+module Ply
+  VERSION = '0.9'
+
+  # module for working with ply file format -- see
+  #    http://en.wikipedia.org/wiki/PLY_(file_format)
+  # right now, this supports reading, but not writing ply files
+
+  class PlyFile
+    attr_reader :format, :version, :elements, :data
+
+    # versions of the ply file format we know how to parse (this is the only defined version as of the time of writing)
+    Versions = %w{1.0}
+    # formats of the ply file format we know about (we don't yet implement ascii)
+    Formats = %w{binary_big_endian binary_little_endian ascii}
+    # property types defined by the ply format;  we assume ILP32 meaning of types without explicit widths
+    Types = %w{char uchar short ushort int uint float double int8 uint8 int16 uint16 int32 uint32 float32 float64 list}
+
+    # parse a ply file takes a file name or an IO stream as argument
+    def initialize f
+      unless f.instance_of? IO
+        f = File.new(f)
+      end
+      @source = f
+      @elements = []
+      parse_header f
+      parse_body f
+    end
+
+    private
+
+    def parse_header f
+      raise BadFile.new("missing magic") unless f.gets.chomp == "ply"
+
+      raise BadFile.new("malformed format line") unless md =
+        f.gets.chomp.match(/^format\s+(?<format>[^\s]+)\s+(?<version>[\d.]+)$/)
+      @format = md[:format]
+      @version = md[:version]
+
+      raise BadFile.new("unknown version: #{version}") unless Versions.find(version)
+      raise BadFile.new("unknown format: #{format}") unless Formats.find(version)
+
+      current_element = false
+      f.each do |s|
+        cmd = s.chomp.split
+        case cmd[0]
+        when "comment"
+        when "obj_info"
+        when "end_header"
+          # stash last element
+          @elements << current_element if current_element
+          break
+        when "element"
+          # stash previous element
+          @elements << current_element if current_element
+          # puts "new element #{cmd[1]}"
+          current_element = { name: cmd[1], count: cmd[2].to_i, properties: [] }
+        when "property"
+          type = cmd[1]
+          raise BadFile.new("unknown element type: #{type}") unless Types.find(type)
+
+          current_element[:properties] << if type == "list"
+                                            # puts "new property #{cmd[4]} of element #{current_element[:name]} has type list indexed by #{cmd[2]} of #{cmd[3]}"
+                                            { name: cmd[4], type: "list", index_type: cmd[2], element_type: cmd[3]}
+                                          else
+                                            # puts "new property #{cmd[2]} of element #{current_element[:name]} has type #{type}"
+                                            { name: cmd[2], type: type}
+                                          end
+        else
+          raise BadFile.new("unknown ply command #{cmd[0]}")
+        end
+      end
+    end
+
+    # parse the body of a ply file, using the structures already parsed out of the header
+    # for each element type foo defined in the header, fills in @data[foo] with an array of hashes keyed on the property names
+    def parse_body f
+      @elements.each do |elt|
+        elt[:count].times do
+          element_callback elt, read_element(f, elt)
+        end
+      end
+    end
+
+    # by default, we accumulate all elements of a given type e, in-memory, into an array @data[e]
+    # this is non-ideal for big files, of course -- to change this behavior, subclass PlyFile, and provide your own
+    # element callback -- it will be called once for each read element, and passed the element definition (in elt), and
+    # the actual values just read (in val)
+    def element_callback elt, val
+      @data ||= {}
+      @data[elt[:name]] ||= []
+      @data[elt[:name]] << val
+    end
+
+    def read_element f, elt
+      current_element = {}
+      if @format == "ascii"
+        fields = f.gets.chomp.split
+        elt[:properties].each do |prop|
+          current_element[prop[:name]] = read_property_ascii(fields, prop[:type], prop[:index_type], prop[:element_type])
+        end
+      else
+        elt[:properties].each do |prop|
+          # last two will be nil for non-list
+          current_element[prop[:name]] = read_property_binary(f, prop[:type], prop[:index_type], prop[:element_type])
+        end
+      end
+      current_element
+    end
+
+    def read_property_ascii fields, type, index_type=false, element_type=false
+      #print "reading one #{type}: "
+      case type
+      when "char", "int8", "uchar", "uint8", "short", "int16", "ushort", "uint16", "int", "int32", "uint", "uint32"
+        # integer types
+        fields.shift.to_i
+      when "float", "float32", "double", "float64"
+        # floating point types
+        fields.shift.to_f
+      when "list"
+        count = read_property_ascii(fields, index_type)
+        count.times.collect { read_property_ascii(fields, element_type) }
+      end
+    end
+
+    # read one property from an IO stream in ply binary format, assuming ILP32 widths for generic types
+    def read_property_binary f, type, index_type=false, element_type=false
+      # print "reading one #{type}: "
+      # pick String#unpack specifiers based on our endian-ness
+      case @format
+      when "binary_big_endian"
+        e, f32, f64 = ">", "g", "G"
+      when "binary_little_endian"
+        e, f32, f64 = "<", "e", "E"
+      end
+      case type
+      when "char", "int8"
+        f.read(1).unpack("c").first
+      when "uchar", "uint8"
+        f.read(1).unpack("C").first
+      when "short", "int16"
+        f.read(2).unpack("s#{e}").first
+      when "ushort", "uint16"
+        f.read(2).unpack("S#{e}").first
+      when "int", "int32"
+        f.read(4).unpack("l#{e}").first
+      when "uint", "uint32"
+        f.read(4).unpack("L#{e}").first
+      when "float", "float32"
+        f.read(4).unpack(f32).first
+      when "double", "float64"
+        f.read(8).unpack(f64).first
+      when "list"
+        count = read_property_binary(f, index_type)
+        count.times.collect { read_property_binary(f, element_type) }
+      end
+    end
+  end
+
+  class BadFile < Exception
+  end
+end

data/test/test_ply.rb

@@ -0,0 +1,56 @@
+require "test/unit"
+require "ply"
+
+class TestPly < Test::Unit::TestCase
+  def test_ascii
+    verify_cube_file "examples/cube_ascii.ply"
+  end
+
+  def test_binary_big_endian
+    verify_cube_file "examples/cube_binary_big_endian.ply"
+  end
+
+  def test_binary_little_endian
+    verify_cube_file "examples/cube_binary_little_endian.ply"
+  end
+
+  def test_ascii_callback
+    verify_cube_callback "examples/cube_ascii.ply"
+  end
+
+  def test_binary_big_endian_callback
+    verify_cube_callback "examples/cube_binary_big_endian.ply"
+  end
+
+  def test_binary_little_endian_callback
+    verify_cube_callback "examples/cube_binary_little_endian.ply"
+  end
+
+  def verify_cube_file c
+    p = Ply::PlyFile.new c
+    assert p.data["vertex"].size == 8
+    assert p.data["face"].size == 12
+    assert p.data["vertex"][7]["x"] == 1.0
+    assert p.data["face"][11]["vertex_indices"][2] == 3
+  end
+
+  class PlyFileCounter < Ply::PlyFile
+    attr_reader :counts
+
+    def initialize f
+      @counts = {}
+      super f
+    end
+
+    def element_callback e, v
+      @counts[e[:name]] ||= 0
+      @counts[e[:name]] = @counts[e[:name]] + 1
+    end
+  end
+
+  def verify_cube_callback c
+    p = PlyFileCounter.new c
+    assert p.counts["vertex"] == 8
+    assert p.counts["face"] == 12
+  end
+end

data/test/test_ply2ascii.rb

@@ -0,0 +1,23 @@
+require "test/unit"
+require "ply"
+
+class TestPly2Ascii < Test::Unit::TestCase
+  def test_ply2ascii
+    assert system("env RUBYOPT=-I./lib bin/ply2ascii examples/cube_binary_big_endian.ply")
+    verts = File.new "vertices_cube_binary_big_endian.ascii"
+    tris = File.new "triangles_cube_binary_big_endian.ascii"
+    nv, nt = 0, 0
+    verts.lines {|l| nv = nv + 1}
+    tris.lines {|l| nt = nt + 1}
+    assert nv == 9
+    assert nt == 13
+  ensure
+    File.unlink "vertices_cube_binary_big_endian.ascii"
+    File.unlink "triangles_cube_binary_big_endian.ascii"
+  end
+
+  def test_help
+    out = `env RUBYOPT=-I./lib bin/ply2ascii`
+    assert out.match(/^This utility/)
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: ply
+version: !ruby/object:Gem::Version
+  version: '0.9'
+  prerelease: 
+platform: ruby
+authors:
+- Jim Wise
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: ! "Ply is a ruby gem for reading Stanford PLY-format 3D model files.\n\nThe
+  PLY file format is a flexible format for storing semi-structured binary data,\nand
+  is often used to stored polygonalized 3D models generated with range\nscanning hardware.
+  \ You can find some examples of the format at the the\n{Stanford 3D Scanning Repository}[http://graphics.stanford.edu/data/3Dscanrep/].\n
+  \nPly provides a simple API for quick access to the data in a PLY file\n(including
+  examining the structure of a particular file's content), and\nan almost-as-simple
+  event-driven API which can be used to process extremely\nlarge ply files in a streaming
+  fashion, without needing to keep the full\ndataset represented in the file in memory.
+  \ Ply handles all three types of\nPLY files (ascii, binary-big-endian and binary-little-endian).\n\nIf
+  you don't have any Stanford PLY files on hand, you probably don't need\nthis gem,
+  but if you're curious, the PLY file format, described at\nWikipedia[http://en.wikipedia.org/wiki/PLY_(file_format)]"
+email:
+- jwise@draga.com
+executables:
+- ply2ascii
+extensions: []
+extra_rdoc_files:
+- History.txt
+- LICENSE.txt
+- Manifest.txt
+- README.txt
+- README.rdoc
+files:
+- .autotest
+- History.txt
+- LICENSE.txt
+- Manifest.txt
+- README.txt
+- README.rdoc
+- Rakefile
+- bin/ply2ascii
+- examples/cube_ascii.ply
+- examples/cube_binary_big_endian.ply
+- examples/cube_binary_little_endian.ply
+- examples/examples.rb
+- lib/ply.rb
+- test/test_ply.rb
+- test/test_ply2ascii.rb
+- .gemtest
+homepage: https://github.com/jimwise/ply
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- README.txt
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: ply
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Ply is a ruby gem for reading Stanford PLY-format 3D model files
+test_files:
+- test/test_ply.rb
+- test/test_ply2ascii.rb