depix 1.1.6 → 2.0.0

data/History.txt

@@ -1,3 +1,8 @@
+=== 2.0.0 / 2011-06-14
+
+* Depix::Binary is now public, and it's a nice library. Check it out.
+* Ensure 1.9 compatibility. Note that we COMPLACENTLY force strings to US-ASCII when saving them to DPX.
+
 === 1.1.6 / 2010-10-20
 
 * Fix unpacking reals and longs from little-endian DPX headers

data/Manifest.txt

@@ -1,18 +1,20 @@
-DPX_HEADER_STRUCTURE.txt
+DPX_HEADER_STRUCTURE.rdoc
 History.txt
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
 bin/depix-describe
 lib/depix.rb
-lib/depix/benchmark.rb
+lib/depix/binary/descriptor.rb
+lib/depix/binary/fields.rb
+lib/depix/binary/structure.rb
 lib/depix/compact_structs.rb
-lib/depix/dict.rb
 lib/depix/editor.rb
 lib/depix/enums.rb
 lib/depix/reader.rb
 lib/depix/struct_explainer.rb
 lib/depix/structs.rb
+lib/depix/synthetics.rb
 test/samples/026_FROM_HERO_TAPE_5-3-1_MOV.0029.dpx
 test/samples/E012_P001_L000002_lin.0001.dpx
 test/samples/E012_P001_L000002_lin.0002.dpx

data/{README.txt → README.rdoc}

@@ -21,9 +21,9 @@ Writing headers
   editor.headers.time_code = editor.headers.time_code + 1
   editor.commit!
   
-The data returned is described in the DPX_HEADER_STRUCTURE[link:files/DPX_HEADER_STRUCTURE_txt.html]. It's
-a vanilla Ruby object with no extra methods except for the readers that have the same name as the specified
-fields
+The data returned is described in the DPX_HEADER_STRUCTURE.rdoc
+It's a vanilla Ruby object with no extra methods except for the readers that
+have the same name as the specified fields.
 
 The gem also contains an executable called depix-desribe which can be used from the command line
   

data/Rakefile

@@ -8,10 +8,13 @@ Hoe.spec('depix') do |p|
   p.rubyforge_name = 'guerilla-di'
   p.extra_deps << ['timecode']
   p.remote_rdoc_dir = 'depix'
+  p.readme_file   = 'README.rdoc'
+  p.extra_rdoc_files  = FileList['*.rdoc']
+  
   p.clean_globs = %w( **/.DS_Store )
 end
 
 task :describe_structs do
   require File.dirname(__FILE__) + '/lib/depix/struct_explainer'
-  File.open('DPX_HEADER_STRUCTURE.txt', 'w') {|f| f << RdocExplainer.new.get_rdoc_for(Depix::DPX) }
+  File.open('DPX_HEADER_STRUCTURE.rdoc', 'w') {|f| f << RdocExplainer.new.get_rdoc_for(Depix::DPX) }
 end

data/lib/depix.rb

@@ -1,85 +1,24 @@
 require 'rubygems'
 require 'timecode'
 
-require File.dirname(__FILE__) + '/depix/dict'
-require File.dirname(__FILE__) + '/depix/structs'
-require File.dirname(__FILE__) + '/depix/compact_structs'
-require File.dirname(__FILE__) + '/depix/enums'
-require File.dirname(__FILE__) + '/depix/reader'
-require File.dirname(__FILE__) + '/depix/editor'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/binary/fields'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/binary/structure'
+
+require File.expand_path(File.dirname(__FILE__)) + '/depix/structs'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/compact_structs'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/enums'
+
+require File.expand_path(File.dirname(__FILE__)) + '/depix/synthetics'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/reader'
+require File.expand_path(File.dirname(__FILE__)) + '/depix/editor'
 
 
 module Depix
-  VERSION = '1.1.6'
+  VERSION = '2.0.0'
   
   class InvalidHeader < RuntimeError; end
   
