tracksperanto 1.0.0

data/Manifest.txt

@@ -0,0 +1,37 @@
+Manifest.txt
+README.txt
+Rakefile
+bin/tracksperanto
+lib/export/base.rb
+lib/export/flame_stabilizer.rb
+lib/export/mux.rb
+lib/export/pftrack.rb
+lib/export/shake_text.rb
+lib/export/syntheyes.rb
+lib/import/base.rb
+lib/import/flame_stabilizer.rb
+lib/import/shake_script.rb
+lib/import/shake_text.rb
+lib/import/syntheyes.rb
+lib/middleware/base.rb
+lib/middleware/scaler.rb
+lib/middleware/slipper.rb
+lib/pipeline.rb
+lib/tracksperanto.rb
+test/.DS_Store
+test/helper.rb
+test/samples/.DS_Store
+test/samples/flyover2DP_syntheyes.txt
+test/samples/megaTrack.action.3dtrack.stabilizer
+test/samples/one_shake_tracker.txt
+test/samples/one_shake_tracker_from_first.txt
+test/samples/shake_tracker_nodes.shk
+test/samples/shake_tracker_nodes_to_syntheyes.txt
+test/samples/three_tracks_in_one_stabilizer.shk
+test/samples/two_shake_trackers.txt
+test/samples/two_tracks_in_one_tracker.shk
+test/test_keyframe.rb
+test/test_shake_export.rb
+test/test_shake_script_import.rb
+test/test_shake_text_import.rb
+test/test_syntheyes_import.rb

data/README.txt

@@ -0,0 +1,56 @@
+= Tracksperanto
+
+* http://guerilla-di.org/tracksperanto
+
+== Description
+
+Tracksperanto is a universal 2D-track translator between many apps.
+
+Import support:
+* Shake script (one tracker node per tracker)
+* Shake tracker node export (textfile with many tracks per file), also exported by Boujou and others
+* PFTrack 2dt files
+* Syntheyes 2D tracking data exports (UV coordinates)
+
+Export support:
+
+* Shake text file (many trackers per file), also accepted by Boujou
+* PFTrack 2dt file (with residuals)
+* Syntheyes 2D tracking data import (UV coordinates)
+
+The main way to use Tracksperanto is to use the supplied "tracksperanto" binary, like so:
+  
+  tracksperanto -f ShakeScript -w 1920 -h 1080 /Films/Blockbuster/Shots/001/script.shk
+
+ShakeScript is the name of the translator that will be used to read the file (many apps export tracks as .txt files so
+there is no way for us to autodetect them all). -w and -h stand for Width and Height and define the size of your comp (different
+tracking apps use different coordinate systems and we need to know the size of the comp to properly convert these). You also have
+additional options like -xs, -ys and --slip - consult the usage info for the tracksperanto binary.
+
+The converted files will be saved in the same directory as the source, if resulting converted files already exist ++they will be overwritten without warning++.
+
+== Modularity
+
+Tracksperanto supports many export and import formats. It also can help when you need to import and export the same format,
+but you need some operation applied to the result (like scaling a proxy track up). Internally, Tracksperanto talks
+Exporters, Importers and Middlewares. Any processing chain usually works like this:
+
+1) The tracker file is read and trackers and their keyframes are extracted, converting them to the internal representation.
+   For some formats you need to supply the width and height of the source material
+2) The trackers and their keyframes are dumped to all export formats Tracksperanto supports, optionally passing through middleware
+
+== Internal coordinate system
+
+Frame numbers start from zero (frame 0 is first frame of the track).
+
+Tracksperanto uses the Shake coordinates as base. Image is Y-positive, X-positive, absolute pixel values up and right (zero is in the
+lower left corner). Some apps use a different coordinate system so translation will take place on import or on export, respectively.
+
+We also use residual and not correlation (residual is how far the tracker strolls away, correlation is how sure the tracker is
+about what it's doing). Residual is the inverse of correlation (with total correlation of one the residual excursion becomes zero).
+
+== 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).

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'hoe'
+require './lib/tracksperanto'
+
+
+# Disable spurious warnings when running tests, ActiveMagic cannot stand -w
+Hoe::RUBY_FLAGS.replace ENV['RUBY_FLAGS'] || "-I#{%w(lib test).join(File::PATH_SEPARATOR)}" + 
+  (Hoe::RUBY_DEBUG ? " #{RUBY_DEBUG}" : '')
+  
+Hoe.new('tracksperanto', Tracksperanto::VERSION) do |p|
+  p.rubyforge_name = 'guerilla-di'
+  p.developer('Julik Tarkhanov', 'me@julik.nl')
+end

