tracksperanto 2.1.1 → 2.2.0

data/DEVELOPER_DOCS.rdoc

@@ -30,45 +30,47 @@ to write your own Pipeline class or reimplement parts of it.
 Almost every module in Tracksperanto has a method called report_progress. This method is used to notify an external callback of what you are doing, and helps keep
 the software user-friendly. A well-behaved Tracksperanto module should manage it's progress reports properly.
 
-=== Sample script
-
-require "rubygems"
-require "tracksperanto"
-
-include Tracksperanto
-
-# Create the importer object
-some_importer = Importer.new(:width => 1024, :height => 576)
-
-# Some object responding to #push has to be the receiver
-# In this case we will use an array but this might get out of hand
-# if you have alot of trackers - Tracksperanto uses a disk-based
-# buffer for this instead (see Accumulator)
-some_importer.receiver = [] 
+=== Reusing components
 
-# Run the import with the importer
-some_importer.stream_parse((File.open("source_file.fmt")))
+Tracksperanto contains some nice bits, such as a full grammar lexer for Shake scripts (Tracksperanto::ShakeGrammar::Lexer), a couple of handy buffering
+classes (Tracksperanto::BufferIO and Tracksperanto::Accumulator) and a parser for any Flame setups containing channels (Tracksperanto::Import::FlameStabilizer).
+Play responsibly.
 
-# Now the receiver contains trackers! Weeee!
-trackers = importer.receiver
-
-# Create the exporter and pass the output file to it
-some_exporter = Exporter.new(File.open("exported_file.other", "wb"))
-
-# Now add some middlewares, for example a Scale
-scaler = Middleware::Scaler.new(some_exporter, :x_factor => 2)
-# ... and a slip
-slipper = Middleware::Slipper.new(scaler, :offset => 2)
-# Middlewares wrap exporters and other middlewares, so you can chain them
-# ad nauseam
-
-# Now when we send export commands to the Slipper it will play them through
-# to the Scaler and the Scaler in turn will send commands to the exporter.
-slipper.start_export(1024, 576)
-trackers.each do | t |
- slipper.start_tracker_segment(t.name)
- t.each {|kf slipper.export_point(kf.frame, kf.abs_x, kf.abs_y, kf.residual) }
- slipper.end_tracker_segment
-end
+=== Sample script
 
-# And we are done!
+  require "rubygems"
+  require "tracksperanto"
+
+  include Tracksperanto
+
+  # Create the importer object, for example for a Shake script.
+  # get_importer will give you the good class even you get the capitalization
+  # wrong!
+  some_importer = Tracksperanto.get_importer("shakescript").new(:width => 1024, :height => 576)
+  some_importer.io = File.open("source_file.fmt")
+  
+  # The importer responds to each() so if your file is not too big you can just load all the trackers
+  # as an array. If you expect to have alot of trackers investigate a way to buffer them on disk
+  # instead (see Accumulator)
+  trackers = some_importer.to_a
+  
+  # Create the exporter and pass the output file to it
+  some_exporter = Tracksperanto.get_exporter("flamestabilizer").new(File.open("exported_file.other", "wb"))
+  
+  # Now add some middlewares, for example a Scale
+  scaler = Middleware::Scaler.new(some_exporter, :x_factor => 2)
+  # ... and a slip
+  slipper = Middleware::Slipper.new(scaler, :offset => 2)
+  # Middlewares wrap exporters and other middlewares, so you can chain them
+  # ad nauseam
+  
+  # Now when we send export commands to the Slipper it will play them through
+  # to the Scaler and the Scaler in turn will send commands to the exporter.
+  slipper.start_export(1024, 576)
+  trackers.each do | t |
+   slipper.start_tracker_segment(t.name)
+   t.each {|kf slipper.export_point(kf.frame, kf.abs_x, kf.abs_y, kf.residual) }
+   slipper.end_tracker_segment
+  end
+
+  # And we are done!

data/History.txt

@@ -1,3 +1,10 @@
+=== 2.2.0 / 2011-03-01
+
+* Improve documentation substantially
+* Changed the Import::Base interface yo use enumeration instead of @receiver.
+  Upside: This allows us to convert importers to an array of trackers and other niceties.
+  Downside: stream_parse will be deprecated. It is however still available for backwards compatibility
+  
 === 2.1.1 / 2011-02-14
 
 * Fix handling of Shake scripts containing stabilizer nodes with no animation

data/Manifest.txt

@@ -2,7 +2,7 @@ DEVELOPER_DOCS.rdoc
 History.txt
 MIT_LICENSE.txt
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
 bin/tracksperanto
 lib/export/base.rb
