Pixmap

Pixmaps (“pixel maps”) are objects at the heart of MuPDF’s rendering capabilities. They represent plane rectangular sets of pixels. Each pixel is described by a number of bytes (“components”) defining its color, plus an optional alpha byte defining its transparency.

In PyMuPDF, there exist several ways to create a pixmap. Except the first one, all of them are available as overloaded constructors. A pixmap can be created …

  1. from a document page (method Page.get_pixmap())
  2. empty, based on Colorspace and IRect information
  3. from a file
  4. from an in-memory image
  5. from a memory area of plain pixels
  6. from an image inside a PDF document
  7. as a copy of another pixmap

Note

A number of image formats is supported as input for points 3. and 4. above. See section Supported Input Image Formats.

Have a look at the Collection of Recipes section to see some pixmap usage “at work”.

Method / Attribute Short Description
Pixmap.clear_with() clear parts of a pixmap
Pixmap.copy() copy parts of another pixmap
Pixmap.gamma_with() apply a gamma factor to the pixmap
Pixmap.tobytes() return a memory area in a variety of formats
Pixmap.invert_irect() invert the pixels of a given area
Pixmap.pil_save() save as image using pillow
Pixmap.pil_tobytes() write to bytes object using pillow
Pixmap.pixel() return the value of a pixel
Pixmap.set_alpha() set alpha values
Pixmap.set_pixel() set the color of a pixel
Pixmap.set_rect() set the color of a rectangle
Pixmap.set_dpi() set the image resolution
Pixmap.set_origin() set pixmap x,y values
Pixmap.shrink() reduce size keeping proportions
Pixmap.tint_with() tint a pixmap with a color
Pixmap.save() save a pixmap in a variety of formats
Pixmap.alpha transparency indicator
Pixmap.colorspace pixmap’s Colorspace
Pixmap.digest MD5 hashcode of the pixmap
Pixmap.height pixmap height
Pixmap.interpolate interpolation method indicator
Pixmap.irect IRect of the pixmap
Pixmap.n bytes per pixel
Pixmap.samples pixel area
Pixmap.size pixmap’s total length
Pixmap.stride size of one image row
Pixmap.width pixmap width
Pixmap.x X-coordinate of top-left corner
Pixmap.xres resolution in X-direction
Pixmap.y Y-coordinate of top-left corner
Pixmap.yres resolution in Y-direction

Class API

class Pixmap
__init__(self, colorspace, irect, alpha)

New empty pixmap: Create an empty pixmap of size and origin given by the rectangle. So, irect.top_left designates the top left corner of the pixmap, and its width and height are irect.width resp. irect.height. Note that the image area is not initialized and will contain crap data – use eg. clear_with() or set_rect() to be sure.

Parameters:
  • colorspace (Colorspace) – colorspace.
  • irect (irect_like) – Tte pixmap’s position and dimension.
  • alpha (bool) – Specifies whether transparency bytes should be included. Default is False.
__init__(self, colorspace, source)

Copy and set colorspace: Copy source pixmap converting colorspace. Any colorspace combination is possible, but source colorspace must not be None.

Parameters:
  • colorspace (Colorspace) – desired target colorspace. This may also be None. In this case, a “masking” pixmap is created: its Pixmap.samples will consist of the source’s alpha bytes only.
  • source (Pixmap) – the source pixmap.
__init__(self, source, width, height[, clip])

Copy and scale: Copy source pixmap, scaling new width and height values – the image will appear stretched or shrunk accordingly. Supports partial copying. The source colorspace may be None.

Parameters:
  • source (Pixmap) – the source pixmap.
  • width (float) – desired target width.
  • height (float) – desired target height.
  • clip (irect_like) – restrict the resulting pixmap to this region of the scaled pixmap.

Note

If width or height are not de facto integers (i.e. value.is_integer() != True), then the resulting pixmap will have an alpha channel.

__init__(self, source, alpha=1)