data/bin/tracksperanto

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# == Synopsis
+# 
+# Translate a 2D track file from a single format to many others
+#
+# == Usage
+# 
+#   tracksperanto -f shakescript /Films/Blockbuster/Shots/001/script.shk -w 1920 -h 1080
+#   
+# == Author
+#   Julik <me@julik.nl>
+
+require File.dirname(__FILE__) + '/../lib/tracksperanto'
+require File.dirname(__FILE__) + '/../lib/pipeline'
+require 'optparse'
+
+# Sane defaults
+reader_klass = Tracksperanto::Import::ShakeScript
+width = 1920
+height = 1080
+scale_x = 1.0
+scale_y = 1.0
+slip = 0
+golden_tracks = false
+
+readers = Tracksperanto::Import.constants.map{|e| e.to_s }.reject{|e| e == 'Base'}
+informative_readers = readers.reject{|e| e == 'ShakeScript'}
+
+parser = OptionParser.new do | p |
+ p.banner = "Usage: tracksperanto -f ShakeScript -w 1920 -h 1080 /Films/Blockbuster/Shots/001/script.shk"
+ p.on(" -f", "--from TRANSLATOR", String, "Use the specific import translator (defaults to ShakeScript, but can be \
+ #{informative_readers.join(', ')})") do | f |
+   begin
+     reader_klass = Tracksperanto::Import.const_get(f)
+   rescue NameError => e
+     reader_list = readers.join("\n\t")
+     STDERR.puts "Unknown reader #{f.inspect}, available readers:\n\t#{readers}"
+     exit(-1)
+    end
+ end
+ p.on(" -w", "--width WIDTH_IN_PIXELS", Integer, "Absolute input comp width in pixels") { |w| width = w }
+ p.on(" -h", "--height HEIGHT_IN_PIXELS", Integer, "Absolute input comp height in pixels") {|w| height = w }
+ p.on(" -xs", "--xscale X_SCALING_FACTOR", Float, "Scale the result in X by this factor (1.0 is the default)") {|sx| scale_x = sx }
+ p.on(" -ys", "--yscale Y_SCALING_FACTOR", Float, "Scale the result in Y by this factor (1.0 is the default)") {|sy| scale_y = sy }
+ p.on(" -s", "--slip FRAMES", Integer, "Slip the result by this number of frames, positive is 'later'") {|sy| slip = sy }
+ p.on(" -g", "--golden", "Reset the residuals of all trackers to 0 (ignore correlation)") {|g_flag| 
+   golden_tracks = g_flag
+ }
+end
+
+begin
+  parser.parse!
+rescue OptionParser::MissingArgument => e
+  STDERR.puts "Unknown argument: #{e.message}"
+  puts parser
+  exit(-1)
+end
+
+input_file = ARGV.pop
+if !input_file
+  STDERR.puts "No input file provided - should be the last argument"
+  puts parser
+  exit(-1)
+end
+
+pipe = Tracksperanto::Pipeline.new
+pipe.run(input_file, width, height, reader_klass) do | scaler, slipper, golden |
+  slipper.slip = slip
+  scaler.x_factor = scale_x
+  scaler.y_factor = scale_y
+  golden.enabled = golden_tracks
+end
+
+puts "Converted #{pipe.converted_points} trackers"

data/lib/export/base.rb

