Module: Pixels

Defined in:

lib/pixels.rb

Overview

Ruby Pixels allows you to read and write RGB/RGBA pixel data stored in uncompressed, non-interleaved TGA (Targa) files.

Unlike some other libraries, Ruby Pixels reads and writes one row of pixels at a time, you can work with several large images at once without running out of memory.

Requirements

Ruby Pixels needs no external libraries.

Limitations

Ruby Pixels cannot read or write compressed, interleaved, or colour-mapped images. You may wish to use another tool (e.g. MiniMagick) to convert to and from other formats.

Ruby Pixels currently has no support for reading or writing individual pixels. You need to do it on a row-by-row basis.

Example Code

# invert-image.rb - Invert the colour of an image.
require 'pixels'

input = Pixels.open_tga("mm/mm-01.tga")
output = Pixels.create_tga("output.tga", input.spec)

input.each_row_rgb do |in_row, y|
  out_row = []
  for r, g, b in in_row
    out_row << [255-r, 255-g, 255-b]
  end
  output.put_row_rgb(y, out_row)
end

output.close
input.close

Defined Under Namespace

Modules: HasAlphaChannel, NoAlphaChannel Classes: DataFormatError, Targa15, Targa16, Targa24, Targa32, TargaBase

Constant Summary

VERSION =

'0.0.1'

Class Method Summary

• .create_tga(file_or_path, spec = {}) ⇒ Object

  Create a TGA file according to the given specification, and return an instance of one of TargaBase’s children (one of Targa15, Targa16, Targa24, or Targa32), depending on the format specification.

• .decode_tga_header(raw_header) ⇒ Object

  :nodoc:.

• .open_tga(file_or_path) ⇒ Object

  Open the specified TGA file.

Class Method Details

.create_tga(file_or_path, spec = {}) ⇒ Object

Create a TGA file according to the given specification, and return an instance of one of TargaBase’s children (one of Targa15, Targa16, Targa24, or Targa32), depending on the format specification.

file_or_path may be a pathname or a file-like object. If it is a pathname, it is opened for reading.

spec is a Hash containing the following keys:

:width

Width of the image in pixels

:height

Height of the image in pixels

:color_depth

Color depth of the image in bits per pixel. This does not include the bits used to represent the alpha channel (if any).

Currently, this is always one of [15, 24].

:has_alpha

If the image has an alpha channel, this is true. Otherwise, it is false. (default false)

:origin

Specifies which pixel appears first in the TGA file. Must be one of :UPPER_LEFT or :LOWER_LEFT.

Note: This only affects the TGA file’s internal layout. get_row_rgb(0) always returns the uppermost row in Ruby Pixels. (default :UPPER_LEFT)

# File 'lib/pixels.rb', line 144

def self.create_tga(file_or_path, spec={})
  spec = {
    :width => nil,
    :height => nil,
    :color_depth => nil,
    :has_alpha => false,
    :origin => :UPPER_LEFT,
  }.merge(spec)

  case [spec[:color_depth], !!spec[:has_alpha]]
  when [15, true]
    bpp = 16
    alpha_depth = 1
  when [16, false]
    bpp = 16
    alpha_depth = 0
  when [24, false]
    bpp = 24
    alpha_depth = 0
  when [24, true]
    bpp = 32
    alpha_depth = 8
  else
    raise ArgumentError.new(
      ":depth=#{colour_depth}-bpp with :alpha=#{has_alpha} not supported")
  end

  image_descriptor = alpha_depth
  case spec[:origin]
  when :LOWER_LEFT
    # Do nothing
  when :UPPER_LEFT
    image_descriptor |= 0x20
  else
    raise ArgumentError.new(":origin must be :LOWER_LEFT or :UPPER_LEFT")
  end

  raw_header = [
    0,    # idlength
    0,    # colourmap type
    2,    # data type: Uncompressed RGB(A)
    0,    # colourmap_origin
    0,    # colourmap_length
    0,    # colourmap_depth
    0,    # x_origin
    0,    # y_origin
    spec[:width],
    spec[:height],
    bpp,
    image_descriptor,
  ].pack("CCCvvCvvvvCC")

  h, r = decode_tga_header(raw_header)

  if file_or_path.respond_to?(:write)
    file = file_or_path
  else
    file = File.open(file_or_path, "w+b:binary")
  end

  file.write(raw_header)
  file.seek(0, IO::SEEK_SET)
  return open_tga(file)
end

.decode_tga_header(raw_header) ⇒ Object

:nodoc:

# File 'lib/pixels.rb', line 209

def self.decode_tga_header(raw_header)  #:nodoc:
  h = {}
  h[:idlength], h[:colourmap_type], h[:data_type_code], h[:colourmap_origin],
  h[:colourmap_length], h[:colourmap_depth], h[:x_origin], h[:y_origin],
  h[:width], h[:height], h[:bits_per_pixel], h[:image_descriptor] =
    raw_header.unpack("CCCvvCvvvvCC")

  # Data type
  if h[:data_type_code] != 2
    raise DataFormatError.new(
      "Only uncompressed, unmapped RGB or RGBA data is supported (is this a TGA file?)")
  end

  r = {}
  r[:width] = h[:width]
  r[:height] = h[:height]
  r[:image_data_offset] = 18 + h[:idlength] + h[:colourmap_length]

  r[:bpp] = h[:bits_per_pixel]
  r[:alpha_depth] = h[:image_descriptor] & 0xf
  r[:color_depth] = h[:bits_per_pixel] - r[:alpha_depth]
  r[:origin] = (h[:image_descriptor] & 0x20 != 0) ? :UPPER_LEFT : :LOWER_LEFT

  # Interleaving
  if (h[:image_descriptor] & 0xc0) != 0
    raise DataFormatError.new("Interleaved data not supported")
  end

  return [h, r]
end

.open_tga(file_or_path) ⇒ Object

Open the specified TGA file.

file_or_path may be a pathname or a file-like object. If it is a pathname, it is opened for reading.

Returns an instance of one of TargaBase’s children (one of Targa15, Targa16, Targa24, or Targa32), depending on the format of the specified file.

# File 'lib/pixels.rb', line 87

def self.open_tga(file_or_path)
  if file_or_path.respond_to?(:read)
    file = file_or_path
  else
    file = File.open(file_or_path, "rb:binary")
  end

  raw_header = file.read(18)
  h, r = decode_tga_header(raw_header)
  case [h[:bits_per_pixel], r[:alpha_depth]]
  when [16, 0]
    return Targa15.new(file, h, r, 2)
  when [16, 1]
    return Targa16.new(file, h, r, 2)
  when [24, 0]
    return Targa24.new(file, h, r, 3)
  when [32, 0]
    return Targa24.new(file, h, r, 4)
  when [32, 8]
    return Targa32.new(file, h, r, 4)
  else
    raise DataFormatError.new(
      "#{h[:bits_per_pixel]} bpp with #{h[:alpha_depth]}-bit alpha channel not supported")
  end
end