PNM - A Ruby library for PNM image files (PBM, PGM, PPM)

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]]

# create the image object
image = PNM.create(pixels)

# create the image with additional optional settings
image = PNM.create(pixels, maxgray: 30, comment: "Test Image")

# 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")
image.write("test", add_extension: true)  # adds the appropriate file extension

# use ASCII or "plain" format (default is :binary)
image.write("test.pgm", encoding: :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:

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

Check equality of two images:

color_image == image  # => false

Installation

To install PNM, you can either

• use gem install pnm to install from RubyGems.org,

• 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's current version has been tested with

  • Ruby 3.3, 3.2, 3.1, 3.0,
  • Ruby 2.7, 2.6,
  • JRuby 9.4.5.0.

Documentation

Documentation should be available via ri PNM or can be found at www.rubydoc.info/gems/pnm/.

Reporting bugs

Report bugs on the PNM home page: https://github.com/stomar/pnm/

License

Copyright © 2013-2024 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. There is NO WARRANTY, to the extent permitted by law.