@@ -0,0 +1,35 @@
+# Base exporter
+class Tracksperanto::Export::Base
+  
+  def self.inherited(by)
+    Tracksperanto.exporters << by
+    super
+  end
+  
+  # Should return the suffix and extension of this export file (like "_flame.stabilizer"). It's a class
+  # method because it gets requested before the exporter is instantiated
+  def self.desc_and_extension
+    "data.txt"
+  end
+  
+  def initialize(write_to_io)
+    @io = write_to_io
+  end
+  
+  # Called on export start
+  def start_export( img_width, img_height)
+  end
+  
+  # Called on export end
+  def end_export
+  end
+  
+  # Called on tracker start, one for each tracker. Start of the next tracker
+  # signifies that the previous tracker has passed by
+  def start_tracker_segment(tracker_name)
+  end
+  
+  # Called for each tracker keyframe
+  def export_point(at_frame_i, abs_float_x, abs_float_y, float_residual)
+  end
+end

data/lib/export/flame_stabilizer.rb

@@ -0,0 +1,50 @@
+class Tracksperanto::Export::FlameStabilizer < Tracksperanto::Export::Base
+  PREAMBLE = '' #__DATA__.read
+  
+  # Should return the suffix and extension of this export file (like "_flame.stabilizer")
+  def self.desc_and_extension
+    "flame.stabilizer"
+  end
+  
+  def start_export(w, h)
+    @width = w, @height = h
+  end
+  
+  def start_tracker_segment(tracker_name)
+    @tracker_count ||= 0
+    @tracker_count += 1
+  end
+  
+  def end_export
+    preamble = PREAMBLE % [ @tracker_count, @width, @height]
+  end
+  
+  def export_point(frame, abs_float_x, abs_float_y, float_residual)
+  end
+end
+
+__END__
+StabilizerFileVersion 5.0
+CreationDate Tue Dec  9 21:02:02 2008
+
+
+NbTrackers %d
+Selected 0
+FrameWidth %d
+FrameHeight %d
+AutoKey yes
+MotionPath yes
+Icons yes
+AutoPan no
+EditMode 1
+Format 0
+Padding
+	Red 0
+	Green 0
+	Blue 0
+Oversampling no
+Opacity 50
+Zoom 3
+Field no
+Backward no
+Anim

data/lib/export/mux.rb

@@ -0,0 +1,33 @@
+# Multiplexor. Does not inherit Base so that it does not get used as a translator
+class Tracksperanto::Export::Mux
+  attr_accessor :outputs
+  
+  def initialize(*outputs)
+    @outputs = outputs.flatten
+  end
+  
+  # Called on export start
+  def start_export( img_width, img_height)
+    @outputs.each do | output |
+      output.start_export( img_width, img_height)
+    end
+  end
+
+  # Called on tracker start, one for each tracker
+  def start_tracker_segment(tracker_name)
+    @outputs.each do | output |
+      output.start_tracker_segment(tracker_name)
+    end
+  end
+
+  # Called for each tracker keyframe
+  def export_point(at_frame_i, abs_float_x, abs_float_y, float_residual)
+    @outputs.each do | output |
+      output.export_point(at_frame_i, abs_float_x, abs_float_y, float_residual)
+    end
+  end
+  
+  def end_export
+    @outputs.each{|o| o.end_export }
+  end
+end

data/lib/export/pftrack.rb

@@ -0,0 +1,30 @@
+class Tracksperanto::Export::Pftrack < Tracksperanto::Export::Base
+    
+    # Should return the suffix and extension of this export file (like "_flame.stabilizer")
+    def self.desc_and_extension
+      "pftrack.2dt"
+    end
+    
+    def start_tracker_segment(tracker_name)
+      # If there was a previous tracker, write it out
+      # - now we know how many keyframes it has
+      if @prev_tracker && @prev_tracker.any?
+        block = [
+          "\n",
+          @tracker_name.inspect, # "autoquotes"
+          @prev_tracker.length,
+          @prev_tracker.join("\n")
+        ]
+        @io.puts block.join("\n")
+      end
+      
+      # Setup for the next tracker
+      @prev_tracker = []
+      @tracker_name = tracker_name
+    end
+    
+    def export_point(frame, abs_float_x, abs_float_y, float_residual)
+      line = "%s %.3f %.3f %.3f" % [frame, abs_float_x, abs_float_y, float_residual]
+      @prev_tracker << line
+    end
+end

data/lib/export/shake_text.rb

