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 …
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 Collection of Recipes section to see some pixmap usage “at work”.
Method / Attribute |
Short Description |
---|---|
clear parts of a pixmap |
|
copy parts of another pixmap |
|
apply a gamma factor to the pixmap |
|
return a memory area in a variety of formats |
|
return a PNG as a memory area |
|
invert the pixels of a given area |
|
return the value of a pixel |
|
set the color of a pixel |
|
set the color of a rectangle |
|
set alpha values |
|
reduce size keeping proportions |
|
tint a pixmap with a color |
|
save a pixmap in a variety of formats |
|
save a pixmap as a PNG file |
|
transparency indicator |
|
pixmap’s Colorspace |
|
pixmap height |
|
interpolation method indicator |
|
IRect of the pixmap |
|
bytes per pixel |
|
pixel area |
|
pixmap’s total length |
|
size of one image row |
|
pixmap width |
|
X-coordinate of top-left corner |
|
resolution in X-direction |
|
Y-coordinate of top-left corner |
|
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 areirect.width
resp.irect.height
. Note that the image area is not initialized and will contain crap data – useclearWith()
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 beNone
.- Parameters
colorspace (Colorspace) – desired target colorspace. This may also be
None
. In this case, a “masking” pixmap is created: itsPixmap.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 choosing new width and height values. Supports partial copying and the source colorspace may be alsoNone
.- Parameters
source (
Pixmap
) – the source pixmap.width (float) – desired target width.
height (float) – desired target height.
clip (irect-like) – a region of the source pixmap to take the copy from.
Note
If width or height are not de facto integers (meaning e.g.
hash(width) != hash(int(width))
), then pixmap will be created withalpha = 1
.
-
__init__
(self, source, alpha = 1) Copy and add or drop alpha: Copy
source
and add or drop its alpha channel. Identical copy ifalpha
equalssource.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()
ofwxPython
:>>> # '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())
. Typebytes
is supported in Python 3 only, becausebytes == 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 thecolorspace
andalpha
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:
io.BytesIO
can now also be used. Data are now copied to the pixmap, hence the source data can safely be deleted.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. So, source data becoming unavailable should no longer be a concern.
-
__init__
(self, doc, xref) From a PDF image: Create a pixmap from an image contained in PDF
doc
identified by itsxref
. 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 withDocument.getPageImageList()
, which also shows thexref
numbers of each 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 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.
-
tintWith
(red, green, blue)¶ Colorize (tint) a pixmap with a color provided as an integer triple (red, green, blue). Only colorspaces
CS_GRAY
andCS_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.
-
gammaWith
(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 inrange(256)
.
-
setPixel
(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 equalPixmap.n
, which includes any alpha byte.
-
setRect
(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 equalPixmap.n
, which includes any alpha byte.
- Return type
bool
- Returns
False
if the rectangle was invalid or had an empty intersection withPixmap.irect
, elseTrue
.
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.setRect(pix.irect, (255, 255, 0))
(RGB example, colors the complete pixmap with yellow).
-
setAlpha
([alphavalues])¶ 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, all alpha values are set to 255 (no transparency).Changed in version 1.14.13:
io.BytesIO
is now also supported.
-
invertIRect
([irect])¶ Invert the color of all pixels in IRect
irect
. Will have no effect if colorspace isNone
.- Parameters
irect (irect-like) – The area to be inverted. Omit to invert everything.
-
copyPixmap
(source, irect)¶ Copy the
irect
part of thesource
pixmap into the corresponding area of this one. The two pixmaps may have different dimensions and can each haveCS_GRAY
orCS_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
toCS_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 valuessource.x
andsource.y
(which you are free to modify for this purpose). 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.
-
writeImage
(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) – The filename to save to. The filename’s extension determines the image format, if not overriden 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.
-
writePNG
(filename)¶ Equal to
pix.writeImage(filename, "png")
.
-
getImageData
(output="png")¶ New in version 1.14.5.
Return the pixmap as a
bytes
memory object of the specified format – similar towriteImage()
.- Parameters
output (str) – The requested image format. The default is “png” for which this function equals
getPNGData()
. For other possible values see Supported Output Image Formats.- Return type
bytes
-
getPNGdata
()¶
-
getPNGData
()¶ Equal to
pix.getImageData("png")
.- Return type
bytes
-
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
-
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
-
samples
¶ The color and (if
Pixmap.alpha
is true) transparency values for all pixels. It is a write-protected memory area ofwidth * 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.
- Type
bytes
-
size
¶ Contains
len(pixmap)
. This will generally equallen(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
- 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), thenPixmap.n - Pixmap.aslpha == pixmap.colorspace.n
is true. If colorspace isNone
, thenn == alpha == 1
.- 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”. IfFalse
“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:
Directly create a pixmap with
Pixmap(filename)
orPixmap(byterray)
. The pixmap will then have properties as determined by the image.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.writeImage()
), or to generate a bytes object (Pixmap.getImageData()
). 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.getImageData("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.convertToPDF()
. If this is not 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.