klear 0.0.1 → 0.1.0

data/.gitignore

@@ -4,3 +4,4 @@
 
 ## PROJECT::SPECIFIC
 README.html
+Gemfile.lock

data/Guardfile

@@ -1,6 +1,6 @@
 # Guardfile info at: https://github.com/guard/guard#readme
 
-guard 'rspec', all_on_start: true, cli: '--format nested --color' do
+guard 'rspec', all_on_start: true, cli: '--format nested --debug --color' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }

data/README.md

@@ -0,0 +1,154 @@
+# Kinetic Light Engine Archice - klear
+
+Create and manage choreographies for motors and lights on the Manta Rhei. This
+document describes the Kinetic Light Engine File Format which contains
+Choreographies and all data needed for playing it.
+
+To understand what this is all about please check the Manta Rhei project page:
+
+ - http://www.artcom.de/en/projects/project/detail/manta-rhei/
+
+This gem now is the starting point for refactoring the Manta Rhei code. The klear repo will contain all code for handling the actual content. Running the stepper motors or driving the OLEDs or DMX is part of the kinetic-light-engine which goes online soon.
+
+## File info 
+
+  $ klear info choreo.kle
+
+will show what is in the file. 
+ 
+## New File Generation
+
+*Notice: file generation depends on jruby because of its usage of Java JAI*
+
+Klear files are zipped directory structures which are generated from a set of images. The pixel values directly map to motor position and light intensity. On top of that, the klear file contains some additional meta info and cache date to speed up its loading at runtime. Generating a klear file from a images sequence in a directory goes like:
+
+    $ rvm jruby exec ./bin/klear.rb generate image_sequence_dir outfile.kle
+    
+and of course, more documentation needs to come (means must be converted from the internal wiki to here).
+
+## FileFormat
+
+File of this format have the file extension "kle", e.g. "calm_05.kle"
+
+### Layout and container Structure
+
+A .kle File contains multiple assets, incl. source PNGs, metatdata and a derived binary file containing frames in packed binary form. The Container Format is ZIP so a .kle file is just a zip-file containing files and folders.
+
+*Directory Layout*
+
+* Directory 'META-INF' (mandatory)
+ * 'kle.yml' containing meta-data describing aspects like framerate & more
+ * 'MANIFEST.MF' containing meta-data about the kle file itself (e.g. format version)
+* Directory 'frames' (mandatory)
+ * Source PNGs which were used to generate the kle
+* Directory 'cache' (optional)
+ * File 'frames.bin' containing binary data derived from the PNGs during creation
+ * further pre-processed data or application state for optimized restarts might be stored here.
+* Directory 'icon'
+ * contains one file 'normal.png' for a normal sized icon (150 x 110 px)
+
+### Workflow
+
+The initial source of a kle is a sequence of PNGs + metadata. Those are used to generate a .kle file incl. the file 'frames.bin'. The metadata is stored in 'META-INF/kle.yml' and describes aspects like fps.
+
+If a kle file does not have frame.bin in its cache directory it can be regenerated. This is also useful for future format changes together with the manifest to detect if a frames.bin is deprecated and needs to be regenerated.
+
+The source sequence of PNGs is stored in the KLE-file as well, which allows features like frames.bin regeneration in the first place.
+
+### File Format Details
+
+#### PNGs
+
+Each single PNG represents exactly one frame and is stored with 16-bit / channel. The size of the PNGs is determined by the number of columns and rows, where each tile is 10px x 10px in size. A Column represents the state of a blade at a frame (a certain point in time). The number of columns represents the number of blades. A Row represents one aspect across all blades, e.g. an outermost light or the state of the motor.
+
+*Example*
+
+!Waves_00129.png!
+
+ * We have 11 rows and 14 columns (blades)
+ * The lowest row describes the motor state
+ * The other rows describe the state of the lights from one direction to the other (TODO: Define the direction - what is a point of reference?)
+ * The Png then is 140x110px in size.
+
+#### Sequence of PNGs
+
+The order of the sequence is defined by the sorting delivered by the Posix command `sort -n`. So any natural alphabetical naming to order the sequence is allowed.
+
+The number of columns and rows must be the same for all PNGs.
+
+*Examples*
+
+ * `A.png, B.png, X.png` is valid sequence of 3 PNGs
+ * `Test_0001.png, Test_0002.png, Test__1000.png` is a valid sequence
+
+A sequence does not need to be consecutive (it can have gaps e.g. `01.png,10.png` is valid and the existence of e.g. 05.png is not enforced).
+
+#### kle.yml
+
+Contains information about how to use the frames:
+
+ * Number of columns and rows (geometry)
+ * Frames per second
+ * recommended gamma value
+ * Potentially a free descriptor (name)
+
+The geometry is determined automatically by reading the first png in the png sequence and dividing width and height by 10 respectively. This relies on one tile in the png being 10x10px in size.
+
+*Example:*
+<pre>
+---
+ description: calm_02
+ geometry:
+   rows: 11
+   columns: 14
+ fps: 25
+</pre>
+
+#### MANIFEST.MF
+
+The manifest contains meta information about the file and file format itself:
+
+ * `Manifest-Version` Version of the manifest itself
+ * `Kle-Version` Version of the kle-file format (e.g. `1.0`)
+ * `Created-By` Tool which created this file.
+
+*Example:*
+
+<pre>
+Manifest-Version: 1.0
+
+Kle-Version: 1.0
+Created-By: ruby-kle-generator 0.344b
+</pre>
+
+#### frames.bin
+
+The frames.bin file contains the extracted 16-bit values sampled from each tile of the PNGs. It contains all frames and each frame contains all columns and rows.
+
+Each 16-bit value is saved as unsigned 16 bit integer big endian (network byte order) and uses 2 bytes in frames.bin.
+
+A PNG with 11 rows and 14 columns uses `14 x 11 x 2 bytes = 308 bytes`.
+
+Each frame is encoded rows bottom to top and the columns from left to right.
+
+Example of a PNG with 3 rows & cols:
+
+      col 1   col 2   col 3
+    |-------|-------|-------|
+    | 27009 | 38885 | 47331 | <- row 3
+    |-------|-------|-------|
+    | 51027 | 51233 | 49789 | <- row 2
+    |-------|-------|-------|
+    | 47645 | 45039 | 41857 | <- row 1
+    |-------|-------|-------|
+
+is written as a sequence of values like:
+
+    47645 45039 41857    51027 51233 49789    27009 38885 47331
+
+
+which results in a binary big endian (network) byte order sequence like:
+
+    0xBA1D 0xAFEF 0xA381    0xC753 0xC821 0xC27D    0x6981 0x97E5 0xB8E3
+
+As a note: row 1 is the motor state.