@@ -0,0 +1,29 @@
+class Tracksperanto::Export::ShakeText < Tracksperanto::Export::Base
+  PREAMBLE = "TrackName %s\n   Frame             X             Y   Correlation\n"
+  POSTAMBLE = "\n"
+  
+  # Should return the suffix and extension of this export file (like "_flame.stabilizer")
+  def self.desc_and_extension
+    "shake_trackers.txt"
+  end
+  
+  def start_tracker_segment(tracker_name)
+    if @any_tracks
+      @io.puts POSTAMBLE
+    else
+      @any_tracks = true
+    end
+    
+    @io.puts PREAMBLE % tracker_name
+  end
+  
+  def end_export
+    @io << "\n"
+  end
+   
+  def export_point(frame, abs_float_x, abs_float_y, float_residual)
+    # Shake starts from frame 1, not 0
+    line = "   %.2f   %.3f   %.3f   %.3f" % [frame + 1, abs_float_x, abs_float_y, 1 - float_residual]
+    @io.puts line
+  end
+end

data/lib/export/syntheyes.rb

@@ -0,0 +1,32 @@
+class Tracksperanto::Export::SynthEyes < Tracksperanto::Export::Base
+  
+  # Should return the suffix and extension of this export file (like "_flame.stabilizer")
+  def self.desc_and_extension
+    "syntheyes_2dt.txt"
+  end
+  
+  def start_export( img_width, img_height)
+    @width, @height = img_width, img_height
+  end
+  
+  def start_tracker_segment(tracker_name)
+    @tracker_name = tracker_name
+  end
+  
+  def export_point(frame, abs_float_x, abs_float_y, float_residual)
+    values = [@tracker_name, frame] + syntheyes_coords(abs_float_x, abs_float_y)
+    @io.puts("%s %d %.6f %.6f 30" % values)
+  end
+  
+  private
+    
+    # Syntheyes wants very special coordinates, Y down X right,
+    # 0 is center and values are UV float -1 to 1, doubled
+    def syntheyes_coords(abs_x, abs_y)
+      w, h = 2560, 1080
+      x = (abs_x / @width.to_f) - 0.5
+      y = (abs_y / @height.to_f) - 0.5
+      # .2 to -.3, y is reversed and coords are double
+      [x * 2, y * -2]
+    end
+end

data/lib/import/base.rb

@@ -0,0 +1,24 @@
+require 'stringio'
+
+class Tracksperanto::Import::Base
+  include Tracksperanto::Safety
+  
+  # The original width of the tracked image
+  # Some importers need it
+  attr_accessor :width
+  
+  # The original height of the original image.
+  # Some importers need it
+  attr_accessor :height
+  safe_reader :width, :height
+  
+  def self.inherited(by)
+    Tracksperanto.importers << by
+    super
+  end
+  
+  # Should return an array of Tracksperanto::Tracker objects
+  def parse(track_file_content)
+    []
+  end
+end

data/lib/import/flame_stabilizer.rb

@@ -0,0 +1,34 @@
+require 'stringio'
+
+class Tracksperanto::Import::FlameStabilizer < Tracksperanto::Import::Base
+  # Flame records channels in it's .stabilizer file. Per tracker, we use tracker1/track/x and tracker1/track/y as the base
+  # tracking value. Then, the tracker1/shift/x and tracker1/shift/y are added to it. The problem is that when we track backwards
+  # the main reference keyframe for the x and y coordinates that sets the base for the animation might be at the last frame, at
+  # a frame in the middle or in the end of the setup. We have to pluck it out and then we compute the shift relative to the values
+  # in this main frame. Obviously we discard the track width and search width information as we cannot use it in any meaningful way.
+  #
+  # Here is how the relevant portions look like this (note the tab indents, not spaces, indentation starts at hashmark)
+  #Channel tracker1/shift/x
+  #	Extrapolation linear
+  #	Value 0
+  #	Size 185
+  #	KeyVersion 1
+  #	Key 0
+  #		Frame 1
+  #		Value 0
+  #		Interpolation linear
+  #		RightSlope 0.15802
+  #		LeftSlope 0.15802
+  #		End
+  #	Key 1
+  #
+  # This is in big lines:
+  # (tabs)Key(space)Value
+  def parse(stabilizer_setup_content)
+    trackers = []
+    
+    io = StringIO.new(stabilizer_setup_content)
+    
+    trackers
+  end
+end