Class: MiniMagick::Image

Inherits:
Object
  • Object
show all
Defined in:
lib/mini_magick/image.rb,
lib/mini_magick/image/info.rb

Defined Under Namespace

Classes: Info

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input_path, tempfile = nil) {|MiniMagick::Tool::Mogrify| ... } ⇒ Image

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.

Parameters:

  • input_path (String, Pathname) —

    The location of an image file

Yields:



170
171
172
173
174
175
176
 
# File 'lib/mini_magick/image.rb', line 170

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ self

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

Returns:

  • (self)

See Also:



495
496
497
498
499
 
# File 'lib/mini_magick/image.rb', line 495

def method_missing(name, *args)
  mogrify do |builder|
    builder.send(name, *args)
  end
end

Instance Attribute Details

#colorspace ⇒ String (readonly)

Returns:

  • (String) 


261
 
# File 'lib/mini_magick/image.rb', line 261

attribute :colorspace

#data ⇒ Hash (readonly)

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

Returns:

  • (Hash) 


293
 
# File 'lib/mini_magick/image.rb', line 293

attribute :data

#details ⇒ Hash (readonly)

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

Returns:

  • (Hash) 


299
 
# File 'lib/mini_magick/image.rb', line 299

attribute :details

#dimensions ⇒ Array<Integer> (readonly)

Returns:

  • (Array<Integer>) 


245
 
# File 'lib/mini_magick/image.rb', line 245

attribute :dimensions

#exif ⇒ Hash (readonly)

Returns:

  • (Hash) 


265
 
# File 'lib/mini_magick/image.rb', line 265

attribute :exif

#height ⇒ Integer (readonly)

Returns:

  • (Integer) 


241
 
# File 'lib/mini_magick/image.rb', line 241

attribute :height

#human_size ⇒ String (readonly)

Returns the file size in a human readable format.

Returns:

  • (String) 


257
 
# File 'lib/mini_magick/image.rb', line 257

attribute :human_size

#mime_type ⇒ String (readonly)

Returns:

  • (String) 


233
 
# File 'lib/mini_magick/image.rb', line 233

attribute :mime_type

#path ⇒ String (readonly)

Returns The location of the current working file.

Returns:

  • (String) —

    The location of the current working file



153
154
155
 
# File 'lib/mini_magick/image.rb', line 153

def path
  @path
end

#resolution ⇒ Array<Integer> (readonly)

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

Examples:

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

Returns:

  • (Array<Integer>)

See Also:



275
 
# File 'lib/mini_magick/image.rb', line 275

attribute :resolution

#signature ⇒ String (readonly)

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.

Examples:

image.signature #=> "60a7848c4ca6e36b8e2c5dea632ecdc29e9637791d2c59ebf7a54c0c6a74ef7e"

Returns:

  • (String)

See Also:



287
 
# File 'lib/mini_magick/image.rb', line 287

attribute :signature

#size ⇒ Integer (readonly)

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

Returns:

  • (Integer) 


251
 
# File 'lib/mini_magick/image.rb', line 251

attribute :size

#tempfile ⇒ Tempfile (readonly)

Returns The underlying temporary file.

Returns:

  • (Tempfile) —

    The underlying temporary file



157
158
159
 
# File 'lib/mini_magick/image.rb', line 157

def tempfile
  @tempfile
end

#type ⇒ String (readonly)

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

Returns:

  • (String) 


229
 
# File 'lib/mini_magick/image.rb', line 229

attribute :type, "format"

#width ⇒ Integer (readonly)

Returns:

  • (Integer) 


237
 
# File 'lib/mini_magick/image.rb', line 237

attribute :width

Class Method Details

.attribute(name, key = name.to_s) ⇒ Object 



140
141
142
143
144
145
146
147
148
 
# File 'lib/mini_magick/image.rb', line 140

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) {|Tempfile| ... } ⇒ MiniMagick::Image

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.

Parameters:

  • ext (String) (defaults to: nil) —

    Specify the extension you want to read it as

  • validate (Boolean) (defaults to: MiniMagick.validate_on_create) —

    If false, skips validation of the created image. Defaults to true.

Yields:

  • (Tempfile) —

    You can #write bits to this object to create the new Image

Returns:



127
128
129
130
131
132
133
 
# File 'lib/mini_magick/image.rb', line 127

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

.get_image_from_pixels(pixels, dimension, map, depth, mime_type) ⇒ Object

This is used to create image from pixels. This might be required if you create pixels for some image processing reasons and you want to form image from those pixels.

DANGER: This operation can be very expensive. Please try to use with caution.

Examples:

# It is given in readme.md file


