class MiniMagick::Image
Attributes
@return [String] The location of the current working file
@return [Tempfile] The underlying temporary file
Public Class Methods
@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
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
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
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
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
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
# File lib/mini_magick/image.rb, line 165 def ==(other) self.class == other.class && signature == other.signature end
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
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
@return [String]
# File lib/mini_magick/image.rb, line 248 attribute :colorspace
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
@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
Returns the information from `identify -verbose` in a Hash format, for ImageMagick.
@return [Hash]
# File lib/mini_magick/image.rb, line 280 attribute :data
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
Returns the information from `identify -verbose` in a Hash format, for GraphicsMagick.
@return [Hash]
# File lib/mini_magick/image.rb, line 286 attribute :details
@return [Array<Integer>]
# File lib/mini_magick/image.rb, line 232 attribute :dimensions
@return [Hash]
# File lib/mini_magick/image.rb, line 252 attribute :exif
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
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
# File lib/mini_magick/image.rb, line 170 def hash signature.hash end
@return [Integer]
# File lib/mini_magick/image.rb, line 228 attribute :height
Returns the file size in a human readable format.
@return [String]
# File lib/mini_magick/image.rb, line 244 attribute :human_size
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
# File lib/mini_magick/image.rb, line 574 def layer? path =~ /\[\d+\]$/ end
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
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
@return [String]
# File lib/mini_magick/image.rb, line 220 attribute :mime_type
# 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
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
# 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
@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
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
Returns the file size of the image (in bytes).
@return [Integer]
# File lib/mini_magick/image.rb, line 238 attribute :size
Returns raw image data.
@return [String] Binary string
# File lib/mini_magick/image.rb, line 179 def to_blob File.binread(path) end
Returns the image format (e.g. “JPEG”, “GIF”).
@return [String]
# File lib/mini_magick/image.rb, line 216 attribute :type, "format"
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
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
@return [Integer]
# File lib/mini_magick/image.rb, line 224 attribute :width
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