Ruboid 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+
+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

@@ -0,0 +1,46 @@
+=GeoRuby
+Ruboid is a ruby implementation of Craig Reynolds' Boid alogrithm (http://www.red3d.com/cwr/boids/), which realistically simulates the behaviour of a flock of creatures with a small set of simple rules. See Conrad Parker's page at http://www.vergenet.net/~conrad/boids/pseudocode.html for a more detailed explanation of how the simulation is performed.
+
+===Operations
+==== Basic operations
+Currently, the library implements the 3 rules descibed by Reynolds. You could create a Flock and give it a few boids like this:
+	flock = Flock.new
+	1.upto(10) do |i|
+  		flock << Boid.new(Vector.new([rand(300),rand(300)]),
+                    		  Vector.new([rand(10)-5,rand(10)-5]))
+	end
+Here I created a flock composed of 10 boids with a random starting position and an initial velocity between -5 and 5. The velocity can be understood as the distance the boid moves per time step.
+
+To move the flock, you must call the method +update_and_move+ on the flock:
+	1.upto(100) do |i|
+    		flock.update_and_move
+	end
+The flock has just moved of 100 steps. You should perform some actions (like drawing the flock) between each update.
+
+==== More operations
+On top of these basic rules, some addition ones have been implemented:
+- +scatter+: Scatters the flock, not as a reaction to a particular obstacle, but for example, as a reaction to a loud noise. It will break the cohesion. To reverse it, you should use +regroup+.
+- +go_to+: Gives a goal to reach to the boids. Boids will have a tendency to go in the direction of this goal. Use +forget_goal+ to reverse it.
+- +bound+: Encourages the boids to stay in a certain area (for example the drawing area). Use +move_freely+ to reverse it.
+- +rebel+: Adds an element of chance to the movement of boids. Use +calm_down+ to reverse it.
+
+==== Examples
+I have included 2 examples in the distribution. One is stand-alone, the other necessitates RMagick and draws an animated GIF.
+
+==== Vector class
+To ease the computations, I have created a Vector class, which can be of any dimension. All the positions and velocities of the boids are in this format. You can create a vector from an array of value like this:
+	v = Vector.new(array)
+And access it like that :
+	v[0]
+	v.each ...
+
+
+===Installation
+To install the latest version, just type :
+      gem install Ruboid
+
+===License
+Ruboid is released under the MIT license.
+
+===Support
+Any questions, enhancement proposals, bug notifications or corrections can be sent to mailto:guilhem.vellut+georuby@gmail.com.

data/lib/ruboid.rb

@@ -0,0 +1,2 @@
+require 'ruboid/vector'
+require 'ruboid/ruboid'

data/lib/ruboid/ruboid.rb

