depix 2.0.0 → 3.0.0

data/lib/depix/binary/{descriptor.rb → rdoc_generator.rb}

@@ -1,5 +1,9 @@
+require "stringio"
+
 # Generates a description of the structure in RDoc format
-class Depix::Binary::StructureExplainer
+class Depix::Binary::RdocGenerator
+  include Depix::Binary::Fields
+  
   attr_accessor :io, :attr_template, :struct_template
   
   TPL = <<eof

data/lib/depix/binary/structure.rb

@@ -63,8 +63,14 @@ class Depix::Binary::Structure
     attr_accessor name
     fields << U16Field.new( {:name => name }.merge(opts) )
   end
-
-
+  
+  # Define a blanking field (it's return value is always nil)
+  def self.blanking(name, *extras)
+    length, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << BlankingField.new( {:name => name, :length => length}.merge(opts) )
+  end
+  
   # Define a small unsigned integer
   def self.u8(name, *extras)
     count, opts = count_and_opts_from(extras)
@@ -182,7 +188,7 @@ class Depix::Binary::Structure
   def self.pack(instance, buffer = nil)
     
     # Preallocate a buffer just as big as me since we want everything to remain at fixed offsets
-    buffer ||= ("\000" * length)
+    buffer ||= (0xFF.chr * length)
     
     # We need to enforce ASCII-8bit encoding which in Ruby parlance is actually "bytestream"
     byteify_string(buffer) unless RUBY_VERSION < '1.9.0'
@@ -204,7 +210,6 @@ class Depix::Binary::Structure
 
       # Validate the passed value using the format the field supports
       f.validate!(val)
-      
       packed = f.pack(val)
       
       # Signal offset violation

data/lib/depix/describe.rb

@@ -0,0 +1,53 @@
+# Returns terminal-ready colorized descriptions of DPX headers per file
+class Depix::Describe
+  include Term::ANSIColor
+  
+  # Returns a printable report on all the headers present in the file at the path passed
+  def describe(path, compact = false)
+    struct = Depix.from_file(path, compact)
+    describe_struct(struct) + describe_synthetics_of_struct(struct)
+  end
+  
+  # Returns descriptions of the shorthand synthetic properties
+  def describe_synthetics(path, compact)
+    struct = Depix.from_file(path, compact)
+    describe_synthetics_of_struct(struct)
+  end
+  
+  private
+  
+  # Describe a filled DPX structure
+  def describe_struct(result, pad_offset = 0)
+    result.class.fields.inject([]) do | info, field |
+      value = result.send(field.name)
+      parts = []
+      if value
+        parts << " " * pad_offset
+        parts << red { field.name.to_s }
+        parts << "(#{field.desc})" if field.desc
+        parts << if field.is_a?(Depix::Binary::Fields::InnerField)
+          describe_struct(value, pad_offset + 1)
+        elsif field.is_a?(Depix::Binary::Fields::ArrayField)
+          value.map { | v | v.is_a?(Depix::Binary::Structure) ? describe_struct(v, pad_offset + 1) : v }
+        else
+          blue { value.to_s }
+        end
+      end
+      if parts.any?
+        info << parts.join(' ')
+      end
+      info
+    end.map{|e| ('  ' * pad_offset) + e }.join("\n")
+  end
+  
+  
+  def describe_synthetics_of_struct(struct)
+    fields = Depix::Synthetics.instance_methods.reject{|m| m.to_s.include?('=')}.map do | m |
+      [red{ m.to_s }, blue { struct.send(m).to_s }].join(' : ')
+    end
+    fields.unshift("============")
+    fields.unshift(bold { "\nSynthetic properties" })
+    fields.join("\n")
+  end
+
+end

data/lib/depix/reader.rb

@@ -1,19 +1,7 @@
+require 'term/ansicolor'
+
 module Depix
   class Reader
-  
-    # Returns a printable report on all the headers present in the file at the path passed
-    def describe_file(path, compact = false)
-      header = File.open(path, 'r') { |f| f.read(DPX.length) }
-      struct = parse(header, false)
-      describe_struct(struct) + describe_synthetics_of_struct(struct)
-    end
-  
-    def describe_synthetics_of_struct(struct)
-      Synthetics.instance_methods.reject{|m| m.to_s.include?('=')}.map do | m |
-        [m, struct.send(m)].join(' : ')
-      end.unshift("============").unshift("\nSynthetic properties").join("\n")
-    end
-  
     # Parse DPX headers at the start of file
     def from_file(path, compact)
       header = File.open(path, 'r') { |f| f.read(DPX.length) }
@@ -24,7 +12,19 @@ module Depix
       end
     end
   
