klear 0.1.3 → 0.1.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +64 -49
- data/bin/klear +1 -1
- data/lib/klear/file_generator.rb +29 -15
- data/lib/klear/version.rb +2 -2
- data/spec/lib/klear/file_generator_spec.rb +8 -0
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 2ce4d5cdafe23e6dff8a591fbb74ab16316acff8
|
4
|
+
data.tar.gz: db86b996953818cadb54ae3217a6d911b097d83a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 996c00baae0b8081d085affe62d9d0b07e460148d01698fec8365e0e5be65d8e4699947cfbe7c2018c8cea23a6f3217b8732444db9cf5ffa6598e9cd801a4c66
|
7
|
+
data.tar.gz: 44b5b2ad67c6db67bc7fdf9590064a9f3e506a9612c15c0711b0ee15a4fbdaf62148104b85bde55f1d2d35eb534acda1ea259d87a635d8bb46dc54f5af8c80e5
|
data/README.md
CHANGED
@@ -1,63 +1,77 @@
|
|
1
|
-
# Kinetic Light Engine Archive
|
1
|
+
# klear: Kinetic Light Engine Archive file format and CLI utitlies
|
2
2
|
|
3
|
-
|
4
|
-
|
5
|
-
|
3
|
+
The *klear* gem includes library code and the `klear` command line utility to
|
4
|
+
create and manage the choreographies for motors and/or lights in kinetic
|
5
|
+
installations. It was originally developed as part of the [Manta Rhei
|
6
|
+
project][1] but is now extraced for generic use.
|
6
7
|
|
7
|
-
|
8
|
+
[1]: http://www.artcom.de/en/projects/project/detail/manta-rhei/
|
8
9
|
|
9
|
-
|
10
|
+
This document describes the Kinetic Light Engine File Format which contains
|
11
|
+
Choreographies and all data needed for playing it.
|
10
12
|
|
11
|
-
|
13
|
+
*(background: The gem is the starting point for refactoring the Manta Rhei
|
14
|
+
code. The repo contains all code for handling the actual content while running
|
15
|
+
the stepper motors or driving the OLEDs or DMX is part of the
|
16
|
+
kinetic-light-engine.)*
|
12
17
|
|
13
|
-
## File
|
18
|
+
## File Format
|
14
19
|
|
15
|
-
|
20
|
+
Files of this format should have the file extension `.kle`, e.g.
|
21
|
+
"calm_05.kle".
|
16
22
|
|
17
|
-
|
18
|
-
|
19
|
-
## New File Generation
|
23
|
+
### Layout and container Structure
|
20
24
|
|
21
|
-
|
25
|
+
A .kle File contains multiple assets, incl. source PNGs, metatdata and a
|
26
|
+
derived binary file containing frames in packed binary form. The Container
|
27
|
+
Format is ZIP so a .kle file is just a zip-file containing files and folders.
|
28
|
+
|
29
|
+
**Directory Layout**
|
30
|
+
|
31
|
+
+ *DIR* 'META-INF' (mandatory)
|
32
|
+
+ 'kle.yml', YAML file containing meta-data describing aspects like framerate & more
|
33
|
+
+ 'MANIFEST.MF' containing meta-data about the klear file itself (e.g.
|
34
|
+
format version)
|
35
|
+
+ *DIR* 'frames' (mandatory)
|
36
|
+
+ Source PNGs files which were used to generate the kle
|
37
|
+
+ *DIR* cache' (optional)
|
38
|
+
+ 'frames.bin', binary file containing data derived from the PNGs during
|
39
|
+
creation
|
40
|
+
+ further pre-processed data or application state for optimized restarts
|
41
|
+
might be stored here.
|
42
|
+
+ *DIR* 'icon'
|
43
|
+
+ 'normal.png', PNG file for a normal sized icon (150 x 110 px)
|
22
44
|
|
23
|
-
|
45
|
+
### Workflow
|
24
46
|
|
25
|
-
|
26
|
-
|
27
|
-
and of course, more documentation needs to come (means must be converted from the internal wiki to here).
|
47
|
+
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.
|
28
48
|
|
29
|
-
|
49
|
+
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.
|
30
50
|
|
31
|
-
|
51
|
+
The source sequence of PNGs is stored in the KLE-file as well, which allows features like frames.bin regeneration in the first place.
|
32
52
|
|
33
|
-
|
53
|
+
## Command Line Usage
|
34
54
|
|
35
|
-
|
55
|
+
**File info**
|
36
56
|
|
37
|
-
|
57
|
+
$ klear info choreo.kle
|
38
58
|
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
* Directory 'frames' (mandatory)
|
43
|
-
* Source PNGs which were used to generate the kle
|
44
|
-
* Directory 'cache' (optional)
|
45
|
-
* File 'frames.bin' containing binary data derived from the PNGs during creation
|
46
|
-
* further pre-processed data or application state for optimized restarts might be stored here.
|
47
|
-
* Directory 'icon'
|
48
|
-
* contains one file 'normal.png' for a normal sized icon (150 x 110 px)
|
59
|
+
dumps archive content info to stdout.
|
60
|
+
|
61
|
+
**New File Generation**
|
49
62
|
|
50
|
-
|
63
|
+
*Notice: file generation depends on jruby because of its usage of Java JAI*
|
51
64
|
|
52
|
-
|
65
|
+
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:
|
53
66
|
|
54
|
-
|
67
|
+
$ rvm jruby exec ./bin/klear.rb generate image_sequence_dir outfile.kle
|
68
|
+
|
69
|
+
and of course, more documentation needs to come (means must be converted from the internal wiki to here).
|
55
70
|
|
56
|
-
The source sequence of PNGs is stored in the KLE-file as well, which allows features like frames.bin regeneration in the first place.
|
57
71
|
|
58
|
-
|
72
|
+
## File Format Details
|
59
73
|
|
60
|
-
|
74
|
+
### PNGs
|
61
75
|
|
62
76
|
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.
|
63
77
|
|
@@ -65,12 +79,13 @@ Each single PNG represents exactly one frame and is stored with 16-bit / channel
|
|
65
79
|
|
66
80
|
!Waves_00129.png!
|
67
81
|
|
68
|
-
|
69
|
-
|
70
|
-
|
71
|
-
|
82
|
+
* We have 11 rows and 14 columns (blades)
|
83
|
+
* The lowest row describes the motor state
|
84
|
+
* The other rows describe the state of the lights from one direction to the other (TODO:
|
85
|
+
Define the direction - what is a point of reference?)
|
86
|
+
* The Png then is 140x110px in size.
|
72
87
|
|
73
|
-
|
88
|
+
### Sequence of PNGs
|
74
89
|
|
75
90
|
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.
|
76
91
|
|
@@ -78,12 +93,12 @@ The number of columns and rows must be the same for all PNGs.
|
|
78
93
|
|
79
94
|
*Examples*
|
80
95
|
|
81
|
-
|
82
|
-
|
96
|
+
* `A.png, B.png, X.png` is valid sequence of 3 PNGs
|
97
|
+
* `Test_0001.png, Test_0002.png, Test__1000.png` is a valid sequence
|
83
98
|
|
84
99
|
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).
|
85
100
|
|
86
|
-
|
101
|
+
### kle.yml
|
87
102
|
|
88
103
|
Contains information about how to use the frames:
|
89
104
|
|
@@ -104,7 +119,7 @@ The geometry is determined automatically by reading the first png in the png seq
|
|
104
119
|
fps: 25
|
105
120
|
</pre>
|
106
121
|
|
107
|
-
|
122
|
+
### MANIFEST.MF
|
108
123
|
|
109
124
|
The manifest contains meta information about the file and file format itself:
|
110
125
|
|
@@ -121,9 +136,9 @@ Kle-Version: 1.0
|
|
121
136
|
Created-By: ruby-kle-generator 0.344b
|
122
137
|
</pre>
|
123
138
|
|
124
|
-
|
139
|
+
### frames.bin
|
125
140
|
|
126
|
-
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.
|
141
|
+
The frames.bin binary 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.
|
127
142
|
|
128
143
|
Each 16-bit value is saved as unsigned 16 bit integer big endian (network byte order) and uses 2 bytes in frames.bin.
|
129
144
|
|
data/bin/klear
CHANGED
data/lib/klear/file_generator.rb
CHANGED
@@ -3,25 +3,34 @@
|
|
3
3
|
|
4
4
|
class Klear::FileGenerator
|
5
5
|
|
6
|
+
Defaults = {
|
7
|
+
overwrite: false,
|
8
|
+
}
|
9
|
+
|
6
10
|
def initialize options = {}
|
11
|
+
@options = Defaults.merge(options)
|
7
12
|
@png_path = nil
|
8
13
|
@kle_path = nil
|
9
14
|
@fps = 25
|
10
|
-
if options.has_key? :fps
|
11
|
-
@fps = options[:fps]
|
15
|
+
if @options.has_key? :fps
|
16
|
+
@fps = @options[:fps]
|
12
17
|
end
|
13
18
|
@gamma = 1.0
|
14
|
-
if options.has_key? :gamma
|
15
|
-
@gamma = options[:gamma]
|
19
|
+
if @options.has_key? :gamma
|
20
|
+
@gamma = @options[:gamma]
|
16
21
|
end
|
17
22
|
@geometry = nil
|
18
23
|
@raw_frame_values = []
|
19
24
|
@kle_file = nil
|
20
25
|
@silent = true
|
21
|
-
if options.has_key? :silent
|
22
|
-
@silent =
|
26
|
+
if @options.has_key? :silent
|
27
|
+
@silent = !!@options[:silent]
|
23
28
|
end
|
24
29
|
end
|
30
|
+
|
31
|
+
def overwrite?
|
32
|
+
@options[:overwrite]
|
33
|
+
end
|
25
34
|
|
26
35
|
def load
|
27
36
|
Zip::ZipFile.open(@kle_path) { |kle|
|
@@ -30,15 +39,15 @@ class Klear::FileGenerator
|
|
30
39
|
end
|
31
40
|
|
32
41
|
def write
|
33
|
-
Zip::ZipFile.open(@kle_path, Zip::ZipFile::CREATE)
|
42
|
+
Zip::ZipFile.open(@kle_path, Zip::ZipFile::CREATE) do |kle|
|
34
43
|
@kle_file = kle
|
35
44
|
add_pngs
|
36
45
|
regenerate_cache
|
37
46
|
|
38
47
|
# Meta
|
39
48
|
kle.mkdir('META-INF')
|
40
|
-
kle.file.open("META-INF/MANIFEST.MF", "w") do |
|
41
|
-
|
49
|
+
kle.file.open("META-INF/MANIFEST.MF", "w") do |fd|
|
50
|
+
fd.write <<-MANIFEST
|
42
51
|
Manifest-Version: 1.0
|
43
52
|
|
44
53
|
Kle-Version: 1.0
|
@@ -47,21 +56,26 @@ Generated-At: #{Time.now}
|
|
47
56
|
|
48
57
|
MANIFEST
|
49
58
|
end
|
50
|
-
|
51
|
-
|
59
|
+
|
60
|
+
kle.file.open("META-INF/kle.yml", "w") do |fd|
|
61
|
+
fd.write({
|
52
62
|
"geometry" => @geometry,
|
53
63
|
"gamma" => @gamma,
|
54
64
|
"fps" => @fps
|
55
65
|
}.to_yaml)
|
56
|
-
|
57
|
-
|
66
|
+
end
|
67
|
+
end
|
58
68
|
end
|
59
69
|
|
60
70
|
def generate thePngPath, theKleFile
|
61
71
|
@png_path = thePngPath
|
62
72
|
@kle_path = theKleFile
|
63
|
-
if File.exists? @kle_path
|
64
|
-
|
73
|
+
if (File.exists? @kle_path)
|
74
|
+
if overwrite?
|
75
|
+
FileUtils.rm(@kle_path, force: true)
|
76
|
+
else
|
77
|
+
raise "'#{@kle_path}' :: already exists! (use --overwrite to force it)"
|
78
|
+
end
|
65
79
|
end
|
66
80
|
write
|
67
81
|
report
|
data/lib/klear/version.rb
CHANGED
@@ -4,6 +4,14 @@ require 'fileutils'
|
|
4
4
|
|
5
5
|
describe Klear::FileGenerator do
|
6
6
|
if RUBY_PLATFORM.match /java/i
|
7
|
+
|
8
|
+
context 'default options' do
|
9
|
+
let(:fg) { Klear::FileGenerator.new }
|
10
|
+
it 'defaults to not overwrite' do
|
11
|
+
expect(fg.overwrite?).to be(false)
|
12
|
+
end
|
13
|
+
end
|
14
|
+
|
7
15
|
|
8
16
|
it "reads a directory with pngs and produces a valid kle file" do
|
9
17
|
fg = Klear::FileGenerator.new :fps => 33, :gamma => 2.4
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: klear
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.1.
|
4
|
+
version: 0.1.4
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- art+com/dirk luesebrink
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2013-
|
11
|
+
date: 2013-11-12 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: applix
|