pnm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0626fcd5c88b2477eb1f76891857c83fb10d881
+  data.tar.gz: 29724fe5ca19969bb9bf66358272222189b17f33
+SHA512:
+  metadata.gz: 9e1f19e832e56b253d9db10794d4b414fc0211222c8e24ac572ffa93399e505bab04648b51ad1598916959480e2769fbac6f74253557f8a2a2ec81fca06aab8f
+  data.tar.gz: de73725df2c7703abd73e105ea770c4efe89d5db7caa01da45a747335a3d819003a946a8aaa31aa08869e0a8a6662e578cd23227d31daab00eabc686ac86e0ef

data/README.md

@@ -0,0 +1,93 @@
+PNM - A Ruby library for PNM image files (PBM, PGM, PPM)
+========================================================
+
+PNM is a pure [Ruby][Ruby] library for creating, reading,
+and writing of `PNM` image files (Portable Anymap):
+
+- `PBM` (Portable Bitmap),
+- `PGM` (Portable Graymap), and
+- `PPM` (Portable Pixmap).
+
+Examples
+--------
+
+Create a PGM grayscale image from a two-dimensional array of gray values:
+
+    require 'pnm'
+
+    # pixel data
+    pixels = [[ 0, 10, 20],
+              [10, 20, 30]]
+
+    # optional settings
+    options = {:maxgray => 30, :comment => 'Test Image'}
+
+    # create the image object
+    image = PNM::Image.new(:pgm, pixels, options)
+
+    # retrieve some image properties
+    image.info    # => "PGM 3x2 Grayscale"
+    image.width   # => 3
+    image.height  # => 2
+
+See PNM::Image.new for a more detailed description of pixel data formats
+and available options.
+
+Write an image to a file:
+
+    image.write('test.pgm')
+
+    # use ASCII or "plain" format (default is binary)
+    image.write('test.pgm', :ascii)
+
+    # write to an I/O stream
+    File.open('test.pgm', 'w') {|f| image.write(f) }
+
+Read an image from a file (returns a PNM::Image object):
+
+    image = PNM.read('test.pgm')
+    image.comment  # => "Test Image"
+    image.maxgray  # => 30
+    image.pixels   # => [[0, 10, 20], [10, 20, 30]]
+
+
+Installation
+------------
+
+To install PNM, you can either
+
+- use `gem install pnm`, or
+
+- clone or download the repository and use
+  `rake build` and `[sudo] gem install pnm`.
+
+Requirements
+------------
+
+- No additional Ruby gems or native libraries are needed.
+
+- PNM has been tested with Ruby 1.9.3 and Ruby 2.0.0
+  on Linux and on Windows.
+
+Documentation
+-------------
+
+Documentation should be available via `ri PNM`.
+
+Reporting bugs
+--------------
+
+Report bugs on the PNM home page: <https://github.com/stomar/pnm/>
+
+License
+-------
+
+Copyright &copy; 2013 Marcus Stollsteimer
+
+`PNM` is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 3 or later (GPLv3+),
+see [www.gnu.org/licenses/gpl.html](http://www.gnu.org/licenses/gpl.html).
+There is NO WARRANTY, to the extent permitted by law.
+
+
+[Ruby]: http://www.ruby-lang.org/

data/Rakefile

@@ -0,0 +1,34 @@
+# rakefile for the PNM library.
+#
+# Copyright (C) 2013 Marcus Stollsteimer
+
+require 'rake/testtask'
+
+require_relative 'lib/pnm'
+
+
+def gemspec_file
+  'pnm.gemspec'
+end
+
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/test_*.rb'
+  t.ruby_opts << '-rubygems'
+  t.verbose = true
+  t.warning = true
+end
+
+
+desc 'Run benchmarks'
+task :benchmark do
+  Dir['benchmark/**/bm_*.rb'].each {|f| require_relative f }
+end
+
+
+desc 'Build gem'
+task :build do
+  sh "gem build #{gemspec_file}"
+end

data/benchmark/bm_converter.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# bm_converter.rb: Benchmarks for the PNM library.
+#
+# Copyright (C) 2013 Marcus Stollsteimer
+
+require 'benchmark'
+require_relative '../lib/pnm'
+require_relative '../lib/pnm/converter'
+
+class ConverterBenchmark
+
+  def initialize
+    @repetitions = ARGV[0].to_i  if ARGV[0] =~ /[0-9]+/
+    @repetitions ||= 10
+
+    @srcpath = File.dirname(__FILE__)
+
+    print 'Initializing test data...'
+    @pbm_image = PNM.read(File.expand_path("#{@srcpath}/random_image.pbm"))
+    @pgm_image = PNM.read(File.expand_path("#{@srcpath}/random_image.pgm"))
+    @ppm_image = PNM.read(File.expand_path("#{@srcpath}/random_image.ppm"))
+    puts " done\n"
+
+    @user   = 0.0
+    @system = 0.0
+    @total  = 0.0
+  end
+
+  def run
+    puts "Running benchmarks (#{@repetitions} repetitions)..."
+
+    run_benchmark(@pbm_image)
+    run_benchmark(@pgm_image)
+    run_benchmark(@ppm_image)
+
+    puts "\nTotal:               " <<
+         @user.round(2).to_s.ljust(11) <<
+         @system.round(2).to_s.ljust(11) <<
+         @total.round(2).to_s
+  end
+
+  def run_benchmark(image)
+    type   = image.type
+    type_string = type.upcase
+    width  = image.width
+    height = image.height
+    array  = image.pixels
+    ascii  = PNM::Converter.array2ascii(array)
+    binary = PNM::Converter.array2binary(type, array)
+
+    puts
+
+    Benchmark.bm(18) do |bm|
+      bm.report("#{type_string} / ascii2array") {
+        @repetitions.times do
+          PNM::Converter.ascii2array(type, ascii)
+        end
+      }
+
+      bm.report("#{type_string} / array2ascii") {
+        @repetitions.times do
+          PNM::Converter.array2ascii(array)
+        end
+      }
+
+      bm.report("#{type_string} / binary2array") {
+        @repetitions.times do
+          PNM::Converter.binary2array(type, width, height, binary)
+        end
+      }
+
+      bm.report("#{type_string} / array2binary") {
+        @repetitions.times do
+          PNM::Converter.array2binary(type, array)
+        end
+      }
+
+      @user   += bm.list.map {|tms| tms.utime }.reduce(:+)
+      @system += bm.list.map {|tms| tms.stime }.reduce(:+)
+      @total  += bm.list.map {|tms| tms.total }.reduce(:+)
+    end
+  end
+end
+
+ConverterBenchmark.new.run

data/lib/pnm.rb

@@ -0,0 +1,155 @@
+# = pnm.rb - create/read/write PNM image files (PBM, PGM, PPM)
+#
+# See PNM module for documentation.
+
+require_relative 'pnm/version'
+require_relative 'pnm/image'
+require_relative 'pnm/parser'
+require_relative 'pnm/converter'
+
+
+# PNM is a pure Ruby library for creating, reading,
+# and writing of +PNM+ image files (Portable Anymap):
+#
+# - +PBM+ (Portable Bitmap),
+# - +PGM+ (Portable Graymap), and
+# - +PPM+ (Portable Pixmap).
+#
+# == Examples
+#
+# Create a PGM grayscale image from a two-dimensional array of gray values:
+#
+#     require 'pnm'
+#
+#     # pixel data
+#     pixels = [[ 0, 10, 20],
+#               [10, 20, 30]]
+#
+#     # optional settings
+#     options = {:maxgray => 30, :comment => 'Test Image'}
+#
+#     # create the image object
+#     image = PNM::Image.new(:pgm, pixels, options)
+#
+#     # retrieve some image properties
+#     image.info    # => "PGM 3x2 Grayscale"
+#     image.width   # => 3
+#     image.height  # => 2
+#
+# See PNM::Image.new for a more detailed description of pixel data formats
+# and available options.
+#
+# Write an image to a file:
+#
+#     image.write('test.pgm')
+#
+#     # use ASCII or "plain" format (default is binary)
+#     image.write('test.pgm', :ascii)
+#
+#     # write to an I/O stream
+#     File.open('test.pgm', 'w') {|f| image.write(f) }
+#
+# Read an image from a file (returns a PNM::Image object):
+#
+#     image = PNM.read('test.pgm')
+#     image.comment  # => "Test Image"
+#     image.maxgray  # => 30
+#     image.pixels   # => [[0, 10, 20], [10, 20, 30]]
+#
+# == See also
+#
+# Further information on the PNM library is available on the
+# project home page: <https://github.com/stomar/pnm/>.
+#
+# == Author
+#
+# Copyright (C) 2013 Marcus Stollsteimer
+#
+# License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+#
+#--
+#
+# == PNM magic numbers
+#
+#  Magic Number  Type              Encoding
+#  ------------  ----------------  -------
+#  P1            Portable bitmap   ASCII
+#  P2            Portable graymap  ASCII
+#  P3            Portable pixmap   ASCII
+#  P4            Portable bitmap   Binary
+#  P5            Portable graymap  Binary
+#  P6            Portable pixmap   Binary
+#
+#++
+#
+module PNM
+
+  LIBNAME  = 'pnm'                                                # :nodoc:
+  HOMEPAGE = 'https://github.com/stomar/pnm'                      # :nodoc:
+  TAGLINE  = 'create/read/write PNM image files (PBM, PGM, PPM)'  # :nodoc:
+
+  COPYRIGHT = <<-copyright.gsub(/^ +/, '')                        # :nodoc:
+    Copyright (C) 2012-2013 Marcus Stollsteimer.
+    License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+    This is free software: you are free to change and redistribute it.
+    There is NO WARRANTY, to the extent permitted by law.
+  copyright
+
+  # Reads an image from +file+ (a filename or an IO object).
+  #
+  # Returns a PNM::Image object.
+  def self.read(file)
+    raw_data = nil
+    if file.kind_of?(String)
+      raw_data = File.binread(file)
+    else
+      file.binmode
+      raw_data = file.read
+    end
+
+    content = Parser.parse(raw_data)
+
+    case content[:magic_number]
+    when 'P1'
+      type = :pbm
+      encoding = :ascii
+    when 'P2'
+      type = :pgm
+      encoding = :ascii
+    when 'P3'
+      type = :ppm
+      encoding = :ascii
+    when 'P4'
+      type = :pbm
+      encoding = :binary
+    when 'P5'
+      type = :pgm
+      encoding = :binary
+    when 'P6'
+      type = :ppm
+      encoding = :binary
+    end
+
+    width   = content[:width].to_i
+    height  = content[:height].to_i
+    maxgray = content[:maxgray].to_i
+    pixels = if encoding == :ascii
+               Converter.ascii2array(type, content[:data])
+             else
+               Converter.binary2array(type, width, height, content[:data])
+             end
+
+    options = {:maxgray => maxgray}
+    options[:comment] = content[:comments].join("\n")  if content[:comments]
+
+    Image.new(type, pixels, options)
+  end
+
+  def self.magic_number  # :nodoc:
+    {
+      :pbm => {:ascii => 'P1', :binary => 'P4'},
+      :pgm => {:ascii => 'P2', :binary => 'P5'},
+      :ppm => {:ascii => 'P3', :binary => 'P6'}
+    }
+  end
+end

data/lib/pnm/converter.rb

@@ -0,0 +1,101 @@
+module PNM
+
+  # Converter for pixel data. Only for internal usage.
+  class Converter
+
+    # Returns the number of bytes needed for one row of pixels
+    # (in binary encoding).
+    def self.byte_width(type, width)
+      case type
+      when :pbm
+        (width - 1) / 8 + 1
+      when :pgm
+        width
+      when :ppm
+        3 * width
+      end
+    end
+
+    # Converts from ASCII format to an array of pixel values.
+    #
+    # +type+:: +:pbm+, +:pgm+, or +:ppm+.
+    # +data+:: A string containing the raw pixel data in ASCII format.
+    #
+    # Returns a two-dimensional array of bilevel, gray, or RGB values.
+    def self.ascii2array(type, data)
+      pixels = data.split("\n").map do |row|
+        row.split(/ +/).map {|value| value.to_i }
+      end
+
+      pixels.map! {|row| row.each_slice(3).to_a }  if type == :ppm
+
+      pixels
+    end
+
+    # Converts from binary format to an array of pixel values.
+    #
+    # +type+::            +:pbm+, +:pgm+, or +:ppm+.
+    # +width+, +height+:: The image dimensions in pixels.
+    # +data+::            A string containing the raw pixel data in binary format.
+    #
+    # Returns a two-dimensional array of bilevel, gray, or RGB values.
+    def self.binary2array(type, width, height, data)
+      bytes_per_row = byte_width(type, width)
+
+      if data.size == bytes_per_row * height + 1 && data[-1] =~ /[ \n\t\r]/
+        data.slice!(-1)
+      end
+
+      if data.size != bytes_per_row * height
+        raise 'data size does not match expected size'
+      end
+
+      case type
+      when :pbm
+        pixels = data.scan(/.{#{bytes_per_row}}/m)
+        pixels.map! {|row| row.unpack('B*').first[0, width].each_char.map {|char| char.to_i }  }
+      when :pgm
+        pixels = data.each_byte.each_slice(bytes_per_row).to_a
+      when :ppm
+        pixels = data.each_byte.each_slice(bytes_per_row).map {|row| row.each_slice(3).to_a }
+      end
+
+      pixels
+    end
+
+    # Converts a two-dimensional array of pixel values to an ASCII format string.
+    #
+    # +data+:: A two-dimensional array of bilevel, gray, or RGB values.
+    #
+    # Returns a string containing the pixel data in ASCII format.
+    def self.array2ascii(data)
+      case data.first.first
+      when Array
+        output = data.map {|row| row.flatten.join(' ') }.join("\n")
+      else
+        output = data.map {|row| row.join(' ') }.join("\n")
+      end
+
+      output << "\n"
+    end
+
+    # Converts a two-dimensional array of pixel values to a binary format string.
+    #
+    # +type+:: +:pbm+, +:pgm+, or +:ppm+.
+    # +data+:: A two-dimensional array of bilevel, gray, or RGB values.
+    #
+    # Returns a string containing the pixel data in binary format.
+    def self.array2binary(type, data)
+      height = data.size
+
+      if type == :pbm
+        binary_rows = data.map {|row| row.join }
+        data_string = binary_rows.pack('B*' * height)
+      else
+        data_string = data.flatten.pack('C*')
+      end
+
+      data_string
+    end
+  end
+end