-    # Parse a DPX header (blob of bytes starting at the magic word)
+    # Parse a DPX header (blob of bytes starting at the magic word). The "compact"
+    # flag specifies whether a full-blown parser has to be used. This has substantial
+    # speed implications. For example:
+    # Reading DPX header 1000 times, all data
+    #   1.220000   0.080000   1.300000 (  1.898979)
+    # Reading DPX header 1000 times, compact data
+    #   0.480000   0.050000   0.530000 (  0.766509)
+    # This is 2.5 times faster when using compact header form. The compact header form
+    # is usually sufficient for reliable sequence data (it only takes fields which change)
+    # from one frame to another.
+    #
+    # When using the compact form a CompactDPX structure will be returned instead of the
+    # full-blown DPX structure.
     def parse(data, compact)
       magic = data[0..3]
       raise InvalidHeader, "No magic bytes found at start" unless %w( SDPX XPDS).include?(magic)
@@ -42,30 +42,5 @@ module Depix
       struct = compact ? CompactDPX : DPX
       is_le ? struct.apply_le!(data) : struct.apply!(data)
     end
-  
-    # Describe a filled DPX structure
-    def describe_struct(result, pad_offset = 0)
-      result.class.fields.inject([]) do | info, field |
-        value = result.send(field.name)
-        parts = []
-        if value
-          parts << field.desc if field.desc
-          parts << if field.is_a?(Depix::Binary::Fields::InnerField)
-            describe_struct(value, pad_offset + 1)
-          elsif field.is_a?(ArrayField)
-            # Exception for image elements
-            value = result.image_elements[0...result.number_elements] if field.name == :image_elements
-            value.map { | v | v.is_a?(Depix::Binary::Structure) ? describe_struct(v, pad_offset + 2) : v }
-          else
-            value
-          end
-        end
-        if parts.any?
-          info << parts.join(' ')
-        end
-        info
-      end.map{|e| ('  ' * pad_offset) + e }.join("\n")
-    end
-  
   end
 end

data/lib/depix/structs.rb

@@ -18,7 +18,7 @@ module Depix
     char :copyright, 200, :desc => 'Copyright'
     
     u32  :encrypt_key,    :desc => 'Encryption key'
-    char :reserve, 104
+    blanking :reserve, 104
   end
   
   class FilmInfo < Binary::Structure
@@ -38,7 +38,7 @@ module Depix
 
     char :frame_id, 32,   :desc => 'Frame identification (keyframe)' 
     char :slate, 100,     :desc => 'Slate information'
-    char :reserve, 56
+    blanking :reserve, 56
   end
   
   class ImageElement < Binary::Structure
@@ -82,7 +82,7 @@ module Depix
     array :border, :u16, 4, :desc => 'Border validity: XL, XR, YT, YB'
     array :aspect_ratio , :u32, 2, :desc => "Aspect (H:V)"
     
-    char :reserve, 28
+    blanking :reserve, 28
   end
   
   class TelevisionInfo < Binary::Structure
@@ -104,7 +104,7 @@ module Depix
     r32 :break_point,            :desc => 'Break point (?)'
     r32 :white_level,            :desc => 'White level'
     r32 :integration_times,      :desc => 'Integration times (S)'
-    r32 :reserve
+    blanking :reserve, 4 # As long as a real
   end
   
   class UserInfo < Binary::Structure
@@ -123,7 +123,7 @@ module Depix
       elements[0].req = true
     end
     
-    char :reserve, 52
+    blanking :reserve, 52
     
     # Only expose the elements present
     def image_elements #:nodoc:

data/lib/depix/synthetics.rb

@@ -52,13 +52,23 @@ module Depix::Synthetics
     Depix::COMPONENT_TYPE.invert[image.image_elements[0].descriptor]
   end
   
+  # Returns the pixel aspect
+  def pixel_aspect
+    (orientation.aspect_ratio[0].to_f / orientation.aspect_ratio[1].to_f)
+  end
+  
   # Aspect in it's traditional representation (1.77 for 16x9 and so on)
   def aspect
-    "%.2f" % (orientation.aspect_ratio[0].to_f / orientation.aspect_ratio[1].to_f)
+    "%.2f" % (image.pixels_per_line / image.lines_per_element.to_f * pixel_aspect)
   end
   
   # Is this DPX file little-endian?
-  def le?
+  def little_endian?
     file.magic == 'XPDS'
   end
+  
+  def le?
+    # $stderr.puts "Depix::Synthetics.le? is deprecated, use little_endian? instead"
+    little_endian?
+  end
 end

data/test/{test_dict.rb → test_binary.rb}

