Class: ChunkyPNG::Palette

### Home Classes Methods

### In Files

- lib/chunky_png/palette.rb

### Parent

SortedSet

### Methods

- ::from_canvas
- ::from_chunks
- ::from_pixels
- ::new
- #[]
- #best_color_settings
- #black_and_white?
- #can_decode?
- #can_encode?
- #determine_bit_depth
- #grayscale?
- #index
- #indexable?
- #opaque?
- #opaque_palette
- #to_plte_chunk
- #to_trns_chunk

### 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::Palette

A palette describes the set of colors that is being used for an image.

A PNG image can contain an explicit palette which defines the colors of that image, but can also use an implicit palette, e.g. all truecolor colors or all grayscale colors.

This palette supports decoding colors from a palette if an explicit palette is provided in a PNG datastream, and it supports encoding colors to an explicit palette (stores as PLTE & tRNS chunks in a PNG file).

@see ChunkyPNG::Color

### Public Class Methods

from_canvas(canvas) click to toggle source

Builds a palette instance from a given canvas. @param canvas [ChunkyPNG::Canvas] The canvas to create a palette for. @return [ChunkyPNG::Palette] The palette instance.

    # File lib/chunky_png/palette.rb, line 63
    def self.from_canvas(canvas)
      # Although we don't need to call .uniq.sort before initializing, because
      # Palette subclasses SortedSet, we get significantly better performance
      # by doing so.
      new(canvas.pixels.uniq.sort)
    end

from_chunks(palette_chunk, transparency_chunk = nil) click to toggle source

Builds a palette instance from a PLTE chunk and optionally a tRNS chunk from a PNG datastream.

This method will cerate a palette that is suitable for decoding an image.

@param palette_chunk [ChunkyPNG::Chunk::Palette] The palette chunk to

    load from

@param transparency_chunk [ChunkyPNG::Chunk::Transparency, nil] The

    optional transparency chunk.

@return [ChunkyPNG::Palette] The loaded palette instance. @see ChunkyPNG::Palette#can_decode?

    # File lib/chunky_png/palette.rb, line 37
    def self.from_chunks(palette_chunk, transparency_chunk = nil)
      return nil if palette_chunk.nil?

      decoding_map = []
      index = 0

      palatte_bytes = palette_chunk.content.unpack('C*')
      if transparency_chunk
        alpha_channel = transparency_chunk.content.unpack('C*')
      else
        alpha_channel = []
      end

      index = 0
      palatte_bytes.each_slice(3) do |bytes|
        bytes << alpha_channel.fetch(index, ChunkyPNG::Color::MAX)
        decoding_map << ChunkyPNG::Color.rgba(*bytes)
        index += 1
      end

      new(decoding_map, decoding_map)
    end

from_pixels(pixels) click to toggle source

Builds a palette instance from a given set of pixels. @param pixels [Enumerable<Integer>] An enumeration of pixels to create a

    palette for

@return [ChunkyPNG::Palette] The palette instance.

    # File lib/chunky_png/palette.rb, line 74
    def self.from_pixels(pixels)
      new(pixels)
    end

new(enum, decoding_map = nil) click to toggle source

Builds a new palette given a set (Enumerable instance) of colors.

@param enum [Enumerable<Integer>] The set of colors to include in this

    palette.This Enumerable can contain duplicates.

@param decoding_map [Array] An array of colors in the exact order at

    which they appeared in the palette chunk, so that this array can be
    used for decoding.

    # File lib/chunky_png/palette.rb, line 21
    def initialize(enum, decoding_map = nil)
      super(enum)
      @decoding_map = decoding_map if decoding_map
    end

### Public Instance Methods

[](index) click to toggle source

Returns a color, given the position in the original palette chunk. @param index [Integer] The 0-based position of the color in the palette. @return [ChunkyPNG::Color] The color that is stored in the palette under

    the given index

@see ChunkyPNG::Palette#can_decode?

    # File lib/chunky_png/palette.rb, line 148
    def [](index)
      @decoding_map[index]
    end

best_color_settings() click to toggle source

Determines the most suitable colormode for this palette. @return [Integer] The colormode which would create the smallest possible

    file for images that use this exact palette.

    # File lib/chunky_png/palette.rb, line 195
    def best_color_settings
      if black_and_white?
        [ChunkyPNG::COLOR_GRAYSCALE, 1]
      elsif grayscale?
        if opaque?
          [ChunkyPNG::COLOR_GRAYSCALE, 8]
        else
          [ChunkyPNG::COLOR_GRAYSCALE_ALPHA, 8]
        end
      elsif indexable?
        [ChunkyPNG::COLOR_INDEXED, determine_bit_depth]
      elsif opaque?
        [ChunkyPNG::COLOR_TRUECOLOR, 8]
      else
        [ChunkyPNG::COLOR_TRUECOLOR_ALPHA, 8]
      end
    end

