wavefront-obj 1.0.1 → 1.0.2

data/README.md

@@ -0,0 +1,77 @@
+wavefront-obj
+=============
+
+#### Description
+
+Ruby library to create wavefront .obj files.
+
+This library provides a handy interface to create [wavefront .obj files](http://en.wikipedia.org/wiki/Wavefront_.obj_file). You can add vertex and faces to define a 3d object. It handles the syntax of the .obj file format and takes care of vertex definition (no vertex is defined twice which reduces filesize). You can access the result in raw data or write it into a file.
+
+Obj-Files can be used to feed a 3d printer.
+
+#### Usage
+
+install
+
+	gem install wavefront-obj	
+
+require library, create an object and give it a name
+
+	require 'wavefront_obj'
+	cube = WavefrontObj.new
+	cube.name = "my awesome cube"
+
+add faces
+
+	cube.add_face [[1, -1, -1],[1, -1, 1],[-1, -1, 1],[-1, -1, -1]]
+	cube.add_face [[1, 1, -1],[-1, 1, -1],[-1, 1, 1],[1, 1, 1]]
+	cube.add_face [[1, -1, -1],[1, 1, -1],[1, 1, 1],[1, -1, 1]]
+	cube.add_face [[1, -1, 1],[1, 1, 1],[-1, 1, 1],[-1, -1, 1]]
+	cube.add_face [[-1, -1, 1],[-1, 1, 1],[-1, 1, -1],[-1, -1, -1]]
+	cube.add_face [[1, 1, -1],[1, -1, -1],[-1, -1, -1],[-1, 1, -1]]
+
+access the raw data
+
+	puts cube.get_raw_data
+
+which will look like this
+
+	o my awesome cube
+	v 1 -1 -1
+	v 1 -1 1
+	v -1 -1 1
+	v -1 -1 -1
+	v 1 1 -1
+	v -1 1 -1
+	v -1 1 1
+	v 1 1 1
+	f 1 2 3 4
+	f 5 6 7 8
+	f 1 5 8 2
+	f 2 8 7 3
+	f 3 7 6 4
+	f 5 1 4 6
+
+or save it as a file
+
+	cube.save "my_awesome_cube.obj"
+
+You can open .obj files with most 3d programs like blender or some newer Photoshop versions as well.
+
+
+## Version History
+**v1.0.0** 02/25/2013
+
+- initial release (yanked)
+
+**v1.0.1** 02/25/2013
+
+- renamed _export\_obj\_path_ method to _save_
+
+**v1.0.2** 03/02/2013
+
+- make _add\_face_ method return _true_ instead of _void_
+- added dependency injection to mock ruby file class
+- added test for save method 
+- added yard documentation
+- updated _README.md_ - Fixed some typos, adjust structure, added version history

data/lib/wavefront_obj.rb

@@ -1,36 +1,45 @@
 require 'rubygems'
 require 'digest/md5'
 
+# @author Stefan Kracht
 class WavefrontObj
 
   attr_reader :point_index
   attr_accessor :name, :points, :faces
   
+  # dependency injectors
+  attr_writer :file
+  
   DEFAULT_NAME = "Wavefront Obj"
   
+  # inits attributes
 	def initialize
 		@name = DEFAULT_NAME
 		@points = Hash.new
 		@point_index = 0
 		@faces = Hash.new
 	end
-  
+
+  # adds a point to the 3d object 
+  # @param pnt [Array] array of 3 coordinates
+  # @return [String, false] the point index
 	def add_point(pnt)
-		if pnt.class == Array && pnt.length == 3
-			indentifier = create_point_identifier(pnt)
-			if @points[indentifier].nil?
-				@points[indentifier] = Hash.new 
-				@point_index = @point_index+1
-				@points[indentifier]["index"] = @point_index
-			end
-			@points[indentifier]["point"] = pnt
-			return @points[indentifier]["index"]
-    else
-      false
+    # TODO add error handling
+		indentifier = create_point_identifier(pnt)
+		if @points[indentifier].nil?
+			@points[indentifier] = Hash.new 
+			@point_index = @point_index+1
+			@points[indentifier]["index"] = @point_index
 		end
+		@points[indentifier]["point"] = pnt
+		return @points[indentifier]["index"]
 	end
   
+  # adds a face to the 3d object 
+  # @param pnt_arr [Array] array of multiple point arrays
+  # @return [true]
 	def add_face(pnt_arr)
+    # TODO add error handling
 		face_points = []
 		pnt_arr.each do |pnt|
 			face_points.push add_point(pnt)
@@ -40,15 +49,11 @@ class WavefrontObj
 			@faces[indentifier] = Hash.new
 			@faces[indentifier]["face"] = face_points
 		end
+    return true
 	end
-  
-	def save(path)
-		raw_data = get_raw_data
-		path = "#{path}.obj" unless path.split(".").last == "obj"
-		File.open(path, 'w') {|f| f.write(get_raw_data) }
-		path
-  end
-  
+    
+  # returns the raw data of the obj file
+  # @return [String] raw data
 	def get_raw_data
 		buffer = []
 		buffer.push(get_name_syntax(@name))
@@ -63,26 +68,59 @@ class WavefrontObj
 
 		return buffer.join("\n")
   end
+
+  # stores the obj data as a file
+  # @param path [String] path to store the file, ".obj" will be added if missing
+  # @return [String] the path of the created file
+  def save(path)
+    # TODO add error handling
+    raw_data = get_raw_data
+    path = "#{path}.obj" unless path.split(".").last == "obj"
+    file.open(path, 'w') {|f| f.write(get_raw_data) }
+    path
+  end
   
   private
   
+  # injectable dependencies for file
+  # @return [void]
+  def file
+    @file || File
+  end
+  
+  # returns the syntax of object definition
+  # @param name [String] object name
+  # @return [String] object name in .obj format
   def get_name_syntax(name)
   	"o #{name}"
   end
 
+  # returns the syntax of a point definition
+  # @param point [String] object name
+  # @return [String, false] point in .obj format
   def get_point_syntax(point)
+    # TODO convert to array
   	"v #{point.join(" ")}"
   end
 
+  # returns the syntax of a face definition
+  # @return [String, false] face in .obj format
   def get_face_syntax(face)
+    # TODO convert to array
   	"f #{face.join(" ")}"
   end
-
+  
+  # generates the unique id of a point
+  # @return [String] point indetifier
   def create_point_identifier(pnt)
+    # TODO convert to array
     Digest::MD5.hexdigest(pnt.join("|"))
   end
-  
+
+  # generates the unique id of a face
+  # @return [String] face indetifier  
   def create_face_identifier(pnts)
+    # TODO convert to array
     Digest::MD5.hexdigest(pnts.join("|"))
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wavefront-obj
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -19,9 +19,11 @@ description: This library provides a handy interface to create wavefront .obj fi
 email: stefankracht@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - lib/wavefront_obj.rb
+- README.md
 homepage: https://github.com/krachtstefan/wavefront-obj
 licenses: []
 post_install_message: 
@@ -47,3 +49,4 @@ signing_key:
 specification_version: 3
 summary: Ruby library to create wavefront obj files
 test_files: []
+has_rdoc: