depix 1.1.6 → 2.0.0

data/lib/depix/binary/structure.rb

@@ -0,0 +1,239 @@
+# A basic C structs library (only works by value).
+# Here's the basic mode of operation:
+#  1) You define a struct, with a number of fields in it. This hould be a subclass of Dict within which you
+#     create Field objects which are saved in a class variable
+#  3) Each created Field instance knows how big it is and how to produce a pattern to get it's value from the byte stream
+#     by using Ruby's "pack/unpack". Each field thus provides an unpack pattern, and patterns are ordered
+#     into a stack, starting with the first unpack pattern
+#  4) When you parse some bytes using the struct:
+#     - An unpack pattern will be compiled from all of the fields composing the struct,
+#      and it will be a single string. The string gets applied to the bytes passed to parse()
+#     - An array of unpacked values returned by unpack is then passed to the struct's consumption engine,
+#       which lets each field take as many items off the stack as it needs. A field might happily produce
+#       4 items for unpacking and then take the same 4 items off the stack of parsed values. Or not.
+#     - A new structure gets created and for every named field it defines an attr_accessor. When consuming,
+#       the values returned by Field objects get set using the accessors (so accessors can be overridden too!)
+#  5) When you save out the struct roughly the same happens but in reverse (readers are called per field,
+#     then it's checked whether the data can be packed and fits into the alloted number of bytes, and then
+#     one big array of values is composed and passed on to Array#pack)
+# 
+# For example
+# 
+#  class OneIntegerAndOneFloat < Structure
+#    uint32 :identifier, :description => "This is the important ID", :required => true
+#    real :value, :description => "The value that we store"
+#  end
+#  
+#  ready_struct = OneIntegerAndOneFloat.new
+#  ready_struct.identifier = 23 # Plain Ruby assignment
+#  ready_struct.value = 45.0
+#  
+#  binary_file.write(OneIntegerAndOneFloat.pack(ready_struct)) # dumps the packed struct with paddings
+class Depix::Binary::Structure
+  
+  DEF_OPTS = { :req => false, :desc => nil }
+  
+  # Allows us to use field names from Fields module
+  def self.const_missing(c)
+    Depix::Binary::Fields.const_get(c)
+  end
+  
+  # Get the array of fields defined in this struct
+  def self.fields
+    @fields ||= []
+  end
+  
+  # Validate a passed instance
+  def self.validate!(instance)
+    fields.each do | f |
+      f.validate!(instance.send(f.name)) if f.name
+    end
+  end
+  
+  # Define a 4-byte unsigned integer
+  def self.u32(name, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << U32Field.new( {:name => name }.merge(opts) )
+  end
+
+  # Define a double-width unsigned integer
+  def self.u16(name, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << U16Field.new( {:name => name }.merge(opts) )
+  end
+
+
+  # Define a small unsigned integer
+  def self.u8(name, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << U8Field.new( {:name => name }.merge(opts) )
+  end
+
+  # Define a real number
+  def self.r32(name, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << R32Field.new( {:name => name}.merge(opts) )
+  end
+
+  # Define an array of values
+  def self.array(name, mapped_to, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    a = ArrayField.new({:name => name}.merge(opts))
+    a.members = if mapped_to.is_a?(Class) # Array of structs
+      [InnerField.new(:cast => mapped_to)] * count
+    else
+      c = Depix::Binary::Fields.const_get("#{mapped_to.to_s.upcase}Field")
+      [c.new] * count
+    end
+    yield a.members if block_given?
+    fields << a
+  end
+  
+  # Define a nested struct
+  def self.inner(name, mapped_to, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << InnerField.new({:name => name, :cast => mapped_to}.merge(opts))
+  end
+  
+  # Define a char field
+  def self.char(name, *extras)
+    count, opts = count_and_opts_from(extras)
+    attr_accessor name
+    fields << CharField.new( {:name => name, :length => count}.merge(opts) )
+  end
+  
+  # Get the pattern that will be used to unpack this structure and all of it's descendants
+  def self.pattern
+    fields.map{|f| f.pattern }.join
+  end
+  
+  # Get the pattern that will be used to unpack this structure and all of it's descendants
+  # from a buffer with pieces in little-endian byte order
+  def self.pattern_le
+    pattern.tr("gN", "eV")
+  end
+  
+  # How many bytes are needed to complete this structure
+  def self.length
+    fields.inject(0){|_, s| _ + s.length.to_i }
+  end
+  
+  # Consume a stack of unpacked values, letting each field decide how many to consume
+  def self.consume!(stack_of_unpacked_values)
+    new_item = new
+    @fields.each do | field |
+      new_item.send("#{field.name}=", field.consume!(stack_of_unpacked_values)) unless field.name.nil?
+    end
+    new_item
+  end
+  
+  # Apply this structure to data in the string, returning an instance of this structure with fields completed
+  def self.apply!(string)
+    consume!(string.unpack(pattern))
+  end
+  
+  # Apply this structure to data in the string, returning an instance of this structure with fields completed
+  # assume little-endian fields
+  def self.apply_le!(string)
+    consume!(string.unpack(pattern_le))
+  end
+  
+  # Get a class that would parse just the same, preserving only the fields passed in the array. This speeds
+  # up parsing because we only extract and conform the fields that we need
+  def self.only(*field_names)
+    distillate = fields.inject([]) do | m, f |
+      if field_names.include?(f.name) # preserve
+        m.push(f)
+      else # create filler
+        unless m[-1].is_a?(Filler)
+          m.push(Filler.new(:length =>  f.length))
+        else
+          m[-1].length += f.length
+        end
+        m
+      end
+    end
+    
+    anon = Class.new(self)
+    anon.fields.replace(distillate)
+    only_items = distillate.map{|n| n.name }
+    
+    anon
+  end
+  
+  # Get an opaque struct based on this one, that will consume exactly as many bytes as this
+  # structure would occupy, but discard them instead
+  def self.filler
+    only([])
+  end
+  
+  # Only relevant for 1.9
+  def self.byteify_string(string)
+    string.force_encoding("ASCII-8BIT")
+  end
+    
+  # Pack the instance of this struct
+  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)
+    
+    # We need to enforce ASCII-8bit encoding which in Ruby parlance is actually "bytestream"
+    byteify_string(buffer) unless RUBY_VERSION < '1.9.0'
+    
+    # If the instance is nil return pure padding
+    return buffer if instance.nil?
+    
+    # Now for the important stuff. For each field that we have, replace a piece at offsets in the buffer
+    # with the packed results, skipping fillers
+    fields.each_with_index do | f, i |
+      
+      # Skip blanking, we just dont touch it. TODO - test!
+      next if f.is_a?(Filler)
+      
+      # Where should we put that value?
+      offset = fields[0...i].inject(0){|_, s| _ + s.length }
+
+      val = instance.send(f.name)
+
+      # Validate the passed value using the format the field supports
+      f.validate!(val)
+      
+      packed = f.pack(val)
+      
+      # Signal offset violation
+      raise "Improper length for #{f.name} - packed #{packed.length} bytes but #{f.length} is required to fill the slot" if packed.length != f.length
+      
+      # See above, byt we need to do this with the packed string as well
+      byteify_string(packed) unless RUBY_VERSION < '1.9.0'
+      
+      buffer[offset...(offset+f.length)] = packed
+    end
+    raise "Resulting buffer not the same length, expected #{length} bytes but compued #{buffer.length}" if buffer.length != length
+    buffer
+  end
+  
+  private
+
+  # extract_options! on a diet
+  def self.count_and_opts_from(args)
+    options, count = (args[-1].is_a?(Hash) ? DEF_OPTS.merge(args.pop) : DEF_OPTS), (args.shift || 1)
+    [count, options]
+  end
+  
+  public
+  
+  def []=(field, value)
+    send("#{field}=", value)
+  end
+  
+  def [](field)
+    send(field)
+  end
+end

data/lib/depix/compact_structs.rb

@@ -30,7 +30,7 @@ module Depix
 
   
   # A version of the DPX structure that only accounts for the values that change per frame if the ditto_key is set to 1
-  class CompactDPX < Dict
+  class CompactDPX < Binary::Structure
     inner :file, CompactInfo, :desc => "File information, only frame-transient values"
     
     inner :image, ImageInfo.filler

data/lib/depix/reader.rb

@@ -9,11 +9,12 @@ module Depix
     end
   
     def describe_synthetics_of_struct(struct)
-      Synthetics.instance_methods.reject{|m| m.include?('=')}.map do | m |
+      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) }
       begin
@@ -23,7 +24,7 @@ module Depix
       end
     end
   
-    # The hear of Depix
+    # Parse a DPX header (blob of bytes starting at the magic word)
     def parse(data, compact)
       magic = data[0..3]
       raise InvalidHeader, "No magic bytes found at start" unless %w( SDPX XPDS).include?(magic)
@@ -49,12 +50,12 @@ module Depix
         parts = []
         if value
           parts << field.desc if field.desc
-          parts << if field.is_a?(InnerField)
+          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?(Dict) ? describe_struct(v, pad_offset + 2) : v }
+            value.map { | v | v.is_a?(Depix::Binary::Structure) ? describe_struct(v, pad_offset + 2) : v }
           else
             value
           end

data/lib/depix/structs.rb

@@ -1,9 +1,6 @@
-require File.dirname(__FILE__) + '/dict'
-
-
 module Depix
   
-  class FileInfo < Dict
+  class FileInfo < Binary::Structure
     char :magic, 4,       :desc => 'Endianness (SDPX is big endian)', :req => true
     u32  :image_offset,   :desc => 'Offset to image data in bytes', :req => true
     char :version, 8,     :desc => 'Version of header format', :req => true
@@ -24,7 +21,7 @@ module Depix
     char :reserve, 104
   end
   
-  class FilmInfo < Dict
+  class FilmInfo < Binary::Structure
     char :id, 2,          :desc => 'Film mfg. ID code (2 digits from film edge code)'
     char :type, 2,        :desc => 'Film type (2 digits from film edge code)'
     char :offset, 2,      :desc => 'Offset in perfs (2 digits from film edge code)'
@@ -44,7 +41,7 @@ module Depix
     char :reserve, 56
   end
   
-  class ImageElement < Dict
+  class ImageElement < Binary::Structure
     u32 :data_sign, :desc => 'Data sign (0=unsigned, 1=signed). Core is unsigned', :req => true
     
     u32 :low_data,      :desc => 'Reference low data code value'
@@ -66,7 +63,7 @@ module Depix
     char :description, 32
   end
 
-  class OrientationInfo < Dict
+  class OrientationInfo < Binary::Structure
 
     u32 :x_offset
     u32 :y_offset
@@ -88,7 +85,7 @@ module Depix
     char :reserve, 28
   end
   
-  class TelevisionInfo < Dict
+  class TelevisionInfo < Binary::Structure
     u32 :time_code, :desc => "Timecode, formatted as HH:MM:SS:FF in the 4 higher bits of each 8bit group"
     u32 :user_bits, :desc => "Timecode UBITs"
     u8 :interlace,  :desc => "Interlace (0 = noninterlaced; 1 = 2:1 interlace"
@@ -110,12 +107,12 @@ module Depix
     r32 :reserve
   end
   
-  class UserInfo < Dict
+  class UserInfo < Binary::Structure
     char :id, 32, :desc => 'Name of the user data tag'
     u32 :user_data_ptr
   end
   
-  class ImageInfo < Dict
+  class ImageInfo < Binary::Structure
     u16 :orientation, OrientationInfo,    :desc => 'Orientation descriptor',    :req => true
     u16 :number_elements,                   :desc => 'How many elements to scan', :req => true
     
@@ -134,8 +131,8 @@ module Depix
     end
   end
   
-  #:include:DPX_HEADER_STRUCTURE.txt
-  class DPX < Dict
+  # This is the main structure represinting headers of one DPX file, see DPX_HEADER_STRUCTURE.rdoc
+  class DPX < Binary::Structure
     inner :file, FileInfo,   :desc => "File information", :req => true
     inner :image, ImageInfo, :desc => "Image information", :req => true
     inner :orientation, OrientationInfo, :desc => "Orientation", :req => true

data/lib/depix/synthetics.rb

@@ -0,0 +1,64 @@
+# Offers convenience access to a number of interesting fields of the DPX object
+# already decoded into the most usable form (and pulled from a field that you
+# won't expect)
+module Depix::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
+    Depix::COLORIMETRIC.invert[image.image_elements[0].colorimetric]
+  end
+  
+  # Get the name of the compnent type (RGB, YCbCr, ...)
+  def component_type
+    Depix::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?
+  def le?
+    file.magic == 'XPDS'
+  end
+end

data/test/test_depix.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + '/../lib/depix'
+require File.expand_path(File.dirname(__FILE__)) + '/../lib/depix'
 require 'test/unit'
 require "fileutils"
 
@@ -84,22 +84,19 @@ class ReaderTest < Test::Unit::TestCase
   end
   
   def test_describe
-    assert_nothing_raised do
-      desc =  Depix.describe_file(SAMPLE_DPX)
-      assert_match(/320/, desc)
-      assert_match(/Offset to data for this image element/, desc)
-    end
+    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]
     
-    assert_nothing_raised do
-      dpx = Depix.from_string(original_header)
-      packed =  Depix::DPX.pack(dpx, original_header.dup)
+    # If these do not raise anything we are good on the encodings front
+    dpx = Depix.from_string(original_header)
+    packed =  Depix::DPX.pack(dpx, original_header.dup)
+    dpx2 = Depix.from_string(packed)
     
-      dpx2 = Depix.from_string(packed)
-    end
   end
   
   def test_parsing_something_else_should_raise