RONCC
/
Geografic-Information-System


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
							<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
 <title>Cairo driver</title>
 <meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
 <link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgColor=white>

<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>

<h2>NAME</h2>
<em><b>Cairo driver</b></em> - display driver for bitmap or vector
output using the Cairo graphics library.

<h2>DESCRIPTION</h2>

The Cairo driver generates PNG, BMP, PPM, PS, PDF or SVG images by
GRASS display commands, using the
<a href="http://www.cairographics.org/">Cairo graphics library</a>.
The image format is selected from the extension of the output file.

The Cairo driver is used for GRASS display commands by default if
available, otherwise <em><a href="pngdriver.html">PNG driver</a></em>
is used.

<h2>USAGE</h2>

<h3>Environment variables</h3>

The Cairo driver can be enabled by
setting <b>GRASS_RENDER_IMMEDIATE</b> variable, eg.

<div class="code"><pre>
export GRASS_RENDER_IMMEDIATE=cairo
</pre></div>

Several environment variables affect the operation of the Cairo driver:

<ul>
  <li><b>GRASS_WIDTH=xxx</b><br>
    the width of the image map (default is 640).
  </li>
  <li><b>GRASS_HEIGHT=yyy</b><br>
    the height of the image map (default is 480).
  </li>
  <li><b>GRASS_BACKGROUNDCOLOR=RRGGBB</b><br>
    specifies the background color to use in RGB notation (hex or
    R:G:B values). Named colors are also supported. Default
    is <b>FFFFFF</b> (white).
  </li>
  <li><b>GRASS_TRANSPARENT=[TRUE|FALSE]</b><br>
    sets transparent background on (TRUE) or off (FALSE, default).
  </li>
  <li><b>GRASS_ANTIALIAS</b><br> can be <em>default</em>,
    <em>none</em>, <em>gray</em>, or <em>subpixel</em>, corresponding to
    <a href="http://www.cairographics.org/manual/cairo-cairo-t.html#cairo-antialias-t">cairo_antialias_t</a>
  </li>
  <li><b>GRASS_PNGFILE=filename</b><br>
     the name and format of the resulting image file, default is
     <tt>map.png</tt>.<br>
     The image format is determined from the file extension.<br>
     Supported bitmap formats:
     <ul>
       <li><b>.png</b> - Portable Network Graphics (PNG)</li>
       <li><b>.bmp</b> - Windows Bitmap (BMP, 32-bpp)
           (these are not readable by some older viewers)</li>
       <li><b>.ppm</b> - Portable Pixmap (PPM + PGM for alpha channel)</li>
     </ul>
     Supported vector formats:
     <ul>
       <li><b>.pdf</b> - Portable Document Format (PDF)</li>
       <li><b>.ps</b> - PostScript (PS)</li>
       <li><b>.svg</b> - Scalable Vector Graphics (SVG)</li>
     </ul>
     (Note: Some formats may not be available, depending on your platform and
     the Cairo library that GRASS was built with.)
  </li> 
  <li><b>GRASS_PNG_READ</b><br>
     if <tt>TRUE</tt>, the Cairo driver will initialize the image from
    the contents of GRASS_PNGFILE.<br>
    (<em>Note: This is only supported for bitmap formats</em>)
  </li>
  <li><b>GRASS_PNG_MAPPED</b><br>
    if <tt>TRUE</tt>, the Cairo driver will map GRASS_PNGFILE as its framebuffer,
    rather than using memory.<br>
    (<em>Note: This only works with BMP files.</em>)
  </li>
  <li><b>GRASS_CAIRO_SCREEN</b><br>
    defines Cairo screen
  </li>
  <li><b>GRASS_CAIRO_VISUAL</b><br>
    defines Cairo visual
  </li>
</ul>

<h3>Examples</h3>

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

<div class="code"><pre>
export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_PNGFILE=nc_spm.png
export GRASS_WIDTH=800
export GRASS_HEIGHT=800
export GRASS_PNG_READ=TRUE

g.region rast=elevation
d.rast map=elevation
d.vect map=streams width=1 color=blue fcolor=aqua type=area,line
d.vect map=roadsmajor width=2
</pre></div>

<!-- TODO: why does it generate rasterized output?

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

<div class="code"><pre>
export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_PNGFILE=nc_spm.pdf
export GRASS_WIDTH=800
export GRASS_HEIGHT=800

g.region vect=roadsmajor
# activate vector font
d.font Vera
d.vect map=roadsmajor layer=1 display=shape,attr attrcolumn=ROAD_NAME lcolor=0:90:255
</pre></div>
-->

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

<div class="code"><pre>
export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_PNGFILE=nc_spm.pdf
export GRASS_WIDTH=800
export GRASS_HEIGHT=800

g.region rast=elevation
d.rast map=elevation
</pre></div>


<h2>NOTES</h2> 

The driver is still in development. Enable it by specifying
<code>--with-cairo</code> when configuring GRASS. This
requires a reasonably recent version of the Cairo libraries
and a working <tt>pkg-config</tt>.

<p>Antialiasing is enabled by default for bitmap formats. There is
currently no way of disabling this.

<p>The resolution of the output images is defined by current region
extents. Use <tt>g.region -p</tt> 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.

<p>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.

<h2>SEE ALSO</h2>
<em>
<a href="pngdriver.html">PNG driver</a>,
<a href="psdriver.html">PS driver</a>,
<a href="htmldriver.html">HTML driver</a>,
<a href="variables.html">variables</a>
</em>
<p>
<em>
<a href="d.rast.html">d.rast</a>,
<a href="d.vect.html">d.vect</a>,
<a href="d.mon.html">d.mon</a>,
<a href="d.erase.html">d.erase</a>,
<a href="d.redraw.html">d.redraw</a>
</em>

<h2>AUTHOR</h2>
Lars Ahlzen &lt;<i>lars (at) ahlzen.com</i>&gt;<br>
and the GRASS Development Team.