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.

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 …

from a document page (method Page.GetPixmap())
empty, based on ColorSpace and IRect information
from a file
from an in-memory image
from a memory area of plain pixels
from an image inside a PDF document
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 FAQ section to see some pixmap usage “at work”.

Method / Attribute	Short Description
`Pixmap.ClearWith()`	Clear parts of the pixmap
`Pixmap.ColorCount()`	Determine used colors
`Pixmap.ColorTopUsage()`	Determine share of most used color
`Pixmap.Copy()`	Copy parts of another pixmap
`Pixmap.GammaWith()`	Apply a gamma factor to the pixmap
`Pixmap.InvertIrect()`	Invert the pixels of a given area
`Pixmap.SavePdfOCR()`	Save the pixmap as an OCRed 1-page PDF
`Pixmap.PdfOCR2Bytes()`	Save the pixmap as an OCRed 1-page PDF
`Pixmap.GetPixel()`	Return the value of a pixel
`Pixmap.Save()`	Save the pixmap in a variety of formats
`Pixmap.SetAlpha()`	Set alpha values
`Pixmap.SetDpi()`	Set the image resolution
`Pixmap.SetOrigin()`	Set pixmap x,y values
`Pixmap.SetPixel()`	Set color and alpha of a pixel
`Pixmap.SetRect()`	Set color and alpha of all pixels in a rectangle
`Pixmap.Shrink()`	Reduce size keeping proportions
`Pixmap.TintWith()`	Tint the pixmap
`Pixmap.ToBytes()`	Return a memory area in a variety of formats
`Pixmap.Warp()`	Return a pixmap made from a quad inside
`Pixmap.Dispose()`	Disposes of the pixmap
`Pixmap.Alpha`	Transparency indicator
`Pixmap.ColorSpace`	Pixmap’s ColorSpace
`Pixmap.Digest`	MD5 hashcode of the pixmap
`Pixmap.IsMonoChrome`	Check if only black and white occur
`Pixmap.IsUniColor`	Check if only one color occurs
`Pixmap.IRect`	IRect of the pixmap
`Pixmap.N`	Bytes per pixel
`Pixmap.SAMPLES_MV`	`memoryview` of pixel area
`Pixmap.SamplesPtr`	Pointer to pixel area
`Pixmap.SAMPLES`	`bytes` copy of pixel area
`Pixmap.Size`	Pixmap’s total length
`Pixmap.Stride`	Size of one image row
`Pixmap.W`	Pixmap width
`Pixmap.H`	Pixmap height
`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#

Pixmap(ColorSpace colorspace, IRect irect, bool alpha)#

New empty pixmap: Create an empty pixmap of size and origin given by the rectangle. So, irect.TopLeft 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. ClearWith() or SetRect() to be sure.

Parameters:

colorspace (ColorSpace) – colorspace.
irect (IRect) – The pixmap’s position and dimension.
alpha (bool) – Specifies whether transparency bytes should be included. Default is false.

Pixmap(ColorSpace colorspace, Pixmap source)#

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

Parameters:

colorspace (ColorSpace) – desired target colorspace. This may also be null. 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.

Pixmap(self, Pixmap source, Pixmap mask)#

Copy and add image mask: Copy source pixmap, add an alpha channel with transparency data from a mask pixmap.

Parameters:

source (Pixmap) – pixmap without alpha channel.
mask (Pixmap) – a mask pixmap. Must be a graysale pixmap.

Pixmap(Pixmap source, float width, float height, Rect clip: null)#

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 null.

Parameters:

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

Note

If width or height do not represent integers, then the resulting pixmap will have an alpha channel.

Pixmap(Pixmap source, int 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 (int) – whether the target will have an alpha channel, default and mandatory if source colorspace is null.

Pixmap(string 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.

Pixmap(byte[] 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 (byte[]) – Data containing a complete, valid image.

Pixmap(ColorSpace colorspace, float width, float height, byte[] samples, bool 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 FAQ.

Parameters:

colorspace (ColorSpace) – ColorSpace of image.
width (float) – image width
height (float) – image height
samples (byte[]) – an area containing all pixels of the image. Must include alpha values if specified.
alpha (bool) – whether a transparency channel is included.

Note

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

Pixmap(Document doc, int xref)#

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

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.GetPageImages(), which also shows the xref numbers of each image.

ClearWith(int value, IRect 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) – the area to be cleared. Omit to clear the whole pixmap. Can only be specified, if value is also specified.

TintWith(int black, int white)#

Colorize a pixmap by replacing black and / or white with colors given as sRGB integer values. Only colorspaces CS_GRAY and CS_RGB are supported, others are ignored with a warning.

If the colorspace is CS_GRAY, the average (red + green + blue)/3 will be taken. The pixmap will be changed in place.

Parameters:

black (int) – replace black with this value. Specifying 0x000000 makes no changes.
white (int) – replace white with this value. Specifying 0xFFFFFF makes no changes.

Examples:

TintWith(0x000000, 0xFFFFFF) is a no-op.

TintWith(0x00FF00, 0xFFFFFF) changes black to green, leaves white intact.

TintWith(0xFF0000, 0x0000FF) changes black to red and white to blue.

GammaWith(float gamma)#

Apply a gamma factor to a pixmap, i.e. lighten or darken it. Pixmaps with colorspace null 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 2:sup:n.

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 16^th 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.

GetPixel(int x, int y)#

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).

SetPixel(int x, int y, float[] color)#

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 (float[]) – the desired pixel value given as a sequence of integers in range(256). The length of the sequence must equal Pixmap.N, which includes any alpha byte.

SetRect(IRect bbox, byte[] color)#

Parameters:

irect (IRect) – the rectangle to be filled with the value. 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 (byte[]) – the desired value, 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

This method is equivalent to Pixmap.SetPixel() executed for each pixel in the rectangle, but is obviously very much faster if many pixels are involved.
This method can be used similar to Pixmap.ClearWith() 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).

SetOrigin(x, y)#

Set the x and y values of the pixmap’s top-left point.

Parameters:

x (int) – x coordinate
y (int) – y coordinate

SetDpi(int xres, int yres)#

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

Parameters:

xres (int) – resolution in x direction.
yres (int) – resolution in y direction.

SetAlpha(dynamic alphavalues: null, int premultiply: 1, dyanmic opaque: null, dynamic matte: null)#

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

Parameters:

alphavalues (byte[]) – the new alpha values. If provided, its length must be at least width * height. If omitted (null), all alpha values are set to 255 (no transparency).
premultiply (bool) – Whether to premultiply color components with the alpha value.
opaque (list,tuple) – ignore the alpha value and set this color to fully transparent. A sequence of integers in range(256) with a length of Pixmap.N. Default is null. For example, a typical choice for RGB would be opaque=(255, 255, 255) (white).
matte (list,tuple) – preblending background color.

InvertIrect(IRect bbox: null)#

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

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

Copy(Pixmap source, IRect bbox)#

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) – The area to be copied.

Note

Example: Suppose you have two pixmaps, pix1 and pix2 and you want to copy the lower right quarter of pix2 to pix1 such that it starts at the top-left point of pix1. Use the following snippet:

// safeguard: set top-left of pix1 and pix2 to (0, 0)
pix1.SetOrigin(0, 0)
pix2.SetOrigin(0, 0)
// compute top-left coordinates of pix2 region to copy
int x1 = int(pix2.Width / 2)
int y1 = int(pix2.Height / 2)
pix2.SetOrigin(-x1, -y1)
pix1.Copy(pix2, (0, 0, x1, y1))

Save(string filename, string output: null, int jpgQuality: 95)#

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.

Parameters:

filename (string) – The file to save to. May be provided as a string. 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 (string) – The desired image format. The default is the filename’s extension. If both, this value and the file extension are unsupported, an exception is raised. For possible values see Supported Output Image Formats.
jpgQuality (int) – The desired image quality, default 95. Only applies to JPEG images, else ignored. This parameter trades quality against file size. A value of 98 is close to lossless. Higher values should not lead to better quality.

Raises:

ValueError – For unsupported image formats.

ToBytes(string output: "png", int jpgQuality: 95)#

Parameters:

output (str) – The desired image format. The default is “png”. For possible values see Supported Output Image Formats.
jpgQuality (int) – The desired image quality, default 95. Only applies to JPEG images, else ignored. This parameter trades quality against file size. A value of 98 is close to lossless. Higher values should not lead to better quality.
output – The requested image format. The default is “png”. For other possible values see Supported Output Image Formats.

Raises:

ValueError – For unsupported image formats.

Return type:

byte[]

SavePdfOCR(string filename, bool compress: true, string language: "eng", string tessdata: null)#

Perform text recognition using Tesseract and save the image as a 1-page PDF with an OCR text layer.

Parameters:

filename (string) – identifies the file to save to. May be either a string or a pointer to a file opened with “wb”.
compress (bool) – whether to compress the resulting PDF, default is true.
language (string) – the languages occurring in the image. This must be specified in Tesseract format. Default is “eng” for English. Use “+”-separated Tesseract language codes for multiple languages, like “eng+spa” for English and Spanish.
tessdata (string) – folder name of Tesseract’s language support. If omitted, this information must be present as environment variable TESSDATA_PREFIX.

Note

Will fail if Tesseract is not installed or if the environment variable “TESSDATA_PREFIX” is not set to the tessdata folder name and not provided as parameter.

PdfOCR2Bytes(bool compress: true, string language: "eng", string tessdata: null)#

Perform text recognition using Tesseract and convert the image to a 1-page PDF with an OCR text layer. Internally invokes Pixmap.SavePdfOCR().

Returns:

A 1-page PDF file in memory. Could be opened like doc=new Document("pdf", pix.PdfOCR2Bytes()), and text extractions could be performed on its page=doc[0].

Note

Another possible use is insertion into some pdf. The following snippet reads the images of a folder and stores them as pages in a new PDF that contain an OCR text layer:

Document doc = new Document();
foreach (string imgfile in Directory.GetFiles(folder))
{
   Pixmap pix = new Pixmap(imgfile);
   Document imgpdf = new Document("pdf", pix.PdfOCR2Bytes());
   doc.InsertPdf(imgpdf);
   pix = null;
   imgpdf.Close();
}
doc.Save("ocr-images.pdf")

Warp(Quad quad, float width, float height)#

Return a new pixmap by “warping” the quad such that the quad corners become the new pixmap’s corners. The target pixmap’s IRect will be (0, 0, Width, Height).

Parameters:

quad (Quad) – a convex quad with coordinates inside Pixmap.IRect (including the border points).
width (int) – desired resulting width.
height (int) – desired resulting height.

Returns:

A new pixmap where the quad corners are mapped to the pixmap corners in a clockwise fashion: quad.UpperLeft -> irect.TopLeft, quad.UpperRight -> irect.TopRight, etc.

Return type:

Pixmap

ColorCount(bool colors: false, dynamic clip: null)#

Determine the pixmap’s unique colors and their count.

Parameters:

colors (bool) – If true return a dictionary of color pixels and their usage count, else just the number of unique colors.
clip (Rect, Tuple) – a rectangle inside Pixmap.IRect. If provided, only those pixels are considered. This allows inspecting sub-rectangles of a given pixmap directly – instead of building sub-pixmaps.

Return type:

Dictionary<string, int>

Returns:

either the number of colors, or a dictionary with the items pixel: count. The pixel key is a bytes object of length Pixmap.N.

Note

To recover the tuple of a pixel, use tuple(colors.keys()[i]) for the i-th item.

The response time depends on the pixmap’s samples size and may be more than a second for very large pixmaps.
Where applicable, pixels with different alpha values will be treated as different colors.

ColorTopUsage(dynamic clip: null)#

Return the most frequently used color and its relative frequency.

Parameters:: clip (Rect, Tuple) – A rectangle inside Pixmap.Rect. If provided, only those pixels are considered. This allows inspecting sub-rectangles of a given pixmap directly – instead of building sub-pixmaps.
Return type:: Tuple(float, byte[])
Returns:: A Tuple (ratio, pixel) where 0 < ratio <= 1 and pixel is the pixel value of the color. Use this to decide if the image is “almost” unicolor: a response (0.95, b"x00x00x00") means that 95% of all pixels are black.

Dispose()#: Disposes of the pixmap.

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:: byte[]

ColorSpace#

The colorspace of the pixmap. This value may be null 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

IsMonoChrome#

Is true for a gray pixmap which only has the colors black and white.

Type:: bool

IsUniColor#

Is true if all pixels are identical (any colorspace). Where applicable, pixels with different alpha values will be treated as different colors.

Type:: bool

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.

Note

The underlying data is typically a large memory area, from which a bytes copy is made for this attribute … each time you access it: for example an RGB-rendered letter page has a samples size of almost 1.4 MB. So consider assigning a new variable to it or use the memoryview version Pixmap.SAMPLES_MV.
Any changes to the underlying data are available only after accessing this attribute again. This is different from using the memoryview version.

Type:: bytes

SAMPLES_MV#

Memory format. It is built pointing to the memory in the pixmap – not from a copy of it. So its creation speed is independent from the pixmap size, and any changes to pixels will be available immediately.

We also have len(pix.SAMPLES) == len(pix.SAMPLES_MV).

Type:: Memory<byte>

SamplesPtr#

Both of the above lead to the same Qt image, but (2) can be many hundred times faster, because it avoids an additional copy of the pixel area.

Type:: long

Size#

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

Type:: float

W#

w#

Width of the region in pixels.

Type:: float

H#

h#

Height of the region in pixels.

Type:: float

X#

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

Type:: float

Y#

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

Type:: float

N#

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

Type:: float

Xres#

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

Type:: float

Yres#

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

Type:: float

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:

Directly create a pixmap with Pixmap(filename) or Pixmap(byte[]). The pixmap will then have properties as determined by the image.
Open such files with Document(filename). 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 byte[] object (Pixmap.ToBytes()). Both methods accept a 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
jpg, jpeg	gray, rgb, cmyk	no	.jpg, .jpeg	Joint Photographic Experts Group
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 rgbPix = new Pixmap(Utils.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 and JPEG are probably the most popular.
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).

Footnotes