We have developed SOAP based Webservice interfaces(please follow this link to learn about SOAP) to many non-interactive functions of GRASS (Geographic Resources Analysis Support System) software. This page contains detailed description of the Webservice interfaces and information on how to use them. Interfaces to about  200 GRASS 6.0 functions are developed. .

What should you know to use these interfaces
 
To be able to use these interfaces directly you should know the basics of how to run GRASS software. GRASS users should be able to use these interfaces without much difficulty. We are in the process of developing a few higher level "processes" like unsupervised classification, supervised classification using training map, resampling etc, using these  interfaces. To use these processes you do not need to have the knowledge of GRASS (though many people would like to know how their data is modified as it passes from one GRASS function to another). We are also developing some other(non-GRASS) webservices to support these processes. You can build your own processes using all of these services if you know  how to chain web services(see [1],[2]). The processes can be integrated into your own GIS applications. We have also developed a BPEL/WSDL engine. The engine provides an interface, which allows you to run the webservices/processes directly from your web browser.


GRASS Interfaces 


 The interfaces are divided into seven webservices depending on their functionality. This division follows roughly the same division as the way GRASS commands are divided(see here ):

         Webservice                                   WSDL (Web Service Description Language) file                       Java Interface

1)  General Commands                                            WSDL                                                                     Interface
      Intefaces for non-interactive commands which start with "g.". (Note:  Here non-interactive commands are commands which  can be executed non-interactively in a command line inside GRASS. Many non-interactive commands can also be run interactively inside GRASS, as the users of GRASS know.)
2)  Imagery Commands                                           WSDL                                                                      Interface
      Intefaces for non-interactive commands which start with "i.".
3)  Raster Commands                                              WSDL                                                                      Interface
      Interfaces for non-interactive commands which start with "r.". This webservice does not include interfaces for commands which start with "r.in" and "r.out". They are
     clubbed into another webservice. See below
4) Raster 3D Commands                                        WSDL                                                                       Interface
     Intefaces for non-interactive commands which start with "r3.".
5) Vector  Commands                                              WSDL                                                                      Interface
     Interfaces for non-interactive commands which start with "v.". This webservice does not include interfaces for commands which start with "v.in" and "v.out". They are clubbed
     into another webservice. See below.
6)  Raster in-out Commands                                   WSDL                                                                       Interface
      Interfaces for non-interactive commands which start with "r.in" and "r.out".
7)  Vector in-out Commands                                    WSDL                                                                      Interface
      Interfaces for non-interactive commands which start with "v.in" and "v.out".

     These interfaces are developed in Java. Each interface is independent of other interfaces. The GRASS commands are invoked from Java programs, which are implementation of these interfaces.  Most of these java programs are generated using another Java program. The input to this program is a file containing GRASS commands which are put in a way that the program can understand. This program can be used to generate new interfaces when the version of GRASS changes. Please be warned that many of the interfaces,especially vector functions, are not fully tested, although we don't expect any major problem. If you discover any problem please mail to this address:udadi@gmu.edu.

The general structure of the interfaces is described next.


Structure of the Interfaces

The structure of the interfaces match closely with the structure of the corresponding GRASS command. The structure of the interfaces will be explained with some examples. It is easy and straight forward. Consider a GRASS 6.0 Command- i.maxlik .i.maxlik has the following structure-

i.maxlik [-q] group= name subgroup=name sigfile=name class= name [reject=name]

The corresponding java interface has the following structure:
 

public String i_maxlik(String gbasePointer,String locationName,String mapsetName,boolean flag_q,String group,String subgroup,
String sigfile,String className,String option_reject) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

Here the arguments of the function i_maxlik are
  gbasePointer-   A string used to identify the GRASS gbase.
  locationName-  Name of a location in the gbase.
  mapset -            Name of a mapset in the location.
 Almost all the interfaces have the above three arguments as their first three arguments.
  flag_q-              Boolean argument corresponding to the flag q. "true" implies the flag is present. For flags, "flag_" is prefixed.
  group-               This corresponds to "group" in the command
  subgroup-          This corresponds to "subgroup" in the command
  sigfile-                This corresponds to "sigfile" in the command
  className-        This corresponds to "class" in the commands. The name was changed  to "className" instead of "class" since "class" is a java keyword. Almost all of the arguments have the same name as the corresponding parameter in the command. Only exceptions are cases like this.
