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”) plus an (optional since v1.10.0) alpha byte.

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

1. from a document page (via methods Page.getPixmap() or Document.getPagePixmap())
2. empty based on Colorspace and IRect information
3. from an image file
4. from an in-memory image (bytearray)
5. from a memory area of plain pixels
6. from an image inside a PDF document
7. as a copy of another pixmap

Have a look at the example section to see some pixmap usage “at work”.

Class API

class Pixmap

__init__(self, colorspace, irect, alpha)

Empty pixmap: Create an empty pixmap of size and origin given by a rectangle. So, for a fitz.IRect(x0, y0, x1, y1), fitz.Point(x0, y0) designates the top left corner of the pixmap. Note that the image area is not initialized and will contain crap data.

Parameters:	colorspace (Colorspace) – colorspace of the pixmap. irect (IRect) – Tte pixmap’s area and location. alpha (bool) – Specifies whether transparency bytes should be included. Default is False.

__init__(self, colorspace, source[, alpha])

Copy and set colorspace: Copy source pixmap choosing the colorspace. Any colorspace combination is possible.

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. alpha (bool) – whether to also copy the source’s alpha channel. If the source has no alpha, this parameter has no effect. If False the result will have no alpha.

__init__(self, source, width, height[, clip])

Copy and scale: Copy source pixmap choosing new width and height values. Supports partial copying.

Parameters:	source (Pixmap) – the source pixmap. width (float) – desired target width. height (float) – desired target height. clip (IRect) – a region of the source pixmap to take the copy from.

__init__(self, source)

Copy and add alpha: Identical copy from source with an added alpha channel. The alpha values are set to 255.

Parameters:	source (Pixmap) – the source pixmap, must not have alpha.

__init__(self, filename)

From a file: Create a pixmap from filename. Image type and all properties are determined automatically.

Parameters:	filename (str) – Path / name of the file. The origin of the resulting pixmap is (0, 0).

__init__(self, img)

From memory: Create a pixmap from bytearray img. Image type and all properties are determined automatically.

Parameters:	img (bytearray) – Data containing a complete, valid image in one of the supported formats. Could have been created by something like img = bytearray(open('somepic.png', 'rb').read()). The origin of the resulting pixmap is (0,0). Type bytes is not supported here, because that cannot be distinguished from string in Python 2.

__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 examples below.

Parameters:

colorspace (Colorspace) – Colorspace of the image. Together with alpha this parameter controls the interpretation of the samples area. The following must be true: (colorspace.n + alpha) * width * height == len(samples). width (int) – image width height (int) – image height samples (bytes) – an area containing all pixels of the image. Must include alpha values if specified. Type bytearray is also supported. alpha (bool) – whether a transparency channel is included.

Caution

The method will not make a copy of samples, but rather record a pointer. Therefore make sure that it remains available throughout the lifetime of the pixmap. Otherwise the pixmap’s image will likely be destroyed or even worse things will happen.

__init__(self, doc, xref)

From a PDF image: Create a pixmap from an image contained in PDF doc identified by its XREF number. All pimap properties are set by the image.

Parameters:	doc (Document) – an opened PDF document. xref (int) – the XREF number of the image.

