Intro to Cairo Graphics in Rust


In the past few weeks, I’ve been itching to learn some new stuff. Those who know me even just a little bit know that “new stuff” is generally going include “new ways of creating graphics and/or animations”. And so it does this time.

I’ve been creating graphics in HTML5 Canvas for quite a few years now, and that’s cool. But there are a few pain points with its workflow:

1. It sometimes seems silly to pipe everything through the browser all the time. I’d like to just be able to run a program and have it create a file and display that file.

2. Running in the browser via the file system introduces various security issues, so you need to run some kind of local server, and even then you run into issues with saving files to disk automatically, so you need to right click and save or set up some kind of button to save an image.

3. At work, I’m using React with Webpack and Babel, so I get to use the latest and greatest ECMAScript with classes and all the other syntactic sugar. It’s really nice, but setting all of that up is not trivial. For a one-time large project, it’s not a huge deal to spend some time on creating all that config. But if you’re going to be doing random experiments all the time, it’s a ton of overhead. I get stuck with whatever the current browsers implement.

So I’ve been looking for some other language / drawing api I could learn.

After a short amount of searching, I came across Cairo Graphics.

It’s a 2D graphics library, written in C, but has bindings for several other languages. Well, that sounds pretty cool. Looking over the tutorials and api documents (, I see that you create a surface, then get a context from that surface, then call various commands on the context such as move_to and line_to, and then follow up with stroke and/or fill. Well that sounds awfully familiar. In fact, I’m going to guess that HTML5’s Canvas is either backed up by Cairo at some level, or is at the very least inspired by Cairo’s api. At any rate, it sounded worth looking into.

I wasn’t about to dive into C programming, but as I mentioned, there are bindings for several other languages. The first I tried was Python, and that worked great. I’ll probably do another tutorial on pyCairo at some point, but I wanted to take it a little further and really dive into something new. I’ve had my eye on a couple of languages – Rust and Go. Both have Cairo bindings, so I flipped a coin and decided to try out Rust.

Rust is a pretty interesting programming language. It’s built around speed and safety – preventing you from doing bad things. As such, it has some programming paradigms that seem really strange at first. But there’s a lot of logic behind those decisions. I’m not going to do a Rust tutorial here. But the documentation on how to learn the language is some of the best learning material I’ve seen on any site for any language or system.

Just start reading “The Book”:

I’m going through the Second edition, which is still listed as “under construction”, but I haven’t run into any flaws or incompleteness as of yet.

What I do want to cover in this tutorial is using Cairo in Rust. There’s a lot resources on how to use Cairo, lots of stuff on how to use Rust. But the center part of the Venn diagram is rather thin.

So, here’s what you need to do:

1. Install Rust and learn how to program in it. At least the basics. I had to read maybe 1/3 of “The Book” before I felt I was ready to start trying to pull in the Cairo bindings and create some graphics.

2. Install Cairo. This is the C library itself. It needs to be on your system so that the Rust bindings for Cairo have something to bind to.

I’m on Ubuntu, so this was really easy, just:

sudo apt install libcairo2-dev

On MacOS, it seems you’re supposed to use MacPorts, which I’m not really familiar with, or fink, which I’ve never heard of.

On Windows, it looks like you just have to add a few dlls to your path.

OK, we’ll carry on, assuming you got Cairo installed.

3. Create a project and set up the dependencies.

Again, this is not a Rust tutorial, but to create a Rust project, you can use cargo new.

cargo new cairo_stuff --bin

This creates a new project named cairo_stuff, which will be a binary executable, (bin) as opposed to a library project.

You’ll see a new folder with the project name. Inside that will be a src folder and a .toml file. It also sets up the project to use git by default, so you get a .git folder and .gitignore file. The .toml file is the project configuration file. It should look something like this:

name = "cairo_stuff"
version = "0.1.0"
authors = ["Your Name <>"]


The authors data is taken from your .gitconfig file if you have one. We need to add our Cairo binding as dependencies for this project. To do that, we list them under dependencies. We’ll need two packages or “crates” as they are called in Rust.

We’ll need the png crate so we can save images, and the cairo-rs crate which contains the actual Cairo bindings. We also need to add png as a feature to cairo-rs, so that cairo-rs itself knows how to save pngs.

Whenever you’re doing dependency configuration in any language, it’s important to have a way to know what versions of different dependencies are available. In Rust, you can go to and search for the package you want to add, in this case, “png”.

The first match tells us that we want version 0.11.0.

And for cairo-rs, it’s 0.2.0.

Note, these will definitely and continuously change, so actually go to the site and check the numbers.

For png, we can just add a line in the dependencies section that says

png = "0.11.0"


But the cairo-rs line is a bit more complicated because we need to pass png into it as a feature. So we say

png = "0.11.0"
cairo-rs = { version = "0.2.0", features = ["png"] }

Again, read “The Book” to fully understand all the syntax here. But this will get you up and running.

Now, if you look at the main source file in the project, it’s src/ and it looks like this:

fn main() {
    println!("Hello, world!");

If you’ve done any kind of programming, all that should be pretty self-explanatory. You have a function called main. Rust follows the pattern of many other languages where main is the function that is called when the program is executed.

In main, we call println, passing a string. Other than the exclamation point there, it should be straightforward. (The ! indicates that println is implemented as a macro, not a function, but … whatever.)

At this point you can call cargo run from the main project directory. This will satisfy all your dependencies, build the executable, and run it. It should print out the message “Hello, world!”. Great! It probably took a while to download everything it needed. But if you run it again, it should complete almost instantly.

If you now look in your project folder, you’ll see you have a Cargo.lock file and a target folder. The target is where your final executable and all the build artifacts are. The lock file lists all the other dependencies that got pulled in when you added png and cairo-rs. For me, this file wound up at 171 lines, so there were quite a few other libraries it needed to pull down to satisfy those two that we added.

Let’s Draw Some Stuff

Now that we’ve set things up, let’s draw something.

Here are the basic steps:

1. Create an image surface.

2. Create a 2D drawing context that references that surface.

3. Draw things.

4. Create a file.

5. Write the surface to the file as a png.

For most of your projects, steps 1, 2, 4 and 5 are going to be boilerplate. The meat is going to be step 3 where you draw the actual content you want to draw.

First, we’re going to need to import the cairo-rs bindings. That’s an external crate that we downloaded in our dependencies. So up at the top of the file we say

extern crate cairo;

Note that although the crate name was cairo-rs, we just link to it as cairo.

We’ll be using three modules from the cairo library: ImageSurface, Format, and Context. We could access these like so:


But repeating that leading cairo:: every time is unnecessary. Instead we can say:

use cairo::{ ImageSurface, Format, Context };

This would be equivalent to something like the following in the latest versions of JavaScript:

import { ImageSurface, Format, Context } from "cairo";

Now we can use those modules directly. Next, let’s make our surface. Delete the println line inside of main and add this instead:

let surface = ImageSurface::create(Format::ARgb32, 600, 600);

So ImageSurface has a method named create which gets a format, width and height and creates a new surface. The format will have four channels – a, r, g, b – each 32 bits.

But actually, this is not quite right as it stands. The ImageSurface::create method does not directly return a surface, it returns a result because this call may fail. Maybe you don’t have enough memory to make a surface the size that you requested for example. So you need to check the result to make sure that it’s valid before proceeding.

There are a few ways to handle that result and get at the surface. Rust provides a quick shortcut to let us do this in one step: just call expect, passing in a message string. If the call succeeds, it will pass through the newly created surface. If it fails, the program will crash, displaying your message.

let surface = ImageSurface::create(Format::ARgb32, 600, 600)
    .expect("Couldn't create a surface!");

Now, obviously, this is not great error handling for a program you’re going to release into the world, but it’s good enough for a first pass of something you’re testing out.

Now we create a context based on this surface, assuming it gets created.

let context = Context::new(&surface);

Context has a new method which takes a reference to a surface, hence the ampersand. (Read “The Book”!)

Now we have a context to draw stuff on! Let’s start by painting it red.

context.set_source_rgb(1.0, 0.0, 0.0);

set_source_rgb takes three normalized floating point values. paint fills the context with the current source value.

Where is My Image?

So how do we see this thing? The program we are creating has no UI. It just runs on the command line. We can’t just display the image in a window, because we have no window. We can save it to a file though.

First we need to create a file object. That would be std::fs::File. We can use use up at the top to shorten that in our code.

use std::fs::File;

After the context.paint() line, create the file:

let mut file = File::create("output.png")
    .expect("Couldn't create file.");

The mut there means this is a mutable variable. It can be changed. By default, variables are immutable in Rust. Our next line will require a mutable reference though, so we make file mutable. Again, this call may fail, so we tack on expect with a message string so that we get a file not a result, and we’ll crash if this fails.

Now we can write the surface as a png to this file:

surface.write_to_png(&mut file)
    .expect("Couldn't write to png");

The write_to_png method needs a mutable reference to a file object. &mut file is how we specify that (see “The Book”). And once again, we check the result.

And that’s that. Here’s the whole program:

extern crate cairo;
use cairo::{ ImageSurface, Format, Context };
use std::fs::File;

fn main() {
    let surface = ImageSurface::create(Format::ARgb32, 600, 600)
        .expect("Couldn't create surface");
    let context = Context::new(&surface);
    context.set_source_rgb(1.0, 0.0, 0.0);
    let mut file = File::create("output.png")
        .expect("Couldn't create file");
    surface.write_to_png(&mut file)
        .expect("Couldn't write to png");

When you run that, you should wind up with a file called ouput.png in the main project directory. It should be a 600×600 red square.

Wait, That’s Not Drawing!

OK, OK, filling a png with a single color is not really drawing. Let’s get a taste of the drawing api itself. I’m just going to throw the whole file at you and let you figure it out.

extern crate cairo;
extern crate rand;

use cairo::{ ImageSurface, Format, Context };
use std::fs::File;

fn main() {
    let surface = ImageSurface::create(Format::ARgb32, 600, 600)
        .expect("Couldn't create surface");
    let context = Context::new(&surface);

    // paint canvas white
    context.set_source_rgb(1.0, 1.0, 1.0);

    // draw 100 random black lines
    context.set_source_rgb(0.0, 0.0, 0.0);
    for _i in 0..100 {
        let x = rand::random::<f64>() * 600.0;
        let y = rand::random::<f64>() * 600.0;
        context.line_to(x, y);

    let mut file = File::create("output.png")
        .expect("Couldn't create file");
    surface.write_to_png(&mut file)
        .expect("Couldn't write to png");

Again, the top and bottom of this file is mostly boilerplate. After we create the surface and context, we paint the surface white this time, and use a for loop to draw 100 lines. This is done with context.line_to.

Note that we’re using a random number generator here. That’s another crate. Up top I’ve imported that with extern crate rand; I’ll leave it up to you to search to find the current version and add it to your .toml file.

Now the random functionality gets a bit wordy here, with specifying the type each time (f64 = 64-bit floating point number). But you’re probably going to want to create your own random range function anyway, so you can say random(min, max) and get a result in that range. When you do that, you can just abstract the actual random call within that function.

What Next?

I’ve already said it enough, but read “The Book” if you want to learn more about Rust. It’s really that good.

In terms of cairo-rs, all the api docs are here:

And all the actual drawing commands are on the context object here:

A lot of those will look really familiar if you’ve been working in HTML5 Canvas. move_to, line_to, curve_to, arc, rectangle, etc.

And once you’re familiar with Rust and cairo-rs, you should be able to go to any C-specific Cairo documentation and figure out how that can be translated over to Rust.

One point I want to address briefly is that I said in the beginning that setting up a Webpack/Babel project in order to use the latest and greatest JavaScript features is cumbersome. After reading this article, you might be thinking that setting up a Rust project is just as cumbersome, maybe more so.

But it’s not really. Installing Rust and Cairo itself may have taken a bit, but those are one time actions. Once they’re on your system, you’re done. From there, a new project is as simple as running cargo new and adding two lines for the dependencies. For the source file, you can create some kind of snippet or template for all that boilerplate stuff and you’re off to the races, writing drawing commands in under a minute.

Anyway, hopefully this starts you on some kind of journey of learning something new.

Flow Fields, Part II


In Flow Fields, Part I, we covered what a flow field is and looked at a few different formulas to create them. And we rendered flow fields in a various ways. We even animated particles being influenced by fields. In this article we’ll cover a couple more ways to generate flow fields and some new ways to render them. As I said in the first part, the possibilities are endless. I’m just pointing you in a few directions to get started.

Perlin Noise

Using simple math and minimal trigonometry gave us some pretty interesting patterns, but they wound up being very regular and repeating. The more complex function we used (the strange attractor) made for a fairly uninteresting field by itself, but was beautiful with particles tracing lines across it.

What would be nice is something complex but non-repeating. Perlin noise fits the bill, which is why it is used so often to create flow fields. Perlin noise was invented by Ken Perlin and was initially used to generate natural looking textures for computer generated special effects in movies and video games. It gives you random values across a two- or three-dimensional field, and ensures that there is a nice, smooth gradient between the various values. With different settings, scaling and colors applied, you can get textures that look like smoke, fire, liquid, wood grain, rusty metal, etc.

We can tap into Perlin noise to create a flow field that varies all over the place and never repeats. And we can animate it as well by creating a 3D Perlin noise field and moving through slices of it on the z-axis. More on that soon.

If you’re using Processing or some other platform, you may have a Perlin noise function built in. If you’re just using plain vanilla JavaScript like me, however, you’ll need a Perlin noise library to generate the values. There are a few out there. I’m going to use one by Seph Gentle (josephg on github) at I’ve downloaded that into my project folder.

I’m going to start with the same basic HTML file as last time, and add the perlin.js library in the script tag.

And here’s the first script file:

The first block is the same as before. Then we seed the Perlin noise library with a random number so we’ll get a new image each time, and call render.

The render function loops through the canvas in a grid-like fashion as before, getting a value and drawing a line there. All pretty much the same as last time.

It’s the getValue function that changes. Now we’re going to get the value directly from the Perlin noise function. This noise library has a few different functions. We’ll use the 2d Perlin noise function, perlin2, for now. This just takes an x and a y. We’ll scale it down somewhat to make a more interesting pattern. The result of this is a number from -1 to +1. So we can multiply that by 2 PI to get a direction in radians. That’s all, folks. And here’s what it gives us:

Pretty cool, eh? Let’s change the res variable to 2. This makes a much tighter grid:

And now we can see what happens if we change the scale, to maybe 0.004.

It’s like zooming in.

Now, consider 3d Perlin noise as a stack of these 2d Perlin flow fields layered on top of each other, each one varying just a bit. If we could flip through them, one by one, we could see them animating. That’s exactly what our next file does, using the noise.perlin3 function:

Here, we add a z variable set to zero. Then we clear the canvas at the start of render so we can redraw each time. Finally, we increase z by a very small amount and call requestAnimationFrame(render) to set up the next frame of the animation.

The getValue function calls noise.perlin3, passing in the current z. No other changes. A still image would look about the same as the first image in this article, but if you actually run this one, you’ll see a lovely, flowing animation, reminiscent of seaweed, or amber waves of grain.

OK, what’s next? Well, last time we moved on to having the flow field influence the movement of some particles. We’ll do the same thing here, using the Perlin-based flow field.

Again, we create a column of particles on the left edge of the screen, and on each frame, update each particle’s position and draw a line from its last position to where it currently is. This gives us a trail of its movement. The major change here is, again, that we’re using Perlin noise to calculate the flow field. Here’s what we get:

And of course, this looks even cooler as you watch it animate and build up.

One last Perlin example. We’ll use 3d Perlin noise again. This time, on each frame, we’ll create a column of particles down the center of the canvas and iterate each one’s path 500 times. That will create a bunch of flowing lines. Then we’ll update z and draw the next frame. Now, the path of each particle is altered a bit differently on each frame, so you get an eerie, undulating flow going on. The further out from their source each particle gets, the more its path differs from the last frame. Sometimes it jumps off in a totally different direction, giving it a weird, glitchy feeling. The code:

And a single frame of the animation, which you’ll want to see in motion:

What else?

Well, we’ve created flow fields with simple and complex formulas and used third party libraries to create them. You might want to play with the simplex noise contained in that noise library we were using. It’s similar to Perlin noise, also created by Ken Perlin, but has a bit of a different feel to it.

But really we can use anything we want to create a flow field. All we need is something that maps an x, y coordinate to a value. So where could we get a source of values that are mapped to x, y coordinates? Like a map of different… bits of information… like a bit… map. OK, I guess you see where I’m going here. So yeah, any image is simply a 2d map of values. If we can take an image and pass in x and y to some function to get the value at that location, we are golden. And in HTML canvas, we can. And it’s likely you can do the same thing if you are using some other system.

I’ve created a Bitmap module. I’m not going to show it or go into it much here, but you can check out the source at the repo I’ll post at the end of the article. The module takes a url and an onComplete callback that gets called when it’s ready. It then has a getValue method that takes x, y parameters and returns a value between 0 and 255. This is an average of the red, green and blue values of that pixel and basically equates the brightness of the image at that point.

Here’s how we use it:

We create the initial canvas, but we don’t size it full screen like we did before. Then we create the bitmap and wait for it to complete. When it does, we set the canvas to be the same size as the bitmap, create 1000 random points, and call render.

Most of render should look pretty familiar. Get the value at the current location and use that to influence the particle’s velocity. Note that I extracted a couple of values, force and friction. Playing with these can give you very different behaviors. Try out different values. The other main difference here is that if a particle goes off the canvas, we set it back to a random location again.

Finally, the getValue function calls bitmap.getValue. Remember, that will return a value from 0 to 255. So we convert that to be in the range of 2 PI. And that’s it.

All you have to do is supply it an image. Note that for security reasons, you’re not going to just be able to link to any image from anywhere on the web, and you’re probably not going to be able to run this example from the file system. I just set up a simple node.js based server using the http-server package and serve the app and image from there as localhost:8080.

Supplying a random cat image (because this is the Internet, after all), we get the following:

You might even be able to see a hint of the cat there. But if you uncomment line 12 in the code, it will draw the original image before starting to animate the particles. With that, you see the following:

So, there’s a few more ideas. Different images, different settings, different ways of rendering or animating, all make for infinite possibilities. Now you can go explore some of them. Have fun.

The code for all of this can be found at: . Note that the code here is not necessarily super clean or ruggedly tested. I’m just having fun here and pretty much just stopped when things looked good.

Useful, or at least fun?

I plan to use the money I make from these posts to finance my presidential campaign. Or at least pay my Netflix bill for a month or two. If you’re down for helping me with either of those two things…

Flow Fields, Part I


Maybe you’ve heard the term “flow field” and maybe you’ve seen some neat pictures or animations with the term attached. In this article, I’ll cover what a flow field is, show how to create one, and give a few examples of experimenting with them. Flow fields are also known as vector fields.

The Pre-Game Show

I’ll be using HTML5, JavaScript and Canvas for this article, but the concepts will apply to Processing, p5js, WebGL, or just about any other graphics programming platform. That being the case, I’m going to try to focus less on the canvas specific stuff and more on the core concepts.

But, to just lay the foundations, I’m going to go over the files we’re using. It’s all going to be super basic. An HTML file and a JavaScript file. Here’s the HTML:

A bit of CSS, my QuickSettings Panel, which might come in handy eventually, a canvas element and a link to the main script. The script is going to start out like this:

All we’re doing here is getting a reference to the canvas and its context, then resizing the canvas so it fills the browser window, saving the width and height values for later use. Some of the CSS in the HTML file aids in all this being fully possible.

The Main Event: Flow Fields

So, what is a flow field? Well, you can think of a field as just a two-dimensional area. Of course, you could have a 3D flow field, but let’s save that for another day. You can also think of a magnetic field.

In this image of iron filings revealing a magnetic field, you see various lines and loops. The strength and orientation of the magnetic force is different in different areas of the field. You can imagine that an object moving through this field would be influenced by it and tend to move along those visible lines.

Basically, that’s what we want to do – create a two-dimensional area where each point has a different value. But these aren’t just random values. A particular point has a particular value and as you move out from that point to neighboring points, you get similar, but gradually changing values. In flow fields, these values are usually interpreted as directions. So if you map your values so they are between 0 and 360, they can be directly used as degrees of direction. Of course, we’ll probably map them between 0 and 2PI radians because the computer likes that better.

Once we have values for each point, we can graphically render each one based on it value. For example, we can draw a line pointing in the direction associated with that value.

So that brings us to two different tasks – how to come up with the different values for the field, and how to render the different values on the field. The great thing is, there are no correct answers for either one of those questions. In fact, there are nearly infinite ways of doing either one, so you can explore this technique for quite a while.

Let’s start out really simple, to get the idea of what’s going on. I’m just going to loop through from left to right and top to bottom, every 10 pixels. The value for that point on the grid will simply be (x + y) * 0.01 % Math.PI * 2. Just adding x and y together, scaling it down and modding it by 360 degrees (Math.PI * 2 radians). Then we render that value by translating to that point, rotating by the value and drawing a short line at the point.

Simple as that all is, we already have the start of something interesting going on.

You might now see why this is starting to be something you’d call a “flow field”. As you follow the directions of the lines, you start to see some very directional motion going on.

We can start cleaning this up a bit by extracting the two things that we’ve already determined are going to change a lot – the calculation of the value and how each value point is rendered. We’ll put each one of those into its own function and call them where appropriate.

No change in behavior, but we’ve isolated the things that we now want to change. Furthermore, we don’t necessarily always want this to be in a strict grid. Instead we can grab any number of random points on the grid and render those.

I’ve arbitrarily defined a value of 20,000 for number of points to render. Just looping through that many times, getting a random point and finding its value and rendering it. I’ve changed a few other values as well, such as the length of the line and the scale value that (x + y) is multiplied by. Now we’re getting something a bit more natural looking.

At this point, we can just start messing with the formula we use to get the value. Generally, you’re going to want to use the x and y inputs somehow, but really, just do whatever you want here. Here’s a somewhat interesting one I came up with.

Just taking the sine of x and y and adding them together. Some rendering changes too: reduced the line width and varied the line length at each point. But with just those few small changes, we’re onto something really hairy looking.

Now I could spend all day iterating on this – different formulas, different parameters for the lines it’s drawing etc. I know I could spend all day on it because I have spent whole days doing just that in the past. But let’s move on to something else.

Earlier I mentioned the idea that you could possibly imagine an object moving through a flow field and being influenced by those flows. Let’s simulate that. I’ll start with a single random point. Call it a particle. This particle will actually be an object with not only position, but velocity on the x and y axes. Initially these will be set to zero. On each iteration, wherever the particle is, we’ll get the value at that location – which is a direction, remember – and use that value to influence the particle’s velocity. Then we’ll add that velocity to the position to get a new position. And repeat.

Hopefully the comments explain a bit more what’s going on here. This gives us the following:

What’s interesting in this case is that we no longer actually see the field. We only see the result that the field has on the motion of the particle.

Do run this one on your own. It’s pretty neat to watch the drawing build up over time. You can see that the flow field is influencing the way the particle moves. You can change some of those hard-coded values to see what they do to the motion. Even in just our fifth iteration here, we have a ton of things to experiment with.

Let’s do one more for this article. Where one particle was fun, more particles is… more fun.

Here, I just made an array of particles and arranged them down the left side of the screen. For the algorithm, I used a strange attractor called the “Clifford Attractor”, published by Paul Bourke and attributed to Clifford Pickover. You can see the code for that here: This gives you a very complex field. The parameters, a-d, are randomized at the top of the file, so you’ll get a different pattern every time.

Again, this is one you want to run on your own and play around with. It’s really quite beautiful to see in action. If you’re curious what the flow field actually looks like for one of these attractors, it’s something like this:

OK, that’s enough for one article. In part two, we’ll look at some other ways to create fields and other ways to render them. If you want to play around with the code itself, you can either grab the gists I’ve embedded here, or just check out the full tutorial repo itself at

Pay(pal) it Forward?

If you’ve found this post useful or at least entertaining and want to contribute in some way, I will gladly accept your kindness.

It’s not my plan to make any kind of premium, subscriber-only content. And the Patreon model doesn’t really cut it for me. I just want to write tutorials for a while. If I make a few bucks here and there, I will probably want to write tutorials even more.