Springz (Class)

In: Springz.rb
Parent: Object

Each Springz instance represents a single join between two objects. A quick feature overview:

  • The strength of each spring may be varied.
  • The library performs (simple) collision prevention, if desired, between object pairs (see avoid_collisions in apply) as well as between all objects tracked by Springz (see Springz.uncollide and the avoid_collisions parameter of Springz.apply).
  • The desired length of a spring may be non-zero, pushing/pulling objects to achieve a desired separation distance.
  • Objects can be set to have ‘mass’, which effects how far each object moves when the Spring pulls on it. Light objects are pushed/pulled more easily than massive ones. (Note: this does not impart inertia to the movement.)
  • The overall strength of springs can be scaled using Springz.strength_scale

The following bare-bones application shows how to use the library: 

  require 'Springz'

  class Ball
      include Springz::ObjectInterface
      # ...

      def draw_thyself
              x = self.springz_loc.x
              y = self.springz_loc.y

              draw_some_circle_at(x,y)
      end
  end

  b1 = Ball.new
  b2 = Ball.new
  b3 = Ball.new

  Springz.set(b1,b2,1,10)
  Springz.set(b1,b3,2,5)
  Springz.set(b2,b3,0.5,40)

  # Set some random locations to give the library something to work with
  b1.move_to(10,10)
  b2.move_to(20,20)
  b3.move_to(0,0)

  # Apply each spring 100 times
  Springz.apply_all(100)

  # The balls have now been moved to locations which minimize the spring forces

  # Draw the springs
  Springz.all.each{ |spring|
      # draw a line for the spring using a made-up method
      draw_some_line(
              spring.o1.springz_loc.x,
              spring.o1.springz_loc.y,
              spring.o2.springz_loc.x,
              spring.o2.springz_loc.y
      )
  }

  # Draw the balls
  b1.draw_thyself
  b2.draw_thyself
  b3.draw_thyself

Methods

all   apply   apply_all   each   find   hide   new   prevent_collisions   remove_thyself   set   show   strength_scale   strength_scale=   uncollide   use_mass   use_mass=  

Attributes

disabled  [RW]  Should this spring be applied during calls to apply()?
distance  [RW]  The ideal distance the spring should move the objects towards
o1  [R]  The first object associated with the spring
o2  [R]  The second object associated with the spring
strength  [RW]  Strength of this spring, useful mainly in relationship to other springs. This value is scaled by the global Springz.strength_scale class ‘constant’
visible  [RW]  This convenience property does not affect the functionality of the library. Springz are initially set to visible=true; beyond that the use of this property is up to the user. This property is modified by the show and hide methods.

Classes and Modules

Module Springz::ObjectInterface
Class Springz::Point

Public Class methods

all()

Returns an array of all instances created, which haven’t been removed with a call to remove_thyself

apply_all( iterations=1, avoid_collisions=true )
iterations:the number of times to call the apply method
avoid_collisions:should the library attempt to prevent collisions between objects?

Calls the apply method for every spring created and not removed (see all) the number of times specified by iterations.

Additionally, if avoid_collisions is true, prevent_collisions is called at the end of each iteration.

Springs which have disabled=true set will be skipped.

each(&proc)

Applies the supplied block to each instance created, which hasn’t been removed with a call to remove_thyself

Springz.each{ #… } is identical to Springz.all.each{ #… }

find(o1,o2)

Returns the spring set between o1 and o2. If no spring exists between the two objects, returns nil.

See also Springz.set and Springz.new

new(o1, o2, strength=1, distance=0)
o1:the object attached to one end of the spring
o2:the object attached to the other end of the spring
strength:the initial value of the strength attribute for the spring
distance:the initial value of the distance attribute for the spring

Only one spring may exist for each unique pair of objects. If a spring already exists between o1 and o2 that spring will be destroyed (see remove_thyself) and a new spring created.

Objects attached at either end of a spring must include the Springz::ObjectInterface module (or its equivalent methods).

The strength of a spring affects how quickly objects move, and is scaled by the global Springz.strength_scale ‘constant’.

The distance for a spring is the distance the spring is attempting to achieve; with no other springs present, a value of 0 will cause the objects to pull together until they touch, while a value of 200 will cause them to push/pull at each other until they are 200 units away.

See also Springz.set and Springz.find

prevent_collisions()

Attempts to keep objects attached to springs from overlapping; calls uncollide for each unique pair of objects tracked by one or more Springz.

Due to the simplistic way this is applied, some objects may still overlap after a call to this method. Although multiple successive calls yield a better chance of preventing any overlapping, it is possible under some circumstances to have objects still overlapping after a near-infinite number of calls to this method.

set(o1,o2,strength=nil,distance=nil)

Returns the spring set between o1 and o2. If no spring exists between the two objects, a new spring is created.

If strength and/or distance are supplied, the strength and/or distance for the spring is set to the new value; if not supplied, the attributes are left untouched.

See also Springz.find and Springz.new

strength_scale()

Returns the global scale factor which is applied to the strength attribute of each individual spring.

strength_scale=(s)

Sets the global scale factor which is applied to the strength attribute of each individual spring.

uncollide(o1,o2)

Attempts to prevent two objects from overlapping (based only on the springz_radius for each object; see Springz::ObjectInterface).

If an overlap is detected, o1 is moved just far enough away from o2 (along the path connecting their springz_loc points) to fix the problem.

use_mass()

Returns the boolean value indicating whether or not calls to apply take the springz_mass of objects into account.

use_mass=(m)

Sets whether or not calls to apply take into account the springz_mass property for objects on the end of Springz.

Public Instance methods

apply( avoid_collisions=true )

The heart of the library, this method pushes/pulls at the objects attached to in an attempt to move them to the ideal distance.

If Springz.use_mass is true, the springz_mass of each object (see Springz::ObjectInterface) will be used to determine how far each moves. (For example, if o1 has a springz_mass of 100 and o2 has a springz_mass of 300, o2 will move 1/3 the distance that o1 moves.)

If avoid_collisions is true, the objects will not move closer together than the sum of their respective springz_radius properties. (See also uncollide.)

If this spring has its disabled attribute set to true, this method will do nothing and return false.

hide()

Equivalent to mySpring.visible=false

remove_thyself()

Removes this spring from all internal references and returns itself. Of importance is the fact that the spring will no longer appear in the Springz.all array, and thus will not be used if Springz.apply_all is invoked.

show()

Equivalent to mySpring.visible=true

[Validate]