Description
Averages all the images together. Each image in the image must have the same width and height.
Returns
A single image representing the average of all the images in the imagelist.
Example
Magick API
AverageImages
Magick::ImageList.new [ { optional
arguments } ] -> imagelist
Magick::ImageList.new(filename[,
filename...]]) [ { optional
arguments } ] -> imagelist
Creates a new imagelist. If one or more image filenames are
specified, opens and reads the files, adding a new image for
each image in the image file(s). Sets the scene number to the
index of the last image, or nil if no filenames
are specified.
Zero or more image file names. You can also specify optional arguments to be used when reading the file(s) by setting Image::Info attributes in the optional block.
A new imagelist. The imagelist contains an Image object for each image in the specified files. A file can contain more than one image. For example, new will create an image for each frame in an animated GIF or each layer in a multi-layer Photoshop file.
i = Magick::ImageList.new
i = Magick::ImageList.new("Button_A.gif", "Cheetah.jpg")
ilist.delay=n
In conjunction with ticks_per_second sets the length of
time between each image in an animation. The
delay= attribute assigns the same delay to all the
images in the ilist. Use Image#delay= to set different delay
values on individual images.
An integer value representing the number of ticks that must elapse between each image in an animation.
self
ilist.delay = 20 # delay 1/5 of a second between images.
ilist.iterations=n
Sets the number of times an animated image should loop.
The animate method and the ImageMagick animate command does not respect this number. Both will repeat the animation until you stop them. Mozilla (and presumably Netscape) do respect the value..
The number of iterations.
self
ilist.iterations = 10
ilist.length -> integer
Returns the number of images in the imagelist.
i = Magick::ImageList.new("images/Button_A.gif", "images/Button_B.gif")
i.length » 2
ilist.scene ->
integer
ilist.scene = integer
Get/set the current scene number. The scene number indicates the image to which Image methods are sent.
ilist.scene = 10 ilist.scene » 10
ilist.ticks_per_second = integer
Used in conjunction with delay to establish the elapsed time between frames in an animation. By default the number of ticks per second is 100.
ilist.ticks_per_second = 1000
ImageList delegates many methods to
Array, so you can manipulate the images in an
imagelist using almost all of the methods defined in
Array. Typically these methods also update the
scene number. The scene number will never exceed the number of
images in the list, and if the imagelist contains no images the
scene number will be nil.
Array methods that would normally return an array return an ImageList.
Most array methods keep the current image current. If the method moves the current image to a new position, the method updates the scene number to the new index. If the method deletes the current image, the scene number is set to the last image in the list. The following table lists the methods that do not follow these rules.
| Array method | scene number will be... |
|---|---|
| << | set to index the last image in the list |
| clear | set to nil |
| concat | set to index the last image in the list |
| push | set to index the last image in the list |
| unshift | set to 0 |
Adding anything other than a image to an imagelist has
undefined results. Most of the time RMagick will raise an
ArgumentError exception. For example, if you call
collect! on an imagelist you should make sure that
the members of the imagelist remain images. If you need to
replace images in an imagelist with non-image objects, convert
the imagelist to an array with the to_a method,
then modify the array.
The assoc, flatten,
flatten!, join, pack,
and rassoc methods are not defined in the
ImageList class.
Add noise to a model image. Append the resulting image to
the imagelist in "example". (See the demo.rb
example.)
example = Magick::ImageList.new model = Magick::ImageList.new "model.miff" example << model.add_noise Magick::LaplacisanNoise
ilist <=> other_imagelist -> -1, 0, 1
Compares two imagelists and returns -1, 0, or 1 if the receiver is less than, equal to, or greater than the other imagelist. The comparison between the receiver (a) and the other (b) is performed this way:
n, if the result of
a[n] <=> b[n] is not 0 then that
is the result of a <=> b. Individual images
are compared by comparing their signatures.a.scene <=> b.scene is
not 0, returns the resulta.length <=> b.lengthImageList mixes in the Comparable
module.
ilist.animate([delay]) [ { optional arguments } ] -> self
Animate the images to an X Window screen. By default
displays to the local screen. You can specify a different
screen by assigning the name to the server_name
attribute in the optional arguments block.
self
ilist.animate
ilist.animate { self.server_name = "other:0.0" }
The animate method is not supported on native MS Windows.
AnimateImages
ilist.append(true or
false) -> image
Append all the images in the imagelist, either vertically or horizontally. If the images are not of the same width, any narrow images will be expanded to fit using the background color.
If true, rectangular images are stacked
top-to-bottom, otherwise left-to-right.
A image composed of all the images in the imagelist.
AppendImages
ilist.average -> image
Averages all the images together. Each image in the image must have the same width and height.
A single image representing the average of all the images in the imagelist.
AverageImages
ilist.clone -> other_imagelist
Same as dup, but the frozen state of the original is propagated to the copy.
A new imagelist
ilist.coalesce -> imagelist
Merges all the images in the imagelist into a new imagelist. Each image in the new imagelist is formed by flattening all the previous images.
The length of time between images in the new image is specified by the delay attribute of the input image. The position of the image on the merged images is specified by the page attribute of the input image.
A new imagelist
This example is an animated GIF created by coalescing 25 small images in a grid. Mouse over the image to start the animation.
flatten_images, optimize_layers
CoalesceImages
destination_list.composite_layers(source_list, operator=OverCompositeOp) ->
imagelist
An image from source_list is composited over an image from destination_list until one list is finished. Use the geometry and gravity attributes of the first image in destination_list to position the source images over the destination images. Unlike a normal composite operation, the canvas offset is also included to the composite positioning. If one of the image lists only contains one image, that image is applied to all the images in the other image list, regardless of which list it is. In this case it is the image meta-data of the list which preserved.
The optional operator argument specifies a CompositeOperator to use for the compositing operations.
An imagelist
This example is an animated GIF. Mouse over the image to start the animation.
This method is equivalent to the -layers
Composite option of ImageMagick's convert
command. See the Layers
Composition section in Examples of ImageMagick
Usage for more information.
ilist.copy -> other_imagelist
Creates a deep copy of the imagelist. The new imagelist contains a copy of all the images in the original imagelist.
An imagelist
imagelist2 = imagelist1.copy
ilist.cur_image -> image
Retrieves the image indexed by scene.
Raises IndexError if there are no images in the
list.
Both the ImageList class and the Image class support the
cur_image method. Of course, in the Image class,
cur_image simply returns self. When a
method accepts either an image or a imagelist as an argument,
it sends the cur_image method to the argument to
get the current image.
An image
ilist.deconstruct -> imagelist
This method constructs a new imagelist containing images that include only the changed pixels between each image and its successor. The resulting imagelist usually produces a much smaller file.
The deconstruct method starts by copying the
first image in the list to the output imagelist. Then, for each
pair of images, deconstruct computes the smallest
rectangle that encompasses all the changes between the first
and second image and stores just the changed rectangle of the
second image, along with the offset of the rectangle relative
to the boundary of the first image.
A new imagelist
DeconstructImages
ilist.dup -> other_imagelist
Makes a shallow copy of the receiver. The image elements in the new imagelist are references to the image elements in the original imagelist, not copies.
ilist.display [ { optional arguments } ] -> self
Displays the images in the imagelist to any X Window screen.
By default displays to the local screen. You can specify a
different screen by assigning the name to the
server_name attribute in the optional arguments
block.
self
The display method is not supported on native MS Windows.
DisplayImages
ilist.flatten_images -> image
Combines all the images in the imagelist into a single image by overlaying each successive image onto the preceding images. If a image has transparent areas, the underlying image will show through. Use the page attribute to specify the position of each image with respect to the preceding images.
This is useful for combining Photoshop layers into a single image.
An image
MergeImageLayers with the FlattenLayer method.
ilist.from_blob(blob[, blob...]) [ { optional arguments } ] -> self
Creates images from the blob (Binary Large Objects) arguments and appends the images to the imagelist.
A blob can be a string containing an image file such as a JPEG or GIF. The string can contain a multi-image file such as an animated GIF or a Photoshop image with multiple layers. A blob can also be one of the strings produced by to_blob. Control how the image(s) are created by setting additional Image::Info attributes in the optional block argument. Useful attributes include scene, number_scenes, and extract.
An image created from the blob argument(s). The
scene attribute is set to the last image in the
imagelist.
require "rmagick"
f = File.open('Cheetah.jpg')
blob = f.read
ilist = Magick::ImageList.new
ilist.from_blob(blob)
ilist.display
BlobToImageList
ilist .fx(expression [, channel...]) -> image
Applies the specified mathematical expression to the input images. This method corresponds to ImageMagick's -fx operator.
u and v symbols refer to
the 0th and 1st image in the list. The image reference index
(u[2] for example) works as expected. The
current scene number has no meaning in
the context of the fx method.The image created by the expression.
# Produce a navy blue image from a black image
imgl = Magick::ImageList.new
imgl << Magick::Image.new(64, 64) {self.background_color = 'black'}
res = imgl.fx('1/2', Magick::BlueChannel)
FxImageChannel
ilist.inspect -> string
Produces a string that describes the images in the imagelist.
The returned string is a concatenation of the strings returned by Image#inspect for all the images in the imagelist.
i = Magick::ImageList.new("images/Button_A.gif", "images/Button_B.gif")
» [images/Button_A.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 18136b
images/Button_B.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 5157b]
scene=1
ilist.map(reference, dither) -> imagelist
Reduces the colors in the imagelist images to the set of colors in the reference image.
map uses the current image as the reference
image.true, dither the mapped images.A new imagelist the same length as the receiver.
This method is deprecated when using ImageMagick 6.4.3-6 and later. Use remap instead.
MapImages
ilist.montage [ { optional arguments } ] -> imagelist
Creates a composite image by reducing the size of the input images and arranging them in a grid on the background color or texture of your choice. There are many configuration options. For example, you can specify the number of columns and rows, the distance between images, and include a label with each small image (called a tile).
All of montage's configuration options are
specified by assigning values to attributes in a block
associated with the method call.
As you can see in the examples below, when you assign a
value to a montage attribute you must specify self
as the receiver so that Ruby can distinguish the method call
from an assignment to a local variable.
You may assign a Pixel object to any attribute that accepts a color name.
OverCompositeOp.compose to UndefinedCompositeOp.<width>x<height>+<outer bevel
width>+<inner bevel width>. If the argument
is a Geometry object, specify the width and height of the
frame with the width and height
attributes, and specify the outer bevel width and the inner
bevel width with the x and y
attributes. The values are in pixels. For example, to
surround each tile with a frame 20 pixels wide by 20 pixels
high and a 4-pixel inner and outer bevel, use:
self.frame = "20x20+4+4"or
self.frame = Magick::Geometry.new(20,20,4,4)
<tile-width>x<tile-height>+<distance-between-columns>+<distance-between-rows>.
If you use a Geometry object, specify the tile width and
height with the width and height
attributes, and the distance between rows and distance
between columns by the x and y
attributes. To create tiles that are 130 pixels wide and
194 pixels tall, with 10 pixels between each column of
tiles and 5 between each row, use:
self.geometry = "130x194+10+5"or
self.geometry = Magick::Geometry.new(130, 194, 10, 5)Both the geometry string and the
Geometry object
support flags that specify additional constraints. The default
geometry is "120x120+4+3>".
true, adds a drop shadow to each
tile. The default is false.
self.texture = Magick::Image.read("granite:").first
The default is no texture.
"<columns>x<rows>". If the value
is a Geometry object, specify the number of columns as the
width attribute and the number of rows as the
height attribute. montage always
generates all the rows, leaving empty cells if necessary.
To arrange the tiles 4 across and 10 down, use:
self.tile = "4x10"or
self.tile = Magick::Geometry.new(4,10)
The default is "6x4". If there are too many tiles to fit
on one composite image, montage creates
multiple composite images.
To add labels to the tiles, assign a "Label" property to
each image. The montage method will use the value
of the property as the label. For example,
img[2]['Label'] = "Mom's Birthday"
See []=.
An imagelist that contains as many images as are required to display all the tiles.
MontageImages
ilist.morph(n) -> imagelist
Transforms a image into another image by inserting
n in-between images. Requires at least two images.
If more images are present, the 2nd image is transformed into
the 3rd, the 3rd to the 4th, etc.
The number of in-between images to insert between each pair of images.
An imagelist containing copies of the original images plus the in-between images.
This animated GIF was created by reading the "0", "1", "2"
and "3" images, then using morph to create 8
images between each original image. Mouse over the image to
start the animation.
MorphImages
ilist.mosaic -> image
Composites all the images into a single new image. The location of each image is determined by the value of its page attribute.
An image
MergeImageLayers with the MosaicLayer method.
ilist.new_image(columns, rows[, fill]) [ { optional arguments } ] -> self
Adds a new image to the imagelist. The image can have an optional fill applied to it.
Creates a new image with the specified number of rows and
columns. If the optional fill argument is used,
calls the fill method to fill the image.
Otherwise, the image is filled with the background color.
You can set any Image::Info attributes in an associated block. These attributes supply options to be used when creating the image. For example, you can specify the background color to fill the image with (see the example), the depth, border color, etc.
self
Create a square red image.
ilist = Magick::ImageList.new
ilist.new_image(100, 100) { self.background_color = "red" }
ilist.optimize_layers(layer_method) -> imagelist
Optimizes or compares the images in the list. Equivalent to
the -layers option in ImageMagick's
mogrify command.
The optimize_layers method corresponds to the
-layers option on ImageMagick's
convert and mogrify commands. Anthony
Thyssen's excellent Examples of ImageMagick
Usage site has very detailed information and
examples of the -layers option and and the
optimization methods .
One of the following ImageLayerMethod enum values:
Some of these values are not supported by older versions of ImageMagick. To see what values are available, enter the following code in irb:
Magick::ImageLayerMethod.values {|v| puts v}
In releases of ImageMagick before 6.3.6, this type was called MagickLayerMethod, so you may need to use this instead:
Magick::MagickLayerMethod.values {|v| puts v}
A new imagelist
deconstruct is an alias for
optimize_layers with the
CompareAnyLayer argument.
coalesce is an alias for
optimize_layers with the
CoalesceLayer argument.
OptimizeImageLayers, CompareImageLayers
ilist.ping(filename[, filename...])
-> self
ilist.ping(file[, file...]) ->
self
Reads the image files and creates one or more images that
contain all the image attributes but without the pixel data. If
all you need is the image attributes, the ping
method is much faster and consumes less memory than read.
One or more image file names or open file objects.
self
ilist = Magick::ImageList.new
ilist.ping "Button_A.gif"
puts "The image has #{i.columns} columns and #{i.rows} rows." »
The image has 127 columns and 120 rows.
PingImage
ilist.quantize(nc=256,
colorspace=RGBColorspace,
dither=RiemersmaDitherMethod, tree_depth=0,
measure_error=false) -> imagelist
Analyzes the colors within a set of reference images and chooses a fixed number of colors to represent the set. The goal of the algorithm is to minimize the difference between the input and output images while minimizing the processing time.
A new imagelist containing quantized copies of the images in the original image.
This example shows the effect of quantizing 3 images to a set of 16 colors in the RGB colorspace. Mouse over the image to see the images before quantizing.
QuantizeImages
ilist.read(filename[, filename...]) [ { optional arguments } ] ->
self
ilist.read(file[,
file...]) [ { optional arguments
} ] -> self
Reads one or more image files and adds the images to the imagelist. After reading all the files, sets the scene number to the last image in the list.
The image files may be multi-frame (animated or layered)
files. In this case read adds multiple images per
file to the imagelist.
One or more filenames or open file objects. You can also specify optional arguments to be used when reading the file(s) by setting Image::Info attributes in the optional block.
self
i = Magick::ImageList.new
number = '0'
4.times do
i.read "images/Button_" + number + ".gif"
number.succ!
end
Also see the morph.rb example and the demo.rb example.
ReadImage
You can create images using ImageMagick's built-in formats
with the read method. See Built-in image formats.
ilist.remap(remap_image=nil, dither=RiemersmaDitherMethod) -> self
Reduce the colors used in the imagelist to the set of colors in remap_image.
self
This example shows the effect of reducing the colors used in the apple, beach scene, and leaf images to the set of colors used in the yellow rose image.
RemapImages (available in ImageMagick 6.4.3-6)
ilist.to_blob [ { optional arguments } ] -> string
Converts the images in the imagelist to a blob. A blob contains data that directly represent a particular image format in memory instead of on disk.
Control the format of the blob by setting Image::Info attributes in an associated block.
The blob in the form of a string
i = Magick::ImageList.new "birthday.png" s = i.to_blob » a string representing the image.
from_blob, Image#to_blob, Image.from_blob
ImageListToBlob
ilist.to_a -> array
Returns an array containing all the images in the list.
An array
ilist.write(filename) [ { optional
arguments } ] -> self
ilist.write(file) [ { optional
arguments } ] -> self
If the image format indicated
by the filename supports multiple images per file (animated
images), write writes all the images in the
imagelist to a single file. Otherwise, write
writes each image to a separate file.
Regardless of the original format, write
converts the images to the format specified by the
filename.
If the imagelist contains more than one image and the output format does not support multi-frame images, each image is written to a file that has the filename you specify followed by a period (.) and the scene number. You can change this behavior by embedding a %d, %0Nd, %o, %0No, %x, or %0Nx printf format specification in the file name.
A filename or open file object. Indicate the desired image
format either by the suffix
(i.e. .jpg, .png) or the prefix
(ps:) to the filename. If the argument is an open
file object, you can specify a format for each image in the
list by setting its format
attribute. (See the Notes section for Image#write.)
You can also specify optional arguments by setting Image::Info attributes in an associated block.
self, or nil if the format cannot be
determined.
# The PNG format does not support multi-frame files,
# so each image is written to a separate file.
i = Magick::ImageList.new "animated.gif"
p i.length » 3 # contains 3 images
i.write "test.png" » test.png.0
» test.png.1
» test.png.2
# ImageMagick's MIFF format does support multi-frame
# files, so all 3 images are written to one file.
i.write "animated.miff" » animated.miff
WriteImages