@@ -26,6 +26,7 @@ lib/import/equalizer4.rb
 lib/import/flame_stabilizer.rb
 lib/import/match_mover.rb
 lib/import/maya_live.rb
+lib/import/nuke_grammar/utils.rb
 lib/import/nuke_script.rb
 lib/import/pftrack.rb
 lib/import/shake_grammar/catcher.rb
@@ -152,6 +153,7 @@ test/middleware/test_reformat_middleware.rb
 test/middleware/test_scaler_middleware.rb
 test/middleware/test_shift_middleware.rb
 test/middleware/test_slip_middleware.rb
+test/test_accumulator.rb
 test/test_buffer_io.rb
 test/test_cli.rb
 test/test_const_name.rb

data/{README.txt → README.rdoc}

@@ -41,10 +41,6 @@ footage you are tracking came cropped or in a wrong aspect - the only way to sol
 will be to retrack it from scratch. Tracksperanto allows you to work around this
 by applying simple transformations to the tracks.
 
-== Licensing
-
-Tracksperanto is made avalable under the MIT license that is included in the package.
-
 == Usage
 
 The main way to use Tracksperanto is with the the supplied "tracksperanto" binary, like so:
@@ -69,7 +65,7 @@ Import and export support:
 * Syntheyes 2D tracking data exports
 * 3DE point exports (as output by the default script) - versions 3 and 4
 * MatchMover Pro .rz2
-* MayaLive track export (square pixel aspect only, you will need to write some extra code to convert that)
+* MayaLive track export (square pixel aspect only, you will need to write some extra code if your tracks are based on nonsquare pixels)
 * Flame .stabilizer file
 * Boujou feature track export
 
@@ -79,19 +75,21 @@ Import only:
 == Modularity
 
 Tracksperanto is very modular and can process data passing through it (like
-scaling a proxy track up). Internally, Tracksperanto talks Exporters, Importers and
-Middlewares. Any processing chain (called a Pipeline) usually works like this:
+scaling a proxy track up). Consult the --help option to see what is available.
 
-* Tracker file is read and trackers and their
-  keyframes are extracted, converting them to
-  the internal representation.
-* Trackers and their keyframes are dumped to all export
-  formats Tracksperanto supports, optionally passing through Middleware
+== Development
 
+If you are interested in reusing Tracksperanto's code or adding modules to the software consult
+the {short developer introduction}[DEVELOPER_DOCS.rdoc]
 
 == Limitations
 
 Information about the search area, reference area and offset is not passed along (outside
 of scope for the app and different trackers handle these differently, if at all). For some
 modules no residual will be passed along (3D tracking apps generally do not export residual
-with backprojected 3D features).
+with backprojected 3D features).
+
+
+== Licensing
+
+Tracksperanto is made avalable under the MIT license that is included in the package.

data/Rakefile

@@ -8,12 +8,14 @@ begin
     (Hoe::RUBY_DEBUG ? " #{RUBY_DEBUG}" : '')
   
   Hoe.spec('tracksperanto') do | p |
+    p.readme_file   = 'README.rdoc'
+    p.extra_rdoc_files  = FileList['*.rdoc']
     p.version = Tracksperanto::VERSION
+    
     p.extra_deps = {"progressbar" => ">=0"}
     p.extra_dev_deps = {"flexmock" => ">=0"}
     p.rubyforge_name = 'guerilla-di'
     p.developer('Julik Tarkhanov', 'me@julik.nl')
