Module: ChunkyPNG::Canvas::Masking

Included in:
ChunkyPNG::Canvas
Defined in:
lib/chunky_png/canvas/masking.rb

Overview

The ChunkyPNG::Canvas::Masking module defines methods to perform masking and theming operations on a ChunkyPNG::Canvas. The module is included into the Canvas class so all these methods are available on every canvas.

See Also:

Instance Method Summary collapse

Instance Method Details

#change_mask_color!(new_color) ⇒ Object

Changes the color of a mask image.

This method works on a canvas extracted out of another image using the #extract_mask method. It can then be applied on the extracted base image. See #change_theme_color! to perform these operations in one go.

Parameters:

  • new_color (Integer) —

    The color to replace the original mask color with.

Raises:

  • (ChunkyPNG::ExpectationFailed) —

    when this canvas is not a mask image, i.e. its palette has more than once color, disregarding transparency.

See Also:



84
85
86
87
88
 
# File 'lib/chunky_png/canvas/masking.rb', line 84

def change_mask_color!(new_color)
  raise ChunkyPNG::ExpectationFailed, "This is not a mask image!" if palette.opaque_palette.size != 1
  pixels.map! { |pixel| (new_color & 0xffffff00) | ChunkyPNG::Color.a(pixel) }
  self
end

#change_theme_color!(old_theme_color, new_theme_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5) ⇒ ChunkyPNG::Canvas

Creates a new image, based on the current image but with a new theme color.

This method will replace one color in an image with another image. This is done by first extracting the pixels with a color close to the original theme color as a mask image, changing the color of this mask image and then apply it on the original image.

Mask extraction works best when the theme colored pixels are clearly distinguishable from a background color (preferably white). You can set a tolerance level to influence the extraction process.

Parameters:

  • old_theme_color (Integer) —

    The original theme color in this image.

  • new_theme_color (Integer) —

    The color to replace the old theme color with.

  • bg_color (Integer) (defaults to: ChunkyPNG::Color::WHITE) —

    The background color on which the theme colored pixels are placed.

  • tolerance (Integer) (defaults to: 5) —

    The tolerance level to use when extracting the mask image. Five is the default; increase this if the masked image does not extract all the required pixels, decrease it if too many pixels get extracted.

Returns:

See Also:



30
31
32
33
34
 
# File 'lib/chunky_png/canvas/masking.rb', line 30

def change_theme_color!(old_theme_color, new_theme_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5)
  base, mask = extract_mask(old_theme_color, bg_color, tolerance)
  mask.change_mask_color!(new_theme_color)
  self.replace!(base.compose!(mask))
end

#extract_mask(mask_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5) ⇒ Array<ChunkyPNG::Canvas, ChunkyPNG::Canvas>

Creates a base image and a mask image from an original image that has a particular theme color. This can be used to easily change a theme color in an image.

It will extract all the pixels that look like the theme color (with a tolerance level) and put these in a mask image. All the other pixels will be stored in a base image. Both images will be of the exact same size as the original image. The original image will be left untouched.

The color of the mask image can be changed with #change_mask_color!. This new mask image can then be composed upon the base image to create an image with a new theme color. A call to #change_theme_color! will perform this in one go.

Parameters:

  • mask_color (Integer) —

    The current theme color.

  • bg_color (Integer) (defaults to: ChunkyPNG::Color::WHITE) —

    The background color on which the theme colored pixels are applied.

  • tolerance (Integer) (defaults to: 5) —

    The tolerance level to use when extracting the mask image. Five is the default; increase this if the masked image does not extract all the required pixels, decrease it if too many pixels get extracted.

Returns:

See Also:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/chunky_png/canvas/masking.rb', line 56

def extract_mask(mask_color, bg_color = ChunkyPNG::Color::WHITE, tolerance = 5)
  base_pixels = []
  mask_pixels = []

  pixels.each do |pixel|
    if ChunkyPNG::Color.alpha_decomposable?(pixel, mask_color, bg_color, tolerance)
      mask_pixels << ChunkyPNG::Color.decompose_color(pixel, mask_color, bg_color, tolerance)
      base_pixels << bg_color
    else
      mask_pixels << (mask_color & 0xffffff00)
      base_pixels << pixel
    end
  end
  
  [ self.class.new(width, height, base_pixels), self.class.new(width, height, mask_pixels) ]
end