flame_channel_parser 1.1.1

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,10 @@
+=== 1.1.1 / 2011-05-17
+
+* Added support for 2012 Bezier splines
+  
+=== 1.0.0 / 2011-03-21
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,27 @@
+.autotest
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/flame_channel_parser.rb
+lib/interpolator.rb
+lib/parser_2011.rb
+lib/parser_2012.rb
+lib/segments.rb
+plots.numbers
+plots_2012.numbers
+test/baked.csv
+test/channel_with_constants.dat
+test/curve.csv
+test/sample_channel.dat
+test/snaps/FLEM_BrokenTangents.action
+test/snaps/FLEM_advanced_curve.png
+test/snaps/FLEM_advanced_curve_example_FL2012.action
+test/snaps/FLEM_baked_curve.png
+test/snaps/FLEM_curves_example.action
+test/snaps/FLEM_curves_example_migrated_to_2012.action
+test/snaps/FLEM_std_curve.png
+test/snaps/TW.timewarp
+test/test_flame_channel_parser.rb
+test/test_interpolator.rb
+test/test_segments.rb

data/README.rdoc

@@ -0,0 +1,65 @@
+= flame_channel_parser
+
+* http://guerilla-di.org/flame-channel-parser
+
+== DESCRIPTION:
+
+Includes a small library for parsing and baking anmation curves made on Discrodesk Floke/Inflinto, also known as flame.
+
+== FEATURES/PROBLEMS:
+
+* Only constant extrapolation for now, no looping or pingpong or linear
+* Expressions on channels won't be evaluated (obviously!)
+
+== SYNOPSIS:
+
+    require "flame_channel_parser"
+    channels = File.open("TW_Setup.timewarp") do | f |
+      FlameChannelParser.parse(f)
+    end
+    
+    # Find the channel that we are interested in, in this case
+    # this is the "Timing" channel from any Timewarp setup
+    frame_channel = channels.find{|c| c.name == "Timing/Timing" }
+    
+    # Grab the interpolator object for this channel.
+    interpolator = FlameChannelParser::Interpolator.new(frame_channel)
+    
+    # Now sample from frame 20 to frame 250.
+    # You can also sample at fractional frames if you want to.
+    (20..250).each do | frame_in_setup |
+      p interpolator.value_at(frame_in_setup)
+    end
+    
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+* FIX (sudo gem install, anything else)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Julik Tarkhanov
+
+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/Rakefile

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.spec 'flame_channel_parser' do | p |
+  p.readme_file   = 'README.rdoc'
+  p.extra_rdoc_files  = FileList['*.rdoc'] + FileList['*.txt']
+  p.developer('Julik Tarkhanov', 'me@julik.nl')
+  p.clean_globs = %w( **/.DS_Store  coverage.info **/*.rbc .idea .yardoc)
+end
+
+# vim: syntax=ruby

data/lib/flame_channel_parser.rb

@@ -0,0 +1,24 @@
+require "delegate"
+
+module FlameChannelParser
+  VERSION = '1.1.1'
+  
+  # Parse a Flame setup into an array of ChannelBlock objects
+  def self.parse(io)
+    # Scan the IO
+    parser_class = Parser2011
+    until io.eof?
+      str = io.gets
+      if str =~ /RHandleX/ # Flame 2012, use that parser
+        parser_class = Parser2012
+        break
+      end
+    end
+    io.rewind
+    parser_class.new.parse(io)
+  end
+end
+
+require File.dirname(__FILE__) + "/parser_2011"
+require File.dirname(__FILE__) + "/parser_2012"
+require File.dirname(__FILE__) + "/interpolator"

data/lib/interpolator.rb

@@ -0,0 +1,92 @@
+require File.expand_path(File.dirname(__FILE__)) + "/segments"
+
+# Used to sample Flame animation curves. Pass a Channel
+# object to the interpolator and you can then sample values at arbitrary
+# frames.
+#
+#   i = Interpolator.new(parsed_channel)
+#   i.value_at(245.5) # => will interpolate and return the value
+#
+class FlameChannelParser::Interpolator
+  include FlameChannelParser::Segments
+  
+  attr_reader :segments
+  
+  NEG_INF = (-1.0/0.0)
+  POS_INF = (1.0/0.0)
+  
+  # The constructor will accept a ChannelBlock object and convert it internally to a number of
+  # segments from which samples can be made
+  def initialize(channel)
+    
+    # Edge case - channel has no anim at all
+    if (channel.length == 0)
+      @segments = [ConstantFunction.new(channel.base_value)]
+    elsif (channel.length == 1)
+      @segments = [ConstantFunction.new(channel[0].value)]
+    else
+      @segments = []
+      
+      # TODO: extrapolation is set for the whole channel, both begin and end.
+      # First the prepolating segment
+      @segments << ConstantPrepolate.new(channel[0].frame, channel[0].value)
+      
+      # The last key defines extrapolation for the rest of the curve...
+      channel[0..-2].each_with_index do | key, index |
+        @segments << key_pair_to_segment(key, channel[index + 1])
+      end
+      
+      # so we just output it separately
+      @segments << ConstantExtrapolate.new(@segments[-1].end_frame, channel[-1].value)
+    end
+  end
+  
+  # Sample the value of the animation curve at this frame
+  def sample_at(frame)
+    segment = @segments.find{|s| s.defines?(frame) }
+    segment.value_at(frame)
+  end
+  
+  # Returns the first frame number that is concretely defined as a keyframe
+  # after the prepolation ends
+  def first_defined_frame
+    first_f = @segments[0].end_frame
+    return 1 if first_f == NEG_INF
+    return first_f
+  end
+  
+  # Returns the last frame number that is concretely defined as a keyframe
+  # before the extrapolation starts
+  def last_defined_frame
+    last_f = @segments[-1].start_frame
+    return 100 if last_f == POS_INF
+    return last_f
+  end
+  
+  private
+  
+  # We need both the preceding and the next key
+  def key_pair_to_segment(key, next_key)
+    case key.interpolation
+      when :bezier
+        BezierSegment.new(key.frame, next_key.frame,
+          key.value, next_key.value, 
+          key.r_handle_x, 
+          key.r_handle_y, 
+          next_key.l_handle_x, next_key.l_handle_y)
+      when :natural, :hermite
+        HermiteSegment.new(key.frame, next_key.frame, key.value, next_key.value, key.right_slope, incoming_slope(next_key))
+      when :constant
+        ConstantSegment.new(key.frame, next_key.frame, key.value)
+      else # Linear and safe
+        LinearSegment.new(key.frame, next_key.frame, key.value, next_key.value)
+    end
+  end
+  
+  # Flame uses the right slope for both left and right unless the BrokenSlope tag is set
+  def incoming_slope(key)
+    key.broken? ? key.left_slope : key.right_slope
+  end
+  
+end
+

data/lib/parser_2011.rb

@@ -0,0 +1,121 @@
+require "delegate"
+
+class FlameChannelParser::Parser2011
+  
+  class Key
+    attr_accessor :frame, :value, :interpolation, :extrapolation, :left_slope, :right_slope, :break_slope
+    alias_method :to_s, :inspect
+    
+    def broken?
+      break_slope
+    end
+  end
+  
+  def matchers
+    [
+      [:frame, :to_i,  /Frame ([\-\d\.]+)/],
+      [:value, :to_f,  /Value ([\-\d\.]+)/],
+      [:left_slope, :to_f, /LeftSlope ([\-\d\.]+)/],
+      [:right_slope, :to_f, /RightSlope ([\-\d\.]+)/],
+      [:interpolation, :to_s, /Interpolation (\w+)/],
+      [:extrapolation, :to_s, /Extrapolation (\w+)/],
+      [:break_slope, :to_s, /BreakSlope (\w+)/]
+    ]
+  end
+  
+  def create_key
+    Key.new
+  end
+  
+  class ChannelBlock < DelegateClass(Array)
+    attr_accessor :base_value
+    attr_accessor :name
+    def initialize(io, channel_name, parent_parser)
+      super([])
+      
+      @parser = parent_parser
+      @name = channel_name.strip
+      
+      base_value_matcher = /Value ([\-\d\.]+)/
+      keyframe_count_matcher = /Size (\d+)/
+      indent = nil
+      
+      while line = io.gets
+        
+        unless indent 
+          indent = line.scan(/^(\s+)/)[1]
+          end_mark = "#{indent}End"
+        end
+        
+        if line =~ keyframe_count_matcher
+          $1.to_i.times { push(extract_key_from(io)) }
+        elsif line =~ base_value_matcher && empty?
+          self.base_value = $1.to_f
+        elsif line.strip == end_mark
+          break
+        end
+      end
+      
+    end
+    
+
+    
+    def create_key
+      Key.new
+    end
+    
+    INTERPS = [:constant, :linear, :hermite, :natural, :bezier]
+    
+    def extract_key_from(io)
+      frame = nil
+      end_matcher = /End/
+      
+      key = @parser.create_key
+      matchers = @parser.matchers
+      
+      until io.eof?
+        line = io.gets
+        if line =~ end_matcher
+          return key
+        else
+          matchers.each do | property, cast_method, pattern  |
+              if line =~ pattern
+                v = symbolize_literal($1.send(cast_method))
+                key.send("#{property}=", v) 
+              end
+          end
+        end
+      end
+      raise "Did not detect any keyframes!"
+    end
+    
+    LITERALS = %w( linear constant natural hermite)
+    
+    def symbolize_literal(v)
+      LITERALS.include?(v) ? v.to_sym : v
+    end
+    
+  end
+  
+  CHANNEL_MATCHER = /Channel (.+)\n/
+  
+  def parse(io)
+    channels = []
+    until io.eof?
+      line = io.gets
+      if line =~ CHANNEL_MATCHER && channel_is_useful?($1)
+        report_progress("Extracting channel #{$1}")
+        channels << ChannelBlock.new(io, $1, self)
+      end
+    end
+    channels
+  end
+  
+  def channel_is_useful?(channel_name)
+    true
+  end
+  
+  def report_progress(message)
+    # flunk
+  end
+end

data/lib/parser_2012.rb

@@ -0,0 +1,57 @@
+require "delegate"
+require File.dirname(__FILE__) + "/interpolator"
+
+class FlameChannelParser::Parser2012 < FlameChannelParser::Parser2011
+
+  class ModernKey
+    attr_accessor :frame, :value, :r_handle_x, :l_handle_x, :r_handle_y, :l_handle_y, :curve_mode, :curve_order, :break_slope
+    alias_method :to_s, :inspect
+    
+    # Adapter for old interpolation
+    def interpolation
+      return :constant if @curve_order.to_s == "constant"
+      return :hermite if @curve_order.to_s == "cubic" && (@curve_mode.to_s == "hermite" || @curve_mode.to_s == "natural")
+      return :bezier if @curve_order.to_s == "cubic" && @curve_mode.to_s == "bezier"
+      return :linear if @curve_order.to_s == "linear"
+      
+      raise "Cannot determine interpolation for #{self.inspect}"
+    end
+    
+    # Compute pre-212 slope which we use for interpolations
+    def left_slope
+      dy = value - l_handle_y
+      dx = l_handle_x - frame
+      dy / dx  * -1
+    end
+    
+    # Compute pre-212 slope which we use for interpolations
+    def right_slope
+      dy = value - r_handle_y
+      dx = frame - r_handle_x
+      dy / dx
+    end
+    
+    def broken?
+      break_slope
+    end
+  end
+  
+  def matchers
+     [
+       [:frame, :to_i,  /Frame ([\-\d\.]+)/],
+       [:value, :to_f,  /Value ([\-\d\.]+)/],
+       [:r_handle_x, :to_f, /RHandleX ([\-\d\.]+)/],
+       [:l_handle_x, :to_f, /LHandleX ([\-\d\.]+)/],
+       [:r_handle_y, :to_f, /RHandleY ([\-\d\.]+)/],
+       [:l_handle_y, :to_f, /LHandleY ([\-\d\.]+)/],
+       [:curve_mode, :to_s,  /CurveMode (\w+)/],
+       [:curve_order, :to_s,  /CurveOrder (\w+)/],
+       [:break_slope, :to_s,  /BreakSlope (\w+)/],
+     ]
+   end
+   
+  
+  def create_key
+    ModernKey.new
+  end
+end

data/lib/segments.rb

@@ -0,0 +1,231 @@
+require "matrix"
+
+module FlameChannelParser::Segments
+  
+  # This segment just stays on the value of it's keyframe
+  class ConstantSegment
+  
+    NEG_INF = (-1.0/0.0)
+    POS_INF = (1.0/0.0)
+    
+    attr_reader :start_frame, :end_frame
+    
+    # Tells whether this segment defines the value of the function at this time T
+    def defines?(frame)
+      (frame < end_frame) && (frame >= start_frame)
+    end
+    
+    # Returns the value at this time T
+    def value_at(frame)
+      @v1
+    end
+    
+    def initialize(from_frame, to_frame, value)
+      @start_frame = from_frame
+      @end_frame = to_frame
+    
+      @v1 = value
+    end
+  end
+  
+  # This segment linearly interpolates
+  class LinearSegment < ConstantSegment
+  
+    def initialize(from_frame, to_frame, value1, value2)
+      @vint = (value2 - value1)
+      super(from_frame, to_frame, value1)
+    end
+  
+    # Returns the value at this time T
+    def value_at(frame)
+      on_t_interval = (frame - @start_frame).to_f / (@end_frame - @start_frame)
+      @v1 + (on_t_interval * @vint)
+    end
+  end
+  
+  # This segment does Hermite interpolation
+  # using the Flame algo.
+  class HermiteSegment < LinearSegment
+  
+    # In Ruby matrix columns are arrays, so here we go
+    HERMATRIX = Matrix[
+      [2,  -3,   0,  1],
+      [-2,  3,   0,  0],
+      [1,   -2,  1,  0],
+      [1,   -1,  0,  0]
+    ].transpose
+  
+    def initialize(from_frame, to_frame, value1, value2, tangent1, tangent2)
+      
+      @start_frame, @end_frame = from_frame, to_frame
+      
+      frame_interval = (@end_frame - @start_frame)
+      
+      # Default tangents in flame are 0, so when we do nil.to_f this is what we will get
+      # CC = {P1, P2, T1, T2}
+      p1, p2, t1, t2 = value1, value2, tangent1.to_f * frame_interval, tangent2.to_f * frame_interval
+      @hermite = Vector[p1, p2, t1, t2]
+    end
+  
+    # P[s_] = S[s].h.CC where s is 0..1 float interpolant on T (interval)
+    def value_at(frame)
+    
+      # Q[frame_] = P[ ( frame - 149 ) / (time_to - time_from)]
+      on_t_interval = (frame - @start_frame).to_f / (@end_frame - @start_frame)
+    
+      # S[s_] = {s^3, s^2, s^1, s^0}
+      multipliers_vec = Vector[on_t_interval ** 3,  on_t_interval ** 2, on_t_interval ** 1, on_t_interval ** 0]
+    
+      # P[s_] = S[s].h.CC --> Kaboom!
+      interpolated_scalar = dot_product(HERMATRIX * @hermite, multipliers_vec)
+    end
+  
+    private
+  
+    def dot_product(one, two)
+      sum = 0.0
+      (0...one.size).each { |i|  sum += one[i] * two[i] }
+      sum
+    end
+  
+  end
+  
+  Point = Struct.new(:x, :y, :tanx, :tany)
+
+  class BezierSegment < LinearSegment
+    def initialize(x1, x2, y1, y2, t1x, t1y, t2x, t2y)
+      @start_frame, @end_frame = x1, x2
+
+      @a = Point.new(x1, y1, t1x, t1y)
+      @b = Point.new(x2, y2, t2x, t2y)
+    end
+
+    def value_at(frame)
+      # Solve T from X. This determines the correlation between X and T.
+      t = approximate_t(frame, @a.x, @a.tanx, @b.tanx, @b.x)
+      vy = bezier(t, @a.y, @a.tany, @b.tany, @b.y)
+    end
+
+    private
+    
+    # t is the T interpolant (0 < T < 1)
+    # a is the coordinate of the starting vertex
+    # b is the coordinate of the left tangent handle
+    # c is the coordinate of the right tangent handle
+    # d is the coordinate of right vertex
+    def bezier(t, a, b, c, d)
+      a + (a*(-3) + b*3)*(t) + (a*3 - b*6 + c*3)*(t**2) + (-a + b*3 - c*3 + d)*(t**3)
+    end
+
+    def clamp(value)
+       return 0.0 if value < 0
+       return 1.0 if value > 1
+       return value
+    end
+
+    # /**
+    # * Returns the approximated parameter of a parametric curve for the value X
+    # * @param atX At which value should the parameter be evaluated
+    # * @param p0x The first interpolation point of a curve segment
+    # * @param c0x The first control point of a curve segment
+    # * @param c1x The second control point of a curve segment
+    # * @param P1_x The second interpolation point of a curve segment
+    # * @return The parametric argument that is used to retrieve atX using the parametric function representation of this curve
+    # */
+
+    APPROXIMATION_EPSILON = 1.0e-09 
+    VERYSMALL = 1.0e-20 
+    MAXIMUM_ITERATIONS = 1000
+
+    # This is how OPENCOLLADA suggests approximating Bezier animation curves
+    # http://www.collada.org/public_forum/viewtopic.php?f=12&t=1132
+    def approximate_t (atX, p0x, c0x, c1x, p1x )
+
+       return 0.0 if (atX - p0x < VERYSMALL)
+       return 1.0 if  (p1x - atX < VERYSMALL)
+
+       u, v = 0.0, 1.0
+
+       #  iteratively apply subdivision to approach value atX
+       MAXIMUM_ITERATIONS.times do
+
+          # de Casteljau Subdivision. 
+          a = (p0x + c0x) / 2.0
+          b = (c0x + c1x) / 2.0 
+          c = (c1x + p1x) / 2.0
+          d = (a + b) / 2.0 
+          e = (b + c) / 2.0 
+          f = (d + e) / 2.0 # this one is on the curve!
+
+          # The curve point is close enough to our wanted atX
+          if ((f - atX).abs < APPROXIMATION_EPSILON) 
+             return clamp((u + v)*0.5)
+          end
+
+          # dichotomy
+          if (f < atX)
+             p0x = f
+             c0x = e 
+             c1x = c 
+             u = (u + v) / 2.0 
+          else
+             c0x = a
+             c1x = d
+             p1x = f
+             v = (u + v) / 2.0 
+          end 
+       end 
+
+       return ClampToZeroOne((u + v) / 2) 
+
+    end
+  end
+  
+  # This segment does prepolation of a constant value
+  class ConstantPrepolate < LinearSegment
+    def initialize(upto_frame, base_value)
+      @value = base_value
+      @end_frame = upto_frame
+      @start_frame = NEG_INF
+    end
+    
+    def value_at(frame)
+      @value
+    end
+  
+    private
+      def frame_increment
+        23.0
+      end
+  end
+  
+  # This segment does extrapolation using a constant value
+  class ConstantExtrapolate < LinearSegment
+    def initialize(from_frame, base_value)
+      @start_frame = from_frame
+      @base_value = base_value
+      @end_frame = POS_INF
+    end
+  
+    def value_at(frame)
+      @base_value
+    end
+  end
+  
+  # This can be used for an anim curve that stays constant all along
+  class ConstantFunction < ConstantSegment
+  
+    def defines?(frame)
+      true
+    end
+  
+    def initialize(value)
+      @value = value
+    end
+  
+    def value_at(frame)
+      @value
+    end
+  end
+end
+