-  # Offers convenience access to a few common attributes bypassing the piecemeal structs
-  module Synthetics
-    
-    DEFAULT_DPX_FPS = 25
-    
-    # Get formatted keycode as string, empty elements are omitted
-    def keycode
-      [film.id, film.type, film.offset, film.prefix, film.count].compact.join(' ')
-    end
-    
-    # Return the flame reel name. The data after the first null byte is not meant to be seen 
-    # and is used by Flame internally
-    # as it seems
-    def flame_reel
-      return nil unless orientation.device
-      orientation.device.split(0x00.chr).shift
-    end
-    
-    # Assign reel name
-    def flame_reel=(new_reel)
-      orientation.device = new_reel
-    end
-    
-    # Get television.time_code as a Timecode object with a framerate.
-    # We explicitly use the television frame rate since Northlight
-    # writes different rates for television and film time code
-    def time_code
-      framerates = [television.frame_rate, film.frame_rate, DEFAULT_DPX_FPS]
-      framerate = framerates.find{|e| !e.nil? && !e.zero? }
-      if television.time_code
-        Timecode.from_uint(television.time_code, framerate)
-      else
-        # Assume frame position
-        Timecode.new(film.frame_position, framerate)
-      end
-    end
-    
-    # Assign frame rate and timecode from a Timecode object
-    def time_code=(new_tc)
-      television.time_code, television.frame_rate = new_tc.to_uint, new_tc.fps
-    end
-    
-    # Get the name of the transfer function (Linear, Logarithmic, ...)
-    def colorimetric
-      COLORIMETRIC.invert[image.image_elements[0].colorimetric]
-    end
-    
-    # Get the name of the compnent type (RGB, YCbCr, ...)
-    def component_type
-      COMPONENT_TYPE.invert[image.image_elements[0].descriptor]
-    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)
-    end
-    
-    # Is this DPX file little-endian? This would be an exception, but still useful
-    def le?
-      file.magic == 'XPDS'
-    end
-  end
-  
-  class DPX < Dict
-    include Synthetics
-  end
+  DPX.send(:include, Synthetics)
   
   # Return a DPX object describing a file at path.
   # The second argument specifies whether you need a compact or a full description

data/lib/depix/binary/descriptor.rb

@@ -0,0 +1,56 @@
+# Generates a description of the structure in RDoc format
+class Depix::Binary::StructureExplainer
+  attr_accessor :io, :attr_template, :struct_template
+  
+  TPL = <<eof
+= DPX header structure description
+
+DPX metadata gets returned as a Depix::DPX object with nested properties.
+  
+  meta.file.magic # => "SDPX"
+
+== Metadata structure
+
+%s
+eof
+
+  def initialize
+    @padding =  '  '
+    @attr_template = "%s* <tt>%s</tt> %s"
+    @struct_template = "%s* <tt>%s</tt> %s:"
+    @array_template  = "%s* <tt>%s</tt> %s:"
+  end
+  
+  def get_rdoc_for(struct)
+    @io = StringIO.new
+    explain_struct(struct)
+    TPL % @io.string
+  end
+  
+  def explain_struct(struct, padding = '') #:nodoc:
+    struct.fields.each do | e |
+      if e.is_a?(InnerField)
+        
+        @io.puts( @struct_template % [padding, e.name, e.explain])
+        explain_struct(e.rtype, padding + @padding)
+      
+      elsif e.is_a?(ArrayField)
+        
+        @io.puts( @array_template % [padding, e.name, e.explain])
+        
+        inner_struct = e.members[0]
+        
+        if inner_struct.is_a?(InnerField)
+          explain_struct(inner_struct.rtype, padding + @padding)
+        end
+      else
+        explain_attr(padding, e)
+      end
+    end
+  end
+  
+  def explain_attr(padding, e)
+    type_name = e.rtype ? "(#{e.rtype})" : nil
+    @io.puts( @attr_template % [padding, e.name, e.explain])
+  end
+end

data/lib/depix/binary/fields.rb