@@ -0,0 +1,220 @@
+module Ruboid
+
+  #Represents a flock of boids, which move together according to Reynolds' rules
+  class Flock
+    attr_accessor :boids, :velocity_limit, :safety_distance, :rebellion
+    attr_accessor :separation_factor, :cohesion_factor, :alignment_factor, :goal_factor
+        
+    include Enumerable
+
+    def initialize(velocity_limit = 10,
+                   safety_distance = 30,
+                   separation_factor = 1.0,
+                   cohesion_factor = 0.01,
+                   alignment_factor = 0.125)
+                  
+      @boids = []  
+            
+      @velocity_limit = velocity_limit
+      @safety_distance = safety_distance
+      @separation_factor = separation_factor
+      @cohesion_factor = cohesion_factor
+      @alignment_factor = alignment_factor
+      @goal_factor = goal_factor
+      @rebellion = rebellion
+
+      #indicates if the flock must scatter or be grouped
+      @flock = 1
+      
+      @goal=nil
+      @goal_factor = 0
+      
+      @bound_corner1=nil
+      @bound_corner2=nil
+      @bound_encouragement = nil
+      
+      @free_will=false
+      @rebellion = 0
+      
+    end
+
+    #Adds a boid to the flock
+    def <<(boid)
+      @boids << boid
+    end
+
+    def each
+      boids.each {|b| yield b}
+    end
+
+    #Scatters the flock, not as a reaction to a particular obstacle, but for example, as a reaction to a loud noise. It will break the cohesion.
+    def scatter
+      @flock = -1
+    end
+
+    #Regroups the flock
+    def regroup
+      @flock = 1
+    end
+
+    #set a goal for the flock
+    def go_to(goal,goal_factor = 0.05)
+      @goal = goal
+      @goal_factor = goal_factor
+    end
+
+    #go back to meaningless wandering
+    def forget_goal
+      @goal = nil
+    end
+
+    #bound the boids
+    def bound(corner1,corner2,bound_encouragement = 10)
+      @bound_corner1 = corner1
+      @bound_corner2 = corner2
+      @bound_encouragement = bound_encouragement
+    end
+
+    def move_freely
+      @bound_corner1 = nil
+      @bound_corner2 = nil
+      @bound_encouragement = nil
+    end
+
+    #degree of 
+    def rebel(rebellion = 5)
+      @free_will = true
+      @rebellion = rebellion
+    end
+
+    def calm_down
+      @free_will = false
+    end
+
+    #Main method of the class : calculates a variation of the velocity of each boid according to the position and velocity of the other boids. Finally update the velocity and the position of each boid.
+    def update_and_move
+      #calculate the new velocity : keep in a temp variable so all the boids get updated at the same time
+      velocity_update = Array.new
+      
+      #calculate the variation of velocity of the boids
+      @boids.each do |boid|
+        d_vc = boid.cohesion(@boids).mul(@cohesion_factor * @flock)
+        d_vs = boid.separation(@boids,@safety_distance).mul(@separation_factor)
+        d_va = boid.alignment(@boids).mul(@alignment_factor)
+        
+        d_v = d_vc.add(d_vs).add(d_va)
+        
+        if @goal
+          d_vg = boid.go_to(@goal).mul(@goal_factor)
+          d_v.add(d_vg)
+        end
+        
+        if @bound_corner1
+          d_vb = boid.bound(@bound_corner1,@bound_corner2,@bound_encouragement)
+          d_v.add(d_vb)
+        end
+
+        if @free_will
+          d_vf = Vector.new([rand(@rebellion),rand(@rebellion)])
+          d_v.add(d_vf)
+        end
+
+        velocity_update << d_v
+      end
+
+      #calculate a new velocity, limit the speed and update the position of the boids
+      @boids.each_with_index do |boid,index|
+        boid.velocity.add(velocity_update[index])
+        boid.limit(@velocity_limit)
+        boid.move
+      end
+      
+    end
+  end
+  
+  #Represents a boid : You can think of it as a fish or a bird
+  class Boid
+    #position of the boid
+    attr_accessor :position
+    #distance done by the boid by unit of time chosen by the application using the lib
+    attr_accessor :velocity
+    
+    #the initial parameters of the boid are the responsibility of the calling application
+    def initialize(position,velocity)
+      @position = position
+      @velocity = velocity
+    end
+
+    def dimension
+      @position.dimension
+    end
+
+    #Move a boid of one step
+    def move
+      @position.add(@velocity)
+    end
+
+    #Limits the velocity of the boid so it doesn't go supersonic.
+    def limit(velocity_limit)
+      velocity_norm = @velocity.norm
+      if velocity_norm > velocity_limit
+        @velocity.mul(velocity_limit / velocity_norm)
+      end
+    end
+
+    def go_to(goal)
+      goal.clone.sub(@position)
+    end
+
+    def bound(bound_corner1,bound_corner2,bound_encouragement)
+      v = Vector.zero(dimension)
+      v.each_index do |i|
+        if @position[i] < bound_corner1[i]
+          v[i] = bound_encouragement[i]
+        elsif @position[i] > bound_corner2[i]
+          v[i] = -bound_encouragement[i]
+        end
+      end
+      v
+    end
+
+    #Moves the boid to the center of mass : Rule 1 of Conrad Parker's pseudo code
+    def cohesion(boids)
+      perceived_center = Vector.zero(dimension)
+      boids.each do |b|
+        if b != self
+          perceived_center.add(b.position)
+        end
+      end
+      perceived_center.div(boids.length - 1).sub(@position)
+    end
+    
+    #Moves the boid away from the other boids which are too close to it : Rule 2 of Conrad Parker's pseudo code
+    def separation(boids,distance)
+      c = Vector.zero(dimension)
+      boids.each do |b|
+        if b != self
+          if b.position.distance_to(@position) < distance
+            c.add(@position).sub(b.position)
+          end
+        end
+      end
+      c
+    end
+    
+    #Modifies the velocity so the boids have the tendency to go in the same direction : Rule 3 of Conrad Parker's pseudo code
+    def alignment(boids)
+      perceived_velocity = Vector.zero(dimension)
+      boids.each do |b|
+        if b != self
+          perceived_velocity.add(b.velocity)
+        end
+      end
+      perceived_velocity.div(boids.length - 1).sub(@velocity)
+    end
+    
+  end
+
+  
+
+end

