depix 1.0.1 → 1.0.2

data/DPX_HEADER_STRUCTURE.txt

@@ -1,100 +1,97 @@
 = 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
 
-* <tt>file</tt> hash of
-  * <tt>magic</tt> String
-  * <tt>image_offset</tt> Integer
-  * <tt>version</tt> String
-  * <tt>file_size</tt> Integer
-  * <tt>ditto_key</tt> Integer
-  * <tt>generic_size</tt> Integer
-  * <tt>industry_size</tt> Integer
-  * <tt>user_size</tt> Integer
-  * <tt>filename</tt> String
-  * <tt>timestamp</tt> String
-  * <tt>creator</tt> String
-  * <tt>project</tt> String
-  * <tt>copyright</tt> String
-  * <tt>encrypt_key</tt> Integer
-  * <tt>reserve</tt> String
-* <tt>image</tt> hash of
-  * <tt>orientation</tt> Integer
-  * <tt>number_elements</tt> Integer
-  * <tt>pixels_per_line</tt> Integer
-  * <tt>lines_per_element</tt> Integer
-  * <tt>image_elements</tt>  (array , 8 members):
-    * <tt>data_sign</tt> Integer
-    * <tt>low_data</tt> Integer
-    * <tt>low_quantity</tt> Float
-    * <tt>high_data</tt> Integer
-    * <tt>high_quantity</tt> Float
-    * <tt>descriptor</tt> Integer
-    * <tt>transfer</tt> Integer
-    * <tt>colorimetric</tt> Integer
-    * <tt>bit_size</tt> Integer
-    * <tt>packing</tt> Integer
-    * <tt>encoding</tt> Integer
-    * <tt>data_offset</tt> Integer
-    * <tt>end_of_line_padding</tt> Integer
-    * <tt>end_of_image_padding</tt> Integer
-    * <tt>description</tt> String
-  * <tt>reserve</tt> String
-* <tt>orientation</tt> hash of
-  * <tt>x_offset</tt> Integer
-  * <tt>y_offset</tt> Integer
-  * <tt>x_center</tt> Float
-  * <tt>y_center</tt> Float
-  * <tt>x_size</tt> Integer
-  * <tt>y_size</tt> Integer
-  * <tt>filename</tt> String
-  * <tt>timestamp</tt> String
-  * <tt>device</tt> String
-  * <tt>serial</tt> String
-  * <tt>border</tt>  (array , 4 members):
-  * <tt></tt> Integer
-  * <tt>aspect_ratio</tt>  (array , 2 members):
-  * <tt></tt> Integer
-  * <tt>reserve</tt> String
-* <tt>film</tt> hash of
-  * <tt>id</tt> String
-  * <tt>type</tt> String
-  * <tt>offset</tt> String
-  * <tt>prefix</tt> String
-  * <tt>count</tt> String
-  * <tt>format</tt> String
-  * <tt>frame_position</tt> Integer
-  * <tt>sequence_extent</tt> Integer
-  * <tt>held_count</tt> Integer
-  * <tt>frame_rate</tt> Float
-  * <tt>shutter_angle</tt> Float
-  * <tt>frame_id</tt> String
-  * <tt>slate</tt> String
-  * <tt>reserve</tt> String
-* <tt>television</tt> hash of
-  * <tt>time_code</tt> Integer
-  * <tt>user_bits</tt> Integer
-  * <tt>interlace</tt> Integer
-  * <tt>field_number</tt> Integer
-  * <tt>video_signal</tt> Integer
-  * <tt>padding</tt> Integer
-  * <tt>horizontal_sample_rate</tt> Float
-  * <tt>vertical_sample_rate</tt> Float
-  * <tt>frame_rate</tt> Float
-  * <tt>time_offset</tt> Float
-  * <tt>gamma</tt> Float
-  * <tt>black_level</tt> Float
-  * <tt>black_gain</tt> Float
-  * <tt>break_point</tt> Float
-  * <tt>white_level</tt> Float
-  * <tt>integration_times</tt> Float
-  * <tt>reserve</tt> String
-* <tt>user</tt> hash of
-  * <tt>id</tt> String
-  * <tt>user_data</tt> Integer
+* <tt>file</tt> (Depix::FileInfo) File information:
+  * <tt>magic</tt> (String) Endianness (SDPX is big endian) - required
+  * <tt>image_offset</tt> Offset to image data in bytes - required
+  * <tt>version</tt> (String) Version of header format - required
+  * <tt>file_size</tt> Total image size in bytes - required
+  * <tt>ditto_key</tt> Whether the basic headers stay the same through the sequence (1 means they do)
+  * <tt>generic_size</tt> Generic header length
+  * <tt>industry_size</tt> Industry header length
+  * <tt>user_size</tt> User header length
+  * <tt>filename</tt> (String) Original filename
+  * <tt>timestamp</tt> (String) Creation 15
+  * <tt>creator</tt> (String) Creator application
+  * <tt>roject</tt> (String) Project name
+  * <tt>copyright</tt> (String) Copyright
+  * <tt>encrypt_key</tt> Encryption key
+  * <tt>reserve</tt> (String)
+* <tt>image</tt> (Depix::ImageInfo) Image information:
+  * <tt>orientation</tt> (Integer) Orientation descriptor - required
+  * <tt>number_elements</tt> (Integer) How many elements to scan - required
+  * <tt>pixels_per_line</tt> Pixels per horizontal line - required
+  * <tt>lines_per_element</tt> Line count - required
+  * <tt>image_elements</tt> (Array of 8 Depix::ImageElement fields) Image elements:
+    * <tt>data_sign</tt> Data sign (0=unsigned, 1=signed). Core is unsigned - required
+    * <tt>low_data</tt> Reference low data code value
+    * <tt>low_quantity</tt> (Float) Reference low quantity represented
+    * <tt>high_data</tt> Reference high data code value (1023 for 10bit per channel)
+    * <tt>high_quantity</tt> (Float) Reference high quantity represented
+    * <tt>descriptor</tt> (Integer) Descriptor for this image element (ie Video or Film), by enum - required
+    * <tt>transfer</tt> (Integer) Transfer function (ie Linear), by enum - required
+    * <tt>colorimetric</tt> (Integer) Colorimetric (ie YcbCr), by enum - required
+    * <tt>bit_size</tt> (Integer) Bit size for element (ie 10) - required
+    * <tt>packing</tt> (Integer) Packing (0=Packed into 32-bit words, 1=Filled to 32-bit words)) - required
+    * <tt>encoding</tt> (Integer) Encoding (0=None, 1=RLE) - required
+    * <tt>data_offset</tt> Offset to data for this image element - required
+    * <tt>end_of_line_padding</tt> End-of-line padding for this image element
+    * <tt>end_of_image_padding</tt> End-of-line padding for this image element
+    * <tt>description</tt> (String)
+  * <tt>reserve</tt> (String)
+* <tt>orientation</tt> (Depix::OrientationInfo) Orientation:
+  * <tt>x_offset</tt> 
+  * <tt>y_offset</tt> 
+  * <tt>x_center</tt> (Float)
+  * <tt>y_center</tt> (Float)
+  * <tt>x_size</tt> Original X size
+  * <tt>y_size</tt> Original Y size
+  * <tt>filename</tt> (String) Source image filename
+  * <tt>timestamp</tt> (String) Source image/tape timestamp
+  * <tt>device</tt> (String) Input device or tape
+  * <tt>serial</tt> (String) Input device serial number
+  * <tt>border</tt> (Array of 4 Integer fields) Border validity: XL, XR, YT, YB:
+  * <tt>aspect_ratio</tt> (Array of 2  fields) Aspect (H:V):
+  * <tt>reserve</tt> (String)
+* <tt>film</tt> (Depix::FilmInfo) Film industry info:
+  * <tt>id</tt> (String) Film mfg. ID code (2 digits from film edge code)
+  * <tt>type</tt> (String) Film type (2 digits from film edge code)
+  * <tt>offset</tt> (String) Offset in perfs (2 digits from film edge code)
+  * <tt>prefix</tt> (String) Prefix (6 digits from film edge code
+  * <tt>count</tt> (String) Count (4 digits from film edge code)
+  * <tt>format</tt> (String) Format (e.g. Academy)
+  * <tt>frame_position</tt> Frame position in sequence
+  * <tt>sequence_extent</tt> Sequence length
+  * <tt>held_count</tt> For how many frames the frame is held
+  * <tt>frame_rate</tt> (Float) Frame rate
+  * <tt>shutter_angle</tt> (Float) Shutter angle
+  * <tt>frame_id</tt> (String) Frame identification (keyframe)
+  * <tt>slate</tt> (String) Slate information
+  * <tt>reserve</tt> (String)
+* <tt>television</tt> (Depix::TelevisionInfo) TV industry info:
+  * <tt>time_code</tt> Timecode, formatted as HH:MM:SS:FF in the 4 higher bits of each 8bit group
+  * <tt>user_bits</tt> Timecode UBITs
+  * <tt>interlace</tt> (Integer) Interlace (0 = noninterlaced; 1 = 2:1 interlace
+  * <tt>field_number</tt> (Integer) Field number
+  * <tt>video_signal</tt> (Integer) Video signal (by enum)
+  * <tt>padding</tt> (Integer) Zero (for byte alignment)
+  * <tt>horizontal_sample_rate</tt> (Float) Horizontal sampling Hz
+  * <tt>vertical_sample_rate</tt> (Float) Vertical sampling Hz
+  * <tt>frame_rate</tt> (Float) Frame rate
+  * <tt>time_offset</tt> (Float) From sync pulse to first pixel
+  * <tt>gamma</tt> (Float) Gamma
+  * <tt>black_level</tt> (Float) Black pedestal code value
+  * <tt>black_gain</tt> (Float) Black gain code value
+  * <tt>break_point</tt> (Float) Break point (?)
+  * <tt>white_level</tt> (Float) White level
+  * <tt>integration_times</tt> (Float) Integration times (S)
+  * <tt>reserve</tt> (Float)
+* <tt>user</tt> (Depix::UserInfo) User info:
+  * <tt>id</tt> (String) Name of the user data tag
+  * <tt>user_data_ptr</tt> 
 

data/History.txt

@@ -1,4 +1,9 @@
+=== 1.0.2 / 2008-12-19
+
+* refactor struct parsing completely
+
 === 1.0.1 / 2008-12-18
+
 * small doc and usability improvements
 
 === 1.0.0 / 2008-12-18

data/Manifest.txt

@@ -7,6 +7,9 @@ bin/depix-describe
 lib/depix.rb
 lib/depix/struct_explainer.rb
 lib/depix/structs.rb
+lib/depix/compact_structs.rb
+lib/depix/enums.rb
+lib/depix/dict.rb
 test/test_depix.rb
 test/samples/E012_P001_L000002_lin.0001.dpx
 test/samples/E012_P001_L000002_lin.0002.dpx

data/README.txt

@@ -9,10 +9,11 @@ Read DPX file metadata
 == SYNOPSIS:
 
   meta = Depix::Reader.from_file(dpx_file_path)
-  puts meta.television.time_code #=> 10:00:00:02
+  puts meta.time_code #=> 10:00:00:02
   
-The data returned is described in the DPX_HEADER_STRUCTURE[link:files/DPX_HEADER_STRUCTURE_txt.html]. The structs
-used for actual parsing are in the Depix::Structs module (but in a much less readable form, obviously)
+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 gem also contains an executable called depix-desribe which can be used from the command line
   
@@ -20,9 +21,6 @@ The gem also contains an executable called depix-desribe which can be used from
 
 == NOTES:
 
-The reader tries to be efficient - fast Ruby unpacking is used, some shortcuts are taken. Also don't worry - we do not need to read
-the whole DPX file (which usually is around 8mb per frame) to know the details.
-
 In the future there will be a possibility to modify and commit the headers, but it's not a priority at this time.
 
 Autodesk IFFS systems write the reel name for the file to the orientation.device field

data/Rakefile

@@ -1,15 +1,19 @@
 require 'rubygems'
 require 'hoe'
-require './lib/depix.rb'
+require './lib/depix'
 
-Hoe.new('depix', Depix::VERSION) do |p|
+Class.new(Hoe) do
+  def extra_deps
+    super.reject {|e| e[0] == 'hoe' }
+  end
+end.new('depix', Depix::VERSION) do |p|
   p.developer('Julik Tarkhanov', 'me@julik.nl')
   p.rubyforge_name = 'wiretap'
-  p.extra_deps.reject! {|e| e[0] == 'hoe' }
+  p.extra_deps << 'timecode'
   p.remote_rdoc_dir = 'depix'
 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::Structs::DPX_INFO) }