clearWith([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 always be set to 255 (non-transparent). If omitted, then all bytes including alpha are cleared to 0x00. irect (IRect) – the area to be cleared. Omit to clear the whole pixmap. Can only be specified, if value is also specified.

tintWith(red, green, blue)

Colorize (tint) a pixmap with a color provided as a value triple (red, green, blue). Only colorspaces CS_GRAY and CS_RGB are supported.

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

Parameters:	red (int) – red component. green (int) – green component. blue (int) – blue component.

gammaWith(gamma)

Apply a gamma factor to a pixmap, i.e. lighten or darken it.

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 2ⁿ.

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.

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.

setAlpha([alphavalues])

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

Parameters:	alphavalues (bytes) – the new alpha values. Type bytearray is also permitted. If provided, its length must be at least width * height. If omitted, alpha values are all set to 255 (no transparency).

invertIRect(irect)

Invert the color of all pixels in IRect irect.

Parameters:	irect (IRect) – The area to be inverted. Omit to invert everything.

copyPixmap(source, irect)

Copy the IRect part of source into the corresponding area of this one. The two pixmaps may have different dimensions and different colorspaces (provided each is either CS_GRAY or CS_RGB), but currently must have the same alpha property. 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. Then the corresponding data of this intersection are being copied. If the intersection is empty, nothing will happen.

If you want your source pixmap image to land at a specific target position, set its x and y attributes to the top left point of the desired rectangle before copying. See the example below for how this works.

Parameters:	source (Pixmap) – The pixmap from where to copy. irect (IRect) – The area to be copied.

writeImage(filename, output="png")

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 ignored with a warning.

Parameters:	filename (str) – The filename to save to. Depending on the chosen output format, possible file extensions are .pam, .pbm, .pgm, ppm, .pnm, .png and .tga. output (str) – The requested image format. The default is png for which this function is equal to writePNG(), see below. Other possible values are pam, pnm and tga.

writePNG(filename)

Save the pixmap as a PNG file. Please note that only grayscale and RGB colorspaces are supported (this is not a MuPDF restriction). CMYK colorspaces must either be saved as *.pam files or be converted first.

Parameters:	filename (str) – The filename to save to (the extension png must be specified). Existing files will be overwritten without warning.

getPNGData()

Like writePNG but returnes a bytearray instead.

Return type:	bytearray

alpha

Indicates whether the pixmap contains transparency information.

Type:	bool

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 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 alpha == 1) transparency values for all pixels. samples is a memory area of size 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. See example 3.

Type:	bytes

size

Contains len(pixmap). This will generally equal len(pix.samples) + 60 (32bit systems, the delta is 88 on 64bit machines).

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

Type:	int

y

Y-coordinate of top-left corner

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.

Type:	int

xres

Horizontal resolution in dpi (dots per inch).

Type:	int

yres

Vertical resolution in 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

import fitz
# create a pixmap of a picture
pix0 = fitz.Pixmap("editra.png")

# set target colorspace and pixmap dimensions and create it
tar_width  = pix0.width * 3              # 3 tiles per row
tar_height = pix0.height * 4             # 4 tiles per column
tar_irect  = fitz.IRect(0, 0, tar_width, tar_height)
# create empty target pixmap
tar_pix    = fitz.Pixmap(fitz.csRGB, tar_irect, pix0.alpha)
# clear target with a very lively stone-gray (thanks and R.I.P., Loriot)
tar_pix.clearWith(90)

# now fill target with 3 * 4 tiles of input picture
for i in range(4):
    pix0.y = i * pix0.height                     # modify input's y coord
    for j in range(3):
        pix0.x = j * pix0.width                  # modify input's x coord
        tar_pix.copyPixmap(pix0, pix0.irect)     # copy input to new loc
        # save all intermediate images to show what is happening
        fn = "target-%i-%i.png" % (i, j)
        tar_pix.writePNG(fn)

import numpy as np
import fitz
#==============================================================================
# create a fun-colored width * height PNG with fitz and numpy
#==============================================================================
height = 150
width  = 100
bild = np.ndarray((height, width, 3), dtype=np.uint8)

for i in range(height):
    for j in range(width):
        # one pixel (some fun coloring)
        bild[i, j] = [(i+j)%256, i%256, j%256]

samples = bytearray(bild.tostring())    # get plain pixel data from numpy array
pix = fitz.Pixmap(fitz.csRGB, width, height, samples, alpha=False)
pix.writePNG("test.png")

>>> import fitz
>>> from PIL import Image
>>> pix = fitz.Pixmap(...)
>>> ...
>>> # create and save a PIL image
>>> img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
>>> img.save(filename, 'jpeg')
>>> ...
>>> # opposite direction:
>>> # create a pixmap from any PIL-supported image file "some_image.xxx"
>>> img = Image.open("some_image.xxx").convert("RGB")
>>> samples = img.tobytes()
>>> pix = fitz.Pixmap(fitz.csRGB, img.size[0], img.size[1], samples, alpha=False)