PHP Interface to GrADS

From OpenGrads Wiki
Jump to: navigation, search

The PHP interface to GrADS is an alternative method of scripting GrADS that can take advantage of the unique capabilities of PHP. Here are a few reasons for scripting GrADS in PHP:

  • You are an experienced PHP programmer new to GrADS and do not want to spend the time learning a new scripting language.
  • You need some GrADS functionality inside your PHP script, say, parse the contents of a GrADS readable dataset or want to store your metadata in a MySQL database.
  • You would like to use PHP to create web based applications as Graphical User Interface for GrADS.
  • Your script is getting too complex and you could use an object oriented approach to better organize and reuse your code.

The PHP interface to GrADS, which is similar to the Perl interface, enables full scripting capability for GrADS in PHP 5 or greater, and can be used together with the classic GrADS scripting language. This interface is an object oriented PHP class called GrADS.

In the remaining of this document I will assume that you have some familiarity with GrADS and PHP.

Getting Started

Requirements

You will need PHP 5 and GrADS Version 1.9.0 or later, or any OpenGRADS release. These can be downloaded at their respective websites. These packages are available for most Linux distributions, MacOS X and Microsoft Windows, as well as in many flavors of Unix.

Note: this interface was exhaustively tested in Linux and Mac but not in Windows. It may or may not work under this OS. Further versions will be pre-tested in Windows environment as well.

Downloading the software and sample datasets

The PHP GrADS is available for download from the OpenGrADS download area at SourceForge.

For running the tutorials and examples below you need to download the sample data file model.nc.

Installation

You don’t need admin privileges to use PHP GrADS. Just untar the distribution:

% tar xvfz phpgrads-xxxx.tar.gz

This will create a phpgrads directory and you can place it anywhere you want. To use it in your PHP script, just place an include in the script. There are two ways to do this:

1) To put an include function in the script, using the full PHP GrADS path:

include ("$PATH/phpgrads/lib/grads.php");

where $PATH is the path where the phpgrads directory was unpacked.

2) To place the PHP GrADS lib directory in the PHP include path, editing the php.ini configuration file and adding the "$PATH/phpgrads/lib" to the include_path parameter. Then, you just have to put an include like this in your script:

include ("grads.php");

Tutorial: Object Oriented Interface (Grads)

For running this tutorial you will need a sample GrADS dataset. Please download model.nc from

  http://opengrads.org/sample_data. 

If you are new to GrADS you may want to read the Tutorial on

  http://grads.iges.org/grads/gadoc/tutorial.html

This document is not a GrADS tutorial but rather a tutorial of the PHP interface to GrADS.

In this tutorial we will use the command line version of PHP instead of the web based one. The main difference is that we can handle the php script like an executable file and write in the first line:

  #!/usr/bin/php 

The first thing to do is to create a Grads object by starting the gradsnc binary in landscape mode, in batch mode:

  $ga = GrADS::start();

There are several methods to deal with the GrADS commands. One of them is the cmd method, which is used to send generic commands to GrADS, e.g.,

  $rc = $ga->cmd("q config");

Different from the Gerl syntax, the return output $rc will depend on the startup options of GrADS::start() and on the input parameter of the method. By default, GrADS::start() and all the methods are in quiet mode and $rc returns no value. In the cmd method it is possible to send a batch of commands at one time, for example:

  $set_map=”
   set mpdset hires
   set map 1 1 10
   set display color white
  ”
  $rc = $ga->cmd($set_map);


Opening files

The Open method opens a GrADS dataset in any of the supported formats:

  $ga->open("model.nc","sdf");


Querying the GrADS state

Similarly, the Query method returns a query handle with information about the particular GrADS property. Here are a few examples:

  $ga->Query("time");
  $ga->Query("file");
  $ga->Query("dims");

If we use the option “output” in the method, its possible to retrieve the output of the command. There are two ways of doing it:

  $rc = $ga->Query("time",$output=”output”);

