Module: ChunkyPNG::Canvas::Masking

### Home Classes Methods

### In Files

- lib/chunky_png/canvas/masking.rb

### Methods

- #change_mask_color!
- #change_theme_color!
- #extract_mask

### Files

- BENCHMARKING.rdoc
- CHANGELOG.rdoc
- CONTRIBUTING.rdoc
- README.rdoc

### Class/Module Index

Quicksearch

- ChunkyPNG
- ChunkyPNG::CRCMismatch
- ChunkyPNG::Canvas
- ChunkyPNG::Canvas::Adam7Interlacing
- ChunkyPNG::Canvas::DataUrlExporting
- ChunkyPNG::Canvas::DataUrlImporting
- ChunkyPNG::Canvas::Drawing
- ChunkyPNG::Canvas::Masking
- ChunkyPNG::Canvas::Operations
- ChunkyPNG::Canvas::PNGDecoding
- ChunkyPNG::Canvas::PNGEncoding
- ChunkyPNG::Canvas::Resampling
- ChunkyPNG::Canvas::StreamExporting
- ChunkyPNG::Canvas::StreamImporting
- ChunkyPNG::Chunk
- ChunkyPNG::Chunk::Base
- ChunkyPNG::Chunk::CompressedText
- ChunkyPNG::Chunk::End
- ChunkyPNG::Chunk::Generic
- ChunkyPNG::Chunk::Header
- ChunkyPNG::Chunk::ImageData
- ChunkyPNG::Chunk::InternationalText
- ChunkyPNG::Chunk::Palette
- ChunkyPNG::Chunk::Text
- ChunkyPNG::Chunk::Transparency
- ChunkyPNG::Color
- ChunkyPNG::Datastream
- ChunkyPNG::Dimension
- ChunkyPNG::Exception
- ChunkyPNG::ExpectationFailed
- ChunkyPNG::Image
- ChunkyPNG::NotSupported
- ChunkyPNG::OutOfBounds
- ChunkyPNG::Palette
- ChunkyPNG::Point
- ChunkyPNG::RMagick
- ChunkyPNG::SignatureMismatch
- ChunkyPNG::Vector
- Enumerable
- String

No matching classes.

# ChunkyPNG::Canvas::Masking

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 ChunkyPNG::Canvas

### Public Instance Methods

change_mask_color!(new_color) click to toggle source

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.

@param [Integer] new_color The color to replace the original mask color with. @raise [ChunkyPNG::ExpectationFailed] when this canvas is not a mask image, i.e. its palette

    has more than once color, disregarding transparency.

@see change_theme_color! @see extract_mask

    # 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) click to toggle source

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.

@param [Integer] old_theme_color The original theme color in this image. @param [Integer] new_theme_color The color to replace the old theme color with. @param [Integer] bg_color The background color on which the theme colored pixels are placed. @param [Integer] tolerance 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.

@return [ChunkyPNG::Canvas] Returns itself, but with the theme colored pixels changed. @see change_theme_color! @see change_mask_color!

    # 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) click to toggle source

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.

@param [Integer] mask_color The current theme color. @param [Integer] bg_color The background color on which the theme colored pixels are applied. @param [Integer] tolerance 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.

@return [Array<ChunkyPNG::Canvas, ChunkyPNG::Canvas>] An array with the base canvas and the mask

    canvas as elements.

@see change_theme_color! @see change_mask_color!

    # 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.