papirus 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e4a81e5d2a007320dd5fe508cfd8f28e0136265
-  data.tar.gz: dcedbd0e7fee34467acf974839bf0cd715a1cf6b
+  metadata.gz: 7922a759efaac058b340469a65cb2ae523805fc3
+  data.tar.gz: 8b47d280f358a191fdc2682f1a5eeccb1daa2694
 SHA512:
-  metadata.gz: e5e46eda4b6c84f40fd1f7183a2ebafd5ec1cdc4c454366c73e6228f5af17975e4e79a5e438cd46a2c39cc710b0af903f289a388b3eb0a4c50934496e48aa658
-  data.tar.gz: 91e93335743a1d73742d3ad98101ffa0dfd8a00e5db9a00f593d5e53df69b018308c82b04f533bae1d433e22a5888cb6e003c847e1d8f58cede0c038578488b6
+  metadata.gz: f2431df7210edc30a3f5983156968b8eeaec567f737982976f8a483e6fa3541eb309813d54ceb3abcd0b8a36d7d0a8ecccca7d4079aff29212568bab47bc1a3f
+  data.tar.gz: 5a21d57e6c0f22c98fb0d8ac7789bc02d18e6fb8e913b2f012b064570cf09d9ade75c07e558b7989e698129d637387ddab12622370403fd8c9457a11a56fff11

data/README.md

