julik-depix 1.0.2

data/DPX_HEADER_STRUCTURE.txt

@@ -0,0 +1,97 @@
+= DPX header structure description
+
+DPX metadata gets returned as a Depix::DPX object with nested properties.
+  
+  meta.file.magic # => "SDPX"
+
+== Metadata structure
+
+* <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

@@ -0,0 +1,18 @@
+=== 1.0.2 / 2008-12-23
+
+* Do not cleanup null bytes and terminators in the middle of char[] attributes (something useful might be in there)
+
+=== 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
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,17 @@
+History.txt
+Manifest.txt
+README.txt
+DPX_HEADER_STRUCTURE.txt
+Rakefile
+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
+test/samples/E012_P001_L000002_log.0001.dpx
+test/samples/E012_P001_L000002_log.0002.dpx

data/README.txt

@@ -0,0 +1,59 @@
+= depix
+
+* http://wiretap.rubyforge.org/depix
+
+== DESCRIPTION:
+
+Read DPX file metadata
+
+== SYNOPSIS:
+
+  meta = Depix.from_file(dpx_file_path)
+  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]. 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
+  
+  $book depix-describe 001_PTAPE_001.001.dpx
+
+== NOTES:
+
+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
+
+== REQUIREMENTS:
+
+* timecode gem (sudo gem install timecode)
+
+== INSTALL:
+
+* sudo gem install depix
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Julik Tarkhanov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'hoe'
+require './lib/depix'
+
+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 << '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::DPX) }
+end

data/bin/depix-describe

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/depix'
+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"
+  begin
+    puts Depix.describe_file(file, options[:compact])
+  rescue Depix::InvalidHeader
+    puts " - Invalid header data"
+  end
+end

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,357 @@
+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
+    undef :length=, :pattern=
+    
+    def pattern
+      "N"
+    end
+    
+    def length
+      4
+    end
+    
+    def clean(value)
+      value == BLANK ? nil : value
+    end
+  end
+  
+  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 ? nil : v
+    end
+  end
+  
+  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
+  end
+    
+  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
+  end
+  
+  class R32Field < Field
+    undef :length=, :pattern=
+    
+    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"
+    undef :pattern=
+    
+    BLANKING_VALUES = [0x00.chr, 0xFF.chr]
+    BLANKING_PATTERNS = BLANKING_VALUES.inject([]) do | p, char |
+      p << /^(#{char}+)/ << /(#{char}+)$/
+    end
+    
+    def pattern
+      "A#{(length || 1).to_i}"
+    end
+    
+    def clean(v)
+      if v == BLANK
+        nil
+      else
+        2.times { BLANKING_PATTERNS.each{|p| v.gsub!(p, '')} }
+        v.empty? ? nil : v
+      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)
+        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 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