RONCC
/
Geografic-Information-System


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
							<!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> - driver for bitmap or vector output using
the Cairo graphics library.
<BR>
<EM>(drivers)</EM> 

<H2>DESCRIPTION</H2>

The Cairo driver generates PNG, BMP, PPM, PS, PDF or SVG images from 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.

<P>
It is started as 'pseudo' monitor (output to an image file) and when
stopped, all output from previously used display commands are written to
the output file.

<H2>USAGE</H2>

<H3>Environment variables</H3>

Several environment variables affect the operation of the Cairo driver:

<UL>
  <LI><B>GRASS_RENDER_IMMEDIATE=[FALSE|TRUE|PNG|PS|HTML|cairo]</B><BR>
     tells the raster library which driver to use. If
     <tt>TRUE</tt>, the cairo driver is used if it is enabled, otherwise the PNG driver is used.
  <LI><B>GRASS_WIDTH=xxx</B><BR>
     the width of the image.
  </LI>
  <LI><B>GRASS_HEIGHT=yyy</B><BR>
    the height of the image.
  </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_BACKGROUNDCOLOR=RRGGBB</B><BR>
     specifies the background color to use in RGB
    notation (hex values). 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_PNG_READ</B><BR>
     if <tt>TRUE</tt>, the Cairo driver will initialize the image from
    the contents of GRASS_PNGFILE.<BR>
    (Note: This is only supported for bitmap formats)
  </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. This only works with BMP files.
  </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_LINE_WIDTH</B><BR>
    the default line width.
  </LI>
  <LI><B>GRASS_TEXT_SIZE</B><BR>
    the default text size.
  </LI>
  <LI><B>GRASS_FRAME</B><BR>
    contains 4 coordinates, <em>top,bottom,left,right</em>, defining the initial frame.
  </LI>
</UL>

<H3>Examples</H3>

Example using the driver to generate a PNG file (bash-syntax):
<div class="code"><PRE>
export GRASS_PNGFILE=spearfish.png
export GRASS_WIDTH=800
export GRASS_HEIGHT=800
export GRASS_RENDER_IMMEDIATE=CAIRO

d.rast map=elevation.10m
d.vect map=streams width=1 color=blue fcolor=aqua type=area,line
d.vect map=roads width=2
</PRE></div>

Example using the driver to generate a PDF file (bash-syntax):
<div class="code"><PRE>
export GRASS_PNGFILE=spearfish.pdf
export GRASS_WIDTH=800
export GRASS_HEIGHT=800
export GRASS_RENDER_IMMEDIATE=CAIRO

d.rast map=elevation.10m
d.vect map=streams width=1 color=blue fcolor=aqua type=area,line
d.vect map=roads width=2
</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 pkg-config.

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

<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="displaydrivers.html">Display drivers</a>
<br>
<A HREF="pngdriver.html">PNG driver</A>,
<A HREF="psdriver.html">PostScript driver</A>,
<BR>
<A href="d.rast.html">d.rast</A>,
<A href="d.vect.html">d.vect</A>
</EM>

<H2>AUTHOR</H2>
Lars Ahlzen &lt;<I>lars (at) ahlzen.com</I>&gt;<BR>
and the GRASS Development Team.