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) linkAn 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) linkAn 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) linkAn 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) linkThis image manipulator loads an image from binary data.
im.
FactorScale
(im, width, height=None, bilinear=True, **properties) linkAn 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) linkAn 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) linkAn 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) linkAn 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) linkAn image manipulator that tiles the image manipulator im, until it is size.
config.screen_width
, config.screen_height
).The same effect can now be achieved using the Tile()
displayable, with Tile(im, size=size)
.
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) linkAn 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
() linkConstructs 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) linkReturns an im.matrix that alters the brightness of an image.
A suitable equivalent for the matrixcolor
transform property
is BrightnessMatrix(b).
im.matrix.
colorize
(black_color, white_color) linkReturns 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) linkReturns 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
() linkReturns 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) linkReturns 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
() linkReturns an identity matrix, one that does not change color or alpha.
A suitable equivalent for the matrixcolor
transform property
is IdentityMatrix().
im.matrix.
invert
() linkReturns 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) linkReturns 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)) linkReturns an im.matrix that alters the saturation of an image. The alpha channel is untouched.
A suitable equivalent for the matrixcolor
transform property
is SaturationMatrix(value, desat).
im.matrix.
tint
(r, g, b) linkReturns 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))).