julik-depix 1.0.2

data/lib/depix/struct_explainer.rb

@@ -0,0 +1,59 @@
+# Generates an RDoc description of the DPX structs from the structs.rb file
+class RdocExplainer #:nodoc:
+  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
+  
+  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

data/lib/depix/structs.rb

@@ -0,0 +1,137 @@
+require File.dirname(__FILE__) + '/dict'
+
+
+module Depix
+  
+  class FileInfo < Dict
+    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
+    
+    u32  :file_size,      :desc => "Total image size in bytes", :req => true
+    u32  :ditto_key,      :desc => 'Whether the basic headers stay the same through the sequence (1 means they do)'
+    u32  :generic_size,   :desc => 'Generic header length'
+    u32  :industry_size,  :desc => 'Industry header length'
+    u32  :user_size,      :desc => 'User header length'
+    
+    char :filename, 100,  :desc => 'Original filename'
+    char :timestamp, 24,  :desc => 'Creation 15'
+    char :creator, 100,   :desc => 'Creator application'
+    char :roject, 200,    :desc => 'Project name'
+    char :copyright, 200, :desc => 'Copyright'
+    
+    u32  :encrypt_key,    :desc => 'Encryption key'
+    char :reserve, 104
+  end
+  
+  class FilmInfo < Dict
+    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)'
+    char :prefix, 6,      :desc => 'Prefix (6 digits from film edge code'
+    char :count, 4,       :desc => 'Count (4 digits from film edge code)'
+    char :format, 32,     :desc => 'Format (e.g. Academy)'
+
+    u32 :frame_position,  :desc => 'Frame position in sequence'
+    u32 :sequence_extent, :desc => 'Sequence length'
+    u32 :held_count,      :desc => 'For how many frames the frame is held'
+
+    r32 :frame_rate,      :desc => 'Frame rate'
+    r32 :shutter_angle,   :desc => 'Shutter angle'
+
+    char :frame_id, 32,   :desc => 'Frame identification (keyframe)' 
+    char :slate, 100,     :desc => 'Slate information'
+    char :reserve, 56
+  end
+  
+  class ImageElement < Dict
+    u32 :data_sign, :desc => 'Data sign (0=unsigned, 1=signed). Core is unsigned', :req => true
+    
+    u32 :low_data,      :desc => 'Reference low data code value'
+    r32 :low_quantity,  :desc => 'Reference low quantity represented'
+    u32 :high_data,     :desc => 'Reference high data code value (1023 for 10bit per channel)'
+    r32 :high_quantity, :desc => 'Reference high quantity represented'
+    
+    # TODO: Autoreplace with enum values. 
+    u8 :descriptor,   :desc => 'Descriptor for this image element (ie Video or Film), by enum', :req => true
+    u8 :transfer,     :desc => 'Transfer function (ie Linear), by enum', :req => true
+    u8 :colorimetric, :desc => 'Colorimetric (ie YcbCr), by enum', :req => true
+    u8 :bit_size,     :desc => 'Bit size for element (ie 10)', :req => true
+    
+    u16 :packing,     :desc => 'Packing (0=Packed into 32-bit words, 1=Filled to 32-bit words))', :req => true
+    u16 :encoding,    :desc => "Encoding (0=None, 1=RLE)", :req => true
+    u32 :data_offset, :desc => 'Offset to data for this image element', :req => true
+    u32 :end_of_line_padding, :desc => "End-of-line padding for this image element"
+    u32 :end_of_image_padding, :desc => "End-of-line padding for this image element"
+    char :description, 32
+  end
+
+  class OrientationInfo < Dict
+
+    u32 :x_offset
+    u32 :y_offset
+  
+    r32 :x_center
+    r32 :y_center
+  
+    u32 :x_size, :desc => 'Original X size'
+    u32 :y_size, :desc => 'Original Y size'
+    
+    char :filename, 100, :desc => "Source image filename"
+    char :timestamp, 24, :desc => "Source image/tape timestamp"
+    char :device,    32, :desc => "Input device or tape"
+    char :serial,    32, :desc => "Input device serial number"
+  
+    array :border, :u16, 4, :desc => 'Border validity: XL, XR, YT, YB'
+    array :aspect_ratio , :u32, 2, :desc => "Aspect (H:V)"
+    
+    char :reserve, 28
+  end
+  
+  class TelevisionInfo < Dict
+    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"
+
+    u8 :field_number, :desc => 'Field number'
+    u8 :video_signal, :desc => "Video signal (by enum)"
+    u8 :padding,      :desc => "Zero (for byte alignment)"
+    
+    r32 :horizontal_sample_rate, :desc => 'Horizontal sampling Hz'
+    r32 :vertical_sample_rate,   :desc => 'Vertical sampling Hz'
+    r32 :frame_rate,             :desc => 'Frame rate'
+    r32 :time_offset,            :desc => 'From sync pulse to first pixel'
+    r32 :gamma,                  :desc => 'Gamma'
+    r32 :black_level,            :desc => 'Black pedestal code value'
+    r32 :black_gain,             :desc => 'Black gain code value'
+    r32 :break_point,            :desc => 'Break point (?)'
+    r32 :white_level,            :desc => 'White level'
+    r32 :integration_times,      :desc => 'Integration times (S)'
+    r32 :reserve
+  end
+  
+  class UserInfo < Dict
+    char :id, 32, :desc => 'Name of the user data tag'
+    u32 :user_data_ptr
+  end
+  
+  class ImageInfo < Dict
+    u16 :orientation, OrientationInfo,    :desc => 'Orientation descriptor',    :req => true
+    u16 :number_elements,                   :desc => 'How many elements to scan', :req => true
+    
+    u32 :pixels_per_line,                   :desc => 'Pixels per horizontal line', :req => true
+    u32 :lines_per_element,                 :desc => 'Line count', :req => true
+    array :image_elements, ImageElement, 8, :desc => "Image elements"
+    char :reserve, 52
+  end
+  
+  #:include:DPX_HEADER_STRUCTURE.txt
+  class DPX < Dict
+    inner :file, FileInfo,   :desc => "File information"
+    inner :image, ImageInfo, :desc => "Image information"
+    inner :orientation, OrientationInfo, :desc => "Orientation"
+    inner :film, FilmInfo, :desc => "Film industry info"
+    inner :television, TelevisionInfo, :desc => "TV industry info"
+    inner :user, UserInfo, :desc => "User info"
+  end
+end

