Image Manipulators link

An image manipulator is a displayable that takes an image or image manipulator, and either loads it or performs an operation on it. Image manipulators can only take images or other image manipulators as input.

An image manipulator can be used any place a displayable can, but not vice-versa. An Image() is a kind of image manipulator, so an Image can be used whenever an image manipulator is required.

With the few exceptions listed below, the use of image manipulators is historic. A number of image manipulators that had been documented in the past should no longer be used, as they suffer from inherent problems. In any case except for im.Data, the Transform() displayable provides similar functionality in a more general manner, while fixing the problems, although it sometimes requires gl2 to be enabled.

im.AlphaMask(base, mask, **properties) link

An image manipulator that takes two image manipulators, base and mask, as arguments. It replaces the alpha channel of base with the red channel of mask.

This is used to provide an image's alpha channel in a second image, like having one jpeg for color data, and a second one for alpha. In some cases, two jpegs can be smaller than a single png file.

Note that this takes different arguments from AlphaMask(), which uses the mask's alpha channel.

im.Blur(im, xrad, yrad=None, **properties) link

An image manipulator that blurs the image manipulator im using an elliptical kernel described by xrad and optionally yrad.

If yrad is None, it will take the value of xrad resulting in a circular kernel being used.

image logo blurred = im.Blur("logo.png", 1.5)

The same effect can now be achieved with the blur transform property.

im.Crop(im, rect) link

An image manipulator that crops rect, a (x, y, width, height) tuple, out of im, an image manipulator.

image logo crop = im.Crop("logo.png", (0, 0, 100, 307))

The same effect can now be achieved by setting the crop transform property.

im.Data(data, filename, **properties) link

This image manipulator loads an image from binary data.

data: A string of bytes, giving the compressed image data in a standard file format.
filename: A "filename" associated with the image. This is used to provide a hint to Ren'Py about the format of data. (It's not actually loaded from disk.)

im.FactorScale(im, width, height=None, bilinear=True, **properties) link

An image manipulator that scales im (a second image manipulator) to width times its original width, and height times its original height. If height is omitted, it defaults to width.

If bilinear is true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.

image logo doubled = im.FactorScale("logo.png", 1.5)

The same effect can now be achieved with the zoom or the xzoom and yzoom transform properties.

im.Flip(im, horizontal=False, vertical=False, **properties) link

An image manipulator that flips im (an image manipulator) vertically or horizontally. vertical and horizontal control the directions in which the image is flipped.

image eileen flip = im.Flip("eileen_happy.png", vertical=True)

The same effect can now be achieved by setting xzoom (for horizontal flip) or yzoom (for vertical flip) to a negative value.

im.Grayscale(im, **properties) link

An image manipulator that creates a desaturated version of the image manipulator im.

The same effect can now be achieved by supplying SaturationMatrix(0) to the matrixcolor transform property.

im.Sepia(im, **properties) link

An image manipulator that creates a sepia-toned version of the image manipulator im.

The same effect can now be achieved by supplying SepiaMatrix() to the matrixcolor transform property.

im.Tile(im, size=None, **properties) link

An image manipulator that tiles the image manipulator im, until it is size.

size: If not None, a (width, height) tuple. If None, this defaults to (config.screen_width, config.screen_height).

The same effect can now be achieved using the Tile() displayable, with Tile(im, size=size).

im.MatrixColor link

The im.MatrixColor image manipulator is an image manipulator that uses a matrix to control how the colors of an image are transformed. The matrix used can be an im.matrix object, which encodes a 5x5 matrix in an object that supports matrix multiplication, and is returned by a series of functions. im.matrix objects may be multiplied together to yield a second object that performs both operations. For example:

image city blue = im.MatrixColor(
    "city.jpg",
    im.matrix.desaturate() * im.matrix.tint(0.9, 0.9, 1.0))

first desaturates the image, and then tints it blue. When the intermediate image is not needed, multiplying matrices is far more efficient, in both time and image cache space, than using two im.MatrixColors.

The im.MatrixColor image manipulator has been replaced by Transforms and ATL transforms that specify the matrixcolor property. Each im.matrix generator has been given a new Matrix equivalent, which can be found in the matrixcolor documentation.

Warning

The new Matrix objects multiply in the opposite order as the im.Matrixcolor ones. With X being the Matrix corresponding to im.Matrixcolor.x, C*B*A will be the Matrix corresponding to im.a*im.b*im.c.

im.MatrixColor(im, matrix, **properties) link

An image operator that uses matrix to linearly transform the image manipulator im.

