Module: PNM

Defined in:
lib/pnm.rb,
lib/pnm/image.rb,
lib/pnm/parser.rb,
lib/pnm/version.rb,
lib/pnm/converter.rb,
lib/pnm/exceptions.rb

Overview

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).

It is a portable and lightweight utility for exporting or importing of raw pixel data to or from an image file format that can be processed by most image manipulation programs.

PNM comes without any dependencies on other gems or native libraries.

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.create(pixels, options)

# retrieve some image properties
image.info    # => "PGM 3x2 Grayscale"
image.type    # => :pgm
image.width   # => 3
image.height  # => 2

Note that for PBM bilevel images a pixel value of 0 signifies white (and 1 signifies black), whereas for PGM and PPM images a value of 0 signifies black.

See PNM.create 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]]

Force an image type:

image = PNM.create([[0, 1],[1, 0]], :type => :ppm)
image.info  # => "PPM 2x2 Color"

See also

Further information on the PNM library is available on the project home page: <github.com/stomar/pnm/>.

Author

Copyright © 2013-2014 Marcus Stollsteimer

License GPLv3+: GNU GPL version 3 or later <gnu.org/licenses/gpl.html>

Defined Under Namespace

Classes: ArgumentError, DataError, DataSizeError, Error, Image, PBMImage, PGMImage, PPMImage, ParserError

Constant Summary collapse

LIBNAME = 
'pnm'
HOMEPAGE = 
'https://github.com/stomar/pnm'
TAGLINE = 
'create/read/write PNM image files (PBM, PGM, PPM)'
<<-copyright.gsub(/^ +/, '')
  Copyright (C) 2013-2014 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
VERSION = 
'0.4.0'
DATE = 
'2014-12-28'

Class Method Summary collapse

Class Method Details

.create(pixels, options = {}) ⇒ Object

Creates an image from a two-dimensional array of bilevel, gray, or RGB values. The image type is guessed from the provided pixel data, unless it is explicitly set with the type option.

pixels

The pixel data, given as a two-dimensional array of

  • for PBM: bilevel values of 0 (white) or 1 (black),

  • for PGM: gray values between 0 (black) and maxgray (white),

  • for PPM: an array of 3 values between 0 and maxgray, corresponding to red, green, and blue (RGB); a value of 0 means that the color is turned off.

Optional settings that can be specified in the options hash:

type

The type of the image (:pbm, :pgm, or :ppm). By explicitly setting type, PGM images can be created from bilevel pixel data, and PPM images can be created from bilevel or gray pixel data. String values ("pbm", "pgm", or "ppm") are also accepted.

maxgray

The maximum gray or color value. For PGM and PPM, maxgray must be less or equal 255 (the default value). For bilevel pixel data, setting maxgray to a value greater than 1 implies a type of :pgm. When type is explicitly set to :pbm, the maxgray setting is disregarded.

comment

A multiline comment string.

Returns a PNM::Image object.



182
183
184
 
# File 'lib/pnm.rb', line 182

def self.create(pixels, options = {})
  Image.create(pixels, options)
end

.read(file) ⇒ Object

Reads an image from file (a filename or an IO object).

Returns a PNM::Image object.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/pnm.rb', line 103

def self.read(file)
  if file.kind_of?(String)
    raw_data = File.binread(file)
  elsif file.respond_to?(:binmode)
    file.binmode
    raw_data = file.read
  else
    raise PNM::ArgumentError, "wrong argument type"
  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]
  height  = content[:height]
  maxgray = content[:maxgray]
  pixels = if encoding == :ascii
             Converter.ascii2array(type, width, height, content[:data])
           else
             Converter.binary2array(type, width, height, content[:data])
           end

  options = {:type => type, :maxgray => maxgray}
  options[:comment] = content[:comments].join("\n")  if content[:comments]

  create(pixels, options)
end