data/lib/depix.rb

@@ -0,0 +1,142 @@
+require 'stringio'
+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'
+
+module Depix
+  VERSION = '1.0.3'
+  
+  class InvalidHeader < RuntimeError; end
+  
+  # Offers convenience access to a few common attributes bypassing the piecemeal structs
+  module Synthetics
+    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
+      orientation.device.split("\000").shift
+    end
+    
+    def time_code
+      Timecode.from_uint(television.time_code) #, film.frame_rate)
+    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
+    
+    # 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
+  
+  # Return a DPX object describing a file at path.
+  # The second argument specifies whether you need a compact or a full description
+  def self.from_file(path, compact = false)
+    Reader.new.from_file(path, compact)
+  end
+  
+  # Return a DPX object describing headers embedded at the start of the string.
+  # The second argument specifies whether you need a compact or a full description
+  def self.from_string(string, compact = false)
+    Reader.new.parse(string, compact)
+  end
+  
+  # Retrurn a formatted description of the DPX file at path. Empty values are omitted.
+  def self.describe_file(path, compact = false)
+    Reader.new.describe_file(path, compact)
+  end
+  
+  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) }
+      describe_struct(parse(header, false))
+    end
+    
+    def from_file(path, compact)
+      header = File.open(path, 'r') { |f| f.read(DPX.length) }
+      begin
+        parse(header, compact)
+      rescue InvalidHeader => e
+        raise InvalidHeader, "Invalid header in file #{path}"
+      end
+    end
+    
+    # The hear of Depix
+    def parse(data, compact)
+      magic = data[0..3]
+      
+      raise InvalidHeader unless %w( SDPX XPDS).include?(magic)
+      
+      struct = compact ? CompactDPX : DPX
+      
+      is_be = (magic == "SDPX")
+      version_check = FileInfo.only(:magic, :version)
+      
+      result = begin
+        if is_be
+          version_check.consume!(data.unpack(version_check.pattern))
+        else
+          version_check.consume!(data.unpack(make_le(version_check.pattern)))
+        end
+      rescue ArgumentError
+        raise InvalidHeader
+      end
+      
+      raise InvalidHeader unless result.version == "V1.0"
+       
+      template = is_be ? DPX.pattern : make_le(DPX.pattern)
+      struct.consume!(data.unpack(struct.pattern))
+    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?(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 }
+          else
+            value
+          end
+        end
+        if parts.any?
+          info << parts.join(' ')
+        end
+        info
+      end.map{|e| ('  ' * pad_offset) + e }.join("\n")
+    end
+    
+    # Convert an unpack pattern to LE
+    def make_le(pattern)
+      pattern.gsub(/n/, "v").gsub(/N/, "V").gsub(/g/, "f")
+    end
+    
+  end
+end

