[Python-3000] PEP 368: Standard image protocol and class (original) (raw)

Sun Jul 1 03:00:29 CEST 2007

The number of components per pixel (e.g. 4 for an RGBA image).
A tuple of strings; see the column "Component names" in the above
table.
8, 16 or 32; see "Bits per component" in the above table.
``components * bits_per_component // 8``, only available for non
planar modes (see below).
Boolean; ``True`` if the image components reside each in a
separate plane.  Currently this happens if and only if the mode
uses subsampling.
A tuple that for each component in the mode contains a tuple of
two integers that represent the amount of downsampling in the
horizontal and vertical direction, respectively.  In practice it's
``((1, 1), (2, 2), (2, 2))`` for ``YV12`` and ``JPEG_YV12`` and
``((1, 1),) * components`` for everything else.
``max(x for x, y in subsampling)``; the width of an image that
uses this mode must be divisible for this value.
``max(y for x, y in subsampling)``; the height of an image that
uses this mode must be divisible for this value.
A tuple that for each component in the mode contains a tuple of
two integers: the minimum and maximum valid value for the
component.  Its value is ``((16, 235), (16, 240), (16, 240))`` for
``YV12`` and ``((0, 2 ** bits_per_component - 1),) * components``
for everything else.
The parameter must be an iterable that contains two integers: the
width and height of an image; it returns the number of bytes
needed to store an image of these dimensions with this mode.
The format and the arrangement of the pixels in this image; it's
one of the constants in the ``MODES`` set.
An instance of the `ImageSize class`_; it's a named tuple of two
integers: the width and the height of the image in pixels; both of
them must be >= 1 and can also be accessed as the ``width`` and
``height`` attributes of ``size``.
A sequence of integers between 0 and 255; they are the actual
bytes used for storing the image data (i.e. modifying their values
affects the image pixels and vice versa); the data has a
row-major/C-contiguous order without padding and without any
special memory alignment, even when there are more than 8 bits per
component.  The only supported methods are ``__len__``,
``__getitem__``/``__setitem__`` (with both integers and slice
indexes) and ``__iter__``; on the C side it implements the buffer
protocol.

This is a pretty low level interface to the image and the user is
responsible for using the correct (native) byte order for modes
with more than 8 bit per component and the correct value ranges
for ``YV12`` images.  A buffer may or may not keep a reference to
its image, but it's still safe (if useless) to use the buffer even
after the corresponding image has been destroyed by the garbage
collector (this will require changes to the image class of
wxPython and possibly other libraries).  Implementation detail:
this can be an ``array('B')``, a ``bytes()`` object or a
specialized fixed-length type.
A ``dict`` object that can contain arbitrary metadata associated
with the image (e.g. DPI, gamma, ICC profile, exposure time...);
the interpretation of this data is beyond the scope of this PEP
and probably depends on the library used to create and/or to save
the image; if a method of the image returns a new image, it can
copy or adapt metadata from its own ``info`` attribute (the
``ImageMixin`` implementation always creates a new image with an
empty ``info`` dictionary).
Shortcuts for the corresponding ``mode.*`` attributes.
For every pixel in the image, maps each component through the
corresponding function.  If only one function is passed, it is
used repeatedly for each component.  This method modifies the
image **in place** and is usually very fast (most of the time the
functions are called only a small number of times, possibly only
once for simple functions without branches), but it imposes a
number of restrictions on the function(s) passed:

* it must accept a single integer argument and return a number
  (``map`` will round the result to the nearest integer and clip
  it to ``range(0, 2 ** bits_per_component)``, if necessary);

* it must *not* try to intercept any ``BaseException``,
  ``Exception`` or any unknown subclass of ``Exception`` raised by
  any operation on the argument (implementations may try to
  optimize the speed by passing funny objects, so even a simple
  ``"if n == 10:"`` may raise an exception: simply ignore it,
  ``map`` will take care of it); catching any other exception is
  fine;

* it should be side-effect free and its result should not depend
  on values (other than the argument) that may change during a
  single invocation of ``map``.
Return a copy of the image rotated 90, 180 or 270 degrees
counterclockwise around its center.
Saturates invalid component values in ``YV12`` images to the
minimum or the maximum allowed (see ``mode.intervals``), for other
image modes this method does nothing, very fast; libraries that
save/export ``YV12`` images are encouraged to always call this
method, since intermediate operations (e.g. the ``map`` method)
may assign to pixels values outside the valid intervals.
Returns a tuple of ``L``, ``L16`` or ``L32`` images corresponding
to the individual components in the image.
Returns an iterator that iterates over all the pixels in the
image, starting from the top line and scanning each line from left
to right.  See below for a description of the `pixel objects`_.
Returns an iterator that iterates over all the lines in the image,
from top to bottom.  See below for a description of the `line
objects`_.
Returns the number of lines in the image (``size.height``).
Returns the line at the specified (y) position.
The parameter must be a tuple of two integers; they are
interpreted respectively as x and y coordinates in the image (0, 0
is the top left corner) and a pixel object is returned.
The parameter must be a slice or a tuple that contains two slices
or an integer and a slice; the selected area of the image is
copied and a new image is returned; ``image[x:y:z]`` is equivalent
to ``image[:, x:y:z]``.
Modifies the pixel at specified position; ``image[x, y] =
integer`` is a shortcut for ``image[x, y] = (integer,)`` for
images with a single component.
Selects an area in the same way as the corresponding form of the
``__getitem__`` method and assigns to it a copy of the pixels from
the image in the second argument, that must have exactly the same
mode as this image and the same size as the specified area; the
alpha component, if present, is simply copied and doesn't affect
the other components of the image (i.e. no alpha compositing is
performed).
``mode`` must be one of the constants in the ``MODES`` set,
``size`` is a sequence of two integers (width and height of the
new image); ``color`` is a sequence of integers, one for each
component of the image, used to initialize all the pixels to the
same value; ``source`` can be a sequence of integers of the
appropriate size and format that is copied as-is in the buffer of
the new image or an existing image; in Python 2.x ``source`` can
also be an instance of ``str`` and is interpreted as a sequence of
bytes.  ``color`` and ``source`` are mutually exclusive and if
they are both omitted the image is initialized to transparent
black (all the bytes in the buffer have value 16 in the ``YV12``
mode, 255 in the ``CMYK*`` modes and 0 for everything else).  If
``source`` is present and is an image, ``mode`` and/or ``size``
can be omitted; if they are specified and are different from the
source mode and/or size, the source image is converted.