data/bin/{klear.rb → klear}

@@ -50,11 +50,12 @@ Applix.main(ARGV, Defaults) do
     @app.regenerate(*args)
   end
   
- # handle(:info) do |*args, opts|
- #   (0 < args.size) or usage
- #   choreograhpy = Klear::Choreography.load args[0]
- #   puts choreograhpy.info
- # end
+  handle(:info) do |*args, opts|
+    (0 < args.size) or usage
+    path = args.shift
+    choreo = Klear::Choreography.load(path)
+    puts choreo.info
+  end
   
   handle(:any) {|_, _| usage}
 end

data/klear.gemspec

@@ -9,10 +9,11 @@ Gem::Specification.new do |s|
   s.authors     = ['art+com/dirk luesebrink']
   s.email       = ['dirk.luesebrink@artcom.de']
   s.homepage    = 'http://www.artcom.de/en/projects/project/detail/manta-rhei/'
-  s.summary     = 'create, manage and play choreographies and atrificial light patterns on the Manta Rhei'
+  s.summary     = 'create and manage choreographies for motors and lights on the Manta Rhei'
   s.description = %q{ 
-    kinetic light engine by art+com. Create, manage and play choreographies and
-    artificial light patterns on the Manta Rhei
+    create and manage choreographies for motors and lights on the Manta Rhei.
+    klear is the kinetic-light-engine archive format and is used by the
+    kinetic-light-engine runtime to drive the Manta Rhei installation.
   }
   s.add_dependency 'applix'
   s.add_dependency 'rubyzip'
@@ -27,7 +28,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rb-fsevent', '~>0.9.1'
 
   if RUBY_PLATFORM.match /java/i
