cairodriver(1)

📦
version 8.4.2 · 10 versions
, in fedora 44

💖 cairodriver — Cairo DISPLAY DRIVER 💖

okay bestie, welcome to cairodriver, straight outta the GRASS GIS User's Manual ✨ this one is literally the Cairo display driver for bitmap or vector output, powered by the Cairo graphics library. it's giving art school but make it geospatial 🎨

✨ DESCRIPTION ✨

so here's the tea 🫖 the Cairo driver generates PNG, BMP, PPM, PS, PDF or SVG images by running GRASS display commands, and it does it all with the Cairo graphics library. the image format? it's selected from the extension of the output file — yes queen, the extension does the choosing 💅

and the plot twist: the Cairo driver is used for GRASS display commands by default if available, otherwise the PNG driver gets the job instead. main character energy, truly 👑

🌸 USAGE 🌸

Environment variables

you can enable the Cairo driver by setting the GRASS_RENDER_IMMEDIATE variable, like:

export GRASS_RENDER_IMMEDIATE=cairo

and here's the whole cast of environment variables that affect how the Cairo driver operates 🧚

  • GRASS_RENDER_WIDTH=xxx — the width of the image map (default is 640). yes, tiny. yes, you can change it.
  • GRASS_RENDER_HEIGHT=yyy — the height of the image map (default is 480).
  • GRASS_RENDER_BACKGROUNDCOLOR=RRGGBB — specifies the background color to use in RGB notation (hex or R:G:B values). named colors are also supported, fancy. default is FFFFFF (white) 🤍
  • GRASS_RENDER_TRANSPARENT=[TRUE|FALSE] — sets transparent background on (TRUE) or off (FALSE, default).
  • GRASS_RENDER_ANTIALIAS — can be default, none, gray, or subpixel, corresponding to cairo_antialias_t.
  • GRASS_RENDER_FILE=filename — the name and format of the resulting image file, default is map.png. the image format is determined from the file extension. supported bitmap formats:
    • .png — Portable Network Graphics (PNG)
    • .bmp — Windows Bitmap (BMP, 32-bpp) (these are not readable by some older viewers) 💀
    • .ppm — Portable Pixmap (PPM + PGM for alpha channel)

supported vector formats:

  • .pdf — Portable Document Format (PDF)
  • .ps — PostScript (PS)
  • .svg — Scalable Vector Graphics (SVG)

(Note: some formats may not be available, depending on your platform and the Cairo library that GRASS was built with.)

  • GRASS_RENDER_FILE_READ — if TRUE, the Cairo driver will initialize the image from the contents of GRASS_RENDER_FILE. (Note: this is only supported for bitmap formats)
  • GRASS_RENDER_FILE_MAPPED — if TRUE, the Cairo driver will map GRASS_RENDER_FILE as its framebuffer, rather than using memory. (Note: this only works with BMP files.)
  • GRASS_RENDER_CAIRO_SCREEN — defines Cairo screen
  • GRASS_RENDER_CAIRO_VISUAL — defines Cairo visual

🎀 EXAMPLES 🎀

PNG Example

example: using the driver to generate a PNG file (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.png
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
export GRASS_RENDER_FILE_READ=TRUE
g.region raster=elevation
d.rast map=elevation
d.vect map=streams width=1 color=blue fcolor=aqua type=area,line
d.vect map=roadsmajor width=2

PDF Examples

example: using the driver to generate a PDF vector file with a vector map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.pdf
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
g.region vector=roadsmajor
# activate vector font
d.font Vera
d.vect map=roadsmajor layer=1 display=shape attrcolumn=ROAD_NAME lcolor=0:90:255

example: using the driver to generate a PDF raster file with a raster map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.pdf
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
g.region raster=elevation
d.rast map=elevation

SVG Example

example: using the driver to generate a SVG vector file with a vector map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=vectormap.svg
g.region vector=roadsmajor
d.vect map=roadsmajor -c

🔥 NOTES 🔥

ngl bestie, the driver is still in development 🙈 enable it by specifying --with-cairo when configuring GRASS. this requires a reasonably recent version of the Cairo libraries and a working pkg-config.

antialiasing is enabled by default for bitmap formats. there is currently no way of disabling this 😭 so like, it's permanent. periodt.

the resolution of the output images is defined by current region extents. use g.region -p to get the number of rows and cols, and use the environment variables to set the image size. if you would like a larger image, multiply both rows and cols by the same whole number to preserve the aspect ratio — math but make it cute 🧮✨

Cairo supports true vector format output whenever possible. however, if the selected format doesn't support a necessary feature, Cairo may fall back on rendering a bitmap representation of the image wrapped in the selected vector format. it's giving "fake it till you make it" 💅

👑 SEE ALSO 👑

PNG driver, PS driver, HTML driver, variables

d.rast, d.vect, d.mon, d.erase, d.redraw

💅 AUTHOR 💅

Lars Ahlzen <lars (at) ahlzen.com> and the GRASS Development Team.

⭐ SOURCE CODE ⭐

Available at: Cairo DISPLAY DRIVER source code (history)

Accessed: Saturday Jan 17 05:39:56 2026

Main index | Topics index | Keywords index | Graphical index | Full index

and that's the whole vibe check 🦋 this was GRASS 8.4.2, © 2003-2025 GRASS Development Team, from the GRASS GIS 8.4.2 Reference Manual — go make some gorgeous maps, bestie, you got this 💖✨🎀

📦 where this page comes from