Matrix should be a list, tuple, or im.matrix() that is 20 or 25 elements long. If the object has 25 elements, then elements past the 20th are ignored.

When the four components of the source color are R, G, B, and A, which range from 0.0 to 1.0; the four components of the transformed color are R', G', B', and A', with the same range; and the elements of the matrix are named:

[ a, b, c, d, e,
  f, g, h, i, j,
  k, l, m, n, o,
  p, q, r, s, t ]

the transformed colors can be computed with the formula:

R' = (a * R) + (b * G) + (c * B) + (d * A) + e
G' = (f * R) + (g * G) + (h * B) + (i * A) + j
B' = (k * R) + (l * G) + (m * B) + (n * A) + o
A' = (p * R) + (q * G) + (r * B) + (s * A) + t

The components of the transformed color are clamped to the range [0.0, 1.0].

im.matrix() link

Constructs an im.matrix object from matrix. im.matrix objects support The operations supported are matrix multiplication, scalar multiplication, element-wise addition, and element-wise subtraction. These operations are invoked using the standard mathematical operators (*, *, +, and -, respectively). If two im.matrix objects are multiplied, matrix multiplication is performed, otherwise scalar multiplication is used.

matrix is a 20 or 25 element list or tuple. If it is 20 elements long, it is padded with (0, 0, 0, 0, 1) to make a 5x5 matrix, suitable for multiplication.

im.matrix.brightness(b) link

Returns an im.matrix that alters the brightness of an image.

b: The amount of change in image brightness. This should be a number between -1 and 1, with -1 the darkest possible image and 1 the brightest.

A suitable equivalent for the matrixcolor transform property is BrightnessMatrix(b).

im.matrix.colorize(black_color, white_color) link

Returns an im.matrix that colorizes a black and white image. black_color and white_color are Ren'Py style colors, so they may be specified as strings or tuples of (0-255) color values.

# This makes black colors red, and white colors blue.
image logo colored = im.MatrixColor(
    "bwlogo.png",
    im.matrix.colorize("#f00", "#00f"))

A suitable equivalent for the matrixcolor transform property is ColorizeMatrix(black_color, white_color).

im.matrix.contrast(c) link

Returns an im.matrix that alters the contrast of an image. c should be greater than 0.0, with values between 0.0 and 1.0 decreasing contrast, and values greater than 1.0 increasing contrast.

A suitable equivalent for the matrixcolor transform property is ContrastMatrix(c).

im.matrix.desaturate() link

Returns an im.matrix that desaturates the image (makes it grayscale). This is equivalent to calling im.matrix.saturation(0).

A suitable equivalent for the matrixcolor transform property is SaturationMatrix(0).

im.matrix.hue(h) link

Returns an im.matrix that rotates the hue by h degrees, while preserving luminosity.

A suitable equivalent for the matrixcolor transform property is HueMatrix(h).

im.matrix.identity() link

Returns an identity matrix, one that does not change color or alpha.

A suitable equivalent for the matrixcolor transform property is IdentityMatrix().

im.matrix.invert() link

Returns an im.matrix that inverts the red, green, and blue channels of the image without changing the alpha channel.

A suitable equivalent for the matrixcolor transform property is InvertMatrix(1.0).

im.matrix.opacity(o) link

Returns an im.matrix that alters the opacity of an image. An o of 0.0 is fully transparent, while 1.0 is fully opaque.

A suitable equivalent for the matrixcolor transform property is OpacityMatrix(o).

im.matrix.saturation(level, desat=(0.2126, 0.7152, 0.0722)) link

Returns an im.matrix that alters the saturation of an image. The alpha channel is untouched.

level: The amount of saturation in the resulting image. 1.0 is the unaltered image, while 0.0 is grayscale.
desat: This is a 3-element tuple that controls how much of the red, green, and blue channels will be placed into all three channels of a fully desaturated image. The default is based on the constants used for the luminance channel of an NTSC television signal. Since the human eye is mostly sensitive to green, more of the green channel is kept then the other two channels.

A suitable equivalent for the matrixcolor transform property is SaturationMatrix(value, desat).

im.matrix.tint(r, g, b) link

Returns an im.matrix that tints an image, without changing the alpha channel. r, g, and b should be numbers between 0 and 1, and control what fraction of the given channel is placed into the final image. (For example, if r is .5, and the value of the red channel is 100, the transformed color will have a red value of 50.)

A suitable equivalent for the matrixcolor transform property is TintMatrix(Color((r, g, b))).