git.sur5r.net Git - bacula/bacula/blob - gui/bacula-web/external_packages/phplot/doc/quickstart.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <!-- $Id$ -->
   3 <html>
   4 <head>
   5         <title>PHPLOT Quick Start and Examples</title>
   6         <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7         <meta name="author" content="Afan Ottenheimer" />
   8     <meta name="author" content="Miguel de Benito" />
   9         <meta name="created" content="20010302;20371700" />
  10         <meta name="changed" content="20040121;19341300" />
  11         <meta name="description" content="phplot quick start and examples" />
  12         <meta name="keywords" content="phplot, graphs, images, php" />
  13         <meta name="robots" content="all" />
  14         <meta name="locale" content="en-us" />
  15     <link type="text/css" rel="stylesheet" href="style.css" />
  16 </head>
  17
  18 <body lang="en-us" bgcolor="#ffffff">
  19
  20 <h1>PHPlot Quick Start and Examples</h1>
  21
  22 <p>Afan Ottenheimer, January 7, 2001</p>
  23 <p>Miguel de Benito, January 21, 2004</p>
  24 <p><b>Contents</b></p>
  25 <ul>
  26   <li><a href="#intro">Introduction</a></li>
  27   <li><a href="#first">First steps</a></li>
  28   <li><a href="#lines">Multiples lines per graph</a></li>
  29   <li><a href="#multiple">Multiple graphs per image</a></li>
  30   <br />
  31 </ul>
  32
  33 <h2><a name="intro"></a>Introduction</h2>
  34
  35 <p>Many web sites need to create real-time or dynamic charts and graphs.
  36 from live data sets. Many users have found PHP a great way for this dynamic
  37 creation of images using the GD library and there have been several
  38 good articles describing this [] [] []. The advantage of using the server
  39 to create an image (server side scripting) is that one does not have to
  40 worry about browser compatibility or client operating system compatibility issues.
  41 The PHP image generating library uses the GD library to create elementary
  42 shapes (elipse, line, rectangle, ...).
  43 PHPlot is a graphics library which provides a means by which you can have your
  44 (PHP enabled) web server create and manipulate graphs as objects and
  45 display the completed graph as an image. Data sets passed to PHPlot use a very
  46 convenient way for database driven sites, in rows with y coordinate data.
  47 </p>
  48
  49 <p>First, lets discuss how PHPlot works in general with some
  50 terminology. A PHPlot <i>image </i>can consist of several <i>graphs </i>,
  51 each graph consisting of several <i>elements</i>.
  52 You define an object (e.g. a variable like <code>$graph</code>),
  53 select the properties of the element that compose the graph and "<i>Draw</i>"
  54 what you want into the object. Tipically by selecting the plot type with
  55 <code>SetPlotType</code> and at the end calling <code>DrawGraph</code>. You
  56 can also directly invoke <code>PrintImage</code>, which either inserts the image
  57 into the data streaming to the client or writes it to disk.
  58 </p>
  59 <p>In PHPlot there are <em>World coordinates</em>, which are the XY coordinates
  60 relative to the axis origin, in the units of the data set; and
  61 <em>device (pixel)</em> coordinates which in GD are relative to the
  62 origin at the upper left side of the image.
  63 </p>
  64 <p>You can think of the "Draw" functions as shaping the
  65 image object and the "Print" function as the method of
  66 finally creating the digital image. PHPlot is smart enough that if
  67 you only have one graph on an image, then the "Print" is
  68 done for you automatically. If you do have multiple graphs per image
  69 then you'll need to use both the "Draw" and "Print"
  70 functions. We'll talk about that a bit later.
  71 </p>
  72 <p>Since PHP is a server scripted language you have several options
  73 for how you can "Print" the image. You can:</p>
  74 <ol>
  75         <li>Write the image as a file on the server. (You specify a file
  76         name and can specify caching as well)</li>
  77         <li>Have the raw data stream out within an HTML file, as &lt;IMG
  78         SRC="my_PHPlot_code.php"&gt;</li>
  79         <li>Precede the raw data with html image headers and call the
  80         script directly (showing up as an image) e.g.
  81         http://somewhere/my_PHPlot_code2.php .</li>
  82 </ol>
  83 <p>This document explains how to create plots using PHPlot from a
  84 PHP script. Information on PHP can be found at <a href="http://www.php.net/">www.php.net</a>.
  85 Information about the GD library which PHP uses to create images can
  86 be found at <a href="http://www.boutell.com/">www.boutell.com</a>.
  87 More information about PHPlot can be found at <a href="www.phplot.com">www.PHPlot.com</a>.</p>
  88
  89 <h2>Creating the Object</h2>
  90
  91 <p>You create a PHPlot object by first including the code to be used
  92 and then defining the variable:</p>
  93 <div class="box">
  94 <pre>&lt;?php
  95 include('./phplot.php');  // here we include the PHPlot code
  96 $graph =& new PHPlot();   // here we define the variable graph
  97
  98 //Rest of code goes below
  99 ?&gt;</pre>
 100 </div>
 101
 102 <p>The above code assigns the PHPlot object to the variable <code>$graph</code>. Please,
 103 use that '&' to create a reference, it is needed by phplot's approximation of a destructor,
 104 a facility unavailable in PHP4.</p>
 105
 106 <p> <a href="#top">Back to top</a> </p>
 107
 108
 109 <h2>Real World Examples</h2>
 110 <h3><a name="first"></a>Case 1: A simple graph</h3>
 111
 112 <p>We will start with a simple line graph. </p>
 113 <div class="box">
 114 <pre>&lt;?php
 115 //Include the code
 116 include('./PHPlot.php');
 117
 118 //Define the object
 119 $graph =& new PHPlot();
 120
 121 //Define some data
 122 $example_data = array(
 123      array('a',3),
 124      array('b',5),
 125      array('c',7),
 126      array('d',8),
 127      array('e',2),
 128      array('f',6),
 129      array('g',7)
 130 );
 131 $graph-&gt;SetDataValues($example_data);
 132
 133 //Draw it
 134 $graph-&gt;DrawGraph(); // remember, since in this example we have one graph, PHPlot
 135                         // does the <i>PrintImage </i>part for you
 136 ?&gt;</pre>
 137 </div>
 138
 139 <p> And that's it! What we get is the following graph: </p>
 140
 141 <div align=center>
 142   <img src="imgs/qstart_fig1.png" name="fig1" alt="figure 1" align="bottom" border="0" />
 143   <br />Figure 1
 144 </div>
 145
 146 <p>That's a great start, but now we'd like to specify the width and height
 147 of the image.</p>
 148
 149
 150 <h3>Case 1a: Different Size Images and Titles</h3>
 151 <p>
 152 Lets say we want it to have a width of 300 and a height of 250 pixels.
 153 So instead of having the line <br /><br />
 154     <code>$graph =& new PHPlot();</code> <br /><br />
 155 we replace it with <br /><br />
 156     <code>$graph =& new PHPlot(300,250);</code><br /><br />
 157 and you have specified the size in pixels of the image to be created.
 158 A couple of things to note:
 159 </p>
 160 <ul>
 161   <li>The default is <em>not</em> to use TTF fonts. </li>
 162   <li>Since there was only one graph on the image we didn't have to
 163         specify PrintImage, DrawGraph took care of it for us.
 164   </li>
 165   <li>
 166         We did not specify the data type. If you do not specify the data
 167         type PHPlot assumes <code>text-data</code>.
 168   </li>
 169   <li>
 170         We did not specify the file type (gif, png, jpg, ...) .
 171         PHPlot 5.0 assumes PNG image formats.
 172   </li>
 173   <li>
 174         The data is passed in as an array of arrays. This may seem awkward
 175         now, but as we add functionality this will be beneficial.
 176   </li>
 177 </ul>
 178 <p>Ok, now we're ready to add some customization to the plot. Let's change
 179 the size, the title and the x/y axis labels. All we need to do is modify
 180 the variable <code>$graph</code> before printing the image. We achieve this with:
 181 </p>
 182 <div class="box">
 183 <pre>&lt;?php
 184 include ('./phplot.php');
 185
 186 //create an graph object 300x250 pixels
 187 $graph =& new PHPlot(300,250);
 188 //Set titles
 189 $graph-&gt;SetTitle("Title\n\rSubtitle");
 190 $graph-&gt;SetXTitle('X data');
 191 $graph-&gt;SetYTitle('Y data');
 192
 193 //...rest of the code
 194
 195
 196 ?&gt;</pre>
 197 </div>
 198 <div align=center>
 199  <img src="imgs/qstart_fig2.png" name="graphic1" align="bottom" border="0"><br />
 200  Figure 2
 201 </div>
 202
 203 <p>Note that in order for the "\n" and "\r " to be interpreted as
 204 new line/new return characters for <code>SetTitle </code>you have to
 205 enclose the string in <b>double </b>quotes.</p>
 206
 207 <h3><a name="lines"></a>Case 2: Multiple Lines per Graph </h3>
 208 <p>Lets say we want to plot not just one
 209 dataset but several y values for each x position. With PHPlot it is
 210 easy to specify the multiple data lines by just passing in all the Y
 211 values for a given X value at once. So instead of array('label', y)
 212 we specify array('label', y<sub>1</sub>, y<sub>2</sub>, y<sub>3</sub>,
 213 ...) This is very convenient when working with rows of data from databases.
 214 <br />
 215 Now our data will have three Y values for each position on the X axis
 216 </p>
 217 <div class="box">
 218 <pre>&lt;?php
 219 //Include the code
 220 include('./phplot.php');
 221
 222 //Define the object
 223 $graph =& new PHPlot(300,250);
 224
 225 //Set titles
 226 $graph-&gt;SetTitle("Title\n\rSubtitle");
 227 $graph-&gt;SetXTitle('X data');
 228 $graph-&gt;SetYTitle('Y data');
 229
 230
 231 //Define some data
 232 $example_data = array(
 233      array('a',3,4,2),
 234      array('b',5,'',1),  // here we have a missing data point, that's ok
 235      array('c',7,2,6),
 236      array('d',8,1,4),
 237      array('e',2,4,6),
 238      array('f',6,4,5),
 239      array('g',7,2,3)
 240 );
 241 $graph-&gt;SetDataValues($example_data);
 242
 243 //Draw it
 244 $graph-&gt;DrawGraph();
 245 ?&gt;</pre>
 246 </div>
 247 <p>Which gives us: </p>
 248 <div align="center">
 249   <img src="imgs/qstart_fig3.png" name="graphic2" align=bottom border="0" />
 250   <br />Figure 3
 251 </div>
 252
 253 <p>Notice that each set of Y data gets a different color.
 254 Also the missing data point is skipped, this behaviour can be adjusted with
 255 <code>SetDrawBrokenLines(TRUE);</code>
 256 </p>
 257 <p>
 258 This gives you the basics of how to create a graph in PHPlot.
 259 A nice start, but now we'd like to add some customization, namely different
 260 fonts, margins and types of graphs.
 261 </p>
 262 <p><a href="#top">Back to top</a> </p>
 263
 264
 265 <h3>Customization</h3>
 266 <p>Valid types of plots (as of PHPlot 5.0):
 267 <ul>
 268         <li><code>bars</code> (with optional shadows)</li>
 269         <li><code>lines</code></li>
 270         <li><code>linepoints</code> (a faster way of plotting when
 271         you want both points and lines)</li>
 272         <li><code>area</code></li>
 273         <li><code>points</code> (lots of point types here)</li>
 274         <li><code>pie</code> (2D or 3D)</li>
 275         <li><code>thinbarline</code> (sometimes also called impulse) </li>
 276         <li><code>error bar</code> (which can also be used for stock market data graphs)</li>
 277     <li><code>squared</code> (for binary data) </li>
 278 </ul>
 279 </p>
 280 <p>You specify which type with the <code>SetPlotType</code> function.
 281 We'll look at that function with bars and lines in the next example when we look at
 282 multiple graphs per image.
 283 </p>
 284 <p>As we discussed before, there are several ways we can manipulate
 285 the look/feel of the graph object. Almost every parameter of ticks, grids and data labels
 286 can be adjusted via (among many others):
 287 <ul>
 288   <li><code>SetXTickPos()</code></li>
 289   <li><code>SetYTickPos()</code></li>
 290   <li><code>SetXTickLength()</code></li>
 291   <li><code>SetYTickLength()</code></li>
 292   <li><code>SetXTickCrossing()</code></li>
 293   <li><code>SetYTickCrossing()</code></li>
 294   <li><code>SetXTickIncrement()</code></li>
 295   <li><code>SetYTickIncrement()</code></li>
 296   <li><code>SetNumXTicks()</code></li>
 297   <li><code>SetNumYticks()</code></li>
 298   <li><code>SetSkipTopTick()</code></li>
 299   <li><code>SetSkipBottomTick()</code></li>
 300
 301   <li><code>SetDrawXGrid()</code></li>
 302   <li><code>SetDrawYGrid()</code></li>
 303   <li><code>SetDrawDashedGrid()</code></li>
 304   <li><code>SetDrawXDataLabelLines()</code></li>
 305   <li><code>SetDrawYDataLabelLines()</code> (not yet implemented)</li>
 306   <li><code>SetXDataLabelPos()</code></li>
 307   <li><code>SetYDataLabelPos()</code></li>
 308   <li><code>SetXLabelAngle()</code></li>
 309   <li><code>SetYLabelAngle()</code></li>
 310   <li><code>SetXLabelType()</code></li>
 311   <li><code>SetYLabelType()</code></li>
 312 </ul>
 313 As we go further we will introduce some of these features of PHPlot.
 314 For more specialized examples, please go <a href="index.php">back to the index</a> and
 315 look in the examples section.
 316 </p>
 317
 318 <p> <a href="#top">Back to top</a> </p>
 319
 320 <h3><a name="multiple"></a> <b>Case 3: Multiple Graphs per Image </b></h3>
 321
 322 <p>To create an image with several separate graphs
 323 on it is a straightforward process. As in the previous examples we
 324 first have to create an object (e.g. variable) but now we tell it to
 325 <i>not</i> print the image at the same time as the draw command. Now
 326 we want it to wait for the explicit <code>PrintImage</code> function call.
 327 To tell PHPlot this is the way we want to work, we use the
 328 <code>SetPrintImage</code> function.
 329 <code>SetPrintImage(TRUE)</code> is the default, and tells to draw the image
 330 when <code>DrawGraph</code> is called. To turn this
 331 off we use <code>SetPrintImage(FALSE)</code>.</p>
 332 <p>Now we will draw several images entirely within one object. That
 333 means that if we set a value for one graph, there will be a couple of
 334 other commands we will need.
 335 </p>
 336 <p>To specify in pixels the placement of each graph we use
 337 <code>SetNewPlotAreaPixels</code>. The format is
 338 <code>SetNewPlotAreaPixels(upper_left_x, upper_left_y, lower_right_x,
 339 lower_right_y)</code> . Again we are using the GD coordinates where 0,0
 340 is the upper left corner of the image.
 341 </p>
 342 <p>In more detail:</p>
 343 <div class="box">
 344 <pre>&lt;?php
 345 include('./PHPlot.php');  // here we include the PHPlot code
 346 $graph =& new PHPlot(400,250);   // here we define the variable $graph
 347 $graph-&gt;SetPrintImage(0); //Don't draw the image yet
 348
 349 //....Data and Values for first graph here .....
 350
 351 $graph-&gt;SetNewPlotAreaPixels(70,10,375,100);  // where to place it
 352
 353 $graph-&gt;DrawGraph();   //Draw the first graph to the image.
 354
 355 //....Data and Values for second graph here .....
 356
 357 $graph-&gt;SetNewPlotAreaPixels(70,120,375,220); //where to place graph 2
 358 $graph-&gt;DrawGraph();  //Draw the second graph to the image
 359
 360 //Print the image with both graphs
 361 $graph-&gt;PrintImage();
 362 ?&gt;</pre>
 363 </div>
 364
 365 <p>Lets now create an image with 2 graphs on it with some example data.  </p>
 366
 367 <div class="box">
 368 <pre>&lt;?php
 369 //Include the code
 370 include('./phplot.php');
 371
 372 //Define the object
 373 $graph =& new PHPlot(400,250);
 374
 375 $graph-&gt;SetPrintImage(0); //Don't draw the image until specified explicitly
 376
 377 $example_data = array(
 378      array('a',3),
 379      array('b',5),
 380      array('c',7),
 381      array('d',8),
 382      array('e',2),
 383      array('f',6),
 384      array('g',7)
 385 );
 386
 387 $graph-&gt;SetDataType("text-data");  //Must be called before SetDataValues
 388
 389 $graph-&gt;SetDataValues($example_data);
 390 $graph-&gt;SetYTickIncrement(2);  //a smaller graph now - so we set a new tick increment
 391
 392 $graph-&gt;SetXLabelAngle(90);
 393 $graph-&gt;SetXTitle("");
 394 $graph-&gt;SetYTitle("Price");
 395 $graph-&gt;SetPlotType("lines");
 396 $graph-&gt;SetLineWidth(1);
 397
 398 $graph-&gt;SetNewPlotAreaPixels(70,10,375,100);  // where do we want the graph to go
 399 $graph-&gt;DrawGraph(); // remember, since we said not to draw yet, PHPlot
 400                      // still needs a <i>PrintImage </i>command to write an image.
 401
 402
 403 //Now do the second chart on the same image
 404 unset($example_data);  //we are re-using $example_data (to save memory), but you don't have to
 405 $example_data = array(
 406      array('a',30,40,20),
 407      array('b',50,'',10),  // here we have a missing data point, that's ok
 408      array('c',70,20,60),
 409      array('d',80,10,40),
 410      array('e',20,40,60),
 411      array('f',60,40,50),
 412      array('g',70,20,30)
 413 );
 414
 415 $graph-&gt;SetDataType("text-data");  //Must be called before SetDataValues
 416
 417 $graph-&gt;SetDataValues($example_data);
 418
 419 $graph-&gt;SetXTitle("");
 420 $graph-&gt;SetYTitle("Verbal Cues");
 421 $graph-&gt;SetYTickIncrement(10);
 422 $graph-&gt;SetPlotType("bars");
 423 $graph-&gt;SetXLabelAngle(0);  //have to re-set as defined above
 424
 425 $graph-&gt;SetNewPlotAreaPixels(70,120,375,220);
 426 $graph-&gt;SetPlotAreaWorld(0,0,7,80);
 427 $graph-&gt;DrawGraph();
 428
 429 //Print the image
 430 $graph-&gt;PrintImage();
 431 ?&gt;</pre>
 432 </div>
 433
 434 <p> <br /> <br /> Which gives us: </p>
 435
 436 <div align="center">
 437   <img src="imgs/qstart_fig4.png" name="graphic3" align="top" border="0" /> <br />
 438   Figure 4 <br />
 439 </div>
 440
 441 <p>
 442 You must remember that world Coordinates are the XY coordinates relative to the
 443 axis origin that can be drawn. Not the device (pixel) coordinates
 444 which in GD are relative to the origin at the upper left
 445 side of the image.
 446 </p>
 447
 448 <div style="background:#6699cc; color:#ffffff;">
 449   <a href="#top">Back to top</a> <br />
 450   <a href="index.php">Back to the index</a> <br />
 451 </div>
 452 <div class="foot">$Id$</div>
 453
 454 </body>
 455 </html>