-    #s.add_development_dependency 'ruby-debug'
+    s.add_development_dependency 'ruby-debug'
   else
     s.add_development_dependency 'debugger'
   end

data/lib/klear/choreography.rb

@@ -0,0 +1,150 @@
+# TODO Add separate accessors for motors and lights?
+# TODO Add row/blade accessors to Frames so a time-slice can be retrieved?
+
+# Note: Row 0 is the motor setting / this is equivalent to the first value of a blade
+class Klear::Choreography
+
+  #class Frames < BinData::Record
+  #  array :numbers, :type => :uint16be, :read_until => :eof
+  #end
+
+  attr_reader :archive, :geometry, :gamma, :fps
+  attr_accessor :location
+
+  def self.load path
+    #choreo = Zip::ZipFile.open(path) { |klear| new klear }
+    self.new(Klear::File.new(path))
+  end
+
+  def initialize archive
+    @archive = archive
+    @location = @archive.path
+    #info = YAML.load(@archive.read("META-INF/kle.yml"))
+    info = @archive.info
+    @geometry = info['geometry']
+    @fps = info['fps'] || 25
+    @gamma = info['gamma'] || 1.0
+    @frames = @archive.frames
+  end
+
+  def info
+    puts <<-INFO
+Klear file at: #{@location}
+
+Settings:
+----------------
+fps     : #{@fps}
+gamma   : #{@gamma}
+geometry: 
+    columns: #{@geometry[:columns]}
+    rows   : #{@geometry[:rows]}
+----------------
+
+
+Frames:
+----------------
+framesize : #{framesize}
+framecount: #{framecount}
+----------------
+
+
+MANIFEST:
+----------------
+#{@archive.manifest}
+----------------
+    INFO
+  end
+
+  def id
+    File.basename(self.location, ".kle")
+  end
+
+  def framesize
+    @geometry[:columns] * @geometry[:rows]
+  end
+  
+  def framecount
+    @frames.count
+  end
+
+  def frame no
+    @frames.get(no)
+  end
+
+  def each_frame &blk #block_given?
+    (0...framecount).each do |n|
+      myFrame = frame(n)
+      blk.call(myFrame, n+1)
+    end
+  end
+end
+
+__END__
+class Klear::Choreography::Frame
+
+  attr_reader :data
+
+  def initialize data, geometry
+    @data = data
+    @geometry = geometry
+    @num_cols = @geometry[:columns] # local copy of columns to avoid per pixel symbol lookups
+    @num_rows = @geometry[:rows] # local copy of columns to avoid per pixel symbol lookups
+  end
+
+  def size
+    [@geometry[:columns], @geometry[:rows]]
+  end
+
+  def cell column, row
+    @data[@num_cols * row + column] 
+  end
+
+  def row(no)
+    @data.slice(no * @geometry[:columns], @geometry[:columns])
+  end
+
+  # XXX returning an array would be better than hashed by row number...
+  def rows &blk
+    myRows = {}
+    (0...@geometry[:rows]).each do |n|
+      current = myRows[n] = row(n)
+      blk.call(current, n) if block_given?
+    end
+    myRows
+  end
+
+  def column theColumnNumber
+    col = []
+    (0...@geometry[:rows]).each { |curRow|
+      col << @data[theColumnNumber + curRow * @geometry[:columns]]
+    }
+    col
+  end
+
+  def columns &blk
+    myColumns = {}
+    (0...@geometry[:columns]).each do |n|
+      current = myColumns[n] = column(n)
+      blk.call(current, n) if block_given?
+    end
+    myColumns
+  end
+
+  #def each_column &blk
+  #  (0...@geometry[:columns]).each do |n|
+  #    myColumn = column(n)
+  #    blk.call(myColumn, n)
+  #  end
+  #end
+
+  def dump
+    myStr = ""
+    rows { |row, idx|
+      myStr << "#{idx} || " << row.collect{|x| x.to_s}.join(" | ") << "\n"
+    }
+    myStr
+  end
+
+  alias :blade :column
+  alias :blades :columns
+end

data/lib/klear/file.rb