@@ -1,4 +1,10 @@
+# coding: ASCII-8BIT
+
+# Pay attention. The test verifies packing into bit blobs. These are much nahdier
+# to compare and check as US-ASCII. Even though I am completely into Unicode this is exactly
+# the moment to NOT use it.
 require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/depix' unless defined?(Depix)
 
 include Depix::Binary
 include Depix::Binary::Fields
@@ -227,13 +233,13 @@ class TestArrayField < Test::Unit::TestCase
   
   def test_pack_pads_properly
     f = ArrayField.new :members => [U32Field.new, R32Field.new, R32Field.new]
-    assert_equal "\000\000\000\001@\000\000\000\377\377\377\377", f.pack([1.0, 2.0])
+    assert_equal "\x00\x00\x00\x1A?\x80\x00\x00@\x00\x00\x00", f.pack([26,1.0, 2.0])
     assert_equal f.length, f.pack([1.0, 2.0]).length
   end
 
   def test_does_not_try_to_pack_nil_values
     f = ArrayField.new(:members => [AlwaysInvalidField.new(:length => 2)])
-    assert_equal "\377\377", f.pack([])
+    assert_equal 0xFF.chr * 2, f.pack([nil])
   end
 
 end
@@ -329,7 +335,7 @@ class TestWideIntField < Test::Unit::TestCase
   def test_pack
     w = U32Field.new
     assert_equal "\000\000\000\036", w.pack(30)
-    assert_equal "\377\377\377\377", w.pack(nil)
+    assert_equal "\xFF\xFF\xFF\xFF", w.pack(nil)
   end
 end
 
@@ -345,7 +351,7 @@ class TestCharField < Test::Unit::TestCase
   def test_char_field_pads
     f = CharField.new :name => :foo, :length => 15
     
-    assert_equal "A15", f.pattern
+    assert_equal "Z15", f.pattern
     assert_equal 15, f.length
     assert_equal String, f.rtype
   end
@@ -379,8 +385,8 @@ class TestCharField < Test::Unit::TestCase
   def test_char_field_packs
     f = CharField.new(:length => 6)
     assert_equal "xx\000\000\000\000", f.pack("xx")
-    assert_equal "\000\000\000\000\000\000", f.pack("")
-    assert_equal "\000\000\000\000\000\000", f.pack(nil)
+    assert_equal "\xFF\xFF\xFF\xFF\xFF\xFF", f.pack("")
+    assert_equal "\xFF\xFF\xFF\xFF\xFF\xFF", f.pack(nil)
   end
 end
 
@@ -391,21 +397,17 @@ class TestFloatField < Test::Unit::TestCase
     f = R32Field.new :name  => :foo
     conform_field!(f)
     
-    the_nan = Class.new do
-      def nan?; true; end
-    end.new
-    
     assert_equal "g", f.pattern
     assert_equal 4, f.length
     assert_equal :foo, f.name
     assert_equal Float, f.rtype
-    assert_equal nil, f.clean(the_nan)
   end
   
   def test_pack
     w = R32Field.new
     assert_equal "@fff", w.pack(3.6)
-    assert_equal "O\200\000\000", w.pack(nil)
+    blank = 0xFF.chr * 4
+    assert_equal blank, w.pack(nil)
   end
 end
 
@@ -538,13 +540,13 @@ class TestFieldEmit < Test::Unit::TestCase
     f = CharField.new
     conform_field!(f)
     
-    assert_equal "A1", f.pattern
+    assert_equal "Z1", f.pattern
     assert_equal 1, f.length
     
     f = CharField.new :length => 3
     conform_field!(f)
     
-    assert_equal "A3", f.pattern
+    assert_equal "Z3", f.pattern
     assert_equal 3, f.length
   end
   
@@ -601,7 +603,7 @@ class TestStructure < Test::Unit::TestCase
     c.fields << CharField.new
     
     assert_respond_to c, :pattern
-    assert_equal 'A1A1', c.pattern
+    assert_equal 'Z1Z1', c.pattern
     assert_equal 2, c.length
   end
 
@@ -645,7 +647,22 @@ class TestStructureConsume < Test::Unit::TestCase
 end
 
 class TestStructureEmitDSL < Test::Unit::TestCase
-
+  
+  def test_dict_emit_char
+    c = Class.new(Structure)
+    c.blanking :reserved, :length => 48, :desc => "Reserved"
+    assert c.instance_methods.map{|e| e.to_s }.include?("reserved"),
+      "Should create the tag accessor"
+    
+    assert_equal 1, c.fields.length
+    field = c.fields[0]
+    
+    assert_equal 48, field.length
+    assert_equal "Z48", field.pattern
+    assert_equal :reserved, field.name
+  end
+  
+  
   def test_dict_emit_char
     c = Class.new(Structure)
     c.char :tag, :desc => "Some name"