@@ -0,0 +1,302 @@
+module Depix
+  module Binary
+  module Fields
+  
+  # Base class for a padded field in a struct
+  class Field
+    attr_accessor :name, # Field name
+                  :length, # Field length in bytes, including any possible padding
+                  :pattern, # The unpack pattern that defines the field
+                  :req, # Is the field required?
+                  :desc, # Field description
+                  :rtype  # To which Ruby type this has to be cast (and which type is accepted as value)
+    alias_method :req?, :req
+    
+    # Hash init
+    def initialize(opts = {})
+      opts.each_pair {|k, v| send(k.to_s + '=', v) }
+    end
+    
+    # Return a cleaned value (like a null-terminated string truncated up to null)
+    def clean(v)
+      v
+    end
+    
+    # Show a nice textual explanation of the field
+    def explain
+      [rtype ? ("(%s)" % rtype) : nil, desc, (req? ? "- required" : nil)].compact.join(' ')
+    end
+    
+    # Return the actual values from the stack. The stack will begin on the element we need,
+    # so the default consumption is shift. Normally all fields shift the stack
+    # as they go, and if they contain nested substructs they will pop the stack as well
+    def consume!(stack)
+      clean(stack.shift)
+    end
+    
+    # Check that the passed value:
+    # a) Matches the Ruby type expected
+    # b) Fits into the slot
+    # c) Does not overflow
+    # When the validation fails should raise
+    def validate!(value)
+      raise "#{name} value required, but got nil in #{name}".strip if value.nil? && req?
+      raise "Value expected to be #{rtype} but was #{value.class}" if !value.nil? && rtype && !value.is_a?(rtype)
+    end
+    
+    # Pack a value passed into a string
+    def pack(value)
+      raise "No pattern defined for #{self}" unless pattern
+      if value.nil?
+        [self.class.const_get(:BLANK)].pack(pattern)
+      else
+        [value].pack(pattern)
+      end
+    end
+  end
+  
+  # unit32 field
+  class U32Field < Field
+    BLANK = 0xFFFFFFFF
+    undef :length=, :pattern=
+    
+    def pattern
+      "N"
+    end
+    
+    def length
+      4
+    end
+    
+    def clean(value)
+      value == BLANK ? nil : value
+    end
+    
+    # Override - might be Bignum although cast to Integer sometimes
+    def validate!(value)
+      raise "#{name} value required, but got nil".strip if value.nil? && req?
+      raise "#{name} value expected to be #{rtype} but was #{value.class}" if !value.nil? && (!value.is_a?(Integer) && !value.is_a?(Bignum))
+      raise "#{name} value #{value} overflows" if !value.nil? && (value < 0 || value >= BLANK)
+    end
+    
+  end
+  
+  # uint8 field
+  class U8Field < Field
+    undef :length=, :pattern=
+
+    BLANK = 0xFF
+
+    def pattern
+      "c"
+    end
+    
+    def length
+      1
+    end
+    
+    def rtype
+      Integer
+    end
+    
+    def clean(v)
+      (v == BLANK || v == -1) ? nil : v
+    end
+    
+    def validate!(value)
+      super(value)
+      raise "#{name} value #{value} out of bounds for 8 bit unsigned int".lstrip if (!value.nil? && (value < 0 || value >= BLANK))
+    end
+  end
+  
+  # Zero-padded filler, can be used to maintain offsets
+  class Filler < Field
+    undef :pattern=
+    def pattern
+      "x#{length ? length.to_i : 1}"
+    end
+    
+    # Leave the stack alone since we skipped
+    def consume(stack)
+      nil
+    end
+    
+    def pack(data)
+      raise "This is a filler, it cannot be reconstructed from a value"
+    end
+  end
+    
+  # uint16 field
+  class U16Field < Field
+    BLANK = 0xFFFF
+    undef :length=, :pattern=
+    
+    def pattern
+      "n"
+    end
+    
+    def length
+      2
+    end
+    
+    def rtype
+      Integer
+    end
+    
+    def clean(v)
+      v == BLANK ? nil : v
+    end
+    
+    def validate!(value)
+      super(value)
+      raise "#{name} value #{value} out of bounds for 16bit unsigned int" if (value < 0 || value >= BLANK)
+    end
+  end
+  
+  # real32 field
+  class R32Field < Field
+    undef :length=, :pattern=
+    BLANK = 0xFFFFFFFF
+    
+    def pattern
+      "g"
+    end
+    
+    def clean(v)
+      v.nan? ? nil : v
+    end
+    
+    def length
+      4
+    end
+    
+    def rtype
+      Float
+    end
+  end
+  
+  # null-terminated string field with fixed padding
+  class CharField < Field
+    BLANK = "\0"
+    undef :pattern=
+    
+    BLANKING_VALUES = [0x00.chr, 0xFF.chr]
+    BLANKING_PATTERNS = BLANKING_VALUES.inject([]) do | p, char |
+      p << /^([#{char}]+)/ << /([#{char}]+)$/mu
+    end
+    
+    def initialize(opts = {})
+      super({:length => 1}.merge(opts))
+    end
+    
+    def pattern
+      "A#{(length || 1).to_i}"
+    end
+    
+    def clean(v)
+      if v == BLANK
+        nil
+      else
+        # Truncate everything from the null byte up
+        upto_nulb = v.split(0x00.chr).shift
+        (upto_nulb.nil? || upto_nulb.empty?) ? nil : upto_nulb
+      end
+    end
+    
+    def rtype
+      String
+    end
+    
+    def validate!(value)
+      super(value)
+      raise "#{value} overflows the #{length} bytes allocated" if !value.nil? && value.length > length
+    end
+    
+    def pack(value)
+      value.ljust(length, "\000") rescue ("\000" * length)
+    end
+  end
+  
+  # Wrapper for an array structure
+  class ArrayField < Field
+    attr_accessor :members
+    undef :length=, :pattern=
+    
+    def length
+      members.inject(0){|_, s| _ + s.length }
+    end
+    
+    def pattern
+      members.inject(''){|_, s| _ + s.pattern }
+    end
+    
+    def consume!(stack)
+      members.map{|m| m.consume!(stack)}
+    end
+    
+    def rtype
+      Array
+    end
+    
+    def explain
+      return 'Empty array' if (!members || members.empty?)
+      tpl = "(Array of %d %s fields)" % [ members.length, members[0].rtype]
+      r = (req? ? "- required" : nil)
+      [tpl, desc, r].compact.join(' ')
+    end
+    
+    def validate!(array)
+      raise "This value would overflow, #{array.length} elements passed but only #{members.length} fit" unless array.length <= members.length
+      raise "This value is required, but the array is empty" if req? && array.empty?
+      array.zip(members).map do | v, m | 
+        m.validate!(v) unless (v.nil? && !m.req?)
+      end
+    end
+    
+    def pack(values)
+      # For members that are present, get values. For members that are missing, fill with null bytes upto length.
+      # For values that are nil, skip packing
+      members.zip(values).map do |m, v| 
+        if !m.req? && v.nil?
+          raise "#{m} needs to provide length" unless m.length
+          "\377" * m.length
+        else
+          v.respond_to?(:pack) ? v.pack : m.pack(v)
+        end
+      end.join
+    end
+  end
+  
+  # Wrapper for a contained structure
+  class InnerField < Field
+    attr_accessor :cast
+    undef :length=, :pattern=
+    
+    def length
+      cast.length
+    end
+    
+    def pattern
+      cast.pattern
+    end
+    
+    def consume!(stack)
+      cast.consume!(stack)
+    end
+    
+    def rtype
+      cast
+    end
+    
+    def validate!(value)
+      super(value)
+      cast.validate!(value) if cast.respond_to?(:validate!) && (!value.nil? || req?)
+    end
+    
+    def pack(value)
+      cast.pack(value)
+    end
+  end
+end
+end
+end