2D ENGINE(CAIRO)
for real hackers who want to learn real stuff
Cairo is a 2D graphics library with support for multiple output devices. Currently supported
output targets include the X Window System, Quartz, Win32, image buffers, PostScript, PDF,
and SVG file output. Experimental backends include OpenGL (through glitz), XCB, BeOS, OS/2,
and DirectFB.
Cairo is designed to produce consistent output on all output media while taking advantage of
display hardware acceleration when available (eg. through the X Render Extension).
The cairo API provides operations similar to the drawing operators of PostScript and PDF.
Operations in cairo including stroking and filling cubic Bézier splines, transforming and
compositing translucent images, and antialiased text rendering. All drawing operations can
be transformed by any affine transformation (scale, rotation, shear, etc.)
Cairo is implemented as a library written in the C programming language, but bindings are
available for several different programming languages.
Cairo is free software and is available to be redistributed and/or modified under the terms
of either the GNU Lesser General Public License (LGPL) version 2.1 or the Mozilla Public
License (MPL) version 1.1 at your option.
Scrumptious recipes to spice up your applications
Rounded rectangles
Using Win32 Quickstart
Rendering SVG using librsvg in Python
Converting cairo code from C to Python or Haskell and back
Load jpg/png/gif/bmp/etc into CairoContext with help from gdk-pixbuf in Pycairo/Pygtk
Basic matrix transformation reminder
Python: Converting PIL images to Cairo surfaces and back
Loading fonts using FreeType for cairo use in Python
A description of compositing operators in Cairo
How to:A quick framework for testing cairo from Python (And demos masking)
How to:Open a simple SVG file without Pyrsvg
How to:Using path data to create a Hit Area
How to:Using PyCairo and Pyrsvg to handle SVG graphics
How to:Do timeout animation (Also shows rotation around a point)
How to:Render PDF and PostScript files with cairo
How to use librsvg from Python
It finally took me an entire installation of a new O/S and "locate .py | grep rsvg"(*) on my
drive to find what I could not find via google : how to open an SVG file and draw it from
PyCairo.
I had to upgrade my O/S (to Gnu/Linux Kubuntu 7.10) in order to get the latest
Python-gnome2-* packages for, buried in there, is a Python wrapper for librsvg. I don't know
why it's not a stand-alone wrapper like PyCairo, but that's the way it is.
The first demo is directly from the example I found on my drive.
(*) You can find this demo in /usr/share/doc/python-gnome2-desktop/examples/rsvg on *buntu
Gutsy 7.10
#!/usr/bin/env python
import sys
import cairo
import rsvg
import gtk
BORDER_WIDTH = 10
def delete_cb(win, event):
gtk.main_quit()
def expose_cairo(win, event, svg):
x, y, w, h = win.allocation
cr = win.window.cairo_create()
cr.set_source_color(win.style.fg[win.state])
cr.rectangle(BORDER_WIDTH, BORDER_WIDTH,
w - 2*BORDER_WIDTH, h - 2*BORDER_WIDTH)
cr.set_line_width(5.0)
cr.set_line_join(cairo.LINE_JOIN_ROUND)
cr.stroke()
if svg != None:
matrix = cairo.Matrix(3,0,0,3,0, 0)
#cairo.Matrix.rotate( matrix, prop.rot )
cr.transform (matrix)
svg.render_cairo(cr)
return True
def main():
win = gtk.Window ()
win.connect("delete-event", delete_cb)
svg = None
if (len (sys.argv) > 1):
svg = rsvg.Handle(file=sys.argv[1])
else:
raise SystemExit("need svg file")
win.connect("expose-event", expose_cairo, svg)
print svg.props.width, svg.props.height, svg.props.em, svg.props.ex
win.show_all()
win.connect("destroy", lambda w: gtk.main_quit())
gtk.main()
if __name__ == '__main__':
main()
Writing an SVG file
I thought I'd see how writing out an SVG file from Cairo works, this is a short example.
import cairo
import rsvg
import math
fo = file('test.svg', 'w')
WIDTH, HEIGHT = 256, 256
## Prepare a destination surface -> out to an SVG file!
surface = cairo.SVGSurface (fo, WIDTH, HEIGHT)
## draw something - this taken from the web.
ctx = cairo.Context (surface)
ctx.scale (WIDTH/1.0, HEIGHT/1.0) # Normalizing the canvas
pat = cairo.LinearGradient (0.0, 0.0, 0.0, 1.0)
pat.add_color_stop_rgba (1, 0.7, 0, 0, 0.5) # First stop, 50% opacity
pat.add_color_stop_rgba (0, 0.9, 0.7, 0.2, 1) # Last stop, 100% opacity
ctx.rectangle (0, 0, 1, 1) # Rectangle(x0, y0, x1, y1)
ctx.set_source (pat)
ctx.fill ()
ctx.translate (0.1, 0.1) # Changing the current transformation matrix
ctx.move_to (0, 0)
ctx.arc (0.2, 0.1, 0.1, -math.pi/2, 0) # Arc(cx, cy, radius, start_angle, stop_angle)
ctx.line_to (0.5, 0.1) # Line to (x,y)
ctx.curve_to (0.5, 0.2, 0.5, 0.4, 0.2, 0.
# Curve(x1, y1, x2, y2, x3, y3)ctx.close_path ()
ctx.set_source_rgb (0.3, 0.2, 0.5) # Solid color
ctx.set_line_width (0.02)
ctx.stroke ()
## Do the deed.
surface.finish()
You can use 'svgdisplay' (if you have the binary), Inkscape, Firefox or the first demo app
to view test.svg
A feedback loop
What happens when you feed the snake it's tail?
import cairo
import rsvg
fo = file('test.svg', 'w')
WIDTH, HEIGHT = 256, 256
surface = cairo.SVGSurface (fo, WIDTH, HEIGHT)
ctx = cairo.Context (surface)
svg = rsvg.Handle(file="test2.svg")
svg.render_cairo(ctx)
surface.finish()
Well, it works! test.svg comes in and comes out as test2.svg. I don't think it proves
anything, but it's fun.
Python
The following is a minimal windows application that uses cairo. It has double buffering and
uses the PyWin32 library.
from win32api import *
try:
from winxpgui import *
except ImportError:
from win32gui import *
import win32con
import sys, os
import cairo
def WebColour(sCol):
#print sCol
ic = [int(sCol[i:i+2], 16)/255.0 for i in range(1, 7, 2)]
#print ic
return ic
def roundedRectangle(cr,x,y,w,h,radius_x=5,radius_y=5):
#from mono moonlight aka mono silverlight
#test limits (without using multiplications)
# http://graphics.stanford.edu/courses/cs ... al/q1.html
ARC_TO_BEZIER = 0.55228475
if radius_x > w - radius_x:
radius_x = w / 2
if radius_y > h - radius_y:
radius_y = h / 2
#approximate (quite close) the arc using a bezier curve
c1 = ARC_TO_BEZIER * radius_x
c2 = ARC_TO_BEZIER * radius_y
cr.new_path();
cr.move_to ( x + radius_x, y)
cr.rel_line_to ( w - 2 * radius_x, 0.0)
cr.rel_curve_to ( c1, 0.0, radius_x, c2, radius_x, radius_y)
cr.rel_line_to ( 0, h - 2 * radius_y)
cr.rel_curve_to ( 0.0, c2, c1 - radius_x, radius_y, -radius_x, radius_y)
cr.rel_line_to ( -w + 2 * radius_x, 0)
cr.rel_curve_to ( -c1, 0, -radius_x, -c2, -radius_x, -radius_y)
cr.rel_line_to (0, -h + 2 * radius_y)
cr.rel_curve_to (0.0, -c2, radius_x - c1, -radius_y, radius_x, -radius_y)
cr.close_path ()
class MainWindow(object):
def __init__(self):
message_map = {
win32con.WM_DESTROY: self.OnDestroy,
win32con.WM_PAINT: self.OnPaint,
win32con.WM_SETCURSOR: self.OnCursor,
win32con.WM_ERASEBKGND: self.OnBackgroundErase,
win32con.WM_LBUTTONDOWN: self.OnClick,
win32con.WM_KEYUP: self.OnKey,
#win32con.WM_COMMAND: self.OnCommand,
#win32con.WM_USER+20 : self.OnTaskbarNotify,
# owner-draw related handlers.
#win32con.WM_MEASUREITEM: self.OnMeasureItem,
#win32con.WM_DRAWITEM: self.OnDrawItem,
}
# Register the Window class.
wc = WNDCLASS()
hinst = wc.hInstance = GetModuleHandle(None)
self.hinst = hinst
wc.lpszClassName = "CairoWindow"
wc.lpfnWndProc = message_map # could also specify a wndproc.
classAtom = RegisterClass(wc)
# Create the Window.
style = win32con.WS_THICKFRAME | win32con.WS_MAXIMIZEBOX | win32con.WS_MINIMIZEBOX |
win32con.WS_SYSMENU | win32con.WS_VISIBLE
self.hwnd = CreateWindow( classAtom, "Cairo is the greatest thing!", style, \
0, 0, 550, 350, \
0, 0, hinst, None)
UpdateWindow(self.hwnd)
def OnKey(self, hWnd, msg, wParam, lparam):
if wParam == 38: #up
print "up"
elif wParam == 40: #down
print "down"
def OnClick(self, hWnd, msg, wparam, lparam):
x = LOWORD(lparam)
y = HIWORD(lparam)
def Render(self):
try:
InvalidateRect(self.hwnd, None, True)
return True
except:
print "That didn't work"
return False
def OnPaint(self, hWnd, msg, wparam, lparam):
hdc, ps = BeginPaint(hWnd)
rc = GetClientRect(hWnd)
left, top, right, bottom = rc
width = right - left
height = bottom - top
x = left
y = top
_buffer = CreateCompatibleDC(hdc)
#Double Buffer Stage 1
hBitmap = CreateCompatibleBitmap(hdc,width,height)
hOldBitmap = SelectObject(_buffer, hBitmap )
surf = cairo.Win32Surface(_buffer)
ctx = cairo.Context(surf)
ctx.set_source_rgb(1,1,1)
ctx.paint()
roundedRectangle(ctx, 50, 50, 250, 250, 10, 10)
clr = WebColour("#F0FEE9")
ctx.set_source_rgb(clr[0],clr[1],clr[2])
ctx.fill_preserve()
clr = WebColour("#B3FF8D")
ctx.set_source_rgb(clr[0],clr[1],clr[2])
ctx.stroke()
ctx.set_source_rgb(0,0,0)
ctx.select_font_face("Arial",cairo.FONT_SLANT_NORMAL, cairo.FONT_WEIGHT_NORMAL)
ctx.set_font_size(10)
txt = "Cairo is the greatest thing!"
ctx.move_to(5,10)
ctx.show_text(txt)
surf.finish()
BitBlt(hdc,0, 0, width, height,
_buffer, x, y, win32con.SRCCOPY)
SelectObject( _buffer, hOldBitmap )
DeleteObject( hBitmap )
DeleteDC( _buffer )
EndPaint(hWnd,ps)
def OnCursor(self, hwnd, msg, wparam, lparam):
#IDC_HAND = 32649
#IDC_ARROW
cur_normal = LoadCursor(0, win32con.IDC_ARROW)
SetCursor(cur_normal)
def OnBackgroundErase(self, hwnd, msg, wparam, lparam):
return False
def OnDestroy(self, hwnd, msg, wparam, lparam):
#nid = (self.hwnd, 0)
#Shell_NotifyIcon(NIM_DELETE, nid)
PostQuitMessage(0) # Terminate the app.
print "Exited."
w=MainWindow()
PumpMessages()
This is some basic information about matrix transformation for people who forgot their math
course or didn't have one.
PIL and Cairographics / PyCairo
Please note that the code below was to only blur an cairo image surface and thus ignores
conversion from BGRA to RGBA to BGRA that is needed in other situations. Theoretically just
replace RGBA with BGRA in frombuffer and tostring.
im = cairo.ImageSurface.create_from_png("img11.png")
im1 = Image.frombuffer("RGBA",( im.get_width(),im.get_height()
),im.get_data(),"raw","RGBA",0,1)
im1 = im1.filter(ImageFilter.BLUR)
im1 = im1.filter(ImageFilter.BLUR)
im1 = im1.filter(ImageFilter.SMOOTH_MORE)
#imgd = im1.tostring("raw","RGBA",0,1)
imgd = im1.tostring()
a = array('B',imgd)
stride = self.width * 4
surface = cairo.ImageSurface.create_for_data (a, cairo.FORMAT_ARGB32,
self.width, self.height, stride)
roundedrectangles
Method A
From the cairo samples, modified. Gives a very nice shape but takes width and height only as
guides.
def roundedrecA(self,cr,x,y,width,height,radius=5):
#/* a custom shape, that could be wrapped in a function */
#radius = 5 #/*< and an approximate curvature radius */
x0 = x+radius/2.0 #/*< parameters like cairo_rectangle */
y0 = y+radius/2.0
rect_width = width - radius
rect_height = height - radius
cr.save()
#cr.set_line_width (0.04)
#self.snippet_normalize (cr, width, height)
x1=x0+rect_width
y1=y0+rect_height
#if (!rect_width || !rect_height)
# return
if rect_width/2<radius:
if rect_height/2<radius:
cr.move_to (x0, (y0 + y1)/2)
cr.curve_to (x0 ,y0, x0, y0, (x0 + x1)/2, y0)
cr.curve_to (x1, y0, x1, y0, x1, (y0 + y1)/2)
cr.curve_to (x1, y1, x1, y1, (x1 + x0)/2, y1)
cr.curve_to (x0, y1, x0, y1, x0, (y0 + y1)/2)
else:
cr.move_to (x0, y0 + radius)
cr.curve_to (x0 ,y0, x0, y0, (x0 + x1)/2, y0)
cr.curve_to (x1, y0, x1, y0, x1, y0 + radius)
cr.line_to (x1 , y1 - radius)
cr.curve_to (x1, y1, x1, y1, (x1 + x0)/2, y1)
cr.curve_to (x0, y1, x0, y1, x0, y1- radius)
else:
if rect_height/2<radius:
cr.move_to (x0, (y0 + y1)/2)
cr.curve_to (x0 , y0, x0 , y0, x0 + radius, y0)
cr.line_to (x1 - radius, y0)
cr.curve_to (x1, y0, x1, y0, x1, (y0 + y1)/2)
cr.curve_to (x1, y1, x1, y1, x1 - radius, y1)
cr.line_to (x0 + radius, y1)
cr.curve_to (x0, y1, x0, y1, x0, (y0 + y1)/2)
else:
cr.move_to (x0, y0 + radius)
cr.curve_to (x0 , y0, x0 , y0, x0 + radius, y0)
cr.line_to (x1 - radius, y0)
cr.curve_to (x1, y0, x1, y0, x1, y0 + radius)
cr.line_to (x1 , y1 - radius)
cr.curve_to (x1, y1, x1, y1, x1 - radius, y1)
cr.line_to (x0 + radius, y1)
cr.curve_to (x0, y1, x0, y1, x0, y1- radius)
cr.close_path ()
cr.restore()
Method B
From mono moonlight aka mono silverlight. Works very well on larger shapes.
def roundedrecMoonlight(self,cr,x,y,w,h,radius_x=5,radius_y=5):
#from mono moonlight aka mono silverlight
#test limits (without using multiplications)
# http://graphics.stanford.edu/courses/cs ... al/q1.html
ARC_TO_BEZIER = 0.55228475
if radius_x > w - radius_x:
radius_x = w / 2
if radius_y > h - radius_y:
radius_y = h / 2
#approximate (quite close) the arc using a bezier curve
c1 = ARC_TO_BEZIER * radius_x
c2 = ARC_TO_BEZIER * radius_y
cr.new_path();
cr.move_to ( x + radius_x, y)
cr.rel_line_to ( w - 2 * radius_x, 0.0)
cr.rel_curve_to ( c1, 0.0, radius_x, c2, radius_x, radius_y)
cr.rel_line_to ( 0, h - 2 * radius_y)
cr.rel_curve_to ( 0.0, c2, c1 - radius_x, radius_y, -radius_x, radius_y)
cr.rel_line_to ( -w + 2 * radius_x, 0)
cr.rel_curve_to ( -c1, 0, -radius_x, -c2, -radius_x, -radius_y)
cr.rel_line_to (0, -h + 2 * radius_y)
cr.rel_curve_to (0.0, -c2, radius_x - c1, -radius_y, radius_x, -radius_y)
cr.close_path ()
Method C
I can't remember where I got this. If you are the author please add your name. Works well on
smaller shapes.
def roundedrec(self,context,x,y,w,h,r = 10):
"Draw a rounded rectangle"
# A****BQ
# H C
# * *
# G D
# F****E
context.move_to(x+r,y) # Move to A
context.line_to(x+w-r,y) # Straight line to B
context.curve_to(x+w,y,x+w,y,x+w,y+r) # Curve to C, Control points are both at Q
context.line_to(x+w,y+h-r) # Move to D
context.curve_to(x+w,y+h,x+w,y+h,x+w-r,y+h) # Curve to E
context.line_to(x+r,y+h) # Line to F
context.curve_to(x,y+h,x,y+h,x,y+h-r) # Curve to G
context.line_to(x,y+r) # Line to H
context.curve_to(x,y,x,y,x+r,y) # Curve to A
return
Loading images
Based on the cworth recipe. Loads file in any gdk-pixbuf supported format (look into your
gdk-pixbuf.loaders or run 'gdk-pixbuf-query-loaders | grep gtk20'). Can be used as a very
primitive image viewer.
#!/usr/bin/env python
import sys
import gtk
import cairo
def expose (da, event, pixbuf):
ctx = da.window.cairo_create()
# You can put ctx.scale(..) or ctx.rotate(..) here, if you need some
ctx.set_source_pixbuf(pixbuf,0,0)
ctx.paint()
ctx.stroke()
def main():
filename = sys.argv[1]
pixbuf = gtk.gdk.pixbuf_new_from_file(filename)
imgw=pixbuf.get_width()
imgh=pixbuf.get_height()
win = gtk.Window()
win.connect('destroy', gtk.main_quit)
win.set_default_size(imgw, imgh)
da = gtk.DrawingArea()
win.add(da)
da.connect('expose_event', expose, pixbuf)
win.show_all()
gtk.main()
if __name__ == '__main__':
if len(sys.argv) != 2:
program = sys.argv[0]
print program +':', 'usage:', program, '<filename>'
sys.exit(0)
else:
main()
matrix transform
--------------------------------------------------------------------------------
Lets take that C = math.cos(A), S = math.sin(A), T = math.tan(A)
mtrx have to be used in the command ctx.transform(mtrx)
Action Command Matrix for transform
Shift by dx,dy ctx.translate(dx,dy) mtrx = cairo.Matrix(1,0,0,1,dx,dy)
Scale by fx,fy ctx.scale(fx,fy) mtrx = cairo.Matrix(fx,0,0,fy,0,0)
Rotation to A radians ctx.rotate(A) mtrx = cairo.Matrix(C,S,-S,C,0,0)
Rotation to A radians with center in x,y ctx.translate(x,y); ctx.rotate(A);
ctx.translate(-x,-y) mtrx = cairo.Matrix(C,S,-S,C,x-C*x+S*y,y-S*x-C*y)
X-skew by A -- mtrx = cairo.Matrix(1,0,T,1,0,0)
Y-skew by A -- mtrx = cairo.Matrix(1,T,0,1,0,0)
Flip H/V with center in cx:cy -- mtrx = cairo.Matrix(fx,0,0,fy,cx*(1-fx),cy*(fy-1))
Flip H/V and rotation with center in cx:cy -- mtrx =
cairo.Matrix(fx*C,fx*S,-S*fy,C*fy,C*cx*(1-fx)-S*cy*(fy-1)+cx-C*cx+S*cy,S*cx*(1-fx)+C*cy*(fy-
1)+cy-S*cx-C*cy)
(For flips fx/fy = 1 means 'no flip', fx/fy = -1 are used for horizontal/vertical flip).
--------------------------------------------------------------------------------
To apply more than one transformation you can multiply matrix. 'Unfortunately' matrix
multiplication is slightly different than regular multiplication of numbers. For square
matrix with N columns and N rows the rule is 'Rij == sum of Aix to Bxj products, where x =
[1,N]'. It's easy to figure out that for matrix multiplication A*B is not always the same as
B*A. The rule of matrix multiplication is illustrated with a picture here:
quickframework
A Quick GTK+ GNU/Linux Framework
I got this from http://www.tortall.net/mu/wiki/PyGTKCairoTutorial : it's handy for running
snippets of cairo code to see what's going on.
This sample shows how to use a mask (a second source to filter the first source.)
#! /usr/bin/env python
import pygtk
pygtk.require('2.0')
import gtk, gobject, cairo
# Create a GTK+ widget on which we will draw using Cairo
class Screen(gtk.DrawingArea):
# Draw in response to an expose-event
__gsignals__ = { "expose-event": "override" }
# Handle the expose-event by drawing
def do_expose_event(self, event):
# Create the cairo context
cr = self.window.cairo_create()
# Restrict Cairo to the exposed area; avoid extra work
cr.rectangle(event.area.x, event.area.y,
event.area.width, event.area.height)
cr.clip()
self.draw(cr, *self.window.get_size())
def draw(self, cr, width, height):
# Fill the background with gray
cr.set_source_rgb(0.5, 0.5, 0.5)
cr.rectangle(0, 0, width, height)
cr.fill()
# GTK mumbo-jumbo to show the widget in a window and quit when it's closed
def run(Widget):
window = gtk.Window()
window.connect("delete-event", gtk.main_quit)
widget = Widget()
widget.show()
window.add(widget)
window.present()
gtk.main()
## Do all your testing in Shapes ##
class Shapes(Screen):
def draw(self, cr, width, height):
## This will draw using a mask.
cr.scale(width,height) #Without this line the mask does not seem to work!
self.linear = cairo.LinearGradient(0, 0, 1, 1)
self.linear.add_color_stop_rgb(0, 0, 0.3, 0.
self.linear.add_color_stop_rgb(1, 0, 0.8, 0.3)
self.radial = cairo.RadialGradient(0.5, 0.5, 0.25, 0.5, 0.5, 0.5)
self.radial.add_color_stop_rgba(0, 0, 0, 0, 1)
self.radial.add_color_stop_rgba(0.5, 0, 0, 0, 0)
cr.set_source(self.linear)
cr.mask(self.radial)
run(Shapes)
In a cairo.matrix(1,2,3,4,5,6), 1 is a11, 2 is a21, 3 is a12, 4 is a22, 5 is a13 and 6 is
a23. a31 and a32 are 0, a33 is 1.
animationrotation
A pyCairo/PyGTK animation framework
There are two demos now, the first shows (gasp) a square rotating around an arbitrary point.
Scroll down for the second one which is longer and a bit more interesting.
This demo is two things: First it's a nice little framework that gives "life" to a function
so that animation becomes possible. If you want stuff to be drawn again and again with
little changes, this is a good start. (I'd love to see other solutions). Secondly it shows
how to rotate a "shape" (set of cairo commands) around any given ( x, y ) point.
I tried to comment it thoroughly, so it will 'splain itself.
## ani Copyright (C) 2008 anirudh pandey
##
## Contact: anicoolrocks@hotmail.com - I hope this email lasts
import pygtk
import gtk, gobject, cairo
from gtk import gdk
class Screen( gtk.DrawingArea ):
""" This class is a Drawing Area"""
def __init__( self, w, h, speed ):
super( Screen, self ).__init__( )
## Old fashioned way to connect expose. I don't savvy the gobject stuff.
self.connect ( "expose_event", self.do_expose_event )
## We want to know where the mouse is:
self.connect ( "motion_notify_event", self._mouseMoved )
## More GTK voodoo : unmask events
self.add_events ( gdk.BUTTON_PRESS_MASK | gdk.BUTTON_RELEASE_MASK |
gdk.POINTER_MOTION_MASK )
## This is what gives the animation life!
gobject.timeout_add( speed, self.tick ) # Go call tick every 'speed' whatsits.
self.width, self.height = w, h
self.set_size_request ( w, h )
self.x, self.y = 11110,11111110 #unlikely first coord to prevent false hits.
def tick ( self ):
"""This invalidates the screen, causing the expose event to fire."""
self.alloc = self.get_allocation ( )
rect = gtk.gdk.Rectangle ( self.alloc.x, self.alloc.y, self.alloc.width,
self.alloc.height )
self.window.invalidate_rect ( rect, True )
return True # Causes timeout to tick again.
## When expose event fires, this is run
def do_expose_event( self, widget, event ):
self.cr = self.window.cairo_create( )
## Call our draw function to do stuff.
self.draw( )
def _mouseMoved ( self, widget, event ):
self.x = event.x
self.y = event.y
class BunchOfStuff ( object ):
"""Stores a bunch of data"""
def __init__ ( self, x=0, y=0, rx=0, ry=0, rot=0, sx=1, sy=1 ):
self.x = x
self.y = y
self.rx = rx
self.ry = ry
self.rot = rot
self.sx = sx
self.sy = sy
class MyStuff ( Screen ):
"""This class is also a Drawing Area, coming from Screen."""
def __init__ ( self, w, h, speed):
Screen.__init__( self, w, h, speed )
## Setup three sets of data for the three objects to be drawn
self.red = BunchOfStuff ( x=50, y=-10, rx=50, ry=25 )
self.green = BunchOfStuff ( x=-10, y=10 )
self.blue = BunchOfStuff ( x=-70,y=30, sx=1, sy=1 )
self.sign = +1 # to flip the blue animation's sign
def setToCenter ( self ):
"""Shift 0,0 to be in the center of page."""
matrix = cairo.Matrix ( 1, 0, 0, 1, self.width/2, self.height/2 )
self.cr.transform ( matrix ) # Make it so...
def doMatrixVoodoo ( self, bos ):
"""Do all the matrix mumbo to get stuff to the right place on the screen."""
ThingMatrix =cairo.Matrix ( 1, 0, 0, 1, 0, 0 )
## Next, move the drawing to it's x,y
cairo.Matrix.translate ( ThingMatrix, bos.x, bos.y )
self.cr.transform ( ThingMatrix ) # Changes the context to reflect that
## Now, change the matrix again to:
if bos.rx != 0 and bos.ry != 0 : # Only do this if there's a special reason
cairo.Matrix.translate( ThingMatrix, bos.rx, bos.ry ) # move it all to point of
rotation
cairo.Matrix.rotate( ThingMatrix, bos.rot ) # Do the rotation
if bos.rx != 0 and bos.ry != 0 :
cairo.Matrix.translate( ThingMatrix, -bos.rx, -bos.ry ) # move it back again
cairo.Matrix.scale( ThingMatrix, bos.sx, bos.sy ) # Now scale it all
self.cr.transform ( ThingMatrix ) # and commit it to the context
def draw( self ):
cr = self.cr # Shabby shortcut.
#---------TOP LEVEL - THE "PAGE"
self.cr.identity_matrix ( ) # VITAL LINE :: I'm not sure what it's doing.
self.setToCenter ( )
#----------FIRST LEVEL
cr.save ( ) # Creates a 'bubble' of private coordinates. Save # 1
## RED - draw the red object
self.doMatrixVoodoo ( self.red )
self.drawCairoStuff ( self.red )
#---------- SECOND LEVEL - RELATIVE TO FIRST
cr.save ( ) #save 2
## GREEN - draw the green one
self.doMatrixVoodoo ( self.green )
self.drawCairoStuff ( self.green, col= ( 0,1,0 ) )
## Demonstrate how to detect a mouse hit on this shape:
## Draw the hit shape :: It *should* be drawn exactly over the green rectangle.
self.drawHitShape ( )
cr.save ( ) # Start a bubble
cr.identity_matrix ( ) # Reset the matrix within it.
hit = cr.in_fill ( self.x, self.y ) # Use Cairo's built-in hit test
cr.new_path ( ) # stops the hit shape from being drawn
cr.restore ( ) # Close the bubble like this never happened.
cr.restore ( ) #restore 2 :: "pop" the bubble.
## We are in level one's influence now
cr.restore ( ) #restore 1
## Back on PAGE's influence now
#-------- THIRD LEVEL -- RELATIVE TO PAGE
cr.save ( ) # Creates a 'bubble' of private coordinates.
## Draw the blue object
self.doMatrixVoodoo ( self.blue ) # within the bubble, this will not effect the PAGE
self.drawCairoStuff ( self.blue, col= ( 0,0,1 ) )
cr.restore ( )
## Back on the PAGE level again.
#indicate center
self.drawCrosshair ( )
self.guageScale ( )
## Let's animate the red object
## ( which *also* moves the green because it's a 'child'
## of the red by way of being in the same "bubble" )
self.red.rot += 0.01
## Now animate the blue
self.blue.sx += self.sign * 0.1
if self.blue.sx < 0 or self.blue.sx > 4:
self.sign *= -1
self.blue.sy = self.blue.sx
## Print to the console -- low-tech special effects
if hit: print "HIT!", self.x, self.y
def guageScale ( self ):
"""Draw some axis so we can see where stuff is."""
c = self.cr
m = 0
for x in range ( 10,210,10 ):
m += 1
w = 10 + ( m % 2 * 10 )
if x == 100: w = 50
c.rectangle ( x,-w/2,1,w )
c.rectangle ( -x, -w/2, 1, w )
c.rectangle ( -w/2, x, w, 1 )
c.rectangle ( -w/2, -x , w, 1 )
c.set_source_rgb ( 0,0,0 )
c.fill ( )
def drawCairoStuff ( self, bos, col= ( 1,0,0 ) ):
"""This draws the squares we see. Pass it a BagOfStuff (bos) and a colour."""
cr = self.cr
## Thrillingly, we draw a rectangle.
## It's drawn such that 0,0 is in it's center.
cr.rectangle( -25, -25, 50, 50 )
cr.set_source_rgb( col[0],col[1],col[2] )
cr.fill( )
## Now draw an axis
self.guageScale ( )
## Now a visual indicator of the point of rotation
cr.set_source_rgb( 1,1,1 )
cr.rectangle ( bos.rx - 2, bos.ry - 2, 4, 4 )
cr.fill ( )
## Same as the rectangle we see. No fill.
def drawHitShape ( self ):
"""Draws a shape that we'll use to test hits."""
self.cr.rectangle( -25, -25, 50, 50 ) # Same as the shape of the squares
def drawCrosshair ( self ):
"""Another visual aid."""
ctx = self.cr
ctx.set_source_rgb ( 0, 0, 0 )
ctx.move_to ( 0,10 )
ctx.line_to ( 0, -10 )
ctx.move_to ( -10, 0 )
ctx.line_to ( 10, 0 )
ctx.stroke ( )
def run( Widget, w, h, speed ):
window = gtk.Window( )
window.connect( "delete-event", gtk.main_quit )
widget = Widget( w, h, speed )
widget.show( )
window.add( widget )
window.present( )
gtk.main( )
run( MyStuff, 400, 400, speed = 20 )
renderpdf
Rendering a PDF or PS file with cairo
PDF files can be rendered to a cairo context using poppler. PS or EPS files can also be
rendered to a cairo context by first converting to PDF using Ghostscript.
When using a vector backend, the vectors and text in the PDF file are preserved in the
output as vectors. There is no unnecessary rasterization.
Compile the example with:
gcc -o pdf2cairo pdf2cairo.c `pkg-config --cflags --libs cairo poppler-glib`
pdf2cairo.c:
#include <poppler.h>
#include <cairo.h>
#include <cairo-ps.h>
int main(int argc, char *argv[])
{
PopplerDocument *document;
PopplerPage *page;
double width, height;
GError *error;
const char *filename;
gchar *absolute, *uri;
int num_pages, i;
cairo_surface_t *surface;
cairo_t *cr;
cairo_status_t status;
if (argc != 2) {
printf ("Usage: pdf2cairo input_file.pdf\n");
return 0;
}
filename = argv[1];
g_type_init ();
error = NULL;
if (g_path_is_absolute(filename)) {
absolute = g_strdup (filename);
} else {
gchar *dir = g_get_current_dir ();
absolute = g_build_filename (dir, filename, (gchar *) 0);
free (dir);
}
uri = g_filename_to_uri (absolute, NULL, &error);
free (absolute);
if (uri == NULL) {
printf("poppler fail: %s\n", error->message);
return 1;
}
document = poppler_document_new_from_file (uri, NULL, &error);
if (document == NULL) {
printf("poppler fail: %s\n", error->message);
return 1;
}
num_pages = poppler_document_get_n_pages (document);
/* Page size does not matter here as the size is changed before
* each page */
surface = cairo_ps_surface_create ("output.ps", 595, 842);
cr = cairo_create (surface);
for (i = 0; i < num_pages; i++) {
page = poppler_document_get_page (document, i);
if (page == NULL) {
printf("poppler fail: page not found\n");
return 1;
}
poppler_page_get_size (page, &width, &height);
cairo_ps_surface_set_size (surface, width, height);
cairo_save (cr);
/* Use poppler_page_render () for image backends and
* poppler_page_render_for_printing() for vector backends. */
poppler_page_render_for_printing (page, cr);
cairo_restore (cr);
cairo_surface_show_page (surface);
g_object_unref (page);
}
status = cairo_status(cr);
if (status)
printf("%s\n", cairo_status_to_string (status));
cairo_destroy (cr);
cairo_surface_finish (surface);
status = cairo_surface_status(surface);
if (status)
printf("%s\n", cairo_status_to_string (status));
cairo_surface_destroy (surface);
g_object_unref (document);
return 0;
}
svgtopycairo
SVG paths can be parsed and turned into a seqence of cairo commands that re-draw them.
This took a while, the pyparsing had me in knots, but now it's short and sweet. A fuller
implementation of what can be done in SVG would be really nice. (Hint...)
Make sure you pass it a very simple SVG file (from Inkscape is best) -- one that has had all
the shapes reduced to paths. Oh, and keep your canvas 400 by 400 or it may draw clear off
the screen.
Depends on
elementree: import elementree as myDearWatson
It's a great module for slicing through XML.
pyparsing: This module is deeply wonderful. I won't pretend to savvy even 1% of it, but it
really does the job. They have a great mailing list where I got a lot of help. It let's you
parse strings into lists and that is no small feat.
SVG Path element
To briefly explain, inside an svg file (which is just xml) you'll find a tag named 'g' and
under that one or more tags named 'path'. Inside path there is an element called 'd'; that's
the actual path. It's formed like this: "COMMAND NUMBER COMMA NUMBER Optionally[NUMBER COMMA
NUMBER a few more times]", where COMMAND is M for move, L for line, C for curve and Z for
close path. There may be others, but that's what I tackled. Have a look at the pyparsing
grammar which makes it fairly clear how different commands have different numbers behind
them.
Please forgive any bugs.
#!/usr/bin/env python
"""\
Usage: drawsvg.py file
file - one SVG file (from Inkscape!) that is all simple paths
"""
## ani Copyright (C) 2008 anirudh pandey
##
## Contact: anicoolrocks@hotmail.com - I hope this email lasts.
import pygtk
pygtk.require('2.0')
import gtk, gobject, cairo
from pyparsing import *
import os, sys
from elementtree import ElementTree as et
# Create a GTK+ widget on which we will draw using Cairo
class Screen(gtk.DrawingArea):
# Draw in response to an expose-event
__gsignals__ = { "expose-event": "override" }
# Handle the expose-event by drawing
def do_expose_event(self, event):
# Create the cairo context
cr = self.window.cairo_create()
# Restrict Cairo to the exposed area; avoid extra work
cr.rectangle(event.area.x, event.area.y,
event.area.width, event.area.height)
cr.clip()
self.draw(cr, *self.window.get_size())
def draw(self, cr, width, height):
# Fill the background with gray
cr.set_source_rgb(0.5, 0.5, 0.5)
cr.rectangle(0, 0, width, height)
cr.fill()
# GTK mumbo-jumbo to show the widget in a window and quit when it's closed
def run(Widget):
window = gtk.Window()
window.set_size_request(400, 400)
window.connect("delete-event", gtk.main_quit)
widget = Widget()
widget.show()
window.add(widget)
window.present()
gtk.main()
## Do the drawing ##
class Shapes(Screen):
def draw(self, ctx, width, height):
#Build a string of cairo commands
cairo_commands = ""
command_list = []
for tokens in paths:
for command,couples in tokens[:-1]: #looks weird, but it works
c = couples.asList()
if command == "M":
cairo_commands += "ctx.move_to(%s,%s);" % (c[0],c[1])
if command == "C":
cairo_commands += "ctx.curve_to(%s,%s,%s,%s,%s,%s);" %
(c[0],c[1],c[2],c[3],c[4],c[5])
if command == "L":
cairo_commands += "ctx.line_to(%s,%s);" % (c[0],c[1])
if command == "Z":
cairo_commands += "ctx.close_path();"
command_list.append(cairo_commands) #Add them to the list
cairo_commands = ""
#Draw it. Only stroked, to fill as per the SVG drawing is another whole story.
ctx.set_source_rgb(1,0,0)
for c in command_list:
exec(c)
ctx.stroke()
#Check args:
if len(sys.argv) < 2:
raise SystemExit(__doc__)
file = sys.argv[1]
## Pyparsing grammar:
## With HUGE help from Paul McGuire <paul@alanweberassociates.com>
## Thanks!
dot = Literal(".")
comma = Literal(",").suppress()
floater = Combine(Optional("-") + Word(nums) + dot + Word(nums))
## Unremark to have numbers be floats rather than strings.
#floater.setParseAction(lambda toks:float(toks[0]))
couple = floater + comma + floater
M_command = "M" + Group(couple)
C_command = "C" + Group(couple + couple + couple)
L_command = "L" + Group(couple)
Z_command = "Z"
svgcommand = M_command | C_command | L_command | Z_command
phrase = OneOrMore(Group(svgcommand))
## Find and open the svg file
xml_file = os.path.abspath(__file__)
xml_file = os.path.dirname(xml_file)
xml_file = os.path.join(xml_file, file)
tree = et.parse(xml_file)
ns = "http://www.w3.org/2000/svg" #The XML namespace.
paths = []
for group in tree.getiterator('{%s}g' % ns):
for e in group.getiterator('{%s}path' % ns):
p = e.get("d")
tokens = phrase.parseString(p.upper())
paths.append(tokens) # paths is a global var.
run(Shapes)
Loading fonts using FreeType for cairo use in Python
Back to cookbook
The following snippet uses Python's ctypes module to load a font file using FreeType and
create a cairo font face from it, using the cairo-ft API that is not part of pycairo yet.
The resulting cairo font face however can be used normally with pycairo.
import ctypes
import cairo
_initialized = False
def create_cairo_font_face_for_file (filename, faceindex=0, loadoptions=0):
global _initialized
global _freetype_so
global _cairo_so
global _ft_lib
global _surface
CAIRO_STATUS_SUCCESS = 0
FT_Err_Ok = 0
if not _initialized:
# find shared objects
_freetype_so = ctypes.CDLL ("libfreetype.so.6")
_cairo_so = ctypes.CDLL ("libcairo.so.2")
# initialize freetype
_ft_lib = ctypes.c_void_p ()
if FT_Err_Ok != _freetype_so.FT_Init_FreeType (ctypes.byref (_ft_lib)):
raise "Error initialising FreeType library."
class PycairoContext(ctypes.Structure):
_fields_ = [("PyObject_HEAD", ctypes.c_byte * object.__basicsize__),
("ctx", ctypes.c_void_p),
("base", ctypes.c_void_p)]
_surface = cairo.ImageSurface (cairo.FORMAT_A8, 0, 0)
_initialized = True
# create freetype face
ft_face = ctypes.c_void_p()
cairo_ctx = cairo.Context (_surface)
cairo_t = PycairoContext.from_address(id(cairo_ctx)).ctx
_cairo_so.cairo_ft_font_face_create_for_ft_face.restype = ctypes.c_void_p
if FT_Err_Ok != _freetype_so.FT_New_Face (_ft_lib, filename, faceindex,
ctypes.byref(ft_face)):
raise "Error creating FreeType font face for " + filename
# create cairo font face for freetype face
cr_face = _cairo_so.cairo_ft_font_face_create_for_ft_face (ft_face, loadoptions)
if CAIRO_STATUS_SUCCESS != _cairo_so.cairo_font_face_status (cr_face):
raise "Error creating cairo font face for " + filename
_cairo_so.cairo_set_font_face (cairo_t, cr_face)
if CAIRO_STATUS_SUCCESS != _cairo_so.cairo_status (cairo_t):
raise "Error creating cairo font face for " + filename
face = cairo_ctx.get_font_face ()
return face
if __name__ == '__main__':
face = create_cairo_font_face_for_file
("/usr/share/fonts/dejavu-lgc/DejaVuLGCSerif.ttf", 0)
surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, 128, 128)
ctx = cairo.Context(surface)
ctx.set_font_face(face)
ctx.set_font_size(30)
ctx.move_to(0, 44)
ctx.show_text("Hello,")
ctx.move_to(30, 74)
ctx.show_text("world!")
del ctx
surface.write_to_png("hello.png")
Cairo's compositing operators
Normally, you will be using cairo to draw objects on top of each other. But cairo can do
differently, if you need it! In fact, you can use all the Porter/Duff compositing operators.
Fourteen different operators are currently available in cairo. This page is a try to
describe them. It may contain errors and is possibly incomplete. Please help to improve it!
Example images
It is probably best to describe the effect of compositing operators by showing example
images, so that's what is done below. The images show the result of drawing an object (a
translucent blue rectangle) onto a surface which already contains another image (a
translucent red rectangle).
The operator names try to describe what the operators mean. Two words need to be mentioned:
the source and the destination (or dest). In this context, these provide the two objects
which contribute to the graphical output of the drawing operation. The destination is the
name of the surface before the drawing operation, the source is the name of what is added
while drawing.
The Destination
To create the example images, the red rectangle is first drawn to the (empty) destination
surface with the default operator:
cairo_rectangle (cr, 0, 0, 120, 90);
cairo_set_source_rgba (cr, 0.7, 0, 0, 0.
;cairo_fill (cr);
The surface is now a transparent plane with a partially transparent rectangle in it. This
represents the destination to which the next drawing operation will be performed. Both the
red and the fully transparent part of the surface are now natural parts of the destination.
Setting the compositing operator
The current operator is now set using cairo_set_operator().
The Source
The tutorial describes how drawing works in cairo:
"Cairo internally draws with one fundamental drawing operation: the source and mask are
freely placed somewhere over the destination. Then the layers are all pressed together and
the paint from the source is transferred to the destination wherever the mask allows it."
However, there is no mention of a mask in the names of the compositing operators. They refer
to a source and a destination only. This allows for two different interpretations with
regard to what should be regarded as the source for the compositing operation:
Since the mask determines where the paint from the source is transferred, it also determines
the area in which the compositing operation is performed. This interpretation can be called
bounded.
The area where the compositing operation is performed is not bounded by the mask. Instead,
any parts where the source layer is not transferred are considered to be fully transparent.
We call this interpretation of the source unbounded.
For some of the operators, both interpretations lead to the same result, for others they do
not. In cairo, the actual interpretation depends on the operator. The unbounded operators
modify destination outside of the bounds of the mask. However, their effect can still be
limited by way of clipping.
The blue rectangle is drawn with the new operator in effect:
cairo_rectangle (cr, 40, 30, 120, 90);
cairo_set_source_rgba (cr, 0, 0, 0.9, 0.4);
cairo_fill (cr);
The results can be seen in the images below. Note that both rectangles are drawn with
transparency. When studying the images, you may be able to guess how they would look for
opaque objects, too. For reference, the code to create the images is also available.
Operators
For the mathematical description, it is convenient to use the following conventions:
The index A (assigned to color components and transparency factor) refers to the source,
while the index B refers to the destination. The index R refers to the result of the
compositing operation.
Each pixel in both the source and the destination is fully described by a tuple (r, g, b,
a). We will use "x" as a shorthand for any color component, since they are always treated
the same. "a" describes the alpha value (opacity) and is treated differently.
The product of xA and aA is described by xaA. xaB and xaR have analogous meaning.
The color computations equations contain a division by aR, which cannot be done where aR is
zero. But in this case the color doesn't matter anyway (full transparency) and can also be
set to zero. (Internally, the colors may be handled differently, so this might or might not
be necessary.)
CAIRO_OPERATOR_CLEAR
Where the second object is drawn, the first is completely removed. Anywhere else it is left
intact. The second object itself is not drawn.
The effect of the CLEAR operator depends on the interpretation of the source. In cairo, this
operator is bounded.
Resulting alpha (aR) Resulting color (xR)
0 0
CAIRO_OPERATOR_SOURCE
The second object is drawn as if nothing else were below. Only outside of the blue rectangle
the red one is left intact.
The effect of the SOURCE operator depends on the interpretation of the source. In cairo,
this operator is bounded.
Resulting alpha (aR) Resulting color (xR)
aA xA
CAIRO_OPERATOR_OVER
The image shows what you would expect if you held two semi-transparent slides on top of each
other. This operator is cairo's default operator.
The output of the OVER operator is the same for both bounded and unbounded source.
Resulting alpha (aR) Resulting color (xR)
aA + aB·(1-aA) (xaA + xaB·(1-aA))/aR
CAIRO_OPERATOR_IN
The first object is removed completely, the second is only drawn where the first was.
Note that the transparency of the first object is taken into account. That is, the small
blue rectangle is slightly lighter than it would have been, had the first object been
opaque.
The effect of the IN operator depends on the interpretation of the source. In cairo, this
operator is unbounded.
Resulting alpha (aR) Resulting color (xR)
aA·aB xA
CAIRO_OPERATOR_OUT
The blue rectangle is drawn only where the red one wasn't. Since the red one was partially
transparent, you can see a blue shadow in the overlapping area. Otherwise, the red object is
completely removed.
The effect of the OUT operator depends on the interpretation of the source. In cairo, this
operator is unbounded.
Resulting alpha (aR) Resulting color (xR)
aA·(1-aB) xA
CAIRO_OPERATOR_ATOP
This leaves the first object mostly intact, but mixes both objects in the overlapping area.
The second object object is not drawn except there.
If you look closely, you will notice that the resulting color in the overlapping area is
different from what the OVER operator produces. Any two operators produce different output
in the overlapping area!
The output of the ATOP operator is the same for both bounded and unbounded source.
Resulting alpha (aR) Resulting color (xR)
aB xaA + xB·(1-aA)
CAIRO_OPERATOR_DEST
Leaves the first object untouched, the second is discarded completely.
The output of the DEST operator is the same for both bounded and unbounded source.
Resulting alpha (aR) Resulting color (xR)
aB xB
CAIRO_OPERATOR_DEST_OVER
The result is similar to the OVER operator. Except that the "order" of the objects is
reversed, so the second is drawn below the first.
The output of the DEST_OVER operator is the same for both bounded and unbounded source.
Resulting alpha (aR) Resulting color (xR)
(1-aB)·aA + aB (xaA·(1-aB) + xaB)/aR
CAIRO_OPERATOR_DEST_IN
The blue rectangle is used to determine which part of the red one is left intact. Anything
outside the overlapping area is removed.
This works like the IN operator, but again with the second object "below" the first.
Similar to the two interpretations of the source, it is possible to imagine the same
distinction with regard to the destination. In cairo, the DEST_IN operator is unbounded.
Resulting alpha (aR) Resulting color (xR)
aA·aB xB
CAIRO_OPERATOR_DEST_OUT
The second object is used to reduce the visibility of the first in the overlapping area. Its
transparency/opacity is taken into account. The second object is not drawn itself.
The output of the DEST_OUT operator is the same for both bounded and unbounded
interpretations.
Resulting alpha (aR) Resulting color (xR)
(1-aA)·aB xB
CAIRO_OPERATOR_DEST_ATOP
Same as the ATOP operator, but again as if the order of the drawing operations had been
reversed.
In cairo, the DEST_ATOP operator is unbounded.
Resulting alpha (aR) Resulting color (xR)
aA xA·(1-aB) + xaB
CAIRO_OPERATOR_XOR
The output of the XOR operator is the same for both bounded and unbounded source
interpretations.
Resulting alpha (aR) Resulting color (xR)
aA + aB - 2·aA·aB (xaA·(1-aB) + xaB·(1-aA))/aR
CAIRO_OPERATOR_ADD
The output of the ADD operator is the same for both bounded and unbounded source
interpretations.
Resulting alpha (aR) Resulting color (xR)
min(1, aA+aB) (xaA + xaB)/aR
CAIRO_OPERATOR_SATURATE
The output of the SATURATE operator is the same for both bounded and unbounded source
interpretations.
Resulting alpha (aR) Resulting color (xR)
min(1, aA+aB) (min(aA, 1-aB)·xA + xaB)/aR
Links
The original paper by Thomas Porter and Tom Duff:
http://keithp.com/~keithp/porterduff/p253-porter.pdf,
The description of the X Rendering Extension by Keith Packard is where the information about
the ADD and SATURATE operators comes from: http://keithp.com/~keithp/render/protocol.html
A description of compositing in SVG 1.2 by Craig Northway:
http://www.svgopen.org/2005/papers/abstractsvgopen/
