class MiniMagick::Image

Attributes

path[R]

@return [String] The location of the current working file

tempfile[R]

@return [Tempfile] The underlying temporary file

Public Class Methods

attribute(name, key = name.to_s) click to toggle source

@private @!macro [attach] attribute

@!attribute [r] $1
# File lib/mini_magick/image.rb, line 127
def self.attribute(name, key = name.to_s)
  define_method(name) do |*args|
    if args.any? && name != :resolution
      mogrify { |b| b.send(name, *args) }
    else
      @info[key, *args]
    end
  end
end
create(ext = nil, validate = MiniMagick.validate_on_create, &block) click to toggle source

Used to create a new Image object data-copy. Not used to “paint” or that kind of thing.

Takes an extension in a block and can be used to build a new Image object. Used by both {.open} and {.read} to create a new object. Ensures we have a good tempfile.

@param ext [String] Specify the extension you want to read it as @param validate [Boolean] If false, skips validation of the created

image. Defaults to true.

@yield [Tempfile] You can write bits to this object to create the new

Image

@return [MiniMagick::Image] The created image

# File lib/mini_magick/image.rb, line 114
def self.create(ext = nil, validate = MiniMagick.validate_on_create, &block)
  tempfile = MiniMagick::Utilities.tempfile(ext.to_s.downcase, &block)

  new(tempfile.path, tempfile).tap do |image|
    image.validate! if validate
  end
end
import_pixels(blob, columns, rows, depth, map, format = 'png') click to toggle source

Creates an image object from a binary string blob which contains raw pixel data (i.e. no header data).

@param blob [String] Binary string blob containing raw pixel data. @param columns [Integer] Number of columns. @param rows [Integer] Number of rows. @param depth [Integer] Bit depth of the encoded pixel data. @param map [String] A code for the mapping of the pixel data. Example:

'gray' or 'rgb'.

@param format [String] The file extension of the image format to be

used when creating the image object.

Defaults to 'png'. @return [MiniMagick::Image] The loaded image.

# File lib/mini_magick/image.rb, line 52
def self.import_pixels(blob, columns, rows, depth, map, format = 'png')
  # Create an image object with the raw pixel data string:
  create(".dat", false) { |f| f.write(blob) }.tap do |image|
    output_path = image.path.sub(/\.\w+$/, ".#{format}")
    # Use ImageMagick to convert the raw data file to an image file of the
    # desired format:
    MiniMagick::Tool::Convert.new do |convert|
      convert.size "#{columns}x#{rows}"
      convert.depth depth
      convert << "#{map}:#{image.path}"
      convert << output_path
    end

    image.path.replace output_path
  end
end
new(input_path, tempfile = nil, &block) click to toggle source

Create a new {MiniMagick::Image} object.

DANGER: The file location passed in here is the *working copy*. That is, it gets modified. You can either copy it yourself or use {.open} which creates a temporary file for you and protects your original.