black_and_white?() click to toggle source

Check whether this palette only contains bacl and white. @return [true, false] True if all colors in this palette are grayscale

    teints.

@see ChunkyPNG::Color#grayscale??

    # File lib/chunky_png/palette.rb, line 104
    def black_and_white?
      entries == [ChunkyPNG::Color::BLACK, ChunkyPNG::Color::WHITE]
    end

can_decode?() click to toggle source

Checks whether this palette is suitable for decoding an image from a datastream.

This requires that the positions of the colors in the original palette chunk is known, which is stored as an array in the +@decoding_map+ instance variable.

@return [true, false] True if a decoding map was built when this palette

    was loaded.

    # File lib/chunky_png/palette.rb, line 126
    def can_decode?
      !@decoding_map.nil?
    end

can_encode?() click to toggle source

Checks whether this palette is suitable for encoding an image from to datastream.

This requires that the position of the color in the future palette chunk is known, which is stored as a hash in the +@encoding_map+ instance variable.

@return [true, false] True if a encoding map was built when this palette

    was loaded.

    # File lib/chunky_png/palette.rb, line 139
    def can_encode?
      !@encoding_map.nil?
    end

determine_bit_depth() click to toggle source

Determines the minimal bit depth required for an indexed image @return [Integer] Number of bits per pixel, i.e. 1, 2, 4 or 8, or nil if

    this image cannot be saved as an indexed image.

    # File lib/chunky_png/palette.rb, line 216
    def determine_bit_depth
      case size
      when 1..2 then 1
      when 3..4 then 2
      when 5..16 then 4
      when 17..256 then 8
      else nil
      end
    end

grayscale?() click to toggle source

Check whether this palette only contains grayscale colors. @return [true, false] True if all colors in this palette are grayscale

    teints.

@see ChunkyPNG::Color#grayscale??

    # File lib/chunky_png/palette.rb, line 96
    def grayscale?
      all? { |color| Color.grayscale?(color) }
    end

index(color) click to toggle source

Returns the position of a color in the palette @param color [ChunkyPNG::Color] The color for which to look up the index. @return [Integer] The 0-based position of the color in the palette. @see ChunkyPNG::Palette#can_encode?

    # File lib/chunky_png/palette.rb, line 156
    def index(color)
      color.nil? ? 0 : @encoding_map[color]
    end

indexable?() click to toggle source

Checks whether the size of this palette is suitable for indexed storage. @return [true, false] True if the number of colors in this palette is at

    most 256.

    # File lib/chunky_png/palette.rb, line 81
    def indexable?
      size <= 256
    end

opaque?() click to toggle source

Check whether this palette only contains opaque colors. @return [true, false] True if all colors in this palette are opaque. @see ChunkyPNG::Color#opaque?

    # File lib/chunky_png/palette.rb, line 88
    def opaque?
      all? { |color| Color.opaque?(color) }
    end

opaque_palette() click to toggle source

Returns a palette with all the opaque variants of the colors in this palette. @return [ChunkyPNG::Palette] A new Palette instance with only opaque

    colors.

@see ChunkyPNG::Color#opaque!

    # File lib/chunky_png/palette.rb, line 113
    def opaque_palette
      self.class.new(map { |c| ChunkyPNG::Color.opaque!(c) })
    end

to_plte_chunk() click to toggle source

Creates a PLTE chunk that corresponds with this palette to store the r, g, and b channels of all colors.

@note A PLTE chunk should only be included if the image is encoded using

    index colors. After this chunk has been built, the palette becomes
    suitable for encoding an image.

@return [ChunkyPNG::Chunk::Palette] The PLTE chunk. @see ChunkyPNG::Palette#can_encode?

    # File lib/chunky_png/palette.rb, line 180
    def to_plte_chunk
      @encoding_map = {}
      colors        = []

      each_with_index do |color, index|
        @encoding_map[color] = index
        colors += ChunkyPNG::Color.to_truecolor_bytes(color)
      end

      ChunkyPNG::Chunk::Palette.new('PLTE', colors.pack('C*'))
    end

to_trns_chunk() click to toggle source

Creates a tRNS chunk that corresponds with this palette to store the alpha channel of all colors.

Note that this chunk can be left out of every color in the palette is opaque, and the image is encoded using indexed colors.

@return [ChunkyPNG::Chunk::Transparency] The tRNS chunk.

    # File lib/chunky_png/palette.rb, line 167
    def to_trns_chunk
      ChunkyPNG::Chunk::Transparency.new('tRNS', map { |c| ChunkyPNG::Color.a(c) }.pack('C*'))
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.