Copy and add or drop alpha: Copy source and add or drop its alpha channel. Identical copy if alpha equals source.alpha. If an alpha channel is added, its values will be set to 255.

Parameters:
  • source (Pixmap) – source pixmap.
  • alpha (bool) – whether the target will have an alpha channel, default and mandatory if source colorspace is None.

Note

A typical use includes separation of color and transparency bytes in separate pixmaps. Some applications require this like e.g. wx.Bitmap.FromBufferAndAlpha() of wxPython:

>>> # 'pix' is an RGBA pixmap
>>> pixcolors = fitz.Pixmap(pix, 0)    # extract the RGB part (drop alpha)
>>> pixalpha = fitz.Pixmap(None, pix)  # extract the alpha part
>>> bm = wx.Bitmap.FromBufferAndAlpha(pix.widht, pix.height, pixcolors.samples, pixalpha.samples)
__init__(self, filename)

From a file: Create a pixmap from filename. All properties are inferred from the input. The origin of the resulting pixmap is (0, 0).

Parameters:filename (str) – Path of the image file.
__init__(self, stream)

From memory: Create a pixmap from a memory area. All properties are inferred from the input. The origin of the resulting pixmap is (0, 0).

Parameters:stream (bytes,bytearray,BytesIO) –

Data containing a complete, valid image. Could have been created by e.g. stream = bytearray(open(‘image.file’, ‘rb’).read()). Type bytes is supported in Python 3 only, because bytes == str in Python 2 and the method will interpret the stream as a filename.

Changed in version 1.14.13: io.BytesIO is now also supported.

__init__(self, colorspace, width, height, samples, alpha)

From plain pixels: Create a pixmap from samples. Each pixel must be represented by a number of bytes as controlled by the colorspace and alpha parameters. The origin of the resulting pixmap is (0, 0). This method is useful when raw image data are provided by some other program – see Collection of Recipes.

Parameters:
  • colorspace (Colorspace) – Colorspace of image.
  • width (int) – image width
  • height (int) – image height
  • samples (bytes,bytearray,BytesIO) –

    an area containing all pixels of the image. Must include alpha values if specified.

    Changed in version 1.14.13: (1) io.BytesIO can now also be used. (2) Data are now copied to the pixmap, so may safely be deleted or become unavailable.

  • alpha (bool) – whether a transparency channel is included.

Note

  1. The following equation must be true: (colorspace.n + alpha) * width * height == len(samples).
  2. Starting with version 1.14.13, the samples data are copied to the pixmap.
__init__(self, doc, xref)

From a PDF image: Create a pixmap from an image contained in PDF doc identified by its xref. All pimap properties are set by the image. Have a look at extract-img1.py and extract-img2.py to see how this can be used to recover all of a PDF’s images.

Parameters:
  • doc (Document) – an opened PDF document.
  • xref (int) – the xref of an image object. For example, you can make a list of images used on a particular page with Document.get_page_images(), which also shows the xref numbers of each image.
clear_with([value[, irect]])

Initialize the samples area.

Parameters:
  • value (int) – if specified, values from 0 to 255 are valid. Each color byte of each pixel will be set to this value, while alpha will be set to 255 (non-transparent) if present. If omitted, then all bytes (including any alpha) are cleared to 0x00.
  • irect (irect_like) – the area to be cleared. Omit to clear the whole pixmap. Can only be specified, if value is also specified.
tint_with(red, green, blue)

Colorize (tint) a pixmap with a color provided as an integer triple (red, green, blue). Only colorspaces CS_GRAY and CS_RGB are supported, others are ignored with a warning.

If the colorspace is CS_GRAY, (red + green + blue)/3 will be taken as the tint value.

Parameters:
  • red (int) – red component.
  • green (int) – green component.
  • blue (int) – blue component.
gamma_with(gamma)

Apply a gamma factor to a pixmap, i.e. lighten or darken it. Pixmaps with colorspace None are ignored with a warning.

Parameters:gamma (float) – gamma = 1.0 does nothing, gamma < 1.0 lightens, gamma > 1.0 darkens the image.
shrink(n)