@param input_path [String, Pathname] The location of an image file @yield [MiniMagick::Tool::Mogrify] If block is given, {#combine_options}

is called.
# File lib/mini_magick/image.rb, line 157
def initialize(input_path, tempfile = nil, &block)
  @path = input_path.to_s
  @tempfile = tempfile
  @info = MiniMagick::Image::Info.new(@path)

  combine_options(&block) if block
end
open(path_or_url, ext = nil, options = {}) click to toggle source

Opens a specific image file either on the local file system or at a URI. Use this if you don't want to overwrite the image file.

Extension is either guessed from the path or you can specify it as a second parameter.

@param path_or_url [String] Either a local file path or a URL that

open-uri can read

@param ext [String] Specify the extension you want to read it as @param options [Hash] Specify options for the open method @return [MiniMagick::Image] The loaded image

# File lib/mini_magick/image.rb, line 82
def self.open(path_or_url, ext = nil, options = {})
  options, ext = ext, nil if ext.is_a?(Hash)

  ext ||=
    if File.exist?(path_or_url)
      File.extname(path_or_url)
    else
      File.extname(URI(path_or_url).path)
    end

  ext.sub!(/:.*/, '') # hack for filenames or URLs that include a colon

  Kernel.open(path_or_url, "rb", options) do |file|
    read(file, ext)
  end
end
read(stream, ext = nil) click to toggle source

This is the primary loading method used by all of the other class methods.

Use this to pass in a stream object. Must respond to read(size) or be a binary string object (BLOBBBB)

Probably easier to use the {.open} method if you want to open a file or a URL.

@param stream [#read, String] Some kind of stream object that needs

to be read or is a binary String blob

@param ext [String] A manual extension to use for reading the file. Not

required, but if you are having issues, give this a try.

@return [MiniMagick::Image]

# File lib/mini_magick/image.rb, line 29
def self.read(stream, ext = nil)
  if stream.is_a?(String)
    stream = StringIO.new(stream)
  end

  create(ext) { |file| IO.copy_stream(stream, file) }
end

Public Instance Methods

==(other) click to toggle source
# File lib/mini_magick/image.rb, line 165
def ==(other)
  self.class == other.class && signature == other.signature
end
Also aliased as: eql?
[](value) click to toggle source

Use this method if you want to access raw Identify's format API.

@example

image["%w %h"]       #=> "250 450"
image["%r"]          #=> "DirectClass sRGB"

@param value [String] @see www.imagemagick.org/script/escape.php @return [String]

# File lib/mini_magick/image.rb, line 299
def [](value)
  @info[value.to_s]
end
Also aliased as: info
collapse!(frame = 0) click to toggle source

Collapse images with sequences to the first frame (i.e. animated gifs) and preserve quality.

@param frame [Integer] The frame to which to collapse to, defaults to `0`. @return [self]

# File lib/mini_magick/image.rb, line 521
def collapse!(frame = 0)
  mogrify(frame) { |builder| builder.quality(100) }
end
colorspace() click to toggle source

@return [String]

# File lib/mini_magick/image.rb, line 248
attribute :colorspace
combine_options(&block) click to toggle source

You can use multiple commands together using this method. Very easy to use!

@example

image.combine_options do |c|
  c.draw "image Over 0,0 10,10 '#{MINUS_IMAGE_PATH}'"
  c.thumbnail "300x500>"
  c.background "blue"
end

@yield [MiniMagick::Tool::Mogrify] @see www.imagemagick.org/script/mogrify.php @return [self]

# File lib/mini_magick/image.rb, line 443
def combine_options(&block)
  mogrify(&block)
end
composite(other_image, output_extension = type.downcase, mask = nil) { |composite| ... } click to toggle source

@example

first_image = MiniMagick::Image.open "first.jpg"
second_image = MiniMagick::Image.open "second.jpg"
result = first_image.composite(second_image) do |c|
  c.compose "Over" # OverCompositeOp
  c.geometry "+20+20" # copy second_image onto first_image from (20, 20)
end
result.write "output.jpg"

@see www.imagemagick.org/script/composite.php

# File lib/mini_magick/image.rb, line 500
def composite(other_image, output_extension = type.downcase, mask = nil)
  output_tempfile = MiniMagick::Utilities.tempfile(".#{output_extension}")

  MiniMagick::Tool::Composite.new do |composite|
    yield composite if block_given?
    composite << other_image.path
    composite << path
    composite << mask.path if mask
    composite << output_tempfile.path
  end

  Image.new(output_tempfile.path, output_tempfile)
end
data() click to toggle source

Returns the information from `identify -verbose` in a Hash format, for ImageMagick.

@return [Hash]

# File lib/mini_magick/image.rb, line 280
attribute :data
destroy!() click to toggle source

Destroys the tempfile (created by {.open}) if it exists.

# File lib/mini_magick/image.rb, line 528
def destroy!
  if @tempfile
    FileUtils.rm_f @tempfile.path.sub(/mpc$/, "cache") if @tempfile.path.end_with?(".mpc")
    @tempfile.unlink
  end
end
details() click to toggle source

Returns the information from `identify -verbose` in a Hash format, for GraphicsMagick.

@return [Hash]

# File lib/mini_magick/image.rb, line 286
attribute :details
dimensions() click to toggle source

@return [Array<Integer>]

# File lib/mini_magick/image.rb, line 232
attribute :dimensions
eql?(other)
Alias for: ==
exif() click to toggle source

@return [Hash]

# File lib/mini_magick/image.rb, line 252
attribute :exif
format(format, page = 0, read_opts={}) { |convert| ... } click to toggle source

This is used to change the format of the image. That is, from “tiff to jpg” or something like that. Once you run it, the instance is pointing to a new file with a new extension!

DANGER: This renames the file that the instance is pointing to. So, if you manually opened the file with ::new… Then that file is DELETED! If you used ::open then you are OK. The original file will still be there. But, any changes to it might not be…

Formatting an animation into a non-animated type will result in ImageMagick creating multiple pages (starting with 0). You can choose which page you want to manipulate. We default to the first page.

If you would like to convert between animated formats, pass nil as your page and ImageMagick will copy all of the pages.

@param format [String] The target format… Like 'jpg', 'gif', 'tiff' etc. @param page [Integer] If this is an animated gif, say which 'page' you

want with an integer. Default 0 will convert only the first page; 'nil'
will convert all pages.

@param read_opts [Hash] Any read options to be passed to ImageMagick

for example: image.format('jpg', page, {density: '300'})

@yield [MiniMagick::Tool::Convert] It optionally yields the command,

if you want to add something.

@return [self]

# File lib/mini_magick/image.rb, line 395
def format(format, page = 0, read_opts={})
  if @tempfile
    new_tempfile = MiniMagick::Utilities.tempfile(".#{format}")
    new_path = new_tempfile.path
  else
    new_path = Pathname(path).sub_ext(".#{format}").to_s
  end

  input_path = path.dup
  input_path << "[#{page}]" if page && !layer?

  MiniMagick::Tool::Convert.new do |convert|
    read_opts.each do |opt, val|
      convert.send(opt.to_s, val)
    end
    convert << input_path
    yield convert if block_given?
    convert << new_path
  end

  if @tempfile
    destroy!
    @tempfile = new_tempfile
  else
    File.delete(path) unless path == new_path || layer?
  end

  path.replace new_path
  @info.clear

  self
end
frames()
Alias for: layers
get_pixels() click to toggle source

Returns a matrix of pixels from the image. The matrix is constructed as an array (1) of arrays (2) of arrays (3) of unsigned integers:

1) one for each row of pixels 2) one for each column of pixels 3) three elements in the range 0-255, one for each of the RGB color channels

