Internal API¶
pymaging.image
¶
-
class
pymaging.image.
Image
(mode, width, height, loader, meta=None)¶ The image class. This is the core class of pymaging.
Parameters: - mode – The color mode. A
pymaging.colors.ColorType
instance. - width – Width of the image (in pixels).
- height – Height of the image (in pixels).
- loader – A callable which when called returns a tuple containing a
pymaging.pixelarray.GenericPixelArray
instance and a palette (which can beNone
). If you already have all the pixels for your image loaded, usepymaging.image.LoadedImage
instead. - meta – Any further information your format wants to pass along. Your format should document what users can
expect in
meta
.
-
mode
¶ The color mode used in this image. A
pymaging.colors.ColorType
instance.
-
palette
¶ The palette used in this image. A list of
pymaging.colors.Color
instances orNone
.
-
reverse_palette
¶ Cache for
get_reverse_palette()
.
-
pixels
¶ The
pymaging.pixelarray.GenericPixelArray
(or subclass thereof) instance holding the image data.
-
width
¶ The width of the image (in pixels)
-
height
¶ The height of the image (in pixels)
-
pixelsize
¶ The size of a pixel (in
pixels
).1
usually indicates an image with a palette.3
is an standard RGB image.4
is a RGBA image.
-
classmethod
open
(fileobj)¶ Creates a new image from a file object
Parameters: fileobj – A file like object open for reading.
-
classmethod
open_from_path
(filepath)¶ Creates a new image from a file path
Parameters: fileobj – A string pointing at a image file.
-
classmethod
new
(mode, width, height, background_color, palette=None, meta=None)¶ Creates a new image with a solid background color.
Parameters: - mode – The color mode. Must be an instance of
pymaging.colors.ColorType
. - width – Width of the new image.
- height – Height of the new image.
- background_color – The color to use for the background. Must be an instance of
pymaging.colors.Color
. - palette – If given, the palette to use for the image.
- meta – Any further information your format wants to pass along. Your format should document what users can
expect in
meta
.
- mode – The color mode. Must be an instance of
-
save
(fileobj, format)¶ Saves the image.
Parameters: - fileobj – A file-like object (opened for writing) to which the image should be saved.
- format – The format to use for saving (as a string).
-
save_to_path(filepath, format=None):
Saves the image to a path.
Parameters: - filepath – A string pointing at a (writable) file location where the image should be saved.
- format – If given, the format (string) to use for saving. If
None
, the format will be guessed from the file extension used infilepath
.
-
get_reverse_palette
()¶ Returns
reverse_palette
. Ifreverse_palette
isNone
, calls_fill_reverse_palette()
. The reverse palette is a dictionary. If the image has no palette, an empty dictionary is returned.
-
_fill_reverse_palette
()¶ Populates the reverse palette, which is a mapping of
pymaging.colors.Color
instances to their index in the palette. Setsreverse_palette
.
-
_copy
(pixles, **kwargs)¶ Creates a copy of this instances meta information, but setting pixel array to
pixels
.kwargs
can override any argument to thepymaging.image.LoadedImage
constructor. By default the values of this image are used.This method is mostly used by other APIs that return a new copy of the image.
Returns a
pymaging.image.LoadedImage
.
-
resize
(width, height, resample_algorithm=nearest, resize_canvas=True)¶ Resizes the image to the given
width
andheight
, using givenresample_algorithm
. Ifresize_canvas
isFalse
, the actual image dimensions do not change, in which case the excess pixels will be filled by a background color (usually black). Returns the resized copy of this image.Parameters: - width – The new width as integer in pixels.
- height – The new height as integer in pixels.
- resample_algorithm – The resample algorithm to use. Should be a
pymaging.resample.Resampler
instance. - resize_canvas – Boolean flag whether to resize the canvas or not.
-
affine
(transform, resample_algorithm=nearest, resize_canvas=True)¶ Advanced version of
resize()
. Instead of aheight
andwidth
, apymaging.affine.AffineTransform
is passed according to which the image is transformed. Returns the transformed copy of the image.
-
rotate
(degrees, clockwise=False, resample_algorithm=nearest, resize_canvas=True)¶ Rotates the image by
degrees
degrees counter-clockwise (unlessclockwise
isTrue
). Interpolation of the pixels is done usingresample_algorithm
. Returns the rotated copy of this image.
-
get_pixel
(x, y)¶ Returns the pixel at the given
x
/y
location. If the pixel is outside the image, raises anIndexError
. If the image has a palette, the palette lookup will be performed by this method. The pixel is returned as a list if integers.
-
get_color
(x, y)¶ Same as
get_pixel()
but returns apymaging.colors.Color
instance.
-
set_color
(x, y, color)¶ The core drawing API. This should be used to draw pixels to the image. Sets the pixel at
x
/y
to the color given. The color should be apymaging.colors.Color
instance. If the image has a palette, only colors that are in the palette are supported.
-
flip_top_bottom
()¶ Vertically flips the image and returns the flipped copy.
-
flip_left_right
()¶ Horizontally flips the image and returns the flipped copy.
-
crop
(width, height, padding_top, padding_left)¶ Crops the pixel to the new
width
andheight
, starting the cropping at the offset given withpadding_top
andpadding_left
. Returns the cropped copy of this image.
-
draw
(shape, color)¶ Draws the shape using the given color to this image. The shape should be a
pymaging.shapes.BaseShape
subclass instance, or any object that has aiter_pixels
method, which when called with apymaging.colors.Color
instance, returns an iterator that yields tuples of(x, y, color)
of colors to be drawn to pixels.This method is just a shortcut around
set_color()
which allows users to write shape classes that do the heavy lifting for them.This method operates in place and does not return a copy of this image!
-
blit(padding_top, padding_left, image):
Draws the image passed in on top of this image at the location indicated with the padding.
This method operates in place and does not return a copy of this image!
- mode – The color mode. A
-
class
pymaging.image.
LoadedImage
(mode, width, height, pixels, palette=None, meta=None)¶ Subclass of
pymaging.image.Image
if you already have all pixels loaded. All parameters are the same as inpymaging.image.Image
except forloader
which is replaced withpixels
.pixels
must be an instance ofpymaging.pixelarray.GenericPixelArray
or a subclass thereof.
pymaging.affine
¶
-
class
pymaging.affine.
AffineTransform
(matrix)¶ Affine transformation matrix. Used by
pymaging.image.Image.affine()
.The matrix should be given either as a sequence of 9 values or a sequence of 3 sequences of 3 values.
Note
Needs documentation about the actual values of the matrix.
-
matrix
¶ Note
Needs documentation.
-
_determinant
()¶ Note
Needs documentation.
-
inverse
()¶ Note
Needs documentation.
-
rotate
(degrees, clockwise=False)¶ Note
Needs documentation.
-
scale
(x_factor, y_factor=None)¶ Note
Needs documentation.
-
translate
(dx, dy)¶ Note
Needs documentation.
-
pymaging.colors
¶
-
pymaging.colors.
_mixin_alpha
(colors, alpha)¶ Applies the given alpha value to all colors. Colors should be a list of three items:
r
,g
andb
.
-
class
pymaging.colors.
Color
(red, green, blue alpha)¶ Represents a color. All four parameters should be integers between 0 and 255.
-
red
¶
-
green
¶
-
blue
¶
-
alpha
¶
-
classmethod
from_hexcode
(hexcode)¶ Given a hexcode (a string of 3, 4, 6 or 8 characters, optionally prefixed by
'#'
), construct aColor
instance.
-
get_for_brightness
(brightness)¶ Given a brightness (alpha value) between 0 and 1, return the current color for that brightness.
-
cover_with
(cover_color)¶ Covers the current color with another color respecting their respective alpha values. If the
cover_color
is a solid color, return a copy of thecover_color
.cover_color
must be an instance ofColor
.
-
to_pixel
(pixelsize)¶ Returns this color as a pixel (list of integers) for the given
pixelsize
(3 or 4).
-
to_hexcode
()¶ Returns this color as RGBA hexcode. (Without leading
'#'
).
-
pymaging.exception
¶
-
exception
pymaging.exceptions.
PymagingExcpetion
¶ The root exception type for all exceptions defined in this module.
-
exception
pymaging.exceptions.
FormatNotSupported
¶ Raised if an image is saved or loaded in a format not supported by pymaging.
-
exception
pymaging.exceptions.
InvalidColor
¶ Raised if an invalid color is used on an image (usually when the image has a palette).
pymaging.formats
¶
Loads and maintains the formats supported in this installation.
-
class
pymaging.formats.
Format
(open, save, extensions)¶ A named tuple that should be used to define formats for pymaging.
open
andsave
are callables that decode and encode an image in this format.extensions
is a list of file extensions this image type could have.-
open
¶
-
save
¶
-
extensions
¶
-
-
class
pymaging.formats.
FormatRegistry
¶ A singleton class for format registration
-
_populate
()¶ Populates the registry using package resources.
-
get_format_objects
()¶ Returns all formats in this registry.
-
-
pymaging.formats.
registry
¶ The singleton instance of
FormatRegistry
.
-
pymaging.formats.
get_format_objects
()¶ Shortcut to
registry.get_format_objects
.
-
pymaging.formats.
get_format
()¶ Shortcut to
registry.get_format
.
-
pymaging.formats.
register
()¶ Shortcut to
registry.register
.
pymaging.helpers
¶
-
pymaging.helpers.
get_transformed_dimensions
(transform, box)¶ Takes an affine transform and a four-tuple of (x0, y0, x1, y1) coordinates. Transforms each corner of the given box, and returns the (width, height) of the transformed box.
pymaging.pixelarray
¶
-
class
pymaging.pixelarray.
GenericPixelArray
(data, width, height, pixelsize)¶ The base pixel array class.
data
should be a flatarray.array
instance of pixel data,width
andheight
are the dimensions of the array andpixelsize
defines how many items in thedata
array define a single pixel.Use
get_pixel_array()
to instantiate this class!-
data
¶ The image data as array.
-
width
¶ The width of the pixel array.
-
height
¶ The height of the pixel array.
-
pixelsize
¶ The size of a single pixel
-
size
¶ The size of the pixel array.
-
_precalculate
()¶ Precalculates
line_width
andsize
. Should be called wheneverwidth
,height
orpixelsize
change.
-
_translate
(x, y)¶ Translates the logical
x
/y
coordinates into the start of the pixel in the pixel array.
-
get
(x, y)¶ Returns the pixel at
x
/y
as list of integers.
-
set
(x, y, pixel)¶ Sets the
pixel
tox
/y
.
-
copy_flipped_top_bottom
()¶ Returns a copy of this pixel array with the lines flipped from top to bottom.
-
copy_flipped_left_right
()¶ Returns a copy of this pixel array with the lines flipped from left to right.
-
copy
()¶ Returns a copy of this pixel array.
-
remove_lines
(offset, amount)¶ Removes
amount
lines from this pixel array afteroffset
(from the top).
-
remove_columns
(offset, amount)¶ Removes
amount
columns from this pixel array afteroffset
(from the left).Note
If
remove_columns()
andremove_lines()
are used together,remove_lines()
should always be called first, as that method is a lot faster andremove_columns()
gets faster the fewer lines there are in a pixel array.
-
add_lines
(offset, amount, fill=0)¶ Adds
amount
lines to the pixel array afteroffset
(from the top) and fills it withfill
.
-
add_columns
(offset, amount, fill=0)¶ Adds
amount
columns to the pixel array afteroffset
(from the left) and fill it withfill
.Note
As with
remove_columns()
, the cost of this method grows with the amount of lines in the pixe array. If it is used together withadd_lines()
,add_columns()
should be called first.
-
-
class
pymaging.pixelarray.
PixelArray1
(data, width, height)¶ Subclass of
GenericPixelArray
, optimized for pixelsize 1.Use
get_pixel_array()
to instantiate this class!
-
class
pymaging.pixelarray.
PixelArray2
(data, width, height)¶ Subclass of
GenericPixelArray
, optimized for pixelsize 2.Use
get_pixel_array()
to instantiate this class!
-
class
pymaging.pixelarray.
PixelArray3
(data, width, height)¶ Subclass of
GenericPixelArray
, optimized for pixelsize 3.Use
get_pixel_array()
to instantiate this class!
-
class
pymaging.pixelarray.
PixelArray4
(data, width, height)¶ Subclass of
GenericPixelArray
, optimized for pixelsize 4.Use
get_pixel_array()
to instantiate this class!
-
pymaging.pixelarray.
get_pixel_array
(data, width, height, pixelsize)¶ Returns the most optimal pixel array class for the given pixelsize. Use this function instead of instantating the pixel array classes directly.
pymaging.resample
¶
-
class
pymaging.resample.
Resampler
¶ Base class for resampler algorithms. Should never be instantated directly.
-
affine
(source, transform, resize_canvas=True)¶ Note
Document.
-
resize
(source, width, height, resize_canvas=True)¶ Note
Document.
-
-
class
pymaging.resample.
Nearest
¶ Subclass of
Resampler
. Implements the nearest neighbor resampling algorithm which is very fast but creates very ugly resampling artifacts.
pymaging.shapes
¶
Shapes are the high level drawing API used by pymaging.image.Image.draw()
.
-
class
pymaging.shapes.
BaseShape
¶ Dummy base class for shapes.
-
iter_pixels
(color)¶ In subclasses, this is the API used by
pymaging.image.Image.draw()
to draw to an image. Should return an iterator that yieldsx
,y
,color
tuples.
-
-
class
pymaging.shapes.
Pixel
(x, y)¶ A simple single-pixel drawing object.
-
class
pymaging.shapes.
Line
(start_x, start_y, end_x, end_y)¶ Simple line drawing algorithm using the Bresenham Line Algorithm. Draws non-anti-aliased lines, which is very fast but for lines that are not exactly horizontal or vertical, this produces rather ugly lines.
pymaging.test_utils
¶
-
pymaging.test_utils.
image_factory
(colors, alpha=True)¶ Creates an image given a list of lists of
pymaging.color.Color
instances. Thealpha
parameter defines the pixel size of the image.
-
class
pymaging.test_utils.
PymagingBaseTestCase
¶ -
assertImage
(image, colors, alpha=True)¶ Checks that an image is the same as the dummy image given.
colors
andalpha
are passed toimage_factory()
to create a comparison image.
-
pymaging.utils
¶
-
pymaging.utils.
fdiv
(a, b)¶ Does a float division of
a
andb
regardless of their type and returns a float.
-
pymaging.utils.
get_test_file
(testfile, fname)¶ Returns the full path to a file for a given test.
pymaging.webcolors
¶
Defines constant pymaging.color.Color
instances for web colors.
-
pymaging.webcolors.
IndianRed
¶
-
pymaging.webcolors.
LightCoral
¶
-
pymaging.webcolors.
Salmon
¶
-
pymaging.webcolors.
DarkSalmon
¶
-
pymaging.webcolors.
LightSalmon
¶
-
pymaging.webcolors.
Red
¶
-
pymaging.webcolors.
Crimson
¶
-
pymaging.webcolors.
FireBrick
¶
-
pymaging.webcolors.
DarkRed
¶
-
pymaging.webcolors.
Pink
¶
-
pymaging.webcolors.
LightPink
¶
-
pymaging.webcolors.
HotPink
¶
-
pymaging.webcolors.
DeepPink
¶
-
pymaging.webcolors.
MediumVioletRed
¶
-
pymaging.webcolors.
PaleVioletRed
¶
-
pymaging.webcolors.
LightSalmon
-
pymaging.webcolors.
Coral
¶
-
pymaging.webcolors.
Tomato
¶
-
pymaging.webcolors.
OrangeRed
¶
-
pymaging.webcolors.
DarkOrange
¶
-
pymaging.webcolors.
Orange
¶
-
pymaging.webcolors.
Gold
¶
-
pymaging.webcolors.
Yellow
¶
-
pymaging.webcolors.
LightYellow
¶
-
pymaging.webcolors.
LemonChiffon
¶
-
pymaging.webcolors.
LightGoldenrodYellow
¶
-
pymaging.webcolors.
PapayaWhip
¶
-
pymaging.webcolors.
Moccasin
¶
-
pymaging.webcolors.
PeachPuff
¶
-
pymaging.webcolors.
PaleGoldenrod
¶
-
pymaging.webcolors.
Khaki
¶
-
pymaging.webcolors.
DarkKhaki
¶
-
pymaging.webcolors.
Lavender
¶
-
pymaging.webcolors.
Thistle
¶
-
pymaging.webcolors.
Plum
¶
-
pymaging.webcolors.
Violet
¶
-
pymaging.webcolors.
Orchid
¶
-
pymaging.webcolors.
Fuchsia
¶
-
pymaging.webcolors.
Magenta
¶
-
pymaging.webcolors.
MediumOrchid
¶
-
pymaging.webcolors.
MediumPurple
¶
-
pymaging.webcolors.
BlueViolet
¶
-
pymaging.webcolors.
DarkViolet
¶
-
pymaging.webcolors.
DarkOrchid
¶
-
pymaging.webcolors.
DarkMagenta
¶
-
pymaging.webcolors.
Purple
¶
-
pymaging.webcolors.
Indigo
¶
-
pymaging.webcolors.
DarkSlateBlue
¶
-
pymaging.webcolors.
SlateBlue
¶
-
pymaging.webcolors.
MediumSlateBlue
¶
-
pymaging.webcolors.
GreenYellow
¶
-
pymaging.webcolors.
Chartreuse
¶
-
pymaging.webcolors.
LawnGreen
¶
-
pymaging.webcolors.
Lime
¶
-
pymaging.webcolors.
LimeGreen
¶
-
pymaging.webcolors.
PaleGreen
¶
-
pymaging.webcolors.
LightGreen
¶
-
pymaging.webcolors.
MediumSpringGreen
¶
-
pymaging.webcolors.
SpringGreen
¶
-
pymaging.webcolors.
MediumSeaGreen
¶
-
pymaging.webcolors.
SeaGreen
¶
-
pymaging.webcolors.
ForestGreen
¶
-
pymaging.webcolors.
Green
¶
-
pymaging.webcolors.
DarkGreen
¶
-
pymaging.webcolors.
YellowGreen
¶
-
pymaging.webcolors.
OliveDrab
¶
-
pymaging.webcolors.
Olive
¶
-
pymaging.webcolors.
DarkOliveGreen
¶
-
pymaging.webcolors.
MediumAquamarine
¶
-
pymaging.webcolors.
DarkSeaGreen
¶
-
pymaging.webcolors.
LightSeaGreen
¶
-
pymaging.webcolors.
DarkCyan
¶
-
pymaging.webcolors.
Teal
¶
-
pymaging.webcolors.
Aqua
¶
-
pymaging.webcolors.
Cyan
¶
-
pymaging.webcolors.
LightCyan
¶
-
pymaging.webcolors.
PaleTurquoise
¶
-
pymaging.webcolors.
Aquamarine
¶
-
pymaging.webcolors.
Turquoise
¶
-
pymaging.webcolors.
MediumTurquoise
¶
-
pymaging.webcolors.
DarkTurquoise
¶
-
pymaging.webcolors.
CadetBlue
¶
-
pymaging.webcolors.
SteelBlue
¶
-
pymaging.webcolors.
LightSteelBlue
¶
-
pymaging.webcolors.
PowderBlue
¶
-
pymaging.webcolors.
LightBlue
¶
-
pymaging.webcolors.
SkyBlue
¶
-
pymaging.webcolors.
LightSkyBlue
¶
-
pymaging.webcolors.
DeepSkyBlue
¶
-
pymaging.webcolors.
DodgerBlue
¶
-
pymaging.webcolors.
CornflowerBlue
¶
-
pymaging.webcolors.
RoyalBlue
¶
-
pymaging.webcolors.
Blue
¶
-
pymaging.webcolors.
MediumBlue
¶
-
pymaging.webcolors.
DarkBlue
¶
-
pymaging.webcolors.
MidnightBlue
¶
-
pymaging.webcolors.
Cornsilk
¶
-
pymaging.webcolors.
BlanchedAlmond
¶
-
pymaging.webcolors.
Bisque
¶
-
pymaging.webcolors.
Wheat
¶
-
pymaging.webcolors.
BurlyWood
¶
-
pymaging.webcolors.
Tan
¶
-
pymaging.webcolors.
RosyBrown
¶
-
pymaging.webcolors.
SandyBrown
¶
-
pymaging.webcolors.
Goldenrod
¶
-
pymaging.webcolors.
DarkGoldenrod
¶
-
pymaging.webcolors.
Peru
¶
-
pymaging.webcolors.
Chocolate
¶
-
pymaging.webcolors.
SaddleBrown
¶
-
pymaging.webcolors.
Sienna
¶
-
pymaging.webcolors.
Brown
¶
-
pymaging.webcolors.
Maroon
¶
-
pymaging.webcolors.
White
¶
-
pymaging.webcolors.
Snow
¶
-
pymaging.webcolors.
Honeydew
¶
-
pymaging.webcolors.
MintCream
¶
-
pymaging.webcolors.
Azure
¶
-
pymaging.webcolors.
AliceBlue
¶
-
pymaging.webcolors.
GhostWhite
¶
-
pymaging.webcolors.
WhiteSmoke
¶
-
pymaging.webcolors.
Seashell
¶
-
pymaging.webcolors.
Beige
¶
-
pymaging.webcolors.
OldLace
¶
-
pymaging.webcolors.
FloralWhite
¶
-
pymaging.webcolors.
Ivory
¶
-
pymaging.webcolors.
AntiqueWhite
¶
-
pymaging.webcolors.
Linen
¶
-
pymaging.webcolors.
LavenderBlush
¶
-
pymaging.webcolors.
MistyRose
¶
-
pymaging.webcolors.
Gainsboro
¶
-
pymaging.webcolors.
LightGrey
¶
-
pymaging.webcolors.
Silver
¶
-
pymaging.webcolors.
DarkGray
¶
-
pymaging.webcolors.
Gray
¶
-
pymaging.webcolors.
DimGray
¶
-
pymaging.webcolors.
LightSlateGray
¶
-
pymaging.webcolors.
SlateGray
¶
-
pymaging.webcolors.
DarkSlateGray
¶
-
pymaging.webcolors.
Black
¶