-    p.extra_rdoc_files = p.extra_rdoc_files.reject{|e| e =~ "samples\/"}
     p.clean_globs = %w( **/.DS_Store  coverage.info **/*.rbc .idea)
   end
 rescue LoadError

data/lib/export/nuke_script.rb

@@ -1,6 +1,7 @@
 # Export each tracker as a single Tracker3 node
 class Tracksperanto::Export::NukeScript < Tracksperanto::Export::Base
-    #:nodoc:
+    
+    #:nodoc
     
     NODE_TEMPLATE = %[
 Tracker3 {
@@ -27,7 +28,7 @@ Constant {
  xpos 0
  ypos -60
 }]  
-    #:doc:
+    #:doc
     
     # Offset by which the new nodes will be shifted down in the node graph
     SCHEMATIC_OFFSET = 30

data/lib/import/base.rb

@@ -1,16 +1,18 @@
-# The base class for all the import modules. By default, when you inherit from this class the inherited class will be included
-# in the list of supported Tracksperanto importers. The API that an importer should present is very basic, and consists only of a few methods.
-# The main method is parse(io) which should return an array of Tracker objects.
+# The base class for all the import modules. By default, when you inherit from
+# this class the inherited class will be included in the list of supported
+# Tracksperanto importers. The API that an importer should present is very
+# basic, and consists only of a few methods. The main method is
+# stream_parse(io)
 class Tracksperanto::Import::Base
+  include Enumerable
   include Tracksperanto::Safety
   include Tracksperanto::Casts
   include Tracksperanto::BlockInit
   include Tracksperanto::ZipTuples
   include Tracksperanto::ConstName
   
-  # Every time the importer accumulates a tracker this object's #push method will be called.
-  # Can be an array or a more full-featured buffer
-  attr_accessor :receiver
+  # Handle to the IO with data being parsed
+  attr_accessor :io
   
   # Tracksperanto will assign a proc that reports the status of the import to the caller.
   # This block is automatically used by report_progress IF the proc is assigned. Should
@@ -18,17 +20,14 @@ class Tracksperanto::Import::Base
   # yourself)
   attr_accessor :progress_block
   
-  # The original width of the tracked image.
+  # The original width and height of the tracked image.
   # If you need to know the width for your specific format and cannot autodetect it,
   # Trakcksperanto will assign the passed width and height to the importer object before running
   # the import. If not, you can replace the assigned values with your own. At the end of the import
   # procedure, Tracksperanto will read the values from you again and will use the read values
   # for determining the original comp size. +width+ and +height+ MUST return integer values after
   # the import completes
-  attr_accessor :width
-  
-  # The original height of the comp, same conventions as for width apply
-  attr_accessor :height
+  attr_accessor :width, :height
   
   # These reader methods will raise when the values are nil
   cast_to_int :width, :height
@@ -41,6 +40,9 @@ class Tracksperanto::Import::Base
     super
   end
   
+  # OBSOLETE, do not use
+  attr_accessor :receiver
+  
   # Return an extension WITH DOT if this format has a typical extension that
   # you can detect (like ".nk" for Nuke) 
   def self.distinct_file_ext
@@ -64,28 +66,15 @@ class Tracksperanto::Import::Base
     @progress_block.call(message) if @progress_block
   end
   
-  # OBSOLETE: do not implement this method in your importer. This is used to accumulate trackers in an array
-  # and then send it to the caller. Used in tests.
-  def parse(track_file_io)
-    @receiver = []
-    stream_parse(track_file_io)
-    @receiver
-  end
-  
-  # The main method of the parser. Will receive an IO handle to the file being imported, and should
-  # send each consecutive tracker via the send_tracker method.
-  # Note that in general it's a good idea to stream-parse a document
-  # instead of bulk-reading it into memory (since Tracksperanto tries to be mem-efficient when dealing
-  # with large files)
-  def stream_parse(track_file_io)
+  # The main method of the parser. Should
+  # yield each tracker that has been fully parsed. After calling this method the caller can ask for
+  # width and height as well.
+  def each
   end
   
-  # When a tracker has been detected completely (all keyframes) call this method with the tracker object as argument
+  # OBSOLETE: do not use
   def send_tracker(tracker_obj)
-    if @receiver
-      @receiver.push(tracker_obj)
-    else
-      raise "Tracker received but no @receiver has been set for #{self.inspect}"
-    end
+    STDERR.puts "Import::Base#send_tracker has been deprecated, please rewrite your importer to use yield(t) inside each instead"
+    @receiver.push(tracker_obj)
   end
 end

data/lib/import/boujou.rb

@@ -4,13 +4,13 @@ class Tracksperanto::Import::Boujou < Tracksperanto::Import::Base
     "Boujou feature tracks export"
   end
   
-  def stream_parse(io)
-    wrapped_io = Tracksperanto::ExtIO.new(io)
+  def each
+    wrapped_io = Tracksperanto::ExtIO.new(@io)
     detect_columns(wrapped_io)
     trackers = {}
     filtering_trackers_from(wrapped_io) do | name, frame, x, y |
       if @last_tracker && (name != @last_tracker.name)
-        send_tracker(@last_tracker) if @last_tracker && @last_tracker.any?
+        yield(@last_tracker) if @last_tracker && @last_tracker.any?
         @last_tracker = nil
       end
       
@@ -22,7 +22,7 @@ class Tracksperanto::Import::Boujou < Tracksperanto::Import::Base
       @last_tracker.keyframe!(:frame => (frame.to_i - 1), :abs_y => (@height.to_f - y.to_f), :abs_x => x)
     end
     
-    send_tracker(@last_tracker) if @last_tracker && @last_tracker.any?
+    yield(@last_tracker) if @last_tracker && @last_tracker.any?
   end
   
   private

data/lib/import/equalizer3.rb

@@ -9,10 +9,10 @@ class Tracksperanto::Import::Equalizer3 < Tracksperanto::Import::Base
     true
   end
   
-  def stream_parse(passed_io)
-    io = Tracksperanto::ExtIO.new(passed_io)
+  def each
+    io = Tracksperanto::ExtIO.new(@io)
     detect_format!(io)
-    extract_trackers(io)
+    extract_trackers(io) {|t| yield(t) }
   end
   
   private
@@ -25,7 +25,7 @@ class Tracksperanto::Import::Equalizer3 < Tracksperanto::Import::Base
     def extract_trackers(io)
       while line = io.gets do
         if line =~ /^(\w+)/ # Tracker name
-          send_tracker(@last_tracker) if @last_tracker && @last_tracker.any?
+          yield(@last_tracker) if @last_tracker && @last_tracker.any?
           @last_tracker = Tracksperanto::Tracker.new(:name => line.strip)
           report_progress("Capturing tracker #{line.strip}")
         elsif line =~ /^\t/
@@ -33,7 +33,7 @@ class Tracksperanto::Import::Equalizer3 < Tracksperanto::Import::Base
         end
       end
       
-      send_tracker(@last_tracker) if @last_tracker && @last_tracker.any?
+      yield(@last_tracker) if @last_tracker && @last_tracker.any?
     end
     
     def make_keyframe(from_line)

data/lib/import/equalizer4.rb

@@ -5,11 +5,10 @@ class Tracksperanto::Import::Equalizer4 < Tracksperanto::Import::Base
     "3DE v4 point export file"
   end
   
-  
-  def stream_parse(passed_io)
-    io = Tracksperanto::ExtIO.new(passed_io)
+  def each
+    io = Tracksperanto::ExtIO.new(@io)
     num_t = detect_num_of_points(io)
-    num_t.times { send_tracker(extract_tracker(io)) }
+    num_t.times { yield(extract_tracker(io)) }
   end
   
   private

data/lib/import/flame_stabilizer.rb

@@ -71,17 +71,17 @@ class Tracksperanto::Import::FlameStabilizer < Tracksperanto::Import::Base
     private :to_ary
   end
   
-  def stream_parse(io)
+  def each
     report_progress("Extracting setup size")
-    self.width, self.height = extract_width_and_height_from_stream(io)
+    self.width, self.height = extract_width_and_height_from_stream(@io)
     report_progress("Extracting all animation channels")
-    channels = extract_channels_from_stream(io)
+    channels = extract_channels_from_stream(@io)
     
     raise "The setup contained no channels that we could process" if channels.empty?
     raise "A channel was nil" if channels.find{|e| e.nil? }
     
     report_progress("Assembling tracker curves from channels")
-    scavenge_trackers_from_channels(channels) {|t| send_tracker(t) }
+    scavenge_trackers_from_channels(channels) {|t| yield(t) }
   end
   
   private
@@ -185,12 +185,8 @@ Channel tracker1/ref/x
       shift_tuples = zip_curve_tuples(shift_x, shift_y)
       track_tuples = zip_curve_tuples(track_x, track_y)
       
-      base_x, base_y = begin
-        report_progress("Detecting base value")
-        find_base_x_and_y(track_tuples, shift_tuples)
-      rescue UseBase
-        [track_x.base_value, track_y.base_value]
-      end
+      report_progress("Detecting base value")
+      base_x, base_y =  find_base_x_and_y(track_tuples, shift_tuples)
       
       total_kf = 1
       t.keyframes = shift_tuples.map do | (at, x, y) |
@@ -205,18 +201,10 @@ Channel tracker1/ref/x
       return t
     end
     
-    UseBase = RuntimeError
-    
     def find_base_x_and_y(track_tuples, shift_tuples)
       base_track_tuple = track_tuples.find do | track_tuple |
         shift_tuples.find { |shift_tuple| shift_tuple[0] == track_tuple [0] }
-      end
-      if base_track_tuple
-        base_track_tuple[1..2]
-      elsif track_tuples[0]
-        track_tuples[0][1..2]
-      else
-        raise UseBase
-      end
+      end || track_tuples[0]
+      base_track_tuple[1..2]
     end
 end

data/lib/import/match_mover.rb

@@ -12,10 +12,9 @@ class Tracksperanto::Import::MatchMover < Tracksperanto::Import::Base
     ".rz2"
   end
   
-  def stream_parse(io)
-    trackers = []
-    detect_format(io)
-    extract_trackers(io) { |t| send_tracker(t) }
+  def each
+    detect_format(@io)
+    extract_trackers(@io) { |t| yield(t) }
   end
   
   private