# class ImageList

### Table Of Contents

### class methods

- new

### instance attribute methods

- delay=
- iterations=
- length
- scene
- scene=

### instance methods

- Array methods
- <=>
- ==
- animate
- append
- average
- coalesce
- copy
- cur_image
- deconstruct
- display
- flatten_images
- from_blob
- inspect
- map
- montage
- morph
- mosaic
- new_image
- ping
- quantize
- read
- to_blob
- write

## class methods

new | Magick::ImageList.new -> image Magick::ImageList.new(filename[, filename...]]) -> image
Description | Creates a new image. 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.
Arguments | Zero or more image file names.
Returns | A new image.

Example

    i = Magick::ImageList.new
    i = Magick::ImageList.new("Button_A.gif", "Cheetah.jpg")

## instance attribute accessor methods

delay= | imagelist.delay=n
Description | Sets the length of time that each image in the imagelist will be displayed when the sequence is animated.
Arguments | An integer value representing the number of 100ths of a second to display each image.
Returns | self

Example

    imagelist.delay = 20 # delay 1/5 of a second between images.

ImageMagick notes | Image Structure Members
See also | Image#delay=
Advanced | The ImageList class delay= attribute assigns the same delay to all the images in the imagelist. Use Image#delay= to set different delay values on individual images.
iterations= | imagelist.iterations=n
Description | Sets the number of times an animated image should loop.
Arguments | The number of iterations

Example

    imagelist.iterations = 10

ImageMagick notes | Image Structure Members
Notes | The animate method and the ImageMagick animate utility do not respect this number. Both will repeat the animation until you stop them. Mozilla (and presumably Netscape) do respect the value of iterations.
length | imagelist.length -> anInteger
Description | Returns the number of images in the imagelist.

Example

    i = Magick::ImageList.new("images/Button_A.gif", "images/Button_B.gif")
    i.length » 2

scene scene= | scene -> anInteger scene = anInteger -> self
Description | Get or set the current scene number. The scene number indicates the image to which Image methods are sent.

Example

    imagelist.scene = 10
    imagelist.scene » 10

## instance methods

Array methods |

Description

You can manipulate the images in an imagelist using almost any Array method. Many of these methods will 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.

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

Example

Add noise to a model image. Append the resulting image to the imagelist in "example". (See: demo.rb)

    example = Magick::ImageList.new
    model = Magick::ImageList.new "model.miff"
    example << model.add_noise Magick::LaplacisanNoise

See also | scene scene=
Advanced | The assoc, flatten, flatten!, join, pack, and rassoc methods are not defined in the ImageList class. Array methods defined in the ImageList class that would normally return an array return an ImageList. Adding anything other than a image to an imagelist has undefined results. Most of the time RMagick will raise an ArgumentError exception.
<=> | imagelist <=> anOtherImageList -> -1, 0, 1

Description

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 recipient (a) and the other (b) is performed this way:

1. If a has fewer images than b, returns -1.
2. Conversely, if a has more images than b, returns 1.
3. Otherwise, for all images, if the result of `a[n] <=> b[n]`, is not 0 then that is the result of a <=> b
4. Otherwise, the result is 0.

See also | Image#<=>
Advanced | Individual images are compared by comparing their signatures.
== | imagelist == anOtherImageList -> `true` or `false`

Description

Compares two imagelists for equality. ImageLists imglist1 and imglist2 are equal if

1. `imglist1.length == imglist2.length`,
2. for all images `imglist1[n] == imglist2[n]`, and
3. `imglist1.scene == imglist2.scene`.

