Introduction to Pycairo

Pycairo is a Python module providing bindings for the widely used Cairo graphics library. Cairo is a 2D graphics library used for generating high-quality graphics in various output formats, like PNG, PDF, SVG, and others. With Pycairo, developers can create vector graphics, render images, and design applications with detailed custom visualizations.

Getting Started with pycairo

Installing pycairo is simple. You can install it using pip:

pip install pycairo

Once installed, you can begin creating and manipulating high-quality graphic outputs with ease.

Essential pycairo APIs and Code Snippets

1. Creating a Basic SVG File

The following code demonstrates how to create a simple SVG file using pycairo:

 import cairo
WIDTH, HEIGHT = 400, 400
with cairo.SVGSurface("example.svg", WIDTH, HEIGHT) as surface:
    context = cairo.Context(surface)
    context.set_source_rgb(0, 0, 0)  # Black
    context.paint()  # Fill the entire surface with black
    context.set_source_rgb(1, 0, 0)  # Red
    context.rectangle(50, 50, 200, 200)  # Set up a rectangle
    context.fill()  # Fill the rectangle with red

2. Drawing Shapes

Pycairo allows you to draw shapes such as circles, rectangles, and polygons. Here’s how to draw a circle:

 with cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT) as surface:
    context = cairo.Context(surface)
    context.set_line_width(5)
    context.arc(WIDTH / 2, HEIGHT / 2, 100, 0, 2 * 3.14)  # A circle
    context.set_source_rgb(0, 1, 0)  # Green
    context.stroke()
    surface.write_to_png("circle.png")

3. Adding Text

In pycairo, you can render text onto your surfaces. Here’s an example:

 with cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT) as surface:
    context = cairo.Context(surface)
    context.select_font_face("Sans", cairo.FONT_SLANT_NORMAL, cairo.FONT_WEIGHT_NORMAL)
    context.set_font_size(40)
    context.move_to(100, 100)
    context.set_source_rgb(0, 0, 1)  # Blue
    context.show_text("Hello Pycairo!")
    surface.write_to_png("text.png")

4. Gradients

Pycairo supports linear and radial gradients. Here’s how to create a linear gradient:

 with cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT) as surface:
    context = cairo.Context(surface)
    linear = cairo.LinearGradient(0, 0, WIDTH, HEIGHT)
    linear.add_color_stop_rgba(0, 1, 0, 0, 1)  # Red at start
    linear.add_color_stop_rgba(1, 0, 0, 1, 1)  # Blue at end
    context.rectangle(0, 0, WIDTH, HEIGHT)
    context.set_source(linear)
    context.fill()
    surface.write_to_png("gradient.png")

5. Composing Images

Combining multiple elements is easy in pycairo. Here’s an example of combining text and shapes:

 with cairo.ImageSurface(cairo.FORMAT_ARGB32, WIDTH, HEIGHT) as surface:
    context = cairo.Context(surface)
    # Draw background
    context.set_source_rgb(0.95, 0.95, 0.95)  # Light gray
    context.paint()

    # Draw circle
    context.set_source_rgb(1, 0, 0)  # Red
    context.arc(WIDTH / 2, HEIGHT / 2 - 50, 50, 0, 2 * 3.14)
    context.fill()

    # Add text
    context.select_font_face("Sans")
    context.set_font_size(30)
    context.set_source_rgb(0, 0, 0)  # Black
    context.move_to(100, HEIGHT / 2 + 50)
    context.show_text("Pycairo Art")
    surface.write_to_png("composition.png")

Building a Small Application with pycairo

Let’s build a simple application that creates a bar chart using pycairo APIs:

 data = {"A": 10, "B": 20, "C": 30, "D": 40}
with cairo.ImageSurface(cairo.FORMAT_ARGB32, 400, 300) as surface:
    context = cairo.Context(surface)
    context.set_source_rgb(1, 1, 1)  # White background
    context.paint()

    max_height = 200
    bar_width = 50
    spacing = 20

    for i, (label, value) in enumerate(data.items()):
        x = i * (bar_width + spacing) + 50
        height = int((value / max(data.values())) * max_height)
        y = 300 - height - 50

        # Draw bar
        context.set_source_rgb(0.2, 0.4, 0.8)  # Blue bars
        context.rectangle(x, y, bar_width, height)
        context.fill()

        # Add label
        context.set_source_rgb(0, 0, 0)  # Black text
        context.select_font_face("Sans")
        context.set_font_size(14)
        context.move_to(x, 290)
        context.show_text(label)

    surface.write_to_png("barchart.png")

Conclusion

Pycairo is a powerful library for creating high-quality 2D graphics programmatically. With its wide range of APIs, you can draw shapes, render text, work with gradients, and design entire graphics systems. From building visualizations to custom application interfaces, Pycairo offers developers the flexibility and tools they need to create compelling graphics. Download pycairo today and explore the endless possibilities!