@@ -2,7 +2,7 @@
 
 ruby gem to talk to the [PaPiRus](https://www.pi-supply.com/?s=papirus&post_type=product&tags=1&limit=5&ixwps=1) display
 
-before you start playing make sure you got the edp-fuse setup
+before you start playing make sure you got the display driver installed (gratis/edp-fuse)
 
 ## epaper fuse driver installation instructions (if you have not done that already ::)
 ```bash
@@ -16,13 +16,14 @@ systemctl enable epd-fuse.service
 systemctl start epd-fuse
 ```
 
-You can find more detailed instructions [https://github.com/repaper/gratis](here)
+You can find more detailed instructions and updates at the [https://github.com/repaper/gratis](gratis) repo
 
-## gem installation
+## gem installation (add sudo if your not useing [https://rvm.io/](rvm))
 
 ```bash
 $ gem install papirus
 ```
+
 ## usage
 
 ```ruby
@@ -32,6 +33,45 @@ require 'papirus'
 display = PaPiRus::Display.new()
 ```
 
+## there are multiple screen commands ['F', 'P', 'U', 'C']
+
+The `image.to_bit_stream` will be explained for both RMagic and ChunkyPNG below
+
+Full update (with screen cleaning):
+
+`display.show(image.to_bit_stream(display.width, display.height))`
+
+Fast update:
+
+`display.show(image.to_bit_stream(display.width, display.height)), 'F')`
+
+Partial update:
+
+`display.show(image.to_bit_stream(display.width, display.height), 'P')`
+
+# Playing with RMagic
+
+First install rmagick
+
+```bash
+$ # install native Image Magick library
+$ (OSX) brew install imagemagick@6 && brew link imagemagick@6 --force
+$ (debian/ubuntu) sudo apt-get install imagemagick
+$ (Windows) no idea (did not use windows for 20 years, and would like to add some more)
+$ # install the gem that talks to the native Image Magick library
+$ gem install rmagick
+```
+
+Then, start an irb session to play around
+```ruby
+require 'papirus'
+require 'papirus/rmagick'
+
+display = PaPiRus::Display.new()
+image = Magick::Image::read('/path/to/img/file.(png|jpg|etc)'.first
+display.show(image.to_bit_stream(display.width, display.height))
+```
+
 # Playing with Chunky_PNG
 
 First install chunky_png
@@ -39,11 +79,33 @@ First install chunky_png
 ```bash
 $ (OSX) brew install chunky_png
 $ (debian/ubuntu) sudo apt-get install chunky_png
-$ (Windows) no idea (did not use windows for 20 year, yes that is possible)
+$ (Windows) no idea (did not use windows for 20 years, and would like to add some more)
 $ gem install chunky_png
 ```
 
-The, start an irb session to play around
+## Load an image from a png file
+
+```ruby
+irb
+require 'papirus'
+require 'papirus/chunky'
+display = PaPiRus::Display.new()
+image = ChunkyPNG::Image.from_file('out.png')
+display.show(image.to_bit_stream(display.width, display.height))
+```
+
+The only problem here is the aspect ration of the image is not ok anymore. is a todo
+But for now you could also use Image magick's convert tool to rescale  the image and place it in the middle
+
+First, let's use Image Magick's `convert` tool to convert any image into an scaled, centered png
+```bash
+convert in.jpg -resize '264x176' -gravity center -extent '264x176' out.png
+```
+
+now, load it like explaned above and the image should be in the right aspect ration
+
+## Playing with drawing circles
+
 ```ruby
 irb
 require 'papirus'
@@ -75,74 +137,7 @@ display.clear
 end
 ```
 
-## there are multiple screen commands ['F', 'P', 'U', 'C']
-
-Full update (with screen cleaning):
-
-```display.show(image.to_bit_stream); display.update``` or
-
-```display.show(image.to_bit_stream, 'U')```
-
-Fast update:
-
-```display.show(image.to_bit_stream); display.fast_update```
-```display.show(image.to_bit_stream, 'F')```
-
-Partial update:
-
-```display.show(image.to_bit_stream); display.partial_update``` or
-
-```display.show(image.to_bit_stream, 'P')```
-
-## Load an image from a png file with convert and chunky
-
-First, let's use Image Magick's `convert` tool to convert any image into a b/w image the way the diplay likes it
-```bash
-convert in.jpg -resize '264x176' -gravity center -extent '264x176' -colorspace gray  -colors 2 -type bilevel out.png
-```
-
-Where
-* the -resize scales the image to fit the display
-* The -gravity and -extent combination (order is important!) makes sure the image stays at the size of the display and in the centre
-* The -colorspace -colors -type combi makes the image a 1-bit grayscale b/w image
-
-Then we use chucky with our extension to show
-
-```ruby
-irb
-require 'papirus'
-require 'papirus/chunky'
-display = PaPiRus::Display.new()
-image = ChunkyPNG::Image.from_file('out.png')
-display.show(image.to_bit_stream(true))
-```
-result:
-![that's me](https://raw.githubusercontent.com/mmolhoek/papirus/master/example_output.jpg)
-
-# Playing with RMagic (does not work yet), did not figure out right command
-
-First install rmagick
-
-```bash
-$ # install native Image Magick library
-$ (OSX) brew install imagemagick@6 && brew link imagemagick@6 --force
-$ (debian/ubuntu) sudo apt-get install imagemagick
-$ (Windows) no idea (did not use windows for 20 year, yes that is possible)
-$ # install the gem that talks to the native Image Magick library
-$ gem install rmagick
-```
-
-The, start an irb session to play around
-```ruby
-require 'papirus'
-require 'papirus/rmagick'
-
-display = PaPiRus::Display.new()
-img = Magick::Image::read('/path/to/img/file.(png|jpg|etc').first
-img.to_papirus(display)
-```
-
-## Testing without a PAPiRus display
+## Testing without a PaPiRus display
 
 If you want to test the gem, but don't have your PaPiRus available, you can do the following
 
@@ -154,14 +149,26 @@ If you want to test the gem, but don't have your PaPiRus available, you can do t
 * play with the examples above
 * when you run `display.show` the **fake** display /tmp/epd/LE/display is filled with your image
 * now you can use a bin editor like xxd to have a look at the result: `xxd -b /tmp/epd/LE/display`
+* or, use `image.inspect_bitstream(display.width, display.height)` to dump the image as 1's and 0's to the terminal
+* make sure you have your terminal font small enought so the image fits the terminal :)
+
+## handy convert command
+
+This Image Magick convert command creates a 1-bit 2-color png
+```bash
+convert in.jpg -resize '264x176' -gravity center -extent '264x176' -colorspace gray  -colors 2 -type bilevel out.png
+```
+Where
+* the -resize scales the image to fit the display
+* The -gravity and -extent combination (order is important!) makes sure the image stays at the size of the display and in the centre
+* The -colorspace -colors -type combi makes the image a 1-bit grayscale b/w image
 
 ## TODO
 
 * make the image.to_bit_stream routine faster (as it is now to slow to do animations with partial updates)
 * add support for reading the temperature of the display
 * add support for changing the update rate
-* make load png image with chunky_png work (now output is black)
-* make a display.load(image) that takes multiple formats and figures out how to present them
+* make load png image with chunky_png scale keeping aspect ratio in mind
 * create an issue to add your own requests :)
 
 ## Other resources

data/lib/papirus.rb

@@ -4,6 +4,13 @@ module PaPiRus
     class Display
         attr_reader :epd_path, :width, :height, :panel, :cog, :film, :auto, :allowed_commands, :display_path
         attr_accessor :rotation, :inverse, :image
+        # The possible commands to send to the display with {PaPiRus::Display.command}
+        # can be eitheri
+        # 'U' for update
+        # 'F' for fast update
+        # 'P' for partial update
+        # or 'C' for clearing the screen
+        attr_reader :allowed_commands
 
         def initialize(epd_path: '/dev/epd', width: 200, height: 96, panel: 'EPD 2.0', cog: 0, film: 0, auto: false, inverse: false, rotation: 0)
             #transver all vars to attr's
@@ -42,6 +49,8 @@ module PaPiRus
             command('C')
         end
 
+        # send's the display command to the driver
+        # @param c [string] command to execute, have a look at {}
         def command(c)
             raise "command #{c} does not exist" unless @allowed_commands.include?(c)
             File.open(File.join(@epd_path, "command"), "wb") do |io|
@@ -50,9 +59,8 @@ module PaPiRus
         end
 
     private
+        # Reads all panel info and updates the according attributes
         def get_display_info_from_edp
-            #now we will read the info of the installed display
-            #and update the properties accordingly
             if File.exists?(File.join(@epd_path, 'panel'))
                 info = File.read(File.join(@epd_path, 'panel'))
                 @display_path = File.join([@epd_path, 'LE', 'display'])

data/lib/papirus/chunky.rb

@@ -1,25 +1,39 @@
 require 'chunky_png'
 
 module ChunkyPNG::Canvas::StreamExporting
-    def inspect_bitstream
-        #create a simple map of the image of '0's and '1's
-        #for debugging purpuses
-        pixels.each_slice(@width).map{|row| row.each_slice(8).map{|pixels|pixels.map{|pixel| pixel == ChunkyPNG::Color::WHITE ? '0' : '1'}.join}.join(' ')}
+    # Creates a simple map of the image of '0's and '1's to STDERR
+    # this way you can view your image from the terminal
+    # set your terminals font very small, so the image will fit on your screen
+    # @param width[integer] The width of the image to inspect
+    # @param height[integer] The height of the image to inspect
+    def inspect_bitstream(width, height)
+        STDERR.puts to_1_bit_2_color_bw_image(width, height).each_slice(width).map{|row| row.each_slice(8).map{|pixels|pixels.map{|pixel| pixel < 128 ? '0' : '1'}.join}.join(' ')}.join("\n")
     end
 
-    def to_bit_stream(inverse = false)
-        #as the ChunkyPNG library works with 4 bytes data per pixel (1 byte for R, G, B and transparancy)
-        #and the EDP needs 1 bit per pixel (on or off), we need some way to traverse over all pixels
-        #and add a bit to a byte stream for each pixel. so
+    # Creates a rescaled image of whatever image is loaded
+    # image is rescaled to fit the width/height and is placed in the middle
+    # @param width[integer] width the image should be scaled to
+    # @param height[integer] height the image should be scaled to
+    def to_1_bit_2_color_bw_image(width, height)
+        resize(width, height).pixels.map{|pixel| ChunkyPNG::Color.grayscale_teint(pixel)}
+    end
+    # As the EPD display needs 1-bit per pixel, which get written as a string to the fuse-fs display file
+    # and the ChunkyPNG library works with 4 bytes data per pixel (1 byte for R, G, B and transparancy)
+    # we need to load all the bits together in bytes, and packed those bytes into a string
+    # @param width[integer] width the image should be scaled to
+    # @param height[integer] height the image should be scaled to
+    # @param inverse[boolean] wether the image should be made negative
+    # @param mingray{intergeri (0-255)] what grayscale value or higher is needed, to turn a bit on
+    def to_bit_stream(width, height, inverse = false, mingray = 128)
         bytes = []
         #for each 8 pixels (the ChunkyPNG library keeps an array of all pixels used, containing ChunkyPNG::Color elements)
-        pixels.each_slice(8).map do |pixels|
+        to_1_bit_2_color_bw_image(width, height).each_slice(8).map do |pixels|
             #we create a byte with its bits set to 00000000
             byte = 0
             0.upto(7) do |bit|
                 #and switch the bit to 1 (or 0 if not inverse) for each pixel if it was white
                 #we have to check pixels[7-bit] as the order is right to left
-                byte |= 1 << bit if (inverse && pixels[7-bit] == ChunkyPNG::Color::WHITE) || (!inverse && pixels[7-bit] != ChunkyPNG::Color::WHITE)
+                byte |= 1 << bit if (inverse && pixels[7-bit] > mingray) || (!inverse && pixels[7-bit] < mingray)
             end
             #and add it to the output byte stream
             bytes.push(byte)

data/lib/papirus/rmagick.rb

@@ -1,28 +1,60 @@
 require 'rmagick'
 
 class Magick::Image
-    # Send's any image to the PAPiRus display, if it is found
-    # image is rescaled to fit the display (positioning it mid center)
-    # @param display[PaPiRus::Display] The {PaPiRus::Display} object
-    def to_papirus(display)
+    # Creates a simple map of the image of '0's and '1's to STDERR
+    # this way you can view your image from the terminal
+    # set your terminals font very small, so the image will fit on your screen
+    # @param width[integer] The width of the image to inspect
+    # @param height[integer] The height of the image to inspect
+    def inspect_bitstream(width, height)
+        STDERR.puts to_1_bit_2_color_bw_image(width, height).get_pixels(0, 0, width, height).each_slice(width).map{|row| row.each_slice(8).map{|pixels|pixels.map{|pixel| pixel.blue == 0 ? '1' : '0'}.join}.join(' ')}.join("\n")
+    end
+
+    # Creates a 1-bit 2-color image of whatever image is loaded
+    # image is rescaled to fit the width/height and is placed in the middle
+    # @param width[integer] width the image should be scaled to
+    # @param height[integer] height the image should be scaled to
+    def to_1_bit_2_color_bw_image(width, height)
         # Resize to fit the screen
-        resized = resize_to_fit(display.width, display.height)
+        resized = resize_to_fit(width, height)
         # Reduce the image to a limited number of colors for a "poster" effect, brings it donw to 4-bit 16 colors
         posterized = resized.posterize(2)
         #now, as the display expects a file with all pixels set, we need to extend the image to the display size
         #if it is smaller in either width or height or both
-        if (posterize.columns != display.width or posterize.rows != display.height)
+        if (posterize.columns != width or posterize.rows != height)
             # extent fill color
             posterized.background_color = "#FFFFFF"
             # calculate necessary translation to center image on background
-            x = (posterized.columns - display.width) / 2
-            y = (posterized.rows - display.height) / 2
+            x = (posterized.columns - width) / 2
+            y = (posterized.rows - height) / 2
             # now, 'extent' the image to the correct size with the image centered
-            posterized = posterized.extent(display.width, display.height, x, y)
+            posterized = posterized.extent(width, height, x, y)
         end
         # Now, make grayscale with only 2 colors, b/w, brings it down to 1-bit 2 colors
-        quantized = posterized.quantize(2, Magick::GRAYColorspace)
-        #return the raw image data
-        quantized.write(display.display_path){self.format='DIB'} #DIB=Device Independant Binary, as in , no headers, just raw data
+        return posterized.quantize(2, Magick::GRAYColorspace)
+    end
+
+    # As the EPD display needs 1-bit per pixel, which get written as a string to the fuse-fs display file
+    # we need to load all the bits together in bytes, and packed those bytes into a string
+    # @param width[integer] width the image should be scaled to
+    # @param height[integer] height the image should be scaled to
+    # @param inverse[boolean] wether the image should be made negative
+    def to_bit_stream(width, height, inverse = false)
+        bytes =[]
+        # First, we convert whatever image we got to a 1-bit 2-color image,
+        # then we traverse over the pixels in byte (8 bits) chucks to create our output bytes
+        to_1_bit_2_color_bw_image(width, height).get_pixels(0, 0, width, height).each_slice(8).map do |pixels|
+            #we create a byte with its bits set to 00000000
+            byte = 0
+            0.upto(7) do |bit|
+                #and switch the bit to 1 (or 0 if not inverse) for each pixel if it was white
+                #we have to check pixels[7-bit] as the order is right to left
+                byte |= 1 << bit if (inverse && pixels[7-bit].blue == 65535) || (!inverse && pixels[7-bit].blue == 0)
+            end
+            #and add it to the output byte stream
+            bytes.push(byte)
+        end
+        #now we just need to pack all bytes into a file writable string
+        bytes.pack('C*')
     end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papirus
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Mischa Molhoek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-11 00:00:00.000000000 Z
+date: 2017-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shoulda