@example

img = MiniMagick::Image.open 'image.jpg'
pixels = img.get_pixels
pixels[3][2][1] # the green channel value from the 4th-row, 3rd-column pixel

It can also be called after applying transformations:

@example

img = MiniMagick::Image.open 'image.jpg'
img.crop '20x30+10+5'
img.colorspace 'Gray'
pixels = img.get_pixels

In this example, all pixels in pix should now have equal R, G, and B values.

@return [Array] Matrix of each color of each pixel

# File lib/mini_magick/image.rb, line 348
def get_pixels
  convert = MiniMagick::Tool::Convert.new
  convert << path
  convert.depth(8)
  convert << "RGB:-"

  # Do not use `convert.call` here. We need the whole binary (unstripped) output here.
  shell = MiniMagick::Shell.new
  output, * = shell.run(convert.command)

  pixels_array = output.unpack("C*")
  pixels = pixels_array.each_slice(3).each_slice(width).to_a

  # deallocate large intermediary objects
  output.clear
  pixels_array.clear

  pixels
end
hash() click to toggle source
# File lib/mini_magick/image.rb, line 170
def hash
  signature.hash
end
height() click to toggle source

@return [Integer]

# File lib/mini_magick/image.rb, line 228
attribute :height
human_size() click to toggle source

Returns the file size in a human readable format.

@return [String]

# File lib/mini_magick/image.rb, line 244
attribute :human_size
identify() { |builder| ... } click to toggle source

Runs `identify` on itself. Accepts an optional block for adding more options to `identify`.

@example

image = MiniMagick::Image.open("image.jpg")
image.identify do |b|
  b.verbose
end # runs `identify -verbose image.jpg`

@return [String] Output from `identify` @yield [MiniMagick::Tool::Identify]

# File lib/mini_magick/image.rb, line 547
def identify
  MiniMagick::Tool::Identify.new do |builder|
    yield builder if block_given?
    builder << path
  end
end
info(value)
Alias for: []
layer?() click to toggle source
# File lib/mini_magick/image.rb, line 574
def layer?
  path =~ /\[\d+\]$/
end
layers() click to toggle source

Returns layers of the image. For example, JPEGs are 1-layered, but formats like PSDs, GIFs and PDFs can have multiple layers/frames/pages.

@example

image = MiniMagick::Image.new("document.pdf")
image.pages.each_with_index do |page, idx|
  page.write("page#{idx}.pdf")
end