@@ -656,7 +673,7 @@ class TestStructureEmitDSL < Test::Unit::TestCase
     field = c.fields[0]
 
     assert_equal 1, field.length
-    assert_equal "A1", field.pattern
+    assert_equal "Z1", field.pattern
     assert_equal :tag, field.name
   end
   
@@ -669,7 +686,7 @@ class TestStructureEmitDSL < Test::Unit::TestCase
     assert_equal 1, c.fields.length
     field = c.fields[0]
     assert_equal 3, field.length
-    assert_equal "A3", field.pattern
+    assert_equal "Z3", field.pattern
     assert_equal :joe, field.name
   end
   

data/test/test_depix.rb

@@ -1,5 +1,5 @@
-require File.expand_path(File.dirname(__FILE__)) + '/../lib/depix'
 require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/depix' unless defined?(Depix)
 require "fileutils"
 
 SAMPLE_DPX = File.dirname(__FILE__) + '/samples/E012_P001_L000002_lin.0001.dpx'
@@ -24,7 +24,7 @@ class ReaderTest < Test::Unit::TestCase
     
     assert_equal 320, parsed.image.pixels_per_line
     assert_equal 240, parsed.image.lines_per_element
-
+    
     assert_equal 1, parsed.image.number_elements
     assert_equal 1, parsed.image.image_elements.length
     ie = parsed.image.image_elements[0]
@@ -45,8 +45,7 @@ class ReaderTest < Test::Unit::TestCase
     assert_equal 0,     ie.end_of_line_padding
     assert_equal 0,     ie.end_of_image_padding
     assert_equal "IMAGE DESCRIPTION DATA        ", ie.description
-    assert_equal "E012", 
-      parsed.orientation.device #- this is where Flame writes the reel
+    assert_equal "E012", parsed.orientation.device #- this is where Flame writes the reel
     
     assert_equal 853, parsed.orientation.aspect_ratio[0]
     assert_equal 640, parsed.orientation.aspect_ratio[1]
@@ -66,7 +65,7 @@ class ReaderTest < Test::Unit::TestCase
   
   def test_syntethics
     assert_nothing_raised { Depix::Synthetics }
-
+    
     file = SAMPLE_DPX
     parsed = Depix.from_file(file)
     assert_equal false, parsed.le?
@@ -75,7 +74,16 @@ class ReaderTest < Test::Unit::TestCase
     assert_equal :RGB, parsed.component_type
     assert_equal :Linear, parsed.colorimetric
     assert_equal "E012", parsed.flame_reel
-    assert_equal "1.33", parsed.aspect
+    assert_equal "1.78", parsed.aspect
+    
+    file = File.dirname(SAMPLE_DPX) + "/scratch.dpx"
+    parsed = Depix.from_file(file)
+    assert_equal 1, parsed.pixel_aspect, "Should parse square pixels"
+    assert_equal "1.78", parsed.aspect, "Should parse 16x9 aspect"
+    
+    file = File.dirname(SAMPLE_DPX) + "/026_FROM_HERO_TAPE_5-3-1_MOV.0029.dpx"
+    parsed = Depix.from_file(file)
+    assert_equal "2.37", parsed.aspect, "Should parse 2.37 Viper aspect"
   end
   
   def test_parsed_properly_using_compact_structs
@@ -83,12 +91,6 @@ class ReaderTest < Test::Unit::TestCase
     assert_nothing_raised { Depix.from_file(file, compact = true) }
   end
   
-  def test_describe
-    desc =  Depix.describe_file(SAMPLE_DPX)
-    assert_match(/320/, desc)
-    assert_match(/Offset to data for this image element/, desc)
-  end
-  
   def test_packing
     original_header = File.read(SAMPLE_DPX)[0...Depix::DPX.length]
     
@@ -135,6 +137,13 @@ class ReaderTest < Test::Unit::TestCase
     assert_in_delta 25, dpx.film.frame_rate, 0.01
   end
   
+  def test_fields_properly_niled
+    dpx = Depix.from_file(File.dirname(__FILE__) + "/samples/scratch.dpx")
+    assert_equal "Assimilate,SCRATCH", dpx.file.creator
+    [:project, :copyright, :encrypt_key, :reserve].each do | field |
+      assert_nil dpx.file.send(field), "The blanking field #{field.inspect} should have been decoded as nil"
+    end
+  end
 end
 
 class EditorTest < Test::Unit::TestCase