data/test/test_depix.rb

@@ -0,0 +1,98 @@
+require File.dirname(__FILE__) + '/../lib/depix'
+require 'test/unit'
+
+class ReaderTest < Test::Unit::TestCase
+  
+  SAMPLE_DPX = File.dirname(__FILE__) + '/samples/E012_P001_L000002_lin.0001.dpx'
+    
+  def test_parsed_properly
+    file = SAMPLE_DPX
+    parsed = Depix.from_file(file)
+    assert_equal "SDPX", parsed.file.magic
+    assert_equal 8192, parsed.file.image_offset
+    assert_equal "V1.0", parsed.file.version
+    assert_equal 319488, parsed.file.file_size
+    assert_equal 1, parsed.file.ditto_key
+    assert_equal 1664, parsed.file.generic_size
+    assert_equal 384, parsed.file.industry_size
+    assert_equal 6144, parsed.file.user_size
+    assert_equal "E012_P001_L000002_lin.0001.dpx", parsed.file.filename
+    assert_equal "2008:12:19:01:18:37:CEST", parsed.file.timestamp
+    assert_equal "UTODESK", parsed.file.creator
+    assert_equal 0, parsed.image.orientation
+    assert_equal 1, parsed.image.number_elements
+    assert_equal 320, parsed.image.pixels_per_line
+    assert_equal 240, parsed.image.lines_per_element
+    assert_equal 0, parsed.image.image_elements[0].data_sign
+    assert_equal 0, parsed.image.image_elements[0].low_data
+    assert_equal 0.0, parsed.image.image_elements[0].low_quantity
+    assert_equal 1023, parsed.image.image_elements[0].high_data
+    assert_in_delta 2.04699993133545, parsed.image.image_elements[0].high_quantity, 1.0 ** -10
+    
+    assert_equal 50, parsed.image.image_elements[0].descriptor # RGB :-)
+    assert_equal 2, parsed.image.image_elements[0].transfer
+    assert_equal 2, parsed.image.image_elements[0].colorimetric
+    assert_equal 10, parsed.image.image_elements[0].bit_size
+    assert_equal 1, parsed.image.image_elements[0].packing
+    assert_equal 0, parsed.image.image_elements[0].encoding
+    assert_equal 8192, parsed.image.image_elements[0].data_offset
+    assert_equal 0, parsed.image.image_elements[0].end_of_line_padding
+    assert_equal 0, parsed.image.image_elements[0].end_of_image_padding
+    assert_equal "IMAGE DESCRIPTION DATA        \000P", parsed.image.image_elements[0].description
+    assert_equal "E012\000\000\000\000x\340\264\020\000\000\000\000\005", 
+      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]
+
+    assert_equal '75', parsed.film.id
+    assert_equal '00', parsed.film.type
+    assert_equal '19', parsed.film.offset
+    assert_equal '740612', parsed.film.prefix
+    assert_equal '9841', parsed.film.count
+    assert_equal 1, parsed.film.frame_position
+    assert_equal 2, parsed.film.sequence_extent
+    assert_equal 1, parsed.film.held_count
+    assert_equal 25.0, parsed.film.frame_rate
+    assert_equal 18157848, parsed.television.time_code
+    assert_equal 0, parsed.television.user_bits
+  end
+  
+  def test_syntethics
+    assert_nothing_raised { Depix::Synthetics }
+
+    file = SAMPLE_DPX
+    parsed = Depix.from_file(file)
+    assert_equal false, parsed.le?
+    assert_equal "75 00 19 740612 9841", parsed.keycode
+    assert_equal "01:15:11:18", parsed.time_code.to_s
+    assert_equal :RGB, parsed.component_type
+    assert_equal :Linear, parsed.colorimetric
+    assert_equal "E012", parsed.flame_reel
+  end
+  
+  def test_parsed_properly_using_compact_structs
+    file = SAMPLE_DPX
+    assert_nothing_raised { Depix.from_file(file, compact = true) }
+  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
+  end
+  
+  def test_parsing_something_else_should_raise
+    s = "Mary had a little lamb"
+    assert_raise(Depix::InvalidHeader) { Depix.from_string(s) }
+    
+    s = "Mary had a little lamb" * 1000
+    assert_raise(Depix::InvalidHeader) { Depix.from_string(s) }
+
+    s = "SDPX Mary had a little lamb" * 1000
+    assert_raise(Depix::InvalidHeader) { Depix.from_string(s) }
+
+  end
+end