400
401
402
403
404
 
# File 'lib/mini_magick/image.rb', line 400

def self.get_image_from_pixels(pixels, dimension, map, depth, mime_type)
  pixels = pixels.flatten
  blob = pixels.pack('C*')
  import_pixels(blob, *dimension, depth, map, mime_type)
end

.import_pixels(blob, columns, rows, depth, map, format = 'png') ⇒ MiniMagick::Image

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

Defaults to ‘png’.

Parameters:

  • blob (String) —

    Binary string blob containing raw pixel data.

  • columns (Integer) —

    Number of columns.

  • rows (Integer) —

    Number of rows.

  • depth (Integer) —

    Bit depth of the encoded pixel data.

  • map (String) —

    A code for the mapping of the pixel data. Example: ‘gray’ or ‘rgb’.

  • format (String) (defaults to: 'png') —

    The file extension of the image format to be used when creating the image object.

Returns:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# 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

.open(path_or_url, ext = nil, options = {}) ⇒ MiniMagick::Image

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.

Parameters:

  • path_or_url (String) —

    Either a local file path or a URL that open-uri can read

  • ext (String) (defaults to: nil) —

    Specify the extension you want to read it as

  • options (Hash) (defaults to: {}) —

    Specify options for the open method

Returns:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# 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)

  # Don't use Kernel#open, but reuse its logic
  openable =
    if path_or_url.respond_to?(:open)
      path_or_url
    elsif path_or_url.respond_to?(:to_str) &&
          %r{\A[A-Za-z][A-Za-z0-9+\-\.]*://} =~ path_or_url &&
          (uri = URI.parse(path_or_url)).respond_to?(:open)
      uri
    else
      options = { binmode: true }.merge(options)
      Pathname(path_or_url)
    end

  if openable.is_a?(URI::Generic)
    ext ||= File.extname(openable.path)
  else
    ext ||= File.extname(openable.to_s)
  end
  ext.sub!(/:.*/, '') # hack for filenames or URLs that include a colon

  if openable.is_a?(URI::Generic)
    openable.open(options) { |file| read(file, ext) }
  else
    openable.open(**options) { |file| read(file, ext) }
  end
end

.read(stream, ext = nil) ⇒ MiniMagick::Image

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 (BLOB)

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

Parameters:

  • stream (#read, String) —

    Some kind of stream object that needs to be read or is a binary String blob

  • ext (String) (defaults to: nil) —

    A manual extension to use for reading the file. Not required, but if you are having issues, give this a try.

Returns:



29
30
31
32
33
34
35
 
# 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

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



178
179
180
 
# File 'lib/mini_magick/image.rb', line 178

def ==(other)
  self.class == other.class && signature == other.signature
end

#[](value) ⇒ String Also known as: info

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

Examples:

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

Parameters:

  • value (String)

Returns:

  • (String)

See Also:



312
313
314
 
# File 'lib/mini_magick/image.rb', line 312

def [](value)
  @info[value.to_s]
end

#collapse!(frame = 0) ⇒ self

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

Parameters:

  • frame (Integer) (defaults to: 0) —

    The frame to which to collapse to, defaults to ‘0`.

Returns:

  • (self) 


562
563
564
 
# File 'lib/mini_magick/image.rb', line 562

def collapse!(frame = 0)
  mogrify(frame) { |builder| builder.quality(100) }
end

#combine_options {|MiniMagick::Tool::Mogrify| ... } ⇒ self

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

Examples:

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

Yields:

Returns:

  • (self)

See Also:



484
485
486
 
# File 'lib/mini_magick/image.rb', line 484

def combine_options(&block)
  mogrify(&block)
end

#composite(other_image, output_extension = type.downcase, mask = nil) ⇒ Object

Examples:

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 Also:



541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/mini_magick/image.rb', line 541

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

#destroy! ⇒ Object

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



569
570
571
572
573
574
 
# File 'lib/mini_magick/image.rb', line 569

def destroy!
  if @tempfile
    FileUtils.rm_f @tempfile.path.sub(/mpc$/, "cache") if @tempfile.path.end_with?(".mpc")
    @tempfile.unlink
  end
end

#format(format, page = 0, read_opts = {}) {|MiniMagick::Tool::Convert| ... } ⇒ self

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 Image.new(file_path)… Then that file is DELETED! If you used Image.open(file) 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.

Parameters:

  • format (String) —

    The target format… Like ‘jpg’, ‘gif’, ‘tiff’ etc.

  • page (Integer) (defaults to: 0) —

    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.

  • read_opts (Hash) (defaults to: {}) —

    Any read options to be passed to ImageMagick for example: image.format(‘jpg’, page, ‘300’)

Yields:

Returns:

  • (self) 


433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/mini_magick/image.rb', line 433

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
rescue MiniMagick::Invalid, MiniMagick::Error => e
  new_tempfile.unlink if new_tempfile && @tempfile != new_tempfile
  raise e
end

#get_pixels(map = "RGB") ⇒ Array

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 or four elements in the range 0-255, one for each of the RGB(A) color channels

It can also be called after applying transformations:

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

Examples:

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
img = MiniMagick::Image.open 'image.jpg'
pixels = img.get_pixels("RGBA")
pixels[3][2][3] # the alpha channel value from the 4th-row, 3rd-column pixel
img = MiniMagick::Image.open 'image.jpg'
img.crop '20x30+10+5'
img.colorspace 'Gray'
pixels = img.get_pixels

Parameters:

  • map (String) (defaults to: "RGB") —

    A code for the mapping of the pixel data. Must be either ‘RGB’ or ‘RGBA’. Default to ‘RGB’

Returns:

  • (Array) —

    Matrix of each color of each pixel

Raises:

  • (ArgumentError) 


368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/mini_magick/image.rb', line 368

def get_pixels(map="RGB")
  raise ArgumentError, "Invalid map value" unless ["RGB", "RGBA"].include?(map)
  convert = MiniMagick::Tool::Convert.new
  convert << path
  convert.depth(8)
  convert << "#{map}:-"

  # 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(map.length).each_slice(width).to_a

  # deallocate large intermediary objects
  output.clear
  pixels_array.clear

  pixels
end

#hash ⇒ Object 



183
184
185
 
# File 'lib/mini_magick/image.rb', line 183

def hash
  signature.hash
end

#identify {|MiniMagick::Tool::Identify| ... } ⇒ String

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

Examples:

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

Yields:

Returns:

  • (String) —

    Output from ‘identify`



588
589
590
591
592
593
 
# File 'lib/mini_magick/image.rb', line 588

def identify
  MiniMagick::Tool::Identify.new do |builder|
    yield builder if block_given?
    builder << path
  end
end

#landscape? ⇒ Boolean

Compares if image width is greater than height

| | | |

Returns:

  • (Boolean) 


627
628
629
 
# File 'lib/mini_magick/image.rb', line 627

def landscape?
  width > height
end

#layer? ⇒ Boolean

Returns:

  • (Boolean) 


615
616
617
 
# File 'lib/mini_magick/image.rb', line 615

def layer?
  path =~ /\[\d+\]$/
end

#layers ⇒ Array<MiniMagick::Image> Also known as: pages, frames

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

Examples:

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

Returns:



328
329
330
331
332
333
 
# File 'lib/mini_magick/image.rb', line 328

def layers
  layers_count = identify.lines.count
  layers_count.times.map do |idx|
    MiniMagick::Image.new("#{path}[#{idx}]")
  end
end

#mogrify(page = nil) ⇒ Object 



604
605
606
607
608
609
610
611
612
613
 
# File 'lib/mini_magick/image.rb', line 604

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

#portrait? ⇒ Boolean

Compares if image height is greater than width

| | | | | | | |

Returns:

  • (Boolean) 


641
642
643
 
# File 'lib/mini_magick/image.rb', line 641

def portrait?
  height > width
end

#respond_to_missing?(method_name, include_private = false) ⇒ Boolean

Returns:

  • (Boolean) 


501
502
503
 
# File 'lib/mini_magick/image.rb', line 501

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) ⇒ Object 



596
597
598
599
600
601
602
 
# File 'lib/mini_magick/image.rb', line 596

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

#to_blob ⇒ String

Returns raw image data.

Returns:

  • (String) —

    Binary string



192
193
194
 
# File 'lib/mini_magick/image.rb', line 192

def to_blob
  File.binread(path)
end

#valid? ⇒ Boolean

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.

Returns:

  • (Boolean) 


205
206
207
208
209
210
 
# File 'lib/mini_magick/image.rb', line 205

def valid?
  validate!
  true
rescue MiniMagick::Invalid
  false
end

#validate! ⇒ Object

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

Raises:



218
219
220
221
222
 
# File 'lib/mini_magick/image.rb', line 218

def validate!
  identify
rescue MiniMagick::Error => error
  raise MiniMagick::Invalid, error.message
end

#write(output_to) ⇒ Object

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

Parameters:

  • output_to (String, Pathname, #read) —

    Some kind of stream object that needs to be read or a file path as a String



513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
 
# File 'lib/mini_magick/image.rb', line 513

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