data/lib/ruboid/vector.rb

@@ -0,0 +1,98 @@
+module Ruboid
+  
+  #Pure Ruby simplistic vector arithmetic class with no checks at all
+  #For speed, the NArray library could be considered (but some part is in C)
+  #Vectors taking part in operations are assumed to be of the same dimension
+  class Vector
+    attr_accessor :coords
+        
+    include Enumerable
+    
+    def initialize(array)
+      @coords = array
+    end
+
+    def clone
+      Vector.new(@coords.clone)
+    end
+
+    def self.zero(dimension)
+      Vector.new(Array.new(dimension,0.0))
+    end
+    
+    def to_s
+      @coords.join(",")
+    end
+
+    def each
+      @coords.each { |c| yield c}
+    end
+
+    def each_index
+      0.upto(dimension-1) { |i| yield i}
+    end
+    
+    def dimension
+      @coords.length
+    end
+
+    def [](n)
+      @coords[n]
+    end
+
+    def []=(n,value)
+      @coords[n]=value
+    end
+
+    #Calculates the euclidian distance between 2 vectors
+    def distance_to(vector)
+      diff = self.clone.sub(vector)
+      distance = diff.inject(0) do |distance_acc,value|
+        distance_acc + value**2
+      end
+      Math.sqrt(distance)
+    end
+
+    #Calculates the euclidian norm of the vector
+    def norm
+      distance_to(Vector.zero(dimension))
+    end
+    
+    def add(vector)
+      @coords.each_index do |i|
+        @coords[i] += vector[i] 
+      end
+      self
+    end
+
+    def sub(vector)
+      @coords.each_index do |i|
+        @coords[i] -= vector[i] 
+      end
+      self
+    end
+
+    def div(scalar)
+      @coords.each_index do |i|
+        @coords[i] /= scalar
+      end
+      self
+    end
+
+    def mul(scalar)
+      @coords.each_index do |i|
+        @coords[i] *= scalar
+      end
+      self
+    end
+
+    #Tests for the equality of vectors
+    def ==(vector)
+      @coords.each_index do |i|
+        return false if @coords[i] !=  vector[i] 
+      end
+      true
+    end
+  end
+
+end

data/rakefile.rb

