catpix 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fcdff6dbde407d1a3da16b3a1d938175e93e9f0e
-  data.tar.gz: 0fd1b98ca31f31aceb50ddc3b287f584cec30cac
+  metadata.gz: 196bc701b3b4f11b7e85b6f2b7280c0fba468fb0
+  data.tar.gz: 24b01ca8de6cf965dc93c41298335bf67a71b513
 SHA512:
-  metadata.gz: 426b64e05e95359d8fbd0e75ef17b077cac04710bb6507dee5fcd95117748bddb65499d2a192de2766ef8b38c2797ce9b17ad9de04aad99f6f8cc1bcfefd2084
-  data.tar.gz: abbf23e0c4a5de5e83288339b0203302952e3f539943d22245992d22ca4d2de1ddb3b6af91fa0269df6ec241f1835efec7ea885f20bea5defe1b63d8afd393c6
+  metadata.gz: fdbb8c571854223d2516906e59845ddbc6f1e8c218e8a43313031bcb98134038e6fb152e2aa3ddeb8a54b401521ffbd3dd0fe6a0335e7715b39b93244f176c6b
+  data.tar.gz: 1577dc3ecf67e30f69ba406dc442e0aee02348aeff2e1739e18b8c67c6507a4454a164563dfeed75288b0856ed75751e61c91cf317152b90f023b54bd3ce21b7

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.2.0 (2015-07-04)
+
+New features:
+
+  - Quadrupled the resolution of the image
+  - Added line buffering
+  - Drawing margins is slightly quicker

data/README.md

@@ -1,10 +1,98 @@
 # Catpix
 