Shrink the pixmap by dividing both, its width and height by 2n.

Parameters:n (int) – determines the new pixmap (samples) size. For example, a value of 2 divides width and height by 4 and thus results in a size of one 16th of the original. Values less than 1 are ignored with a warning.

Note

Use this methods to reduce a pixmap’s size retaining its proportion. The pixmap is changed “in place”. If you want to keep original and also have more granular choices, use the resp. copy constructor above.

pixel(x, y)

New in version:: 1.14.5: Return the value of the pixel at location (x, y) (column, line).

Parameters:
  • x (int) – the column number of the pixel. Must be in range(pix.width).
  • y (int) – the line number of the pixel, Must be in range(pix.height).
Return type:

list

Returns:

a list of color values and, potentially the alpha value. Its length and content depend on the pixmap’s colorspace and the presence of an alpha. For RGBA pixmaps the result would e.g. be [r, g, b, a]. All items are integers in range(256).

set_pixel(x, y, color)

New in version 1.14.7: Set the color of the pixel at location (x, y) (column, line).

Parameters:
  • x (int) – the column number of the pixel. Must be in range(pix.width).
  • y (int) – the line number of the pixel. Must be in range(pix.height).
  • color (sequence) – the desired color given as a sequence of integers in range(256). The length of the sequence must equal Pixmap.n, which includes any alpha byte.
set_rect(irect, color)

New in version 1.14.8: Set the pixels of a rectangle to a color.

Parameters:
  • irect (irect_like) – the rectangle to be filled with the color. The actual area is the intersection of this parameter and Pixmap.irect. For an empty intersection (or an invalid parameter), no change will happen.
  • color (sequence) – the desired color given as a sequence of integers in range(256). The length of the sequence must equal Pixmap.n, which includes any alpha byte.
Return type:

bool

Returns:

False if the rectangle was invalid or had an empty intersection with Pixmap.irect, else True.

Note

  1. This method is equivalent to Pixmap.set_pixel() executed for each pixel in the rectangle, but is obviously very much faster if many pixels are involved.
  2. This method can be used similar to Pixmap.clear_with() to initialize a pixmap with a certain color like this: pix.set_rect(pix.irect, (255, 255, 0)) (RGB example, colors the complete pixmap with yellow).
set_origin(x, y)

(New in v1.17.7) Set the x and y values.

Parameters:
  • x (int) – x coordinate
  • y (int) – y coordinate
set_dpi(xres, yres)

(New in v1.16.17) Set the resolution (dpi) in x and y direction.

(Changed in v1.18.0) When saving as a PNG image, these values will be stored now.

Parameters:
  • xres (int) – resolution in x direction.
  • yres (int) – resolution in y direction.
set_alpha(alphavalues, premultiply=1, opaque=None)

(Changed in v 1.18.13)

Change the alpha values. The pixmap must have an alpha channel.

Parameters:
  • alphavalues (bytes,bytearray,BytesIO) – the new alpha values. If provided, its length must be at least width * height. If omitted (None), all alpha values are set to 255 (no transparency). Changed in version 1.14.13: io.BytesIO is now also accepted.
  • premultiply (bool) – New in v1.18.13: whether to premultiply color components with the alpha value.
  • opaque (list,tuple) – make this color fully invisible (transparent). A sequence of integers 0 <= i <= 255 with a length of Pixmap.n. Default is None. E.g. in the RGB case a typical choice would be opaque=(255, 255, 255) for white.
invert_irect([irect])

Invert the color of all pixels in IRect irect. Will have no effect if colorspace is None.

Parameters:irect (irect_like) – The area to be inverted. Omit to invert everything.
copy(source, irect)

Copy the irect part of the source pixmap into the corresponding area of this one. The two pixmaps may have different dimensions and can each have CS_GRAY or CS_RGB colorspaces, but they currently must have the same alpha property [2]. The copy mechanism automatically adjusts discrepancies between source and target like so:

If copying from CS_GRAY to CS_RGB, the source gray-shade value will be put into each of the three rgb component bytes. If the other way round, (r + g + b) / 3 will be taken as the gray-shade value of the target.

Between irect and the target pixmap’s rectangle, an “intersection” is calculated at first. This takes into account the rectangle coordinates and the current attribute values Pixmap.x and Pixmap.y (which you are free to modify for this purpose via Pixmap.set_origin()). Then the corresponding data of this intersection are copied. If the intersection is empty, nothing will happen.

Parameters:
  • source (Pixmap) – source pixmap.
  • irect (irect_like) – The area to be copied.
save(filename, output=None)

Save pixmap as an image file. Depending on the output chosen, only some or all colorspaces are supported and different file extensions can be chosen. Please see the table below. Since MuPDF v1.10a the savealpha option is no longer supported and will be silently ignored.

Parameters:
  • filename (str,Path,file) – The file to save to. May be provided as a string, as a pathlib.Path or as a Python file object. In the latter two cases, the filename is taken from the resp. object. The filename’s extension determines the image format, which can be overruled by the output parameter.
  • output (str) – The requested image format. The default is the filename’s extension. If not recognized, png is assumed. For other possible values see Supported Output Image Formats.
tobytes(output="png")

New in version 1.14.5: Return the pixmap as a bytes memory object of the specified format – similar to save().

Parameters:output (str) – The requested image format. The default is “png” for which this function equals tobytes(). For other possible values see Supported Output Image Formats.
Return type:bytes
pil_save(*args, **kwargs)

(New in v1.17.3)

Write the pixmap as an image file using Pillow. Use this method for output unsupported by MuPDF. Examples are

  • Formats JPEG, JPX, J2K, WebP, etc.
  • Storing EXIF information.
  • If you do not provide dpi information, the values xres, yres stored with the pixmap are automatically used.

A simple example: pix.pil_save("some.jpg", optimize=True, dpi=(150, 150)). For details on other parameters see the Pillow documentation.

Note

(Changed in v1.18.0) Pixmap.save() now also sets dpi from xres / yres automatically, when saving a PNG image.

If Pillow is not installed an ImportError exception is raised.

pil_tobytes(*args, **kwargs)

(New in v1.17.3)

Return an image as a bytes object in the specified format using Pillow. For example stream = pix.pil_tobytes(format="JPEG", optimize=True). Also see above. For details on other parameters see the Pillow documentation. If Pillow is not installed, an ImportError exception is raised.

Return type:bytes
alpha

Indicates whether the pixmap contains transparency information.

Type:bool
digest

The MD5 hashcode (16 bytes) of the pixmap. This is a technical value used for unique identifications.

Type:bytes
colorspace

The colorspace of the pixmap. This value may be None if the image is to be treated as a so-called image mask or stencil mask (currently happens for extracted PDF document images only).

Type:Colorspace
stride

Contains the length of one row of image data in Pixmap.samples. This is primarily used for calculation purposes. The following expressions are true:

  • len(samples) == height * stride
  • width * n == stride.
Type:int
irect

Contains the IRect of the pixmap.

Type:IRect
samples

The color and (if Pixmap.alpha is true) transparency values for all pixels. It is an area of width * height * n bytes. Each n bytes define one pixel. Each successive n bytes yield another pixel in scanline order. Subsequent scanlines follow each other with no padding. E.g. for an RGBA colorspace this means, samples is a sequence of bytes like …, R, G, B, A, …, and the four byte values R, G, B, A define one pixel.

This area can be passed to other graphics libraries like PIL (Python Imaging Library) to do additional processing like saving the pixmap in other image formats.

Note

  • The underlying data is a typically large memory area from which a bytes copy is made for this attribute: for example an RGB-rendered letter page has a samples size of almost 1.4 MB. So consider assigning a new variable if you repeatedly use it.
  • Any changes to the underlying data are available only after again accessing this attribute.
Type:bytes
size