@@ -0,0 +1,89 @@
+require 'klear/frames'
+require 'klear/motors'
+
+class Klear::File
+  attr_accessor :path
+
+  def initialize path = nil
+    @path = path
+  end
+
+  def info
+    @info ||= YAML.load(zipfile.read('META-INF/kle.yml'))
+  end
+
+  def manifest
+    @manifest ||= YAML.load(zipfile.read('META-INF/MANIFEST.MF'))
+  end
+
+  def dimensions
+    @dimensions ||= info['geometry']
+  end
+
+  def frame_count
+    @frame_count ||= (zipfile.dir.entries("/frames").size)
+  end
+
+  def frames
+    @frames ||= (
+      data = zipfile.read("cache/frames.bin")
+      Klear::Frames.new(dimensions[:columns], dimensions[:rows], data)
+    )
+  end
+
+  def motors
+    @motors ||= (
+      #begin 
+      #  data = zipfile.read("cache/motors.bin")
+      #  Klear::Motors.new(dimensions[:columns], data)
+      ##rescue Errno::ENOENT => e
+      #  puts " ~~ empty motors cache (#{e})"
+      #  Klear::Motors.new(dimensions[:columns])
+      #end
+
+      motors = frames.all.map do |frame|
+        (frame.row 0) # convention: row zero is the motors
+      end
+      Klear::Motors.new(dimensions[:columns], motors)
+
+      #animations = {}
+      #frames.each do |frame, no|
+      #  puts "frame: ##{no}"
+      #  row = (frame.row 0) # convention: row zero is the motors
+#
+#        # scale input onto manta geometry
+#        low, high = @config[:low], @config[:high]
+#        d = (high - low).to_f
+#
+#        row.each_with_index do |v_in, x|
+#          v_out = (low + d * (v_in.value.to_f / 0xffff)).to_i
+#          (animations[x+1] ||= []) << v_out
+#        end
+#      end
+    )
+  end
+
+  private
+  def zipfile
+    @zipfile ||= (
+      @path or (raise 'path not specified')
+      Zip::ZipFile.new(@path)
+    )
+  end
+end
+
+__END__
+
+  def self.load theKleFile
+    myChoreography = nil
+    Zip::ZipFile.open(theKleFile) { |kle|
+      myChoreography = new kle
+    }
+    myChoreography
+  end
+
+  def initialize theKleFile
+    @kle_file = theKleFile
+    @geometry = YAML.load(@kle_file.read("META-INF/kle.yml"))['geometry']
+    @frames = Kleac::Choreography::Frames.read @kle_file.read("cache/frames.bin")
+  end

data/lib/klear/filters.rb

@@ -0,0 +1,19 @@
+module Klear::Filters
+  # scale input onto manta geometry
+  def project values, low, high
+    #low, high = @config[:low], @config[:high]
+    d = (high - low).to_f
+
+    values.map do |val|
+      (low + d * (val.to_f / 0xffff)).to_i
+    end
+  end
+
+  # hack: sample(F14 by JJ) 600 down to 2 times 20 => 40 frame positions
+  def f14jj values 
+    no = -1
+    values.select { (no += 1) % 30 == 0 }
+  end
+
+  extend(self)
+end

data/lib/klear/frame.rb

@@ -0,0 +1,71 @@
+class Klear::Frame
+
+  attr_reader :data, :row_count, :column_count, :size
+
+  def initialize column_count, row_count, data = nil
+    @row_count, @column_count = row_count, column_count
+    @size = @row_count * @column_count
+    @data = data
+  end
+
+  def cell column, row
+    # TODO implement me
+  end
+
+  def row no
+    @data.slice(no * @column_count, @column_count)
+  end
+
+  #def rows *args, &blk
+  #  if block_given?
+  #    each_row(&blk)
+  #  else
+  #    myRows = {}
+  #    (0...@row_count).each do |n|
+  #      myRows[n] = row(n)
+  #    end
+  #    myRows
+  #  end
+  #end
+
+  # returns array of rows
+  def each_row &blk
+    @rows ||= (0...@row_count).map {|n| row(n)}
+
+    if block_given?
+      @rows.each_with_index {|row, idx| blk.call(row, idx)}
+    end
+
+    @rows
+  end
+  alias_method :rows, :each_row 
+
+  def column no
+    col = []
+    (0...@row_count).each do |curRow|
+      col << @data[no + curRow * @column_count]
+    end
+    col
+  end
+  alias_method :blade, :column
+
+  def each_column &blk
+    @columns ||= (0...@column_count).map {|n| column(n)}
+
+    if block_given?
+      @columns.each_with_index {|column, idx| blk.call(column, idx)}
+    end
+
+    @columns
+  end
+  alias_method :each_blade, :each_column 
+  alias_method :columns, :each_column 
+
+  #def dump
+  #  myStr = ""
+  #  rows do |row, idx|
+  #    myStr << "#{idx} || " << row.collect{|x| x.to_s}.join(" | ") << "\n"
+  #  end
+  #  myStr
+  #end
+end

