wand.image
— Image objects¶
Opens and manipulates images. Image objects can be used in with
statement, and these resources will be automatically managed (even if any
error happened):
with Image(filename='pikachu.png') as i:
print('width =', i.width)
print('height =', i.height)
-
wand.image.
ALPHA_CHANNEL_TYPES
= ('undefined', 'activate', 'background', 'copy', 'deactivate', 'extract', 'opaque', 'reset', 'set', 'shape', 'transparent', 'flatten', 'remove')¶ (
tuple
) The list of alpha channel types'undefined'
'activate'
'background'
'copy'
'deactivate'
'extract'
'opaque'
'reset'
'set'
'shape'
'transparent'
'flatten'
'remove'
See also
- ImageMagick Image Channel
- Describes the SetImageAlphaChannel method which can be used to modify alpha channel. Also describes AlphaChannelType
-
wand.image.
CHANNELS
= {'all_channels': 134217727, 'alpha': 8, 'black': 32, 'blue': 4, 'composite_channels': 47, 'cyan': 1, 'default_channels': 134217719, 'gray': 1, 'gray_channels': 128, 'green': 2, 'index': 32, 'magenta': 2, 'opacity': 8, 'red': 1, 'rgb_channels': 128, 'sync_channels': 256, 'true_alpha': 64, 'undefined': 0, 'yellow': 4}¶ (
dict
) The dictionary of channel types.'undefined'
'red'
'gray'
'cyan'
'green'
'magenta'
'blue'
'yellow'
'alpha'
'opacity'
'black'
'index'
'composite_channels'
'all_channels'
'true_alpha'
'rgb_channels'
'gray_channels'
'sync_channels'
'default_channels'
See also
- ImageMagick Color Channels
- Lists the various channel types with descriptions of each
-
wand.image.
COLORSPACE_TYPES
= ('undefined', 'rgb', 'gray', 'transparent', 'ohta', 'lab', 'xyz', 'ycbcr', 'ycc', 'yiq', 'ypbpr', 'yuv', 'cmyk', 'srgb', 'hsb', 'hsl', 'hwb', 'rec601luma', 'rec601ycbcr', 'rec709luma', 'rec709ycbcr', 'log', 'cmy', 'luv', 'hcl', 'lch', 'lms', 'lchab', 'lchuv', 'scrgb', 'hsi', 'hsv', 'hclp', 'ydbdr')¶ (
tuple
) The list of colorspaces.'undefined'
'rgb'
'gray'
'transparent'
'ohta'
'lab'
'xyz'
'ycbcr'
'ycc'
'yiq'
'ypbpr'
'yuv'
'cmyk'
'srgb'
'hsb'
'hsl'
'hwb'
'rec601luma'
'rec601ycbcr'
'rec709luma'
'rec709ycbcr'
'log'
'cmy'
'luv'
'hcl'
'lch'
'lms'
'lchab'
'lchuv'
'scrgb'
'hsi'
'hsv'
'hclp'
'ydbdr'
See also
- ImageMagick Color Management
- Describes the ImageMagick color management operations
New in version 0.3.4.
-
wand.image.
COMPARE_METRICS
= ('undefined', 'absolute', 'mean_absolute', 'mean_error_per_pixel', 'mean_squared', 'normalized_cross_correlation', 'peak_absolute', 'peak_signal_to_noise_ratio', 'perceptual_hash', 'root_mean_square')¶ (
tuple
) The list of compare metric types'undefined'
'absolute'
'mean_absolute'
'mean_error_per_pixel'
'mean_squared'
'normalized_cross_correlation'
'peak_absolute'
'peak_signal_to_noise_ratio'
'perceptual_hash'
'root_mean_square'
See also
New in version 0.4.3.
-
wand.image.
COMPOSITE_OPERATORS
= ('undefined', 'no', 'add', 'atop', 'blend', 'bumpmap', 'change_mask', 'clear', 'color_burn', 'color_dodge', 'colorize', 'copy_black', 'copy_blue', 'copy', 'copy_cyan', 'copy_green', 'copy_magenta', 'copy_opacity', 'copy_red', 'copy_yellow', 'darken', 'dst_atop', 'dst', 'dst_in', 'dst_out', 'dst_over', 'difference', 'displace', 'dissolve', 'exclusion', 'hard_light', 'hue', 'in', 'lighten', 'linear_light', 'luminize', 'minus', 'modulate', 'multiply', 'out', 'over', 'overlay', 'plus', 'replace', 'saturate', 'screen', 'soft_light', 'src_atop', 'src', 'src_in', 'src_out', 'src_over', 'subtract', 'threshold', 'xor', 'divide')¶ (
tuple
) The list of composition operators'undefined'
'no'
'add'
'atop'
'blend'
'bumpmap'
'change_mask'
'clear'
'color_burn'
'color_dodge'
'colorize'
'copy_black'
'copy_blue'
'copy'
'copy_cyan'
'copy_green'
'copy_magenta'
'copy_opacity'
'copy_red'
'copy_yellow'
'darken'
'dst_atop'
'dst'
'dst_in'
'dst_out'
'dst_over'
'difference'
'displace'
'dissolve'
'exclusion'
'hard_light'
'hue'
'in'
'lighten'
'linear_light'
'luminize'
'minus'
'modulate'
'multiply'
'out'
'over'
'overlay'
'plus'
'replace'
'saturate'
'screen'
'soft_light'
'src_atop'
'src'
'src_in'
'src_out'
'src_over'
'subtract'
'threshold'
'xor'
'divide'
Changed in version 0.3.0: Renamed from
COMPOSITE_OPS
toCOMPOSITE_OPERATORS
.See also
- Compositing Images ImageMagick v6 Examples
- Image composition is the technique of combining images that have, or do not have, transparency or an alpha channel. This is usually performed using the IM composite command. It may also be performed as either part of a larger sequence of operations or internally by other image operators.
- ImageMagick Composition Operators
- Demonstrates the results of applying the various composition composition operators.
-
wand.image.
COMPRESSION_TYPES
= ('undefined', 'b44a', 'b44', 'bzip', 'dxt1', 'dxt3', 'dxt5', 'fax', 'group4', 'jbig1', 'jbig2', 'jpeg2000', 'jpeg', 'losslessjpeg', 'lzma', 'lzw', 'no', 'piz', 'pxr24', 'rle', 'zip', 'zips')¶ (
tuple
) The list ofImage.compression
types.New in version 0.3.6.
-
wand.image.
EVALUATE_OPS
= ('undefined', 'add', 'and', 'divide', 'leftshift', 'max', 'min', 'multiply', 'or', 'rightshift', 'set', 'subtract', 'xor', 'pow', 'log', 'threshold', 'thresholdblack', 'thresholdwhite', 'gaussiannoise', 'impulsenoise', 'laplaciannoise', 'multiplicativenoise', 'poissonnoise', 'uniformnoise', 'cosine', 'sine', 'addmodulus', 'mean', 'abs', 'exponential', 'median', 'sum', 'rootmeansquare')¶ (
tuple
) The list of evaluation operators'undefined'
'add'
'and'
'divide'
'leftshift'
'max'
'min'
'multiply'
'or'
'rightshift'
'set'
'subtract'
'xor'
'pow'
'log'
'threshold'
'thresholdblack'
'thresholdwhite'
'gaussiannoise'
'impulsenoise'
'laplaciannoise'
'multiplicativenoise'
'poissonnoise'
'uniformnoise'
'cosine'
'sine'
'addmodulus'
'mean'
'abs'
'exponential'
'median'
'sum'
See also
- ImageMagick Image Evaluation Operators
- Describes the MagickEvaluateImageChannel method and lists the various evaluations operators
-
wand.image.
FILTER_TYPES
= ('undefined', 'point', 'box', 'triangle', 'hermite', 'hanning', 'hamming', 'blackman', 'gaussian', 'quadratic', 'cubic', 'catrom', 'mitchell', 'jinc', 'sinc', 'sincfast', 'kaiser', 'welsh', 'parzen', 'bohman', 'bartlett', 'lagrange', 'lanczos', 'lanczossharp', 'lanczos2', 'lanczos2sharp', 'robidoux', 'robidouxsharp', 'cosine', 'spline', 'sentinel')¶ (
tuple
) The list of filter types.'undefined'
'point'
'box'
'triangle'
'hermite'
'hanning'
'hamming'
'blackman'
'gaussian'
'quadratic'
'cubic'
'catrom'
'mitchell'
'jinc'
'sinc'
'sincfast'
'kaiser'
'welsh'
'parzen'
'bohman'
'bartlett'
'lagrange'
'lanczos'
'lanczossharp'
'lanczos2'
'lanczos2sharp'
'robidoux'
'robidouxsharp'
'cosine'
'spline'
'sentinel'
See also
- ImageMagick Resize Filters
- Demonstrates the results of resampling images using the various resize filters and blur settings available in ImageMagick.
-
wand.image.
GRAVITY_TYPES
= ('forget', 'north_west', 'north', 'north_east', 'west', 'center', 'east', 'south_west', 'south', 'south_east', 'static')¶ (
tuple
) The list ofgravity
types.New in version 0.3.0.
-
wand.image.
IMAGE_TYPES
= ('undefined', 'bilevel', 'grayscale', 'grayscalematte', 'palette', 'palettematte', 'truecolor', 'truecolormatte', 'colorseparation', 'colorseparationmatte', 'optimize', 'palettebilevelmatte')¶ (
tuple
) The list of image types'undefined'
'bilevel'
'grayscale'
'grayscalematte'
'palette'
'palettematte'
'truecolor'
'truecolormatte'
'colorseparation'
'colorseparationmatte'
'optimize'
'palettebilevelmatte'
See also
- ImageMagick Image Types
- Describes the MagickSetImageType method which can be used to set the type of an image
-
wand.image.
ORIENTATION_TYPES
= ('undefined', 'top_left', 'top_right', 'bottom_right', 'bottom_left', 'left_top', 'right_top', 'right_bottom', 'left_bottom')¶ (
tuple
) The list oforientation
types.New in version 0.3.0.
-
wand.image.
UNIT_TYPES
= ('undefined', 'pixelsperinch', 'pixelspercentimeter')¶ (
tuple
) The list of resolution unit types.'undefined'
'pixelsperinch'
'pixelspercentimeter'
See also
- ImageMagick Image Units
- Describes the MagickSetImageUnits method which can be used to set image units of resolution
-
wand.image.
FUNCTION_TYPES
= ('undefined', 'polynomial', 'sinusoid', 'arcsin', 'arctan')¶ (
tuple
) The list ofImage.function
types.'undefined'
'polynomial'
'sinusoid'
'arcsin'
'arctan'
-
class
wand.image.
BaseImage
(wand)¶ The abstract base of
Image
(container) andSingleImage
. That means the most of operations, defined in this abstract classs, are possible for bothImage
andSingleImage
.New in version 0.3.0.
-
alpha_channel
¶ (
bool
) Get state of image alpha channel. It can also be used to enable/disable alpha channel, but with different behavior new, copied, or existing.Behavior of setting
alpha_channel
is defined with the following values:'activate'
,'on'
, orTrue
will enable an images- alpha channel. Existing alpha data is preserved.
'deactivate'
,'off'
, orFalse
will disable an images- alpha channel. Any data on the alpha will be preserved.
'associate'
&'disassociate'
toggle alpha channel flag in- certain image-file specifications.
'set'
enables and resets any data in an images alpha channel.'opaque'
enables alpha/matte channel, and forces full opaque- image.
'transparent'
enables alpha/matte channel, and forces full- transparent image.
'extract'
copies data in alpha channel across all other channels,- and disables alpha channel.
'copy'
calculates the gray-scale of RGB channels,- and applies it to alpha channel.
'shape'
is identical to'copy'
, but will color the resulting- image with the value defined with
background_color
.
'remove'
will compositebackground_color
value.'background'
replaces full-transparent color with background- color.
New in version 0.2.1.
Changed in version 0.4.1: Support for additional setting values. However
Image.alpha_channel
will continue to returnbool
if the current alpha/matte state is enabled.
-
animation
¶ (
bool
) Whether the image is animation or not. It doesn’t only mean that the image has two or more images (frames), but all frames are even the same size. It’s about image format, not content. It’sFalse
even if image/ico consits of two or more images of the same size.For example, it’s
False
for image/jpeg, image/gif, image/ico.If image/gif has two or more frames, it’s
True
. If image/gif has only one frame, it’sFalse
.New in version 0.3.0.
Changed in version 0.3.8: Became to accept image/x-gif as well.
-
background_color
¶ (
wand.color.Color
) The image background color. It can also be set to change the background color.New in version 0.1.9.
-
blur
(*args, **kwargs)¶ Blurs the image. We convolve the image with a gaussian operator of the given
radius
and standard deviation (sigma
). For reasonable results, theradius
should be larger thansigma
. Use aradius
of 0 andblur()
selects a suitableradius
for you.Parameters: - radius (
numbers.Real
) – the radius of the, in pixels, not counting the center pixel - sigma (
numbers.Real
) – the standard deviation of the, in pixels
New in version 0.4.5.
- radius (
-
caption
(*args, **kwargs)¶ Writes a caption
text
into the position.Parameters: - text (
basestring
) – text to write - left (
numbers.Integral
) – x offset in pixels - top (
numbers.Integral
) – y offset in pixels - width (
numbers.Integral
) – width of caption in pixels. default iswidth
of the image - height (
numbers.Integral
) – height of caption in pixels. default isheight
of the image - font (
wand.font.Font
) – font to use. default isfont
of the image - gravity (
basestring
) – text placement gravity. uses the currentgravity
setting of the image by default
New in version 0.3.0.
- text (
-
clone
()¶ Clones the image. It is equivalent to call
Image
withimage
parameter.with img.clone() as cloned: # manipulate the cloned image pass
Returns: the cloned new image Return type: Image
New in version 0.1.1.
-
colorspace
¶ (
basestring
) The image colorspace.Defines image colorspace as in
COLORSPACE_TYPES
enumeration.It may raise
ValueError
when the colorspace is unknown.New in version 0.3.4.
-
compare
(image, metric='undefined')¶ Compares an image to a reconstructed image.
Parameters: - image (
wand.image.Image
) – The reference image - metric (
basestring
) – The metric type to use for comparing.
Returns: The difference image(
wand.image.Image
), the computed distortion between the images (numbers.Integral
)Return type: ..versionadded:: 0.4.3
- image (
-
composite
(*args, **kwargs)¶ Places the supplied
image
over the current image, with the top left corner ofimage
at coordinatesleft
,top
of the current image. The dimensions of the current image are not changed.Parameters: - image (
wand.image.Image
) – the image placed over the current image - left (
numbers.Integral
) – the x-coordinate where image will be placed - top (
numbers.Integral
) – the y-coordinate where image will be placed
New in version 0.2.0.
- image (
-
composite_channel
(*args, **kwargs)¶ Composite two images using the particular
channel
.Parameters: - channel – the channel type. available values can be found
in the
CHANNELS
mapping - image (
Image
) – the composited source image. (the receiver image becomes the destination) - operator – the operator that affects how the composite
is applied to the image. available values
can be found in the
COMPOSITE_OPERATORS
list - left (
numbers.Integral
) – the column offset of the composited source image - top (
numbers.Integral
) – the row offset of the composited source image
Raises: ValueError – when the given
channel
oroperator
is invalidNew in version 0.3.0.
- channel – the channel type. available values can be found
in the
-
compression_quality
¶ (
numbers.Integral
) Compression quality of this image.New in version 0.2.0.
-
crop
(*args, **kwargs)¶ Crops the image in-place.
+--------------------------------------------------+ | ^ ^ | | | | | | top | | | | | | | v | | | <-- left --> +-------------------+ bottom | | | ^ | | | | | <-- width --|---> | | | | | height | | | | | | | | | | | v | | | | +-------------------+ v | | <--------------- right ----------> | +--------------------------------------------------+
Parameters: - left (
numbers.Integral
) – x-offset of the cropped image. default is 0 - top (
numbers.Integral
) – y-offset of the cropped image. default is 0 - right (
numbers.Integral
) – second x-offset of the cropped image. default is thewidth
of the image. this parameter andwidth
parameter are exclusive each other - bottom (
numbers.Integral
) – second y-offset of the cropped image. default is theheight
of the image. this parameter andheight
parameter are exclusive each other - width (
numbers.Integral
) – thewidth
of the cropped image. default is thewidth
of the image. this parameter andright
parameter are exclusive each other - height (
numbers.Integral
) – theheight
of the cropped image. default is theheight
of the image. this parameter andbottom
parameter are exclusive each other - reset_coords (
bool
) – optional flag. If set, after the rotation, the coordinate frame will be relocated to the upper-left corner of the new image. By default is True. - gravity (
GRAVITY_TYPES
) – optional flag. If set, will calculate thetop
andleft
attributes. This requires bothwidth
andheight
parameters to be included.
Raises: ValueError – when one or more arguments are invalid
Note
If you want to crop the image but not in-place, use slicing operator.
Changed in version 0.4.1: Added
gravity
option. Usinggravity
along withwidth
&height
to auto-adjustleft
&top
attributes.Changed in version 0.1.8: Made to raise
ValueError
instead ofIndexError
for invalidwidth
/height
arguments.New in version 0.1.7.
- left (
-
depth
¶ (
numbers.Integral
) The depth of this image.New in version 0.2.1.
-
distort
(*args, **kwargs)¶ Distorts an image using various distorting methods.
Parameters: - method (
basestring
) – Distortion method name fromDISTORTION_METHODS
- arguments (
collections.Sequence
) – List of distorting float arguments unique to distortion method - best_fit (
bool
) – Attempt to resize resulting image fit distortion. Defaults False
New in version 0.4.1.
- method (
-
equalize
(*args, **kwargs)¶ Equalizes the image histogram
New in version 0.3.10.
-
evaluate
(*args, **kwargs)¶ Apply arithmetic, relational, or logical expression to an image.
Percent values must be calculated against the quantum range of the image:
fifty_percent = img.quantum_range * 0.5 img.evaluate(operator='set', value=fifty_percent)
Parameters: - operator (
EVALUATE_OPS
) – Type of operation to calculate - value (
numbers.Real
) – Number to calculate withoperator
- channel (
CHANNELS
) – Optional channel to apply operation on.
Raises: - TypeError – When
value
is not numeric. - ValueError – When
operator
, orchannel
are not defined in constants.
New in version 0.4.1.
- operator (
-
extent
(*args, **kwargs)¶ extends the image as defined by the geometry, gravity, and wand background color. Set the (x,y) offset of the geometry to move the original wand relative to the extended wand.
Parameters: - width (
numbers.Integral
) – thewidth
of the extended image. default is thewidth
of the image. - height (
numbers.Integral
) – theheight
of the extended image. default is theheight
of the image. - x (
numbers.Integral
) – thex
offset of the extended image. default is 0 - y (
numbers.Integral
) – they
offset of the extended image. default is 0
New in version 0.4.5.
- width (
-
flip
(*args, **kwargs)¶ Creates a vertical mirror image by reflecting the pixels around the central x-axis. It manipulates the image in place.
New in version 0.3.0.
-
flop
(*args, **kwargs)¶ Creates a horizontal mirror image by reflecting the pixels around the central y-axis. It manipulates the image in place.
New in version 0.3.0.
-
font
¶ (
wand.font.Font
) The current font options.
-
font_path
¶ (
basestring
) The path of the current font. It also can be set.
-
font_size
¶ (
numbers.Real
) The font size. It also can be set.
-
frame
(*args, **kwargs)¶ Creates a bordered frame around image. Inner & outer bevel can simulate a 3D effect.
Parameters: - matte (
wand.color.Color
) – color of the frame - width (
numbers.Integral
) – total size of frame on x-axis - height (
numbers.Integral
) – total size of frame on y-axis - inner_bevel (
numbers.Real
) – inset shadow length - outer_bevel (
numbers.Real
) – outset highlight length
New in version 0.4.1.
- matte (
-
function
(*args, **kwargs)¶ Apply an arithmetic, relational, or logical expression to an image.
Defaults entire image, but can isolate affects to single color channel by passing
CHANNELS
value tochannel
parameter.Note
Support for function methods added in the following versions of ImageMagick.
'polynomial'
>= 6.4.8-8'sinusoid'
>= 6.4.8-8'arcsin'
>= 6.5.3-1'arctan'
>= 6.5.3-1
Parameters: - function (
basestring
) – a string listed inFUNCTION_TYPES
- arguments (
collections.Sequence
) – a sequence of doubles to apply againstfunction
- channel (
basestring
) – optionalCHANNELS
, defaults all
Raises: - ValueError – when a
function
, orchannel
is not defined in there respected constant - TypeError – if
arguments
is not a sequence
New in version 0.4.1.
-
fx
(*args, **kwargs)¶ Manipulate each pixel of an image by given expression.
FX will preserver current wand instance, and return a new instance of
Image
containing affected pixels.Defaults entire image, but can isolate affects to single color channel by passing
CHANNELS
value tochannel
parameter.See also
The anatomy of FX expressions can be found at http://www.imagemagick.org/script/fx.php
Parameters: - expression (
basestring
) – The entire FX expression to apply - channel (
CHANNELS
) – Optional channel to target.
Returns: A new instance of an image with expression applied
Return type: New in version 0.4.1.
- expression (
-
gaussian_blur
(*args, **kwargs)¶ Blurs the image. We convolve the image with a gaussian operator of the given
radius
and standard deviation (sigma
). For reasonable results, theradius
should be larger thansigma
. Use aradius
of 0 andblur()
selects a suitableradius
for you.Parameters: - radius (
numbers.Real
) – the radius of the, in pixels, not counting the center pixel - sigma (
numbers.Real
) – the standard deviation of the, in pixels
New in version 0.3.3.
- radius (
-
gravity
¶ (
basestring
) The text placement gravity used when annotating with text. It’s a string fromGRAVITY_TYPES
list. It also can be set.
-
height
¶ (
numbers.Integral
) The height of this image.
-
histogram
¶ (
HistogramDict
) The mapping that represents the histogram. Keys areColor
objects, and values are the number of pixels.New in version 0.3.0.
-
liquid_rescale
(*args, **kwargs)¶ Rescales the image with seam carving, also known as image retargeting, content-aware resizing, or liquid rescaling.
Parameters: - width (
numbers.Integral
) – the width in the scaled image - height (
numbers.Integral
) – the height in the scaled image - delta_x (
numbers.Real
) – maximum seam transversal step. 0 means straight seams. default is 0 - rigidity (
numbers.Real
) – introduce a bias for non-straight seams. default is 0
Raises: wand.exceptions.MissingDelegateError – when ImageMagick isn’t configured
--with-lqr
option.Note
This feature requires ImageMagick to be configured
--with-lqr
option. Or it will raiseMissingDelegateError
:See also
- Seam carving — Wikipedia
- The article which explains what seam carving is on Wikipedia.
- width (
-
matte_color
¶ (
wand.color.Color
) The color value of the matte channel. This can also be set...versionadded:: 0.4.1
-
merge_layers
(*args, **kwargs)¶ Composes all the image layers from the current given image onward to produce a single image of the merged layers.
The inital canvas’s size depends on the given ImageLayerMethod, and is initialized using the first images background color. The images are then compositied onto that image in sequence using the given composition that has been assigned to each individual image. The method must be set with a value from
IMAGE_LAYER_METHOD
that is acceptable to this operation. (See ImageMagick documentation for more details.)Parameters: method ( basestring
) – the method of selecting the size of the initial canvas.New in version 0.4.3.
-
modulate
(*args, **kwargs)¶ Changes the brightness, saturation and hue of an image. We modulate the image with the given
brightness
,saturation
andhue
.Parameters: - brightness (
numbers.Real
) – percentage of brightness - saturation (
numbers.Real
) – percentage of saturation - hue (
numbers.Real
) – percentage of hue rotation
Raises: ValueError – when one or more arguments are invalid
New in version 0.3.4.
- brightness (
-
negate
(grayscale=False, channel=None)¶ Negate the colors in the reference image.
Parameters: New in version 0.3.8.
-
options
= None¶ (
OptionDict
) The mapping of internal option settings.New in version 0.3.0.
Changed in version 0.3.4: Added
'jpeg:sampling-factor'
option.Changed in version 0.3.9: Added
'pdf:use-cropbox'
option.
-
orientation
¶ (
basestring
) The image orientation. It’s a string fromORIENTATION_TYPES
list. It also can be set.New in version 0.3.0.
-
page
¶ The dimensions and offset of this Wand’s page as a 4-tuple:
(width, height, x, y)
.Note that since it is based on the virtual canvas, it may not equal the dimensions of an image. See the ImageMagick documentation on the virtual canvas for more information.
New in version 0.4.3.
-
page_height
¶ (
numbers.Integral
) The height of the page for this wand.New in version 0.4.3.
-
page_width
¶ (
numbers.Integral
) The width of the page for this wand.New in version 0.4.3.
-
page_x
¶ (
numbers.Integral
) The X-offset of the page for this wand.New in version 0.4.3.
-
page_y
¶ (
numbers.Integral
) The Y-offset of the page for this wand.New in version 0.4.3.
-
quantize
(*args, **kwargs)¶ quantize analyzes the colors within a sequence of images and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the color difference between the input and output image while minimizing the processing time.
Parameters: - number_colors (
numbers.Integral
) – the number of colors. - colorspace_type (
basestring
) – colorspace_type. available value can be found in theCOLORSPACE_TYPES
- treedepth (
numbers.Integral
) – normally, this integer value is zero or one. a zero or one tellsquantize()
to choose a optimal tree depth oflog4(number_colors)
. a tree of this depth generally allows the best representation of the reference image with the least amount of memory and the fastest computational speed. in some cases, such as an image with low color dispersion (a few number of colors), a value other thanlog4(number_colors)
is required. to expand the color tree completely, use a value of 8 - dither (
bool
) – a value other than zero distributes the difference between an original image and the corresponding color reduced algorithm to neighboring pixels along a Hilbert curve - measure_error (
bool
) – a value other than zero measures the difference between the original and quantized images. this difference is the total quantization error. The error is computed by summing over all pixels in an image the distance squared in RGB space between each reference pixel value and its quantized value
New in version 0.4.2.
- number_colors (
-
quantum_range
¶ (
int
) The maxumim value of a color channel that is supported by the imagemagick library.New in version 0.2.0.
-
resample
(*args, **kwargs)¶ Adjust the number of pixels in an image so that when displayed at the given Resolution or Density the image will still look the same size in real world terms.
Parameters: - x_res (
numbers.Real
) – the X resolution (density) in the scaled image. default is the original resolution. - y_res (
numbers.Real
) – the Y resolution (density) in the scaled image. default is the original resolution. - filter (
basestring
,numbers.Integral
) – a filter type to use for resizing. choose one inFILTER_TYPES
. default is'undefined'
which means IM will try to guess best one to use. - blur (
numbers.Real
) – the blur factor where > 1 is blurry, < 1 is sharp. default is 1
New in version 0.4.5.
- x_res (
-
reset_coords
()¶ Reset the coordinate frame of the image so to the upper-left corner is (0, 0) again (crop and rotate operations change it).
New in version 0.2.0.
-
resize
(*args, **kwargs)¶ Resizes the image.
Parameters: - width (
numbers.Integral
) – the width in the scaled image. default is the original width - height (
numbers.Integral
) – the height in the scaled image. default is the original height - filter (
basestring
,numbers.Integral
) – a filter type to use for resizing. choose one inFILTER_TYPES
. default is'undefined'
which means IM will try to guess best one to use - blur (
numbers.Real
) – the blur factor where > 1 is blurry, < 1 is sharp. default is 1
Changed in version 0.2.1: The default value of
filter
has changed from'triangle'
to'undefined'
instead.Changed in version 0.1.8: The
blur
parameter changed to takenumbers.Real
instead ofnumbers.Rational
.New in version 0.1.1.
- width (
-
rotate
(*args, **kwargs)¶ Rotates the image right. It takes a
background
color fordegree
that isn’t a multiple of 90.Parameters: - degree (
numbers.Real
) – a degree to rotate. multiples of 360 affect nothing - background (
wand.color.Color
) – an optional background color. default is transparent - reset_coords (
bool
) – optional flag. If set, after the rotation, the coordinate frame will be relocated to the upper-left corner of the new image. By default is True.
New in version 0.2.0: The
reset_coords
parameter.New in version 0.1.8.
- degree (
-
sample
(*args, **kwargs)¶ Resizes the image by sampling the pixels. It’s basically quicker than
resize()
except less quality as a tradeoff.Parameters: - width (
numbers.Integral
) – the width in the scaled image. default is the original width - height (
numbers.Integral
) – the height in the scaled image. default is the original height
New in version 0.3.4.
- width (
-
sequence
= None¶ (
collections.Sequence
) The list ofSingleImage
s that the image contains.New in version 0.3.0.
-
threshold
(*args, **kwargs)¶ Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image. It manipulates the image in place.
Parameters: - threshold (
numbers.Real
) – threshold as a factor of quantum - channel (
basestring
) – the channel type. available values can be found in theCHANNELS
mapping. IfNone
, threshold all channels.
New in version 0.3.10.
- threshold (
-
transform
(*args, **kwargs)¶ Transforms the image using
MagickTransformImage()
, which is a convenience function accepting geometry strings to perform cropping and resizing. Cropping is performed first, followed by resizing. Either or both arguments may be omitted or given an empty string, in which case the corresponding action will not be performed. Geometry specification strings are defined as follows:A geometry string consists of a size followed by an optional offset. The size is specified by one of the options below, where bold terms are replaced with appropriate integer values:
- scale
%
- Height and width both scaled by specified percentage
- scale-x
%x
scale-y%
- Height and width individually scaled by specified percentages. Only one % symbol is needed.
- width
- Width given, height automagically selected to preserve aspect ratio.
x
height- Height given, width automagically selected to preserve aspect ratio.
- width
x
height - Maximum values of width and height given; aspect ratio preserved.
- width
x
height!
- Width and height emphatically given; original aspect ratio ignored.
- width
x
height>
- Shrinks images with dimension(s) larger than the corresponding width and/or height dimension(s).
- width
x
height<
- Enlarges images with dimensions smaller than the corresponding width and/or height dimension(s).
- area
@
- Resize image to have the specified area in pixels. Aspect ratio is preserved.
The offset, which only applies to the cropping geometry string, is given by
{+-}
x{+-}
y, that is, one plus or minus sign followed by an x offset, followed by another plus or minus sign, followed by a y offset. Offsets are in pixels from the upper left corner of the image. Negative offsets will cause the corresponding number of pixels to be removed from the right or bottom edge of the image, meaning the cropped size will be the computed size minus the absolute value of the offset.For example, if you want to crop your image to 300x300 pixels and then scale it by 2x for a final size of 600x600 pixels, you can call:
image.transform('300x300', '200%')
This method is a fairly thing wrapper for the C API, and does not perform any additional checking of the parameters except insofar as verifying that they are of the correct type. Thus, like the C API function, the method is very permissive in terms of what it accepts for geometry strings; unrecognized strings and trailing characters will be ignored rather than raising an error.
Parameters: - crop (
basestring
) – A geometry string defining a subregion of the image to crop to - resize (
basestring
) – A geometry string defining the final size of the image
See also
- ImageMagick Geometry Specifications
- Cropping and resizing geometry for the
transform
method are specified according to ImageMagick’s geometry string format. The ImageMagick documentation provides more information about geometry strings.
New in version 0.2.2.
- scale
-
transform_colorspace
(*args, **kwargs)¶ Transform image’s colorspace.
Parameters: colorspace_type ( basestring
) – colorspace_type. available value can be found in theCOLORSPACE_TYPES
New in version 0.4.2.
-
transparent_color
(*args, **kwargs)¶ Makes the color
color
a transparent color with a tolerance of fuzz. Thealpha
parameter specify the transparency level and the parameterfuzz
specify the tolerance.Parameters: - color (
wand.color.Color
) – The color that should be made transparent on the image, color object - alpha (
numbers.Real
) – the level of transparency: 1.0 is fully opaque and 0.0 is fully transparent. - fuzz (
numbers.Integral
) – By default target must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color for the color. - invert (
bool
) – Boolean to tell to paint the inverse selection.
New in version 0.3.0.
- color (
-
transparentize
(*args, **kwargs)¶ Makes the image transparent by subtracting some percentage of the black color channel. The
transparency
parameter specifies the percentage.Parameters: transparency ( numbers.Real
) – the percentage fade that should be performed on the image, from 0.0 to 1.0New in version 0.2.0.
-
type
¶ (
basestring
) The image type.Defines image type as in
IMAGE_TYPES
enumeration.It may raise
ValueError
when the type is unknown.New in version 0.2.2.
-
units
¶ (
basestring
) The resolution units of this image.
-
unsharp_mask
(*args, **kwargs)¶ Sharpens the image using unsharp mask filter. We convolve the image with a Gaussian operator of the given
radius
and standard deviation (sigma
). For reasonable results,radius
should be larger thansigma
. Use a radius of 0 andunsharp_mask()
selects a suitable radius for you.Parameters: - radius (
numbers.Real
) – the radius of the Gaussian, in pixels, not counting the center pixel - sigma (
numbers.Real
) – the standard deviation of the Gaussian, in pixels - amount (
numbers.Real
) – the percentage of the difference between the original and the blur image that is added back into the original - threshold (
numbers.Real
) – the threshold in pixels needed to apply the diffence amount
New in version 0.3.4.
- radius (
-
virtual_pixel
¶ (
basestring
) The virtual pixel of image. This can also be set with a value fromVIRTUAL_PIXEL_METHOD
… versionadded:: 0.4.1
-
wand
¶ Internal pointer to the MagickWand instance. It may raise
ClosedImageError
when the instance has destroyed already.
-
watermark
(*args, **kwargs)¶ Transparentized the supplied
image
and places it over the current image, with the top left corner ofimage
at coordinatesleft
,top
of the current image. The dimensions of the current image are not changed.Parameters: - image (
wand.image.Image
) – the image placed over the current image - transparency (
numbers.Real
) – the percentage fade that should be performed on the image, from 0.0 to 1.0 - left (
numbers.Integral
) – the x-coordinate where image will be placed - top (
numbers.Integral
) – the y-coordinate where image will be placed
New in version 0.2.0.
- image (
-
width
¶ (
numbers.Integral
) The width of this image.
-
-
class
wand.image.
ChannelDepthDict
(image)¶ The mapping table of channels to their depth.
Parameters: image ( Image
) – an image instanceNote
You don’t have to use this by yourself. Use
Image.channel_depths
property instead.New in version 0.3.0.
-
class
wand.image.
ChannelImageDict
(image)¶ The mapping table of separated images of the particular channel from the image.
Parameters: image ( Image
) – an image instanceNote
You don’t have to use this by yourself. Use
Image.channel_images
property instead.New in version 0.3.0.
-
exception
wand.image.
ClosedImageError
¶ An error that rises when some code tries access to an already closed image.
-
class
wand.image.
HistogramDict
(image)¶ Specialized mapping object to represent color histogram. Keys are colors, and values are the number of pixels.
Parameters: image ( BaseImage
) – the image to get its histogramNew in version 0.3.0.
-
class
wand.image.
Image
(image=None, blob=None, file=None, filename=None, format=None, width=None, height=None, depth=None, background=None, resolution=None)¶ An image object.
Parameters: - image (
Image
) – makes an exact copy of theimage
- blob (
bytes
) – opens an image of theblob
byte array - file (file object) – opens an image of the
file
object - filename (
basestring
) – opens an image of thefilename
string - format (
basestring
) – forces filename to buffer.format
to help imagemagick detect the file format. Used only inblob
orfile
cases - width (
numbers.Integral
) – the width of new blank image or an image loaded from raw data. - height (
numbers.Integral
) – the height of new blank imgage or an image loaded from raw data. - depth (
numbers.Integral
) – the depth used when loading raw data. - background (
wand.color.Color
) – an optional background color. default is transparent - resolution (
collections.Sequence
,numbers.Integral
) – set a resolution value (dpi), useful for vectorial formats (like pdf)
New in version 0.1.5: The
file
parameter.New in version 0.1.1: The
blob
parameter.New in version 0.2.1: The
format
parameter.New in version 0.2.2: The
width
,height
,background
parameters.New in version 0.3.0: The
resolution
parameter.New in version 0.4.2: The
depth
parameter.Changed in version 0.4.2: The
depth
,width
andheight
parameters can be used with thefilename
,file
andblob
parameters to load raw pixel data.-
[left:right, top:bottom]
Crops the image by its
left
,right
,top
andbottom
, and then returns the cropped one.with img[100:200, 150:300] as cropped: # manipulated the cropped image pass
Like other subscriptable objects, default is 0 or its width/height:
img[:, :] #--> just clone img[:100, 200:] #--> equivalent to img[0:100, 200:img.height]
Negative integers count from the end (width/height):
img[-70:-50, -20:-10] #--> equivalent to img[width-70:width-50, height-20:height-10]
Returns: the cropped image Rtype: Image
New in version 0.1.2.
-
auto_orient
(*args, **kwargs)¶ Adjusts an image so that its orientation is suitable for viewing (i.e. top-left orientation). If available it uses
MagickAutoOrientImage()
(was added in ImageMagick 6.8.9+) if you have an older magick library, it will use_auto_orient()
method for fallback.New in version 0.4.1.
-
blank
(width, height, background=None)¶ Creates blank image.
Parameters: - width (
numbers.Integral
) – the width of new blank image. - height (
numbers.Integral
) – the height of new blank imgage. - background (
wand.color.Color
) – an optional background color. default is transparent
Returns: blank image
Return type: New in version 0.3.0.
- width (
-
border
(color, width, height)¶ Surrounds the image with a border.
Parameters: - bordercolor – the border color pixel wand
- width (
numbers.Integral
) – the border width - height (
numbers.Integral
) – the border height
New in version 0.3.0.
-
channel_depths
= None¶ (
ChannelDepthDict
) The mapping of channels to their depth. Read only.New in version 0.3.0.
-
channel_images
= None¶ (
ChannelImageDict
) The mapping of separated channels from the image.with image.channel_images['red'] as red_image: display(red_image)
-
clear
()¶ Clears resources associated with the image, leaving the image blank, and ready to be used with new image.
New in version 0.3.0.
-
close
()¶ Closes the image explicitly. If you use the image object in
with
statement, it was called implicitly so don’t have to call it.Note
It has the same functionality of
destroy()
method.
-
compression
¶ (
basestring
) The type of image compression. It’s a string fromCOMPRESSION_TYPES
list. It also can be set.New in version 0.3.6.
-
contrast_stretch
(*args, **kwargs)¶ Enhance contrast of image by adjusting the span of the available colors.
If only
black_point
is given, match the CLI behavior by assuming thewhite_point
has the same delta percentage off the top e.g. contrast stretch of 15% is calculated asblack_point
= 0.15 andwhite_point
= 0.85.Parameters: - black_point (
numbers.Real
) – black point between 0.0 and 1.0. default is 0.0 - white_point (
numbers.Real
) – white point between 0.0 and 1.0. default value of 1.0 minusblack_point
- channel (
CHANNELS
) – optional color channel to apply contrast stretch
Raises: ValueError – if
channel
is not inCHANNELS
New in version 0.4.1.
- black_point (
-
convert
(format)¶ Converts the image format with the original image maintained. It returns a converted image instance which is new.
with img.convert('png') as converted: converted.save(filename='converted.png')
Parameters: format ( basestring
) – image format to convert toReturns: a converted image Return type: Image
Raises: ValueError – when the given format
is unsupportedNew in version 0.1.6.
-
destroy
()¶ Manually remove
SingleImage
’s in theSequence
, allowing it to be properly garbage collected after using awith Image()
context manager.
-
format
¶ (
basestring
) The image format.If you want to convert the image format, just reset this property:
assert isinstance(img, wand.image.Image) img.format = 'png'
It may raise
ValueError
when the format is unsupported.See also
- ImageMagick Image Formats
- ImageMagick uses an ASCII string known as magick (e.g.
GIF
) to identify file formats, algorithms acting as formats, built-in patterns, and embedded profile types.
New in version 0.1.6.
-
gamma
(*args, **kwargs)¶ Gamma correct image.
Specific color channels can be correct individual. Typical values range between 0.8 and 2.3.
Parameters: - adjustment_value (
numbers.Real
) – value to adjust gamma level - channel (
basestring
) – optional channel to apply gamma correction
Raises: - TypeError – if
gamma_point
is not anumbers.Real
- ValueError – if
channel
is not inCHANNELS
New in version 0.4.1.
- adjustment_value (
-
level
(black=0.0, white=None, gamma=1.0, channel=None)¶ Adjusts the levels of an image by scaling the colors falling between specified black and white points to the full available quantum range.
If only
black
is given,white
will be adjusted inward.Parameters: - black (
numbers.Real
) – Black point, as a percentage of the system’s quantum range. Defaults to 0. - white (
numbers.Real
) – White point, as a percentage of the system’s quantum range. Defaults to 1.0. - gamma (
numbers.Real
) – Optional gamma adjustment. Values > 1.0 lighten the image’s midtones while values < 1.0 darken them. - channel (
CHANNELS
) – The channel type. Available values can be found in theCHANNELS
mapping. IfNone
, normalize all channels.
New in version 0.4.1.
- black (
-
linear_stretch
(*args, **kwargs)¶ Enhance saturation intensity of an image.
Parameters: - black_point (
numbers.Real
) – Black point between 0.0 and 1.0. Default 0.0 - white_point (
numbers.Real
) – White point between 0.0 and 1.0. Default 1.0
New in version 0.4.1.
- black_point (
-
make_blob
(format=None)¶ Makes the binary string of the image.
Parameters: format ( basestring
) – the image format to write e.g.'png'
,'jpeg'
. it is omittableReturns: a blob (bytes) string Return type: bytes
Raises: ValueError – when format
is invalidChanged in version 0.1.6: Removed a side effect that changes the image
format
silently.New in version 0.1.5: The
format
parameter became optional.New in version 0.1.1.
-
mimetype
¶ (
basestring
) The MIME type of the image e.g.'image/jpeg'
,'image/png'
.New in version 0.1.7.
-
normalize
(channel=None)¶ Normalize color channels.
Parameters: channel ( basestring
) – the channel type. available values can be found in theCHANNELS
mapping. IfNone
, normalize all channels.
-
read
(file=None, filename=None, blob=None, resolution=None)¶ Read new image into Image() object.
Parameters: - blob (
bytes
) – reads an image from theblob
byte array - file (file object) – reads an image from the
file
object - filename (
basestring
) – reads an image from thefilename
string - resolution (
collections.Sequence
,numbers.Integral
) – set a resolution value (DPI), useful for vectorial formats (like PDF)
New in version 0.3.0.
- blob (
-
save
(file=None, filename=None)¶ Saves the image into the
file
orfilename
. It takes only one argument at a time.Parameters: - file (file object) – a file object to write to
- filename (
basestring
) – a filename string to write to
New in version 0.1.5: The
file
parameter.New in version 0.1.1.
-
strip
()¶ Strips an image of all profiles and comments.
New in version 0.2.0.
-
transpose
(*args, **kwargs)¶ Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them 90-degrees.
New in version 0.4.1.
-
transverse
(*args, **kwargs)¶ Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them 270-degrees.
New in version 0.4.1.
-
trim
(color=None, fuzz=0)¶ Remove solid border from image. Uses top left pixel as a guide by default, or you can also specify the
color
to remove.Parameters: - color (
Color
) – the border color to remove. if it’s omitted top left pixel is used by default - fuzz (
numbers.Integral
) – Defines how much tolerance is acceptable to consider two colors as the same.
New in version 0.3.0: Optional
color
andfuzz
parameters.New in version 0.2.1.
- color (
- image (
-
class
wand.image.
ImageProperty
(image)¶ The mixin class to maintain a weak reference to the parent
Image
object.New in version 0.3.0.
-
image
¶ (
Image
) The parent image.It ensures that the parent
Image
, which is held in a weak reference, still exists. Returns the dereferencedImage
if it does exist, or raises aClosedImageError
otherwise.Exc: ClosedImageError when the parent Image has been destroyed
-
-
class
wand.image.
Iterator
(image=None, iterator=None)¶ Row iterator for
Image
. It shouldn’t be instantiated directly; instead, it can be acquired throughImage
instance:assert isinstance(image, wand.image.Image) iterator = iter(image)
It doesn’t iterate every pixel, but rows. For example:
for row in image: for col in row: assert isinstance(col, wand.color.Color) print(col)
Every row is a
collections.Sequence
which consists of one or morewand.color.Color
values.Parameters: image ( Image
) – the image to get an iteratorNew in version 0.1.3.
-
clone
()¶ Clones the same iterator.
-
-
class
wand.image.
Metadata
(image)¶ Class that implements dict-like read-only access to image metadata like EXIF or IPTC headers.
Parameters: image ( Image
) – an image instanceNote
You don’t have to use this by yourself. Use
Image.metadata
property instead.New in version 0.3.0.
-
class
wand.image.
OptionDict
(image)¶ Mutable mapping of the image internal options. See available options in
OPTIONS
constant.New in version 0.3.0.
-
wand.image.
manipulative
(function)¶ Mark the operation manipulating itself instead of returning new one.