depix 1.0.1 → 1.0.2

data/lib/depix/compact_structs.rb

@@ -0,0 +1,42 @@
+require File.dirname(__FILE__) + '/structs'
+
+module Depix
+  CompactInfo = FileInfo.only(
+    :magic,
+    :ditto_key,
+    :filename,
+    :timestamp 
+  )
+  
+  
+  CompactFilmInfo = FilmInfo.only(
+    :offset,
+    :count,
+    :frame_position,
+    :frame_id,
+    :slate
+  )
+  
+  CompactOrientation = OrientationInfo.only(
+    :filename,
+    :timestamp
+  )
+  
+  CompactTelevision = TelevisionInfo.only(
+    :time_code,
+    :user_bits,
+    :field_number
+  )
+
+  
+  # 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
+    inner :file, CompactInfo, :desc => "File information, only frame-transient values"
+    
+    inner :image, ImageInfo.filler
+    
+    inner :orientation, OrientationInfo, :desc => "Orientation, only frame-transient values"
+    inner :film, CompactFilmInfo, :desc => "Film industry info, only frame-dependent values"
+    inner :television, CompactTelevision, :desc => "TV industry info, only frame-dependent values"
+  end
+end

data/lib/depix/dict.rb

@@ -0,0 +1,343 @@
+module Depix
+  
+  #:stopdoc:
+  class Field
+    attr_accessor :name, :length, :pattern, :req, :desc, :rtype
+    alias_method :req?, :req
+    
+    # Hash init
+    def initialize(opts = {})
+      opts.each_pair {|k, v| send(k.to_s + '=', v) }
+    end
+
+    # Emit an unsigned int field
+    def self.emit_u32(o = {})
+      U32Field.new(o)
+    end
+    
+    # Emit a short int field
+    def self.emit_u8(o = {})
+      U8Field.new(o)
+    end
+
+    # Emit a double int field
+    def self.emit_u16(o = {})
+      U16Field.new(o)
+    end
+    
+    # Emit a char field
+    def self.emit_char(o = {})
+      opts = {:length => 1}.merge(o)
+      CharField.new(opts)
+    end
+    
+    # Emit a float field
+    def self.emit_r32(o = {})
+      R32Field.new(o)
+    end
+    
+    # Return a cleaned value
+    def clean(v)
+      v
+    end
+    
+    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
+    def consume!(stack)
+      clean(stack.shift)
+    end
+  end
+  
+  class U32Field < Field
+    BLANK = 0xFFFFFFFF
+    
+    def pattern
+      "N"
+    end
+    
+    def length
+      4
+    end
+    
+    def clean(value)
+      value == BLANK ? nil : value
+    end
+  end
+  
+  class U8Field < Field
+
+    BLANK = 0xFF
+
+    def pattern
+      "c"
+    end
+    
+    def length
+      1
+    end
+    
+    def rtype
+      Integer
+    end
+    
+    def clean(v)
+      v == BLANK ? nil : v
+    end
+  end
+  
+  class Filler < Field
+    def pattern
+      "x#{length ? length.to_i : 1}"
+    end
+    
+    # Leave the stack alone since we skipped
+    def consume(stack)
+      nil
+    end
+  end
+    
+  class U16Field < Field
+    BLANK = 0xFFFF
+    
+    def pattern
+      "n"
+    end
+    
+    def length
+      2
+    end
+    
+    def rtype
+      Integer
+    end
+    
+    def clean(v)
+      v == BLANK ? nil : v
+    end
+  end
+  
+  class R32Field < Field
+    def pattern
+      "g"
+    end
+    
+    def clean(v)
+      v.nan? ? nil : v
+    end
+    
+    def length
+      4
+    end
+    
+    def rtype
+      Float
+    end
+  end
+  
+  class CharField < Field
+    BLANK = "\0"
+    
+    def pattern
+      "A#{(length || 1).to_i}"
+    end
+    
+    def clean(v)
+      if v == BLANK
+        nil
+      else
+        cleansed = v.gsub(0xFF.chr, '').gsub(0x00.chr, '')
+        cleansed.empty? ? nil : cleansed
+      end
+    end
+    
+    def rtype
+      String
+    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
+  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
+  end
+  
+  # Base class for a struct. Could also be implemented as a module actually
+  class Dict
+    DEF_OPTS = { :req => false, :desc => nil }
+    
+    class << self
+      
+      # Get the array of fields defined in this struct
+      def fields
+        @fields ||= []
+      end
+
+      # Define a 4-byte unsigned integer
+      def u32(name, *extras)
+        count, opts = count_and_opts_from(extras)
+        attr_accessor name
+        fields << Field.emit_u32( {:name => name }.merge(opts) )
+      end
+
+      # Define a double-width unsigned integer
+      def u16(name, *extras)
+        count, opts = count_and_opts_from(extras)
+        attr_accessor name
+        fields << Field.emit_u16( {:name => name }.merge(opts) )
+      end
+
+
+      # Define a small unsigned integer
+      def u8(name, *extras)
+        count, opts = count_and_opts_from(extras)
+        attr_accessor name
+        fields << Field.emit_u8( {:name => name }.merge(opts) )
+      end
+
+      # Define a real number
+      def r32(name, *extras)
+        count, opts = count_and_opts_from(extras)
+        attr_accessor name
+        fields << Field.emit_r32( {:name => name}.merge(opts) )
+      end
+
+      # Define an array of values
+      def 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
+          [Field.send("emit_#{mapped_to}")] * count
+        end
+        fields << a
+      end
+      
+      # Define a nested struct
+      def 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 char(name, *extras)
+        count, opts = count_and_opts_from(extras)
+        attr_accessor name
+        fields << Field.emit_char( {: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 pattern
+        fields.map{|f| f.pattern }.join
+      end
+      
+      # How many bytes are needed to complete this structure
+      def length
+        fields.inject(0){|_, s| _ + s.length }
+      end
+      
+      # Consume a stack of unpacked values, letting each field decide how many to consume
+      def 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 apply!(string)
+        consume!(string.unpack(pattern))
+      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 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)
+        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 filler
+        only([])
+      end
+      
+      private
+
+      # extract_options! on a diet
+      def 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
+    end
+  end
+  
+  #:startdoc:
+end

data/lib/depix/enums.rb

@@ -0,0 +1,43 @@
+module Depix
+  COLORIMETRIC = {
+      :UserDefined => 0,
+      :PrintingDensity => 1,
+      :Linear => 2,
+      :Logarithmic => 3,
+      :UnspecifiedVideo => 4,
+      :SMTPE_274M => 5,
+      :ITU_R709 => 6,
+      :ITU_R601_625L => 7,
+      :ITU_R601_525L => 8,
+      :NTSCCompositeVideo => 9,
+      :PALCompositeVideo => 10,
+      :ZDepthLinear => 11,
+      :DepthHomogeneous => 12
+  }
+  
+  COMPONENT_TYPE = {
+    :Undefined => 0,
+    :Red => 1,
+    :Green => 2,
+    :Blue => 3,
+    :Alpha => 4,
+    :Luma => 6,
+    :ColorDifferenceCbCr => 7,
+    :Depth => 8,
+    :CompositeVideo => 9,
+    :RGB => 50,
+    :RGBA => 51,
+    :ABGR => 52,
+    :CbYCrY422 => 100,
+    :CbYACrYA4224 => 101,
+    :CbYCr444 => 102,
+    :CbYCrA4444 => 103,
+    :UserDef2Element => 150,
+    :UserDef3Element => 151,
+    :UserDef4Element => 152,
+    :UserDef5Element => 153,
+    :UserDef6Element => 154,
+    :UserDef7Element => 155,
+    :UserDef8Element => 156,
+  }
+end

data/lib/depix/struct_explainer.rb

@@ -1,45 +1,13 @@
 # Generates an RDoc description of the DPX structs from the structs.rb file
-class Formatter #:nodoc:
+class RdocExplainer #:nodoc:
   attr_accessor :io, :attr_template, :struct_template
   
-  def initialize
-    @io = STDOUT
-    @attr_template = "%s%s (%s)"
-    @struct_template = "%s%s (which is a hash with the following elements):"
-    @array_template = "%s%s (array , %d members):"
-    @padding =  '  '
-  end
-  
-  def explain_struct(struct, padding = '') #:nodoc:
-    struct.each do | e |
-      key, cast, len = e
-      if cast.is_a?(Depix::Structs::Struct)
-        @io.puts( @struct_template % [padding, key, len])
-        explain_struct(cast, padding + @padding)
-      elsif cast.is_a?(Array) # Repeats
-        @io.puts( @array_template % [padding, key, cast.size])
-        inner_struct = cast[0]
-        ikey, icast, ilen = inner_struct
-        if icast.is_a?(Depix::Structs::Struct)
-          explain_struct(icast, padding + @padding)
-        else
-          @io.puts( @attr_template % [padding, '', icast, ilen])
-        end
-      else
-        @io.puts( @attr_template % [padding, key, cast, len])
-      end
-    end
-  end
-end
-
-class RdocExplainer < Formatter #:nodoc:
   TPL = <<eof
 = DPX header structure description
 
-DPX metadata gets returned as a hash containing other nested hashes. You can address hash keys by symbol, string
-and method name
-
-  meta.file.magic # same as meta[:file][:magic]
+DPX metadata gets returned as a Depix::DPX object with nested properties.
+  
+  meta.file.magic # => "SDPX"
 
 == Metadata structure
 
@@ -47,16 +15,45 @@ and method name
 eof
 
   def initialize
-    super
+    @padding =  '  '
     @attr_template = "%s* <tt>%s</tt> %s"
-    @struct_template = "%s* <tt>%s</tt> hash of"
-    @array_template  = "%s* <tt>%s</tt>  (array , %d members):"
+    @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(Depix::Structs::DPX_INFO)
+    explain_struct(struct)
     TPL % @io.string
   end
+  
+  include Depix
+  
+  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