data/lib/klear/frames.rb

@@ -0,0 +1,43 @@
+require 'klear/frame'
+
+class Klear::Frames
+  class Data < BinData::Record
+    array :numbers, :type => :uint16be, :read_until => :eof
+  end
+
+  attr_reader :framesize, :rows, :columns
+
+  def initialize columns, rows, binary_string = nil
+    @rows, @columns = rows, columns
+    @framesize =  @rows * @columns
+    @data = nil
+    load(binary_string) unless binary_string.nil?
+  end
+
+  def load binary_string
+    @data = Data.read(binary_string).numbers
+    self
+  end
+
+  def count
+    @data.size / framesize
+  end
+
+  def each &blk
+    0.upto(count-1) do |frame_no|
+      yield(get(frame_no), frame_no)
+    end
+  end
+
+  def get frame_no
+    (0 <= frame_no) or (raise "invalid negative frame no: #{frame_no}")
+    (frame_no < count) or (raise "frame no out of bound: #{frame_no}")
+    Klear::Frame.new(
+      @columns, @rows, @data.slice(frame_no * @framesize, @framesize)
+    )
+  end
+
+  def all
+    (0...count).map { |frame_no| get(frame_no) }
+  end
+end

data/lib/klear/motors.rb

@@ -0,0 +1,53 @@
+class Klear::Motors
+  #class Data < BinData::Record
+  #  array :numbers, :type => :uint16be, :read_until => :eof
+  #end
+
+  attr_reader :count, :frame_count
+  alias :blade_count :count
+
+  def initialize blade_count, frames = nil
+    @count = blade_count
+    @frames = frames || [[0] * @count] # init with one frame
+    @frame_count ||= @frames.size
+  end
+
+  #def frame_count
+  #end
+
+  def each &blk
+    #0.upto(@frame_count - 1) do |frame_no|
+    (1..@count).each do |motor_no|
+      yield(get(motor_no), motor_no)
+    end
+  end
+
+  # motor_no is one-based!!!
+  def get motor_no
+    motor_no = Integer(motor_no)
+    (0 < motor_no) or (raise "invalid motor no: #{motor_no}")
+    (motor_no <= @count) or (raise "motor no out of bounds: #{motor_no}")
+    @frames.map {|frame| frame[motor_no-1]}
+  end
+
+  # frame_no is zero based!!!
+  def frame frame_no
+    (0 <= frame_no) or (raise "invalid negative frame no: #{frame_no}")
+    (frame_no < @frame_count) or (raise "frame no out of bound: #{frame_no}")
+    @frames[frame_no]
+  end
+
+  def render motor_no, options = {}
+    low = options[:low] || 0
+    high = options[:high] || 20000
+    values = get(motor_no)
+    values = f14jj(values)
+    values = project(values, low, high)
+  end
+
+  def render_all options = {}
+    low = options[:low] || 0
+    high = options[:high] || 20000
+    (1..@count).map {|i| render(i, low, high)}
+  end
+end

data/lib/klear/version.rb

@@ -1,4 +1,4 @@
 module Klear
-  VERSION = '0.0.1'
-  DATE    = '2013-06-20'
+  VERSION = '0.1.0'
+  DATE    = '2013-06-23'
 end

data/lib/klear.rb

@@ -4,4 +4,7 @@ require 'yaml'
 
 module Klear; end
 require 'klear/version'
+require 'klear/file'
+require 'klear/filters'
+require 'klear/choreography'
 require 'klear/file_generator'