where $rc is the raw content of the query

or

  $rc = $ga->Query("time",$output=”array”);

where $rc is an array with the content of the query. In this case the subwrd and sublin GrADS commands can be overridden by simple PHP array manipulation, where the array lines are the output lines and the array columns are the words of the output.

For example:

  $rc = $ga->Query("dims");
  echo $rc;

returns nothing in quiet mode.

If we add the $output=”output” option:

  $rc = $ga->Query("dims",$output="output");
  echo $rc;

returns the following:

X is varying   Lon = -52.2 to -39.4   X = -9.44 to -6.88
Y is varying   Lat = -23.8 to -12.6   Y = 17.55 to 20.35
Z is fixed     Lev = 1000  Z = 1
T is fixed     Time = 00Z01JAN1987  T = 1

And if we add the $output=”array” option:

  $rc = $ga->Query("dims",$output="array");
  echo $rc[3][9];

returns the 9th word of the 3th line of the output:

00Z01JAN1987


Other useful methods

Some commonly used GrADS commands have specific methods in PHP interface for GrADS. The Set method, for example is used like this:

  $ga->set("x",$x_coord);

and the Display method is like this:

  $ga->display($var_name);

Combining then its possible to do something like it:

  $xlim=array(42,45); // x limit
  $ylim=array(12,15); // y limit
  $var="ps"; // variable
  $ga->set("gxout","stat");
  $ga->set("x","$xlim[0] $xlim[1]");
  $ga->set("y","$ylim[0] $ylim[1]");
  $stat1=$ga->display($var,"array");
  echo "\n\n  (Min = ".$stat1[7][3]." - Max = ".$stat1[7][4].")";

Another method is the Font, where it's possible to configure font parameters like color, font face and font size, all together. In the line bellow we set the font face to 0 and the size to .25.

  $ga->font($opt=array("Font"=>"0","Size"=>".25"));

In this release only some GrADS commands are directly implemented, but all others can be used through the cmd method.


Example I

A simple example script can be seen here:

  #!/usr/bin/php
  <?php
  include ("lib/grads.php");
  
  $xlim=array(42,45); // a vector containing the x limit
  $ylim=array(12,15); // a vector containing the y limit
  $var="ps"; // string with the name of the variable
  
  // open GrADS in batch and quiet mode
  $ga = GrADS::start($opt=array("Verb"=>"0","Echo"=>"0","Window"=>"0"));
  
  // open file
  $ga->open("model.nc","sdf");
  
  // print in the screen the values of $var
  $ga->set("gxout","shaded");
  for ( $x=$xlim[0]; $x<=$xlim[1]; $x += 1) {
   for ( $y=$ylim[0]; $y<=$ylim[1]; $y += 1) {
    $lon=$ga->set("x",$x,"array");
    $lat=$ga->set("y",$y,"array");
    $val=$ga->display($var,"array");
  // the array is in the [LINE][WORD] format, starting from 0
    echo "\n => ".$var."(lon=".$lon[0][3].",lat=".$lat[0][3].") = ".$val[0][3];
   }
  }
  
  // print in the screen the maximum and minimum of $var
  $ga->set("gxout","stat");
  $ga->set("x","$xlim[0] $xlim[1]");
  $ga->set("y","$ylim[0] $ylim[1]");
  // $stat1 is formatted in an array of $stat[LINE][WORD], starting from 0
  $stat1=$ga->display($var,"array");
  echo "\n\n  (Min = ".$stat1[7][3]." - Max = ".$stat1[7][4].")";
  
  echo "\n";
  
  $ga->quit();
  
  ?>


Terminating your GrADS session

To terminate your GrADS session just enter:

  $ga->quit();

This will cause a quit to be sent to GrADS which in turn will end the connection.


Manual Pages

More information about the Grads PHP class and it's methods can be seen in the Manual Page in http://opengrads.org/doc/php/.