Example

    i1 = Magick::ImageList.new("animated.gif")
    i2 = Magick::ImageList.new("animated.gif")
    i3 = Magick::ImageList.new("animated.gif")
    i3.scene = 0
    i4 = Magick::ImageList.new("single.gif")
    i1 == i2 » true
    i1 == i3 » false (scene numbers don't match)
    i2 == i4 » false (different number of images)

See also | Image#== scene
Advanced | Individual images are compared by comparing their signatures.
animate | imagelist.animate([delay]) [ { optional arguments } ] -> self
Description | 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.
Arguments | None

Example

    imagelist.animate

    imagelist.animate { self.server_name = "other.lnx:0.0" }

ImageMagick API | AnimateImages
See also | display
append | imagelist.append(`true` or `false`) -> anImage
Description | 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.
Arguments | If `true`, rectangular images are stacked top-to-bottom, otherwise left-to-right.
Returns | A image composed of all the images in the imagelist.
Example | See the map example.
ImageMagick API | AppendImages
average | imagelist.average -> anImage
Description | Averages all the images together. Each image in the image must have the same width and height.
Arguments | None
Returns | A single image representing the average of all the images in the imagelist.
Example |
ImageMagick API | AverageImages
coalesce | imagelist.coalesce -> anImageList
Description | 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.
Arguments | None
Returns | A new multi-frame image.

Example

| This an animated GIF is created by coalescing 25 small images in a grid.

ImageMagick API | CoalesceImages
See also | flatten_images
copy | imagelist.copy -> anImageList
Description | Creates a deep copy of the image. The new image contains a copy of all the images in the original image.
Arguments | None
Returns | A new image.

Example

    imagelist2 = imagelist1.copy

See also | Image#copy
cur_image | imagelist.cur_image -> anImage
Description | Retrieves the image indexed by scene.
Arguments | None
Returns | The image in the images array indexed by the current value of scene.

Example

    f = imagelist.cur_image

Advanced | 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 RubyMagick 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.
deconstruct | imagelist.deconstruct -> anImage
Description | Compares each image with the next in a sequence and returns the maximum bounding region of any pixel differences it discovers.
Arguments | None.
Returns | A image.

Example

    f = imagelist.deconstruct

ImageMagick API | DeconstructImages
Other | I'm looking for an example.
display | imagelist.display [ { optional arguments } ] -> self
Description | 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.
Arguments | None

Example

    imagelist.display
    imagelist.display { self.server_name = "other.lnx:0.0" }

ImageMagick API | DisplayImages
See also | animate
flatten_images | imagelist.flatten_images -> anImage
Description | 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.
Arguments | None
Returns | A image that is the combination of all the images in the image.
Example |
ImageMagick API | FlattenImageList
See also | coalesce
Advanced | This is useful for combining Photoshop layers into a single image.
Notes | Since the Array class defines a flatten method I used a different name for this method.
from_blob | imagelist.from_blob(blob[, blob...]) [ { optional arguments } ] -> self
Description | Creates images from the blob (Binary Large Objects) arguments and appends the images to the imagelist in the image.
Arguments | One or more of the strings produced by to_blob. Control the format of the created image(s) by setting additional Image::Info attributes in the optional block argument. Useful attributes include format, size, and depth.
Returns | An image created from the blob argument(s). The scene attribute is set to the last image in the image.

Example

    imagelist = Magick::ImageList.new
    imagelist.from_blob(blob) {
       self.format = "GIF"
       self.size = "120x120"
       self.depth = Magick::QuantumDepth
       }

ImageMagick API | BlobToImageList
See also | to_blob Image#to_blob Image.from_blob
Other | Sorry for the sketchy documentation. I'd appreciate any information on ImageMagick blob support!
inspect | imagelist.inspect -> aString
Description | Produces a string that describes the images in the image.
Arguments | None
Returns | The returned string is a concatenation of the strings returned by Image#inspect for all the images in the imagelist.

Example

    i = Magick::ImageList.new("images/Button_A.gif", "images/Button_B.gif")
    imagelist.inspect »
    "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"

ImageMagick notes | Produces essentially the same information as DescribeImageList
See also | Image#inspect
map | imagelist.map(reference, dither) -> anImageList
Description | Reduces the colors in the imagelist images to the set of colors in the reference image.

Arguments

reference
  An image or a image. If an image, map uses the current image as the reference image.
dither
  if true, dither the mapped images.

Returns | A new imagelist containing one image for every image in the receiver.

Example

This example demonstrates how to map images into the 216 "Web safe" colors. The top half of the images are in the original colors. The bottom half of the images have been mapped using ImageMagick's built-in "NETSCAPE:" format.

ImageMagick API | MapImages
See also | Image#map quantize
montage | imagelist.montage [ { optional arguments } ] -> anImageList

Description

Creates a composite image by reducing the size of the image 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 (tile).

All of montage's configuration options are specified by assigning values to attribute methods in a block associated with the method call.

Configuration attributes

Attribute accessor | Description
--- | ---

background_color=

The composite image background color.

    self.background_color = "white"

The default background color is white.

border_color=

The tile border color.

    self.border_color = "black"

The default border color is #dfdfdf (gray). (Note: I have not been able to get this attribute to override the value of the individual tile's border_color attribute.)

border_width=

The width in pixels of the tile borders.

    self.border_width = 10

The default border width is 0.

compose=

The composite operator to use when compositing the tile images onto the background.

    self.compose = Magick::AtopCompositeOp

The default composition operator is OverCompositeOp.

Hint: You can use a different composite operator for each tile by setting each image's compose= attribute to the desired operator. In the optional arguments block, set compose to UndefinedCompositeOp.

filename= | The filename of the composite image. (Note: Currently RubyMagick does not use this value.)

fill=

If the tiles have labels, the label fill color.

    self.fill = "red"

The default fill color is black.

font=

If the tiles have labels, the label font.

    self.font = "Courier"

The default font is Helvetica.

frame=

The size of an ornamental frame surrounding each tile. The frame specification is a string in the form <width>x<height>+<outer bevel width>+<inner bevel width>. 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"

If the tile has a label, the label is included in the frame. The default is to have no frame.

See Image#frame.

geometry=

The size of the tiles and the distance between tiles. The value should be a string in the form <tile-width>x<tile-height>+<distance-between-columns>+<distance-between-rows>. 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"

The default geometry is "120x120+4+3>".

See geometry.

gravity=

The direction used when adding the tile labels. (See annotate.)

    self.gravity = Magick::CenterGravity

The default is CenterGravity.

matte_color= | The matte color. The default is #bdbdbd.

pointsize=

If the tiles have labels, the size of the label font.

    self.pointsize = 20

The default is 12.

shadow=

If set to true, adds a drop shadow to each tile.

    self.shadow = true

The default is false.

stroke=

If the tiles have labels, sets the stroke (outline) color of the label text.

    self.stroke = "red"

The default is "transparent," that is, no stroke color.

texture=

A image to be tiled on the background of the composite image. If present, overrides the background color. For example, to use ImageMagick's built-in "granite" texture as the background, use:

    self.texture = Magick::Image.read("granite:").first

The default is no texture.

tile=

The number of columns and rows to use when arranging the tiles on the composite image. The value is a string in the form "<columns>x<rows>". To arrange the tiles 4 across and 10 down, use:

    self.tile = "4x10"

The default is "6x4". Note: If there are too many tiles to fit on one composite image, montage creates multiple composite images.

title=

The composite image title.

    self.title = "My Images"

The default is no title. Note: I have not been able to get this to actually put a title on the composite image.

Note:In the above examples, the reference to self is necessary to distinguish the method call from an assignment to a local variable.

Note:You may assign a Pixel object to any attribute that accepts a color name.

Tile labels

To add labels to the tiles, assign a "Label" attribute to each image. The montage method will use the value of the attribute as the tile's label. For example,

    img[2]['Label'] = "Mom's Birthday"

See Image#[]=.

ImageMagick API | MontageImages
Returns | An image containing as many images as were necessary to tile all the images in the original image.
Example | demo.rb
See also | The ImageMagick montage utility
morph | imagelist.morph(n) -> anImageList
Description | 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.
Arguments | The number of in-between images to insert between each pair of images.
Returns | An image containing copies of the original images plus the in-between images.

Example

| This is animated GIF is created by reading the "0", "1", "2" and "3" images, then using morph to create 8 images between each original image.

ImageMagick API | MorphImages
mosaic | imagelist.mosaic -> anImage
Description | Composites all the images into a single new image. The location of each image is determined by the value of its page attribute.
Arguments | None
Returns | A new image.
Example |
ImageMagick API | MosaicImages
See also | coalesce flatten_images montage
new_image | imagelist.new_image(columns, rows[, fill]) [ { optional arguments } ]
Description | Adds a new image to the imagelist. The image can have an optional fill applied to it.

Arguments

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.

Returns | self

Example

    # Create a square red image.
    imagelist = Magick::ImageList.new
    imagelist.new_image(100, 100) { self.background_color = "red" }

ping | imagelist.ping(filename[, filename...]) -> self
Description | 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.
Arguments | One or more image file names.
Returns | self

Example

    imagelist = Magick::ImageList.new
    imagelist.ping "Button_A.gif"
    puts "The image has #{i.columns} columns and #{i.rows} rows." »
          The image has 127 columns and 120 rows.

ImageMagick API | PingImage
See also | read
quantize | imagelist.quantize(nc=256, colorspace=`Magick::RGBColorspace`, dither=`true`, tree_depth=0, measure_error=`false`) -> anImageList
Description | 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.

Arguments

nc
  The maximum number of colors to use in the output images. Must be less than or equal to MaxRGB.
colorspace
  The colorspace to quantize in. Color reduction, by default, takes place in the RGB color space. Empirical evidence suggests that distances in color spaces such as YUV or YIQ correspond to perceptual color differences more closely than do distances in RGB space. The Transparent color space behaves uniquely in that it preserves the matte channel of the image if it exists.
dither
  Apply Floyd/Steinberg error diffusion to the image. When the size of the color palette is less than the image colors, this trades off spacial resolution for color resolution by dithering to achieve a similar looking image.
tree_depth
  Specify the tree depth to use while quantizing. The values 0 and 1 support automatic tree depth determination. The tree depth may be forced via values ranging from two to eight. The ideal tree depth depends on the characteristics of the input image, and may be determined through experimentation.
measure_error
  Calculate quantization errors when quantizing the image.

  Stores the results for each image in the imagelist mean_error_per_pixel, normalized_maximum_error, and normalized_mean_error attributes. Stores the number of colors used for the image in the total_colors attribute.

Returns | A new image containing quantized copies of the images in the original image.

Example

This example shows the effect of quantizing 3 images to a set of 16 colors in the RGB colorspace. The original images are on top. The quantized images are on the bottom.

ImageMagick API | QuantizeImages
See also | Image#quantize
read | imagelist.read(filename[, filename...]) [ { optional arguments } ] -> self
Description | 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) files. In this case read adds multiple images per file to the imagelist.
Arguments | One or more filenames. You can also specify optional arguments to be used when reading the file(s) by setting Image::Info attributes in the optional block.
Returns | self