@@ -0,0 +1,48 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+task :default => :test
+
+desc "Run the tests"
+Rake::TestTask::new do |t|
+    t.test_files = FileList['test/test*.rb']
+    t.verbose = true
+end
+
+desc "Generate the documentation"
+Rake::RDocTask::new do |rdoc|
+  rdoc.rdoc_dir = 'ruboid-doc/'
+  rdoc.title    = "Ruboid Documentation"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification::new do |s|
+  s.platform = Gem::Platform::RUBY
+
+  s.name = 'Ruboid'
+  s.version = "0.0.1"
+  s.summary = "Ruby Boid Library"
+  s.description ="Ruboid is a ruby implementation of Craig Reynolds' Boid alogrithm (http://www.red3d.com/cwr/boids/), which realistically simulates the behaviour of a flock of creatures with a small set of simple rules."
+  s.author = 'Guilhem Vellut' 
+  s.email = 'guilhem.vellut+georuby@gmail.com' 
+  s.homepage = "http://thepochisuperstarmegashow.com"
+  
+  s.requirements << 'none'
+  s.require_path = 'lib'
+  s.files = FileList["lib/**/*.rb", "test/**/*.rb", "README","MIT-LICENSE","rakefile.rb"]
+  s.test_files = FileList['test/test*.rb']
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README"]
+  s.rdoc_options.concat ['--main',  'README']
+end
+
+desc "Package the library as a gem"
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/test/test_vector.rb

@@ -0,0 +1,71 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'ruboid'
+require 'test/unit'
+
+include Ruboid
+
+class TestVector < Test::Unit::TestCase
+  
+  def test_add
+    a = Vector.new([1,2])
+    b = Vector.new([3,4])
+    assert_equal([4,6],a.add(b).coords)
+  end
+
+  def test_sub
+    a = Vector.new([1.5,2.6])
+    b = Vector.new([3.1,4.7])
+    assert_equal([-1.6,-2.1],a.sub(b).coords)
+  end
+
+  def test_mul
+    a = Vector.new([1.5,2.6])
+    assert_equal([3.0,5.2],a.mul(2).coords)
+  end
+
+  def test_div
+    a = Vector.new([1.5,2.6])
+    assert_equal([0.75,1.3],a.div(2).coords)
+  end
+
+  def test_equal
+    a = Vector.new([1.5,2.6])
+    b = Vector.new([3.1,4.7])
+    assert(a != b)
+    
+    c = Vector.new([1.5,2.6])
+    assert(a == c)
+  end
+
+  def test_dimension
+    assert_equal(2,Vector.new([1.5,2.6]).dimension)
+  end
+
+  def test_modification
+    a = Vector.new([1.5,2.6])
+    a[0] = 2
+
+    assert_equal([2,2.6],a.coords)
+    assert_equal(2,a[0])
+  end
+
+  def test_zero
+    a = Vector.zero(2)
+    assert_equal(2,a.dimension)
+    assert_equal([0,0],a.coords)
+  end
+
+  def test_norm
+    a = Vector.new([3,4])
+    assert_equal(5,a.norm)
+  end
+
+  def test_distance_to
+    a = Vector.new([2,3])
+    b = Vector.new([2,9])
+
+    assert_equal(6,a.distance_to(b))
+  end
+
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: Ruboid
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2006-05-11 00:00:00 +05:00
+summary: Ruby Boid Library
+require_paths: 
+- lib
+email: guilhem.vellut+georuby@gmail.com
+homepage: http://thepochisuperstarmegashow.com
+rubyforge_project: 
+description: Ruboid is a ruby implementation of Craig Reynolds' Boid alogrithm (http://www.red3d.com/cwr/boids/), which realistically simulates the behaviour of a flock of creatures with a small set of simple rules.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Guilhem Vellut
+files: 
+- lib/ruboid.rb
+- lib/ruboid/ruboid.rb
+- lib/ruboid/vector.rb
+- test/test_vector.rb
+- README
+- MIT-LICENSE
+- rakefile.rb
+test_files: 
+- test/test_vector.rb
+rdoc_options: 
+- --main
+- README
+extra_rdoc_files: 
+- README
+executables: []
+
+extensions: []
+
+requirements: 
+- none
+dependencies: []
+