+  File.open('DPX_HEADER_STRUCTURE.txt', 'w') {|f| f << RdocExplainer.new.get_rdoc_for(Depix::DPX) }
 end

data/bin/depix-describe

@@ -1,10 +1,19 @@
 #!/usr/bin/env ruby
 
 require File.dirname(__FILE__) + '/../lib/depix'
-if ARGV.flatten.map do | file |
-  data = Depix::Reader.describe_file(file)
-  puts "Describing DPX #{file}. Empty elements are omitted."
-  puts data
-end.empty?
-  STDERR.puts "Usage: depix-describe somefile.dpx anotherfile.dpx"
+require 'optparse'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: depix-describe somefile.dpx anotherfile.dpx [options]"
+
+  opts.on("-c", "--compact", "Compact output (only fields that change per frame)") do |v|
+    options[:compact] = true
+  end
+end.parse!
+
+ARGV.each do | file |
+  puts "Describing DPX #{file}. Empty elements are omitted.\n\n"
+  puts "===================================================\n\n"
+  puts Depix.describe_file(file, options[:compact])
 end

data/lib/depix.rb

@@ -2,29 +2,13 @@ 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.1'
-  
-  BLANK_2 = 0xFFFF #:nodoc:
-  BLANK_4 = 0xFFFFFFFF #:nodoc:
-  BLANK_F = 0xFFFFFFFF #:nodoc:
-  BLANK_CHAR = 0xFF #:nodoc:
-  
-  # Methodic hash - stolen from Camping
-  class H < Hash
-    # Gets or sets keys in the hash.
-    #
-    #   @cookies.my_favorite = :macadamian
-    #   @cookies.my_favorite
-    #   => :macadamian
-    #
-    def method_missing(m,*a)
-        m.to_s=~/=$/ ? (self[$`] = a[0]) : (a == [] ? (self.key?(m.to_s) ? self[m.to_s] : super ) : super)
-    end
-    undef id, type
-  end
+  VERSION = '1.0.2'
   
   # Offers convenience access to a few common attributes bypassing the piecemeal structs
   module Synthetics
@@ -37,111 +21,96 @@ module Depix
     end
     
     def time_code
-      Timecode.from_uint(television.time_code, film.fps)
+      Timecode.from_uint(television.time_code) #, film.frame_rate)
     end
     
     # Get the name of the transfer function (Linear, Logarithmic, ...)
     def colorimetric
-      Structs::COLORIMETRIC.invert[image.image_elements[0].colorimetric]
+      COLORIMETRIC.invert[image.image_elements[0].colorimetric]
     end
     
     # Get the name of the compnent type (RGB, YCbCr, ...)
     def component_type
-      Structs::COMPONENT_TYPE.invert[image.image_elements[0].descriptor]
+      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
   
-  # Reads the metadata
   class Reader
     
-    class << self
-      # Read the header from file (no worries, only the needed number of bytes will be read into memory). Returns a H with the metadata.
-      def from_file(path)
-        new.from_file(path)
-      end
-
-      # Read the metadata from an in-memory string. Returns a H with the metadata.
-      def from_string(str)
-        new.from_string(str)
-      end
-      
-      # Returns a printable report on all the headers present in the string
-      def describe_string(str)
-        reader = new
-        result = reader.deep_parse(str, Structs::DPX_INFO)
-        reader.inform(result)
-      end
-
-      # Returns a printable report on all the headers present in the file at the path passed
-      def describe_file(path)
-        header = File.open(path, 'r') { |f| f.read(Structs::TEMPLATE_LENGTH) }
-        describe_string(header)
-      end
+    # 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
     
-    #:stopdoc:
-    def from_file(path)
-      header = File.open(path, 'r') { |f| f.read(Structs::TEMPLATE_LENGTH) }
-      from_string(header)
+    def from_file(path, compact)
+      header = File.open(path, 'r') { |f| f.read(DPX.length) }
+      parse(header, compact)
     end
     
-    def from_string(str) #:nodoc:
-      wrap(deep_parse(str, Structs::DPX_INFO))
-    end
-    
-    def deep_parse(data, structure)
+    # The hear of Depix
+    def parse(data, compact)
       magic = data[0..3]
-      template = (magic == "SDPX") ? Structs::TEMPLATE_BE : Structs::TEMPLATE_LE
+      struct = compact ? CompactDPX : DPX
       
-      result = data.unpack(template).map do |e| 
-        case e
-          when String
-            clean = unpad(e)
-            clean.empty? ? nil : clean
-          when Integer
-            (e == BLANK_2 || e == BLANK_4) ? nil : e
-          when Float
-            e.nan? ? nil : e
-        end
-      end
-      result
+      template = (magic == "SDPX") ? struct.pattern : make_le(struct.pattern)
+      struct.consume!(data.unpack(template))
     end
     
-    def inform(result)
-      Structs::TEMPLATE_KEYS.zip(result).map{|k, v| "#{k}:#{v}" unless v.nil? }.compact.join("\n")
-    end
-    
-    def wrap(result)
-      eich = self.class.nestify(Structs::TEMPLATE_KEYS, result)
-      class << eich; include Synthetics; end
-      eich
-    end
-    
-    # FIXME - currently no array handling
-    def self.nestify(keys, values)
-      auto_hash = H.new do |h,k| 
-        h[k] = H.new(&h.default_proc)
-      end
-      
-      keys.each_with_index do |path, idx |
-        value = values[idx]
-        
-        sub, elems = auto_hash, path.split('.')
-        while elems.any?
-          dir = elems.shift
-          dir = dir.to_i if dir =~ /^(\d+)$/
-          elems.any? ? (sub = sub[dir]) : (sub[dir] = value)
+    # 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
-      end
-      
-      auto_hash
+        if parts.any?
+          info << parts.join(' ')
+        end
+        info
+      end.map{|e| ('  ' * pad_offset) + e }.join("\n")
     end
     
-    def unpad(string) # :nodoc:
-      string.gsub("\000", '').gsub(0xFF.chr, '')
+    # Convert an unpack pattern to LE
+    def make_le(pattern)
+      pattern.gsub(/n/, "v").gsub(/N/, "V").gsub(/g/, "f")
     end
     
-    #:startdoc:
   end
 end