Example

    i = Magick::ImageList.new
    number = '0'
    4.times do
            i.read "images/Button_" + number + ".gif"
            number.succ!
            end

See the morph example and demo.rb.

ImageMagick notes | ReadImageList
See also | Image.read
Advanced | You can create images using ImageMagick's built-in formats with the read method. See Built-in image formats.
to_blob | imagelist.to_blob [ { optional arguments } ] -> aString
Description | 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.
Arguments | None. You can control the format of the blob by setting Image::Info attributes in an associated block.
Returns | The blob in the form of a Ruby string.

Example

    i = Magick::ImageList.new "birthday.png"
    s = i.to_blob » a string representing the image.

ImageMagick API | ImageListToBlob
See also | from_blob Image#to_blob Image.from_blob
Other | Sorry for the sketchy documentation. I'd appreciate any information on ImageMagick blob support!
write | imagelist.write(filename) [ { optional arguments } ] -> self

Description

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, 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 image 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.

Arguments | A filename. Indicate the desired image format either by the suffix (i.e. `.jpg`, `.png`) or the prefix (`ps:`) to the filename. You can also specify optional arguments by setting Image::Info attributes in an associated block.
Returns | self, or `nil` if the format cannot be determined.

Example

    # 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

ImageMagick API | WriteImages
See also | Image#write

Advanced

If you want to write each image to a separate file using a format that supports multi-frame files, loop over the images individually and use the write method in the Image class:

    x = 'A'
    imagelist.each { |f| f.write "#{image}_#{x}.gif"; x.succ! }