Contains len(pixmap). This will generally equal len(pix.samples) plus some platform-specific value for defining other attributes of the object.

Type:int
width
w

Width of the region in pixels.

Type:int
height
h

Height of the region in pixels.

Type:int
x

X-coordinate of top-left corner in pixels. Cannot directly be changed – use Pixmap.set_origin().

Type:int
y

Y-coordinate of top-left corner in pixels. Cannot directly be changed – use Pixmap.set_origin().

Type:int
n

Number of components per pixel. This number depends on colorspace and alpha. If colorspace is not None (stencil masks), then Pixmap.n - Pixmap.aslpha == pixmap.colorspace.n is true. If colorspace is None, then n == alpha == 1.

Type:int
xres

Horizontal resolution in dpi (dots per inch). Please also see resolution. Cannot directly be changed – use Pixmap.set_dpi().

Type:int
yres

Vertical resolution in dpi (dots per inch). Please also see resolution. Cannot directly be changed – use Pixmap.set_dpi().

Type:int
interpolate

An information-only boolean flag set to True if the image will be drawn using “linear interpolation”. If False “nearest neighbour sampling” will be used.

Type:bool

Supported Input Image Formats

The following file types are supported as input to construct pixmaps: BMP, JPEG, GIF, TIFF, JXR, JPX, PNG, PAM and all of the Portable Anymap family (PBM, PGM, PNM, PPM). This support is two-fold:

  1. Directly create a pixmap with Pixmap(filename) or Pixmap(byterray). The pixmap will then have properties as determined by the image.
  2. Open such files with fitz.open(…). The result will then appear as a document containing one single page. Creating a pixmap of this page offers all the options available in this context: apply a matrix, choose colorspace and alpha, confine the pixmap to a clip area, etc.

SVG images are only supported via method 2 above, not directly as pixmaps. But remember: the result of this is a raster image as is always the case with pixmaps [1].

Supported Output Image Formats

A number of image output formats are supported. You have the option to either write an image directly to a file (Pixmap.save()), or to generate a bytes object (Pixmap.tobytes()). Both methods accept a 3-letter string identifying the desired format (Format column below). Please note that not all combinations of pixmap colorspace, transparency support (alpha) and image format are possible.

Format Colorspaces alpha Extensions Description
pam gray, rgb, cmyk yes .pam Portable Arbitrary Map
pbm gray, rgb no .pbm Portable Bitmap
pgm gray, rgb no .pgm Portable Graymap
png gray, rgb yes .png Portable Network Graphics
pnm gray, rgb no .pnm Portable Anymap
ppm gray, rgb no .ppm Portable Pixmap
ps gray, rgb, cmyk no .ps Adobe PostScript Image
psd gray, rgb, cmyk yes .psd Adobe Photoshop Document

Note

  • Not all image file types are supported (or at least common) on all OS platforms. E.g. PAM and the Portable Anymap formats are rare or even unknown on Windows.
  • Especially pertaining to CMYK colorspaces, you can always convert a CMYK pixmap to an RGB pixmap with rgb_pix = fitz.Pixmap(fitz.csRGB, cmyk_pix) and then save that in the desired format.
  • As can be seen, MuPDF’s image support range is different for input and output. Among those supported both ways, PNG is probably the most popular. We recommend using Pillow whenever you face a support gap.
  • We also recommend using “ppm” formats as input to tkinter’s PhotoImage method like this: tkimg = tkinter.PhotoImage(data=pix.tobytes(“ppm”)) (also see the tutorial). This is very fast (60 times faster than PNG) and will work under Python 2 or 3.

Footnotes

[1]If you need a vector image from the SVG, you must first convert it to a PDF. Try Document.convert_to_pdf(). If this is not good enough, look for other SVG-to-PDF conversion tools like the Python packages svglib, CairoSVG, Uniconvertor or the Java solution Apache Batik. Have a look at our Wiki for more examples.
[2]To also set the alpha property, add an additional step to this method by dropping or adding an alpha channel to the result.