option_reject-       For the optional parameters, "option_" is prefixed.

The output of this function is a unique String for identifying the modified gbase on the server on which this function is executed. Any error messages are captured in edu.gmu.laits.ws.WebServiceExceptionsType.

A GRASS command which takes a an external(or an OS) file as an input is r.in.gdal . r.in.gdal has the following structure:

r.in.gdal [-oefk] input =string output=string [band=integer ] [target=string] [title=string] [location =string]

The corresponding java interface has the following structure:

public String r_in_gdal(String gbasePointer,String locationName,String mapsetName,boolean flag_o,boolean flag_e,boolean flag_f,
boolean flag_k,org.apache.axis.types.URI inputUrl,String output,String option_band,String option_target,String option_title,
String option_location) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

The stucture follows the same conventions as described above. The only exception is "input" parameter. The input is a URL rather than a string. Whenever the commands expects an input  file, the corresponding argument will be a URL.

Another GRASS command whose output is a an external file is r.out.gdal . r.out.gdal has the following structure:

 r.out.gdal [-l] [input=string] [format =string] [type=string] [output=string ] [createopt=string] [metaopt=string]

The corresponding java interface has the following structure:

public org.apache.axis.types.URI r_out_gdal(String gbasePointer,String locationName,String mapsetName,boolean flag_l,String option_input,
String option_format,String option_type,String option_createopt,String option_metaopt) throws java.rmi.RemoteException,
edu.gmu.laits.ws.WebServiceExceptionsType;

Again, the structure follows the same conventions. The exception is "output" parameter. There is no argument corresponding to the output parameter. The output of this function itself corresponds to the "output" parameter, i.e. this time the output is a file/directory containing the output obtained by executing the command, instead of gbase.  Similarly,  interfaces corresponding to commands like g.list , whose output is text, have a text file as their output.

In some of the commands gbase is modified as well as a reportfile is produced. One example is i.cluster :
     
i.cluster [-q] group=string subgroup =string sigfile=string classes=integer [seed=string] [sample=integer] [iterations =integer] [convergence=float] [separation =float] [min_size=integer] [reportfile= string]

The corresponding java interface has the following structure:

public String i_cluster(String gbasePointer,String locationName,String mapsetName,boolean flag_q,String group,String subgroup,String sigfile,
String classes,String option_seed,String option_sample,String option_iterations,String option_convergence,String option_separation,
String option_min_size) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

 "reportfile" is stored in the same directory as gbase.

Some additional interfaces, not present in grass, are added to general commands. These are:

public String save_UrlGbase(org.apache.axis.types.URI urlGbase) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

public org.apache.axis.types.URI returnGbase(String gbasePointer) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

public String create_location(String locationName,String proj,String zone,String north,String south,String east,String west,String cols,
String rows,String ew_resol,String ns_resol) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

public String remove_location(String gbasePointer,String locationName) throws java.rmi.RemoteException,
edu.gmu.laits.ws.WebServiceExceptionsType;

public String create_dummy_location(String locationName) throws java.rmi.RemoteException,edu.gmu.laits.ws.WebServiceExceptionsType;

save_UrlGbase can be used to upload a gbase to the server. It returns an idetifier of the gbase on the server. "returnGbase" returns the gbase as a zip file.
"create_dummy_location" creates a dummy location which can be used with r.in.gdal with "location" parameter. locationName is the name of the dummy location. "remove_location" removes a location from the gbase. "create_location" creates a new location in the specifed gbase using the parameters.



NOTE: Right now GRASS 5.7 is being run on the server instead of GRASS 6.0. We are having some problems with 6.0. But the interfaces are still for GRASS 6.0. So the the parameters and flags which are present in 6.0 commands but not in 5.7 should not be used. We will replace GRASS 5.7 with 6.0 as soon as it is declared stable.

References

[1] Nadine A, 2003, Chaining Geographic Information Web Services: IEEE Internet Computing,Vol. 7, No. 5, pp22-29.
[2] BPEL, Business Process Execution Language for Web Services. http://www-128.ibm.com/developerworks/library/ws-bpel/