@return [Array<MiniMagick::Image>]

# File lib/mini_magick/image.rb, line 315
def layers
  layers_count = identify.lines.count
  layers_count.times.map do |idx|
    MiniMagick::Image.new("#{path}[#{idx}]")
  end
end
Also aliased as: pages, frames
method_missing(name, *args) click to toggle source

If an unknown method is called then it is sent through the mogrify program.

@see www.imagemagick.org/script/mogrify.php @return [self]

# File lib/mini_magick/image.rb, line 454
def method_missing(name, *args)
  mogrify do |builder|
    builder.send(name, *args)
  end
end
mime_type() click to toggle source

@return [String]

# File lib/mini_magick/image.rb, line 220
attribute :mime_type
mogrify(page = nil) { |builder| ... } click to toggle source
# File lib/mini_magick/image.rb, line 563
def mogrify(page = nil)
  MiniMagick::Tool::MogrifyRestricted.new do |builder|
    yield builder if block_given?
    builder << (page ? "#{path}[#{page}]" : path)
  end

  @info.clear

  self
end
pages()
Alias for: layers
resolution() click to toggle source

Returns the resolution of the photo. You can optionally specify the units measurement.

@example

image.resolution("PixelsPerInch") #=> [250, 250]

@see www.imagemagick.org/script/command-line-options.php#units @return [Array<Integer>]

# File lib/mini_magick/image.rb, line 262
attribute :resolution
respond_to_missing?(method_name, include_private = false) click to toggle source
# File lib/mini_magick/image.rb, line 460
def respond_to_missing?(method_name, include_private = false)
  MiniMagick::Tool::Mogrify.option_methods.include?(method_name.to_s)
end
run_command(tool_name, *args) click to toggle source

@private

# File lib/mini_magick/image.rb, line 555
def run_command(tool_name, *args)
  MiniMagick::Tool.const_get(tool_name.capitalize).new do |builder|
    args.each do |arg|
      builder << arg
    end
  end
end
signature() click to toggle source

Returns the message digest of this image as a SHA-256, hexidecimal encoded string. This signature uniquely identifies the image and is convenient for determining if an image has been modified or whether two images are identical.

@example

image.signature #=> "60a7848c4ca6e36b8e2c5dea632ecdc29e9637791d2c59ebf7a54c0c6a74ef7e"

@see www.imagemagick.org/api/signature.php @return [String]

# File lib/mini_magick/image.rb, line 274
attribute :signature
size() click to toggle source

Returns the file size of the image (in bytes).

@return [Integer]

# File lib/mini_magick/image.rb, line 238
attribute :size
to_blob() click to toggle source

Returns raw image data.

@return [String] Binary string

# File lib/mini_magick/image.rb, line 179
def to_blob
  File.binread(path)
end
type() click to toggle source

Returns the image format (e.g. “JPEG”, “GIF”).

@return [String]

# File lib/mini_magick/image.rb, line 216
attribute :type, "format"
valid?() click to toggle source

Checks to make sure that MiniMagick can read the file and understand it.

This uses the 'identify' command line utility to check the file. If you are having issues with this, then please work directly with the 'identify' command and see if you can figure out what the issue is.

@return [Boolean]

# File lib/mini_magick/image.rb, line 192
def valid?
  validate!
  true
rescue MiniMagick::Invalid
  false
end
validate!() click to toggle source

Runs `identify` on the current image, and raises an error if it doesn't pass.

@raise [MiniMagick::Invalid]

# File lib/mini_magick/image.rb, line 205
def validate!
  identify
rescue MiniMagick::Error => error
  raise MiniMagick::Invalid, error.message
end
width() click to toggle source

@return [Integer]

# File lib/mini_magick/image.rb, line 224
attribute :width
write(output_to) click to toggle source

Writes the temporary file out to either a file location (by passing in a String) or by passing in a Stream that you can write(chunk) to repeatedly

@param output_to [String, Pathname, read] Some kind of stream object

that needs to be read or a file path as a String
# File lib/mini_magick/image.rb, line 472
def write(output_to)
  case output_to
  when String, Pathname
    if layer?
      MiniMagick::Tool::Convert.new do |builder|
        builder << path
        builder << output_to
      end
    else
      FileUtils.copy_file path, output_to unless path == output_to.to_s
    end
  else
    IO.copy_stream File.open(path, "rb"), output_to
  end
end