-TODO: Write a gem description
+[![Gem Version](https://badge.fury.io/rb/catpix.png)](http://badge.fury.io/rb/catpix)
+[![Inline docs](http://inch-ci.org/github/pazdera/catpix.png)](http://inch-ci.org/github/pazdera/catpix)
+
+Renders images in the terminal.
+
+![Pokemon](http://radek.io/assets/images/posts/catpix/pokemon.png)
+
+It will handle most image formats (png, jpg, gif, bpm and many more). As long
+as ImageMagick can read it, catpix can too. By default, it will scale them
+down to fit the width of your terminal. You can set the same for the height
+of the image and also center it by providing custom options (see Usage below).
+
+On the inside, catpix uses [rmagick](https://rubygems.org/gems/rmagick) to read
+and scale images and the [tco](https://github.com/pazdera/tco) gem to map its
+colours to the extended 256 colour palette in the terminal. A pixel is
+approximated as two spaces, so you might get weird results in case your font
+has different proportions.
+
+It can render full resolution photos, although it takes a while and the
+resolution is obviously limited. Here's a photo of some flowers in my window,
+straight from my phone and rendered in the terminal:
+
+![Full photo](http://radek.io/assets/images/posts/catpix/photo.png)
+
+### Resolutions (new in 0.2.0)
+
+Catpix can render images in two resolutions. If you terminal supports
+unicode, it will use the
+[upper half block](http://www.fileformat.info/info/unicode/char/2580/index.htm)
+to dispplay one pixel. Otherwise, a pixel will be approximated as two
+spaces. The detection is automatic, but you can also force one or the
+other via _options_. The higher setting has four times as many pixels as the
+lower one. See how do they compare below:
+
+![Comparing resolutions](http://radek.io/assets/images/posts/catpix/resolution.gif)
 
 ## Usage
 
-TODO: Write usage instructions here
+### In the terminal
+
+The gem will install the `catpix` command on your system that you can use
+directly from shell. To print an image simply pass the path to it as the
+first argument:
+
+    $ catpix pokemon.gif
+
+Use the `-c` flag to center it (x for horizontal and y for vertical centering):
+
+    $ catpix panda.png -c xy
+
+Add `-w` or `-h` to scale it down. These two options require a factor of the
+size of your terminal. If you want to limit the size of your image to half of
+your terminal window use:
+
+    $ catpix trophy.png -w 0.5 -h 0.5
+
+And finally, if your image has any fully transparent pixels, you can specify
+background colour to be rendered behind and around the image. Use `-b` to
+specify the colour and `-f` to make it fill the margins around the image if
+it's centered:
+
+    $ catpix tux.png -b "#00ff00"      # RGB is fine
+    $ catpix tux.png -b green          # tco aliases work too
+    $ catpix tux.png -c xy -b green -f # fill the margins around the image too
+    $ catpix tux.png -c xy -r high     # enforce high resolution
+
+### In Ruby
+
+The Ruby API consists of only a single function called `print_image`:
+
+```ruby
+require 'catpix'
+
+Catpix::print_image "pokemon.png",
+  :limit_x => 1.0,
+  :limit_y => 0,
+  :center_x => true,
+  :center_y => true,
+  :bg => "white",
+  :bg_fill => true,
+  :resolution => low
+```
+
+See the [documentation at RubyDoc](http://www.rubydoc.info/github/pazdera/catpix/master/Catpix.print_image)
+for more detail.
+
+## More examples
+
+![UK Flag](http://radek.io/assets/images/posts/catpix/flag.png)
+
+![Happy Panda](http://radek.io/assets/images/posts/catpix/panda.png)
+
+![Trophy](http://radek.io/assets/images/posts/catpix/trophy.png)
 
 ## Installation
 
@@ -21,6 +109,9 @@ And then execute:
 
     $ bundle
 
+## Author
+
+Radek Pazdera <me@radek.io> [radek.io](http://radek.io/)
 
 ## Contributing
 

data/bin/catpix

@@ -21,6 +21,7 @@ Options:
   -c=<pos>, --center            Set x, y or xy centering in the window.
   -b=<colour>, --bg             Set background colour.
   -f, --bg-fill                 Draw background around the image as well.
+  -r=<res>, --resolution        Either 'high' or 'low' [default: auto].
 
   --help                        Show this message.
   --version                     Print the version.
@@ -36,7 +37,8 @@ end
 options = {
   :limit_x => args['--limit-width'].to_f,
   :limit_y => args['--limit-height'].to_f,
-  :bg_fill => args['--bg-fill']
+  :bg_fill => args['--bg-fill'],
+  :resolution => args['--resolution']
 }
 
 if args['--center']

data/catpix.gemspec

@@ -21,7 +21,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "tco", "~> 0.1", ">= 0.1.6"
+  spec.required_ruby_version = ">= 1.9"
+
+  spec.add_dependency "tco", "~> 0.1", ">= 0.1.8"
   spec.add_dependency "rmagick", "~> 2.15", ">= 2.15.2"
   spec.add_dependency "docopt", "~> 0.5", ">= 0.5.0"
   spec.add_dependency "ruby-terminfo", "~> 0.1", ">= 0.1.1"

data/lib/catpix.rb

@@ -41,38 +41,30 @@ module Catpix
   #                              alias 'red' or 'blue'. [default: nil]
   # @option options [Boolean] :bg_fill Fill the margins around the image with
   #                                    background colour. [default: false]
+  # @option options [String] :resolution Determines the pixel size of the
+  #                                      rendered image. Can be set to `high`,
+  #                                      `low` or `auto` (default). If set to
+  #                                      `auto` the resolution will be picked
+  #                                      automatically based on your terminal's
+  #                                      support of unicode.
   def self.print_image(path, options={})
     options = default_options.merge! options
 
+    if options[:resolution] == 'auto'
+      options[:resolution] = can_use_utf8? ? 'high' : 'low'
+    end
+    @@resolution = options[:resolution]
+
     img = load_image path
     resize! img, options[:limit_x], options[:limit_y]
 
     margins = get_margins img, options[:center_x], options[:center_y]
-    margin_colour = options[:bg_fill] ? options[:bg] : nil
-
-    print_vert_margin margins[:top], margin_colour
-
-    # print left margin for the first row
-    print_horiz_margin margins[:left], margin_colour
+    margins[:colour] = options[:bg_fill] ? options[:bg] : nil
 
-    # print the image
-    img.each_pixel do |pixel, col, row|
-      if pixel.opacity == 65535
-        print_pixel options[:bg]
-      else
-        print_pixel get_normal_rgb pixel
-      end
-
-      if col >= img.columns - 1
-        print_horiz_margin margins[:right], margin_colour
-        puts
-
-        unless row == img.rows - 1
-          print_horiz_margin margins[:left], margin_colour
-        end
-      end
+    if high_res?
+      do_print_image_hr img, margins, options
+    else
+      do_print_image_lr img, margins, options
     end
-
-    print_vert_margin margins[:bottom], margin_colour
   end
 end

data/lib/catpix/private.rb

@@ -7,38 +7,76 @@ require "terminfo"
 
 module Catpix
   private
+  MAX_OPACITY = 65535
+
   def self.default_options
     {
-      :limit_x => 1.0,
-      :limit_y => 0,
-      :center_x => false,
-      :center_y => false,
-      :bg => nil,
-      :bg_fill => false
+      limit_x: 1.0,
+      limit_y: 0,
+      center_x: false,
+      center_y: false,
+      bg: nil,
+      bg_fill: false,
+      resolution: 'auto'
     }
   end
 
-  def self.print_pixel(colour=nil)
-    if colour
-      print "  ".bg colour
-    else
-      print "  "
+  @@resolution = nil
+
+  def self.high_res?
+    @@resolution == 'high'
+  end
+
+  def self.can_use_utf8?
+    ENV.values_at("LC_ALL", "LC_CTYPE", "LANG").compact.first.include?("UTF-8")
+  end
+
+  def self.prep_lr_pixel(colour)
+    colour ? "  ".bg(colour) : "  "
+  end
+
+  def self.print_lr_pixel(colour)
+    print prep_lr_pixel colour
+  end
+
+  def self.prep_hr_pixel(colour_top, colour_bottom)
+    upper = "\u2580"
+    lower = "\u2584"
+
+    return " " if colour_bottom.nil? and colour_top.nil?
+    return lower.fg colour_bottom if colour_top.nil?
+    return upper.fg colour_top if colour_bottom.nil?
+
+    c_top = Tco::match_colour colour_top
+    c_bottom = Tco::match_colour colour_bottom
+    if c_top == c_bottom
+      return " ".bg "@#{c_top}"
     end
+
+    upper.fg("@#{c_top}").bg("@#{c_bottom}")
+  end
+
+  def self.print_hr_pixel(colour_top, colour_bottom)
+    print prep_hr_pixel colour_top, colour_bottom
   end
 
   # Returns normalised size of the terminal window
   #
-  # Catpix uses two blank characters to approximate pixels in the terminal,
-  # so we need to divide the width of the terminal by 2.
+  # Catpix can use either two blank spaces to approximate a pixel in the
+  # temrinal or the 'upper half block' and 'bottom half block' characters.
+  #
+  # Depending on which of the above will be used, the screen size
+  # must be normalised accordingly.
   def self.get_screen_size
     th, tw = TermInfo.screen_size
-    [tw / 2, th]
+    if high_res? then [tw, th * 2] else [tw / 2, th] end
   end
 
   def self.load_image(path)
     Magick::Image::read(path).first
   end
 
+  # Scale the image down based on the limits while keeping the aspect ratio
   def self.resize!(img, limit_x=0, limit_y=0)
     tw, th = get_screen_size
     iw = img.columns
@@ -58,8 +96,8 @@ module Catpix
 
     # Resize the image if it's bigger than the limited viewport
     if iw > width or ih > height
-      img.change_geometry "#{width}x#{height}" do |cols, rows, img|
-        img.resize! (cols).to_i, (rows).to_i
+      img.change_geometry "#{width}x#{height}" do |cols, rows, img_handle|
+        img_handle.resize! (cols).to_i, (rows).to_i
       end
     end
   end
@@ -92,18 +130,94 @@ module Catpix
       margins[:bottom] = 0
     end
 
+    if high_res? and margins[:top] % 2 and margins[:bottom] % 2
+      margins[:top] -= 1
+      margins[:bottom] += 1
+    end
+
     margins
   end
 
-  def self.print_vert_margin(size, colour)
+  def self.prep_vert_margin(size, colour)
     tw, th = get_screen_size
-    size.times do
-      tw.times { print_pixel colour }
-      puts
+
+    buffer = ""
+    if high_res?
+      (size / 2).times do
+        sub_buffer = ""
+        tw.times { sub_buffer += prep_hr_pixel nil, nil }
+        buffer += sub_buffer.bg(colour) + "\n"
+      end
+    else
+      size.times do
+        sub_buffer = ""
+        tw.times { sub_buffer += prep_lr_pixel nil }
+        buffer += sub_buffer.bg(colour) + "\n"
+      end
+    end
+    buffer
+  end
+
+  def self.prep_horiz_margin(size, colour)
+    buffer = ""
+    if high_res?
+      size.times { buffer += prep_hr_pixel nil, nil }
+    else
+      size.times { buffer += prep_lr_pixel nil }
+    end
+    buffer.bg colour
+  end
+
+  # Print the image in low resolution
+  def self.do_print_image_lr(img, margins, options)
+    print prep_vert_margin margins[:top], margins[:colour]
+
+    0.upto(img.rows - 1) do |row|
+      buffer = prep_horiz_margin margins[:left], margins[:colour]
+      0.upto(img.columns - 1) do |col|
+        pixel = img.pixel_color col, row
+
+        buffer += if pixel.opacity == MAX_OPACITY
+          prep_lr_pixel options[:bg]
+        else
+          prep_lr_pixel get_normal_rgb pixel
+        end
+      end
+      buffer += prep_horiz_margin margins[:right], margins[:colour]
+      puts buffer
     end
+
+    print prep_vert_margin margins[:bottom], margins[:colour]
   end
 
-  def self.print_horiz_margin(size, colour)
-    size.times { print_pixel colour }
+  # Print the image in high resolution (using unicode's upper half block)
+  def self.do_print_image_hr(img, margins, options)
+    print prep_vert_margin margins[:top], margins[:colour]
+
+    0.step(img.rows - 1, 2) do |row|
+      # line buffering makes it about 20% faster
+      buffer = prep_horiz_margin margins[:left], margins[:colour]
+      0.upto(img.columns - 1) do |col|
+        top_pixel = img.pixel_color col, row
+        colour_top = if top_pixel.opacity < MAX_OPACITY
+          get_normal_rgb top_pixel
+        else
+          options[:bg]
+        end
+
+        bottom_pixel = img.pixel_color col, row + 1
+        colour_bottom = if bottom_pixel.opacity < MAX_OPACITY
+          get_normal_rgb bottom_pixel
+        else
+          options[:bg]
+        end
+
+        buffer += prep_hr_pixel colour_top, colour_bottom
+      end
+      buffer += prep_horiz_margin margins[:right], margins[:colour]
+      puts buffer
+    end
+
+    print prep_vert_margin margins[:bottom], margins[:colour]
   end
 end

data/lib/catpix/version.rb

@@ -3,5 +3,5 @@
 
 module Catpix
   # Version of the gem
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: catpix
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Radek Pazdera
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-28 00:00:00.000000000 Z
+date: 2015-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tco
@@ -19,7 +19,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.6
+        version: 0.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.6
+        version: 0.1.8
 - !ruby/object:Gem::Dependency
   name: rmagick
   requirement: !ruby/object:Gem::Requirement
@@ -131,6 +131,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -152,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="