xrvg 0.0.1 → 0.0.2

data/lib/bezier.rb

@@ -0,0 +1,461 @@
+# +Bezier+ source
+#
+
+require 'bezierspline'
+require 'shape'
+
+# = Base class for cubic bezier curves
+# == Basics
+# See http://en.wikipedia.org/wiki/B%C3%A9zier_curve
+# == Examples
+# Basically, a Bezier curve is a multi-pieces cubic bezier curve. As a first example, you can create bezier curves as follows :
+#  b = Bezier[ :pieces, [[:raw, p1, pc1, pc2, p2]] ]; # raw description, as SVG
+#  b = Bezier[ :pieces, [[:vector, p1, v1, p2, v2]] ]; # more "symetrical" description.
+# For more extensive description, see http://xrvg.rubyforge.org/XRVGBezierCurve.html
+# == Discussion
+# In XRVG, bezier curves must be also viewed as a way to create smooth and non linear interpolation between values (see +Interpolation+)
+#
+# Other point : to run along a bezier curve, you can use two different parametrization :
+# - the curve generic one, that is "curviligne" abscissa, that is length
+# - the bezier parameter, as bezier curves are parametrized curves. For multi-pieces curve, by extension, parameter goes from one integer value to the next one 
+# As Bezier class provides several methods with a parameter input, it is necessary to specify with parameter type you want to use ! For example,
+# to compute a point from a bezier curve, Bezier class defines the point method as follows :
+#   def point( t, parametertype=:length )
+# This is a general declaration : every method with a parameter input will propose such a kind of interface :
+# - t as Float parameter value
+# - parametertype, by default :length, that can have two values, :length or :parameter. :parameter is kept because is far faster than other indexation.
+# == Attributes
+#  attribute :pieces
+class Bezier < Curve
+  attribute :pieces
+
+# -------------------------------------------------------------
+#  builders
+# -------------------------------------------------------------
+
+  # Initialize with the Attributable format
+  # 
+  # 
+  # Licit formats :
+  #   b = Bezier.new( :pieces, [BezierSpline[:raw, p1, pc1, pc2, p2]] )
+  #   b = Bezier[ :pieces, [BezierSpline[:vector, p1, v1, p2, v2]] ]
+  # However, prefer the use of the following builders
+  #   b = Bezier.vector( p1, v1, p2, v2 )
+  #   b = Bezier.raw( p1, pc1, pc2, p2 )
+  #   b = Bezier.single( :raw, p1, pc1, pc2, p2 )
+  #   b = Bezier.multi( [[:raw, p1, pc1, pc2, p2], [:raw, p1, pc1, pc2, p2]] )
+  # The two last syntaxes are provided as shortcuts, as used quite frequently, and must be used instead of :pieces attributable builder
+  def Bezier.[]( *args )
+    self.new( *args )
+  end
+
+  def Bezier.single( type, p1, p2, p3, p4 )
+    return Bezier.new( :pieces, [BezierSpline[type, p1, p2, p3, p4]] )
+  end
+
+  def Bezier.raw( p1, pc1, pc2, p2 )
+    return Bezier.single( :raw, p1, pc1, pc2, p2 )
+  end
+
+  def Bezier.vector( p1, v1, p2, v2 )
+    return Bezier.single( :vector, p1, v1, p2, v2 )
+  end
+
+  def Bezier.multi( rawpieces )
+    return Bezier.new( :pieces, rawpieces.map {|piece| BezierSpline[*piece]} )
+  end
+
+
+  # bezier point, as 
+  #   Bezier[:raw, V2D::O, V2D::O, V2D::O, V2D::O]
+  O = Bezier.raw( V2D::O, V2D::O, V2D::O, V2D::O )
+
+
+  # return piece of index "index",as BezierSpline object
+  #
+  # index can be 
+  # - integer : in that case, simple return @pieces[index]
+  # - float   : in that case, use second default argument
+  # this method must actually be very rarely called, as usually
+  # we want to compute something with index, and in that case we 
+  # want to delegate computation to a BezierSpline, with parameter
+  # mapping parametermapping
+  def piece( index, parametertype=:length )
+    pieceindex = index
+    if index.is_a? Float
+      pieceindex, t = self.parametermapping( index, parametertype )
+    end
+    return @pieces[ pieceindex ]
+  end
+
+  # return number of pieces
+  def piecenumber
+    return @pieces.length
+  end
+
+# -------------------------------------------------------------
+#  curve interface
+# -------------------------------------------------------------
+
+  # overload Curve::viewbox
+  def viewbox
+    return V2D.viewbox( self.pointlist() )
+  end
+
+
+# -------------------------------------------------------------
+#  piece shortcuts
+# -------------------------------------------------------------
+
+  # generic method to return points list of a curve
+  #   b = Bezier[ :pieces, [[:raw, p1, pc1, pc2, p2], [:raw, p2, pc2b, pc3, p3]] ]
+  #   b.pointlist        #=> equiv to b.pointlist(:raw) 
+  #   b.pointlist(:raw)  #=> [p1, pc1, pc2, p2, p2, pc2b, pc3, p3]
+  # if you want to get a particular piece pointlist, do
+  #   b.piece( t ).pointlist(nil|:raw|:vector)
+  # TODO : result must be cached by type
+  def pointlist( type=:raw )
+    result = []
+    @pieces.each {|piece| result = result + piece.pointlist(type)}
+    return result
+  end
+    
+  # shortcut method to get curve first point
+  def firstpoint
+    return self.pointlist()[0]
+  end
+
+  # shortcut method to get curve last point
+  def lastpoint
+    return self.pointlist()[-1]
+  end
+
+  # shortcut method to build Bezier objects for each piece
+  def beziers
+    return self.pieces.map{ |piece| Bezier.single( *piece.data ) }
+  end
+
+# -------------------------------------------------------------
+#  piece delegation computation
+# -------------------------------------------------------------
+
+  # with index (must be Float) and parametertype as inputs, must compute :
+  # - the index of the piece on which the computation must take place
+  # - the new parameter value corresponding to bezier computation input
+  def parametermapping( index, parametertype=:length ) #:nodoc:
+    check_parametertype( parametertype )
+    result = []
+    if parametertype == :length
+      if index < 0.0 
+	index = 0.0
+      elsif index > 1.0
+	index = 1.0
+      end
+      result = length_parameter_mapping( index )
+    else # no need to test parametertype value, as check_parametertype already do it
+      if index < 0.0 
+	index = 0.0
+      elsif index > self.piecenumber
+	index = self.piecenumber.to_f
+      end
+
+      pieceindex = index < self.piecenumber ? index.to_i : (index-1).to_i
+      t          = index - pieceindex
+      result = [pieceindex, t]
+    end
+
+    return result
+  end
+
+  # utilitary method to factorize abscissa parameter type value checking
+  def check_parametertype( parametertype ) #:nodoc:
+    if !(parametertype == :parameter or parametertype == :length )
+      Kernel::raise("Invalid parametertype value #{parametertype}")
+    end
+  end
+
+# -------------------------------------------------------------
+#  bezier computations
+# -------------------------------------------------------------
+
+  # compute a point at curviligne abscissa or parameter t 
+  #
+  # curve method redefinition
+  def point( t, container=nil, parametertype=:length )
+    pieceindex, t = parametermapping( t, parametertype )
+    return self.piece( pieceindex ).point( t, container )
+  end
+  
+  # compute tangent at curviligne abscissa or parameter t 
+  #
+  # curve method redefinition
+  def tangent ( t, container=nil, parametertype=:length )
+    pieceindex, t = parametermapping( t, parametertype )
+    return self.piece( pieceindex ).tangent( t, container )
+  end
+
+  # compute acceleration at curviligne abscissa or parameter t 
+  #
+  # curve method redefinition
+  def acc( t, container=nil, parametertype=:length )
+    pieceindex, t = parametermapping( t, parametertype )
+    return self.piece( pieceindex ).acc( t, container )
+  end
+
+  # curve method redefinition to factorize parametermapping
+  def frame( t, parametertype=:length )
+    pieceindex, t = parametermapping( t, parametertype )
+    tangent = self.piece( pieceindex ).tangent( t )
+    rotation = self.rotation( nil, tangent )
+    scale    = self.scale( nil, tangent )
+    return Frame[ :center, self.piece( pieceindex ).point( t ), :vector, tangent, :rotation, rotation, :scale, scale ]
+  end
+
+# -------------------------------------------------------------
+#  subpiece computation
+# -------------------------------------------------------------
+
+  # generalize Bezier method
+  def subpieces (t1, t2) #:nodoc:
+    pieceindex1, t1 = parametermapping( t1 )
+    pieceindex2, t2 = parametermapping( t2 )
+    result = []
+
+    if pieceindex1 == pieceindex2
+      result = [self.piece( pieceindex1 ).subpiece( t1, t2 )]
+    else
+      result << self.piece( pieceindex1 ).subpiece( t1, 1.0 )
+      if pieceindex1 + 1 != pieceindex2
+	result += self.pieces[pieceindex1+1..pieceindex2-1]
+      end
+      result << self.piece( pieceindex1 ).subpiece( 0, t2 )
+    end
+    return result
+  end
+
+  # compute the sub curve between abscissa t1 and t2
+  #
+  # may result in a multi-pieces Bezier
+  def subbezier( t1, t2)
+    return Bezier.new( :pieces, self.subpieces( t1, t2 ) )
+  end
+
+  # split method
+  if nil
+  def split(nchildren=2, type=:regular)
+    return self.range.split(nchildren,type).map { |range| self.subbezier( range.begin, range.end ) }
+  end
+
+  def subdivise( samples )
+    return samples.pairs.map { |t1, t2| self.subbezier( t1, t2 ) }
+  end
+  end
+
+# -------------------------------------------------------------
+#  reverse
+# -------------------------------------------------------------
+
+  # return a new Bezier curve reversed from current one
+  #
+  # simply reverse BezierSpline pieces, both internally and in the :pieces list
+  def reverse
+    newpieces = @pieces.map {|piece| piece.reverse()}
+    return Bezier.new( :pieces, newpieces.reverse )
+  end
+
+# -------------------------------------------------------------
+#  translation
+# -------------------------------------------------------------
+
+  # translate the Bezier curve, by translating its points
+  def translate( v )
+    return Bezier.new( :pieces, @pieces.map { |piece| piece.translate( v ) } )
+  end    
+
+# -------------------------------------------------------------
+#  similar (transform is used for samplation)
+#    see XRVG#33
+# -------------------------------------------------------------
+
+  # "Similitude" geometric transformation
+  #
+  # See http://en.wikipedia.org/wiki/Similitude_%28geometry%29
+  #
+  # Similtude geometric transformation is (firspoint..lastpoint) -> pointrange
+  #
+  # TODO : method must be put in Curve interface
+  def similar( pointrange )
+    oldRepere = [self.firstpoint,  self.lastpoint - self.firstpoint]
+    newRepere = [pointrange.begin, pointrange.end - pointrange.begin]
+    rotation    = V2D.angle( newRepere[1], oldRepere[1] )
+    if oldRepere[1].r == 0.0
+      Kernel::raise("similar error : bezier is length 0")
+    end
+    scale       = newRepere[1].r / oldRepere[1].r
+    newpoints = []
+    self.pointlist.each do |oldpoint|
+      oldvector = oldpoint - oldRepere[0]
+      newvector = oldvector.rotate( rotation ) * scale
+      newpoints.push( newRepere[0] + newvector )
+    end
+    splines = []
+    newpoints.foreach do |p1, p2, p3, p4|
+      splines.push( BezierSpline[:raw, p1, p2, p3, p4] )
+    end
+    return Bezier[ :pieces, splines ]
+  end    
+
+# -------------------------------------------------------------
+#  concatenation
+# -------------------------------------------------------------
+
+  # Bezier curve concatenation
+  def +( other )
+    return Bezier.new( :pieces, self.pieces + other.pieces )
+  end
+
+# -------------------------------------------------------------
+#  range
+# -------------------------------------------------------------
+
+  # TODO
+  def ranges #:nodoc:
+    (0..self.piecenumber).to_a.pairs.map {|start,stop| Range.new( start, stop )}
+  end
+  
+  # TODO
+  def range #:nodoc:
+    return (0..self.piecenumber)
+  end
+
+# -------------------------------------------------------------
+#  svg
+# -------------------------------------------------------------
+  
+  # return the svg description of the curve
+  #
+  # if firstpoint == lastpoint, curve is considered as closed
+  def svg()
+    # Trace("Bezier::svg #{self.inspect}")
+    path     = ""
+    previous = nil
+    self.pieces().each do |piece|
+      p1, pc1, pc2, p2 = piece.pointlist
+      # Trace("previous #{previous.inspect} p1 #{p1.inspect}")
+      if previous == nil or not (previous - p1).r <= 0.0000001
+	# Trace("svg bezier not equal => M")
+	path += "M #{p1.x},#{p1.y}"
+      end
+      previous = p2
+      path += "C #{pc1.x},#{pc1.y} #{pc2.x},#{pc2.y} #{p2.x},#{p2.y}"
+    end
+
+    if self.firstpoint == self.lastpoint
+      path += " z"
+    end
+
+    result = "<path d=\"#{path}\"/>"
+    return result
+  end
+
+# -------------------------------------------------------------
+#  gdebug
+# -------------------------------------------------------------
+
+  # Display Bezier curve decorated with points and control points 
+  def gdebug(render)
+    self.pieces.each {|piece| piece.gdebug(render)}
+  end
+
+
+# -------------------------------------------------------------
+#  length computation
+# -------------------------------------------------------------
+
+  # return the length of the bezier curve
+  #
+  # simply add pieces lengths
+  def length
+    if not @length
+      @length = compute_length
+    end
+    return @length
+  end
+  
+  # Note : lengthranges building should be more functional ...
+  #        must use an interpolator ?
+  def compute_length #:nodoc:
+    lengths = self.pieces.map {|piece| piece.length}
+    result  = lengths.sum
+    if result == 0.0
+      lengths = [1.0]
+    else
+      psum = 0.0
+      lengths = lengths.map {|v| psum += v/result}
+    end
+    lmin = 0.0
+    @lengthranges = []
+    lengths.each do |llength|
+      @lengthranges << (lmin..llength)
+      lmin = llength
+    end
+    return result
+  end
+
+  def length_parameter_mapping( t ) #:nodoc:
+    if not @lengthranges
+      compute_length
+    end
+    pieceindex = -1
+    @lengthranges.each_with_index do |lrange,i|
+      if lrange.include?( t )
+	pieceindex = i
+	t = lrange.abscissa( t )
+	t = self.piece( i ).parameterfromlength( t )
+	break
+      end
+    end
+    if pieceindex == -1
+      Kernel::raise("length_parameter_mapping error : t #{t} is not in length range #{@lengthranges.inspect}")
+    end
+    return [pieceindex, t]
+  end
+  
+  
+
+# -------------------------------------------------------------
+#  sampler computation
+# -------------------------------------------------------------
+  include Samplable
+  include Splittable
+
+  # filter, sampler methods
+  #
+  # just a shortcut to define easily specific sampler on bezier curve
+  #
+  # TODO : must be defined on Curve interface !!
+  def filter(type=:point, &block)
+    if type == :length
+      return super(:pointbylength, &block )
+    else
+      return super(type, &block).addfilter( self.range )
+    end
+  end
+
+  def apply_split( t1, t2 ) #:nodoc:
+    return self.subbezier( t1, t2 )
+  end
+
+  alias apply_sample point
+  # alias apply_split  subbezier
+  alias sampler      filter
+
+  # TODO : add generic bezier builder from points : must be adaptative !! (use Fitting)
+end
+
+
+
+
+  
+
+