The exact algorithms used for resizing and doing color space
conversions may differ between Python versions and
implementations, but they always give high quality results (e.g.:
a cubic spline interpolation can be used for upsampling and an
antialias filter can be used for downsampling images); any
combination of mode conversion is supported, but the algorithm
used for conversions to and from the ``CMYK*`` modes is pretty
naïve: if you have the exact color profiles of your devices you
may want to use a good color management tool such as LittleCMS.
The new image has an empty ``info`` ``dict``.
The mode of the image from where this line comes.
Returns an iterator that iterates over all the pixels in the line,
from left to right.  See below for a description of the `pixel
objects`_.
Returns the number of pixels in the line (the image width).
Returns the pixel at the specified (x) position.
The selected part of the line is copied and a new image is
returned; the new image will always have height 1.
Modifies the pixel at the specified position; ``line[x] =
integer`` is a shortcut for ``line[x] = (integer,)`` for images
with a single component.
Selects a part of the line and assigns to it a copy of the pixels
from the image in the second argument, that must have height 1, a
width equal to the specified slice and the same mode as this line;
the alpha component, if present, is simply copied and doesn't
affect the other components of the image (i.e. no alpha
compositing is performed).
The mode of the image from where this pixel comes.
A tuple of integers, one for each component.  Any iterable of the
correct length can be assigned to ``value`` (it will be
automagically converted to a tuple), but you can't assign to it an
integer, even if the mode has only a single component: use, e.g.,
``pixel.l = 123`` instead.
The integer values of each component; only those applicable for
the current mode (in ``mode.component_names``) will be available.
These four methods emulate a fixed length list of integers, one
for each pixel component.
Returns true if the object ``obj`` is a valid image mode.
These functions are equivalent to their corresponding Python
attributes or methods.
Returns true if the object ``obj`` is an ``Image`` object or an
instance of a subtype of the ``Image`` type; see also
``PyObject_CheckImage`` below.
Returns true if the object ``obj`` is an ``Image`` object, but not
an instance of a subtype of the ``Image`` type.
Returns a new ``Image`` instance, initialized to transparent black
(see ``Image.__init__`` above for the details).
Returns a new ``Image`` instance, initialized with the contents of
the ``image`` object rescaled and converted to the specified
``mode``, if necessary.
Returns a new ``Image`` instance, initialized with the contents of
the ``buffer`` object.
Returns true if the object ``obj`` implements a sufficient subset
of the image protocol to be accepted by the functions defined
below, even if its class is not a subclass of ``ImageMixin``
and/or ``Image``.  Currently it simply checks for the existence
and correctness of the attributes ``mode``, ``size`` and
``buffer``.
These functions are equivalent to their corresponding Python
attributes or methods; the image memory can be accessed only with
the GIL and a reference to the image or its buffer held, and extra
care should be taken for modes with more than 8 bits per
component: the data is stored in native byte order and it can be
**not** aligned on 2 or 4 byte boundaries.
# create a new black RGB image of 6x9 pixels
rgb_image = imageop.Image(imageop.RGB, (6, 9))

# same as above, but initialize the image to bright red
rgb_image = imageop.Image(imageop.RGB, (6, 9), color=(255, 0, 0))

# convert the image to YCbCr
yuv_image = imageop.Image(imageop.JPEG_YV12, source=rgb_image)

# read the value of a pixel and split it into three ints
r, g, b = rgb_image[x, y]

# modify the magenta component of a pixel in a CMYK image
cmyk_image[x, y].m = 13

# modify the Y (luma) component of a pixel in a *YV12 image and
# its corresponding subsampled Cr (red chroma)
yuv_image.y[x, y] = 42
yuv_image.cr[x // 2, y // 2] = 54

# iterate over an image
for line in rgb_image:
    for pixel in line:
        # swap red and blue, and set green to 0
        pixel.value = pixel.b, 0, pixel.r

# find the maximum value of the red component in the image
max_red = max(pixel.r for pixel in rgb_image.pixels())

# count the number of colors in the image
num_of_colors = len(set(tuple(pixel) for pixel in image.pixels()))

# copy a block of 4x2 pixels near the upper right corner of an
# image and paste it into the lower left corner of the same image
image[:4, -2:] = image[-6:-2, 1:3]

# create a copy of the image, except that the new image can have a
# different (usually empty) info dict
new_image = image[:]

# create a mirrored copy of the image, with the left and right
# sides flipped
flipped_image = image[::-1, :]

# downsample an image to half its original size using a fast, low
# quality operation and a slower, high quality one:
low_quality_image = image[::2, ::2]
new_size = image.size.width // 2, image.size.height // 2
high_quality_image = imageop.Image(size=new_size, source=image)

# direct buffer access
rgb_image[0, 0] = r, g, b
assert tuple(rgb_image.buffer[:3]) == (r, g, b)

[Python-3000] PEP 368: Standard image protocol and class (original) (raw)

Abstract

Rationale

Specification

Python API

C API

Examples

Backwards Compatibility

Reference Implementation

Acknowledgments

Copyright