GRASS
Class libgis

java.lang.Object
  |
  +--GRASS.libgis
public class libgis
extends java.lang.Object

This class wraps functions of GIS library of GRASS. Programs must use this class first to access the GRASS database. It provides loading of the shared object that contains original GRASS routines and initiats connection to specified GRASS database. This class wraps original GRASS functions in the most simple and straightforward manner and does not provide any object-oriented abstraction in terms of GIS.
Side Effect: This class executes System.runFinalizersOnExit(true) on initialization. You can switch back after calling constructor of this class but it is not safe.

See Also:
libfun

Constructor Summary
libgis(java.lang.String appname)
          Initializes GIS library for applications that run under GRASS.
libgis(java.lang.String appname, java.lang.String gisbase, java.lang.String gisdbase, java.lang.String location, java.lang.String mapset)
          Initializes GIS library for stand-alone applications (i.e. ones not running from beyond GRASS).
 
Method Summary
 void close()
          Deletes rc file if one was created.
 double G_area_of_cell_at_row(int row)
          This routine returns the area in square meters of a cell in the specified row.
 int G_begin_cell_area_calculations()
          This routine must be called once before any call to G_area_of_cell_at_row.
 java.lang.String G_database_projection_name()
          Returns a string which is a printable name for projection in active region.
 java.lang.String G_database_unit_name(boolean plural)
          Returns a string describing the database grid units.
 double G_database_units_to_meters_factor()
          Returns a factor which converts the grid unit to meters (by multiplication).
 java.lang.String G_find_cell(java.lang.String name, java.lang.String mapset)
          Looks for raster file name in the database.
 java.lang.String G_find_sites(java.lang.String name, java.lang.String mapset)
          Looks for stes list name in the database.
 java.lang.String G_find_vector(java.lang.String name, java.lang.String mapset)
          Looks for vector file name in the database.
 FILE G_fopen_sites_new(java.lang.String name)
          Creates an empty site list file name in the current mapset and opens it for writing.
 FILE G_fopen_sites_old(java.lang.String name, java.lang.String mapset)
          Opens the site list file name in mapset for reading.
 Cellhead G_get_default_window()
          Reads the default region for the location.
 Cellhead G_get_set_window()
          Gets the values of currently active region into a new Cellhead object.
 Cellhead G_get_window()
          Reads the database region as stored in the WIND file in the user's current mapset.
 java.lang.String G_gisbase()
          Returns the full path name of the top level directory for GRASS programs.
 java.lang.String G_gisdbase()
          Returns the full UNIX path name of the directory which holds the database locations.
 java.lang.String G_location_path()
          Returns the full UNIX path name of the current database location.
 java.lang.String G_location()
          Returns the name of the current database location.
 java.lang.String G_mapset()
          Returns the name of the current mapset in current location.
 java.lang.String G_myname()
          Returns a one line title for the database location.
 FD G_open_cell_new_random(java.lang.String name)
          Opens a new raster file for random writes by G_put_mpa_row.
 FD G_open_cell_new(java.lang.String name)
          Opens a new raster file.
 FD G_open_cell_old(java.lang.String name, java.lang.String mapset)
          Opens existing raster file.
 int G_projection()
          This routine returns a code indicating the projection for the active region.
 void G_put_window(Cellhead ch)
          Writes the database region file (WIND) in the user's current mapset from cellhead.
 Categories G_read_cats(java.lang.String name, java.lang.String mapset)
          The category file for raster file name in mapset is read into the this object.
 Categories G_read_vector_cats(java.lang.String name, java.lang.String mapset)
          The category file for vector file name in mapset is read into the new Categories object.
 void G_set_window(Cellhead ch)
          Sets the active region using parameters in Cellhead.
 void G_sleep_on_error(boolean flag)
          Sets/unsets pause on errors.
 void G_suppress_warnings(boolean flag)
          Sets/unsets reporting warnings.
 int G_window_cols()
          Returns the number of columns in the active program region.
 int G_window_rows()
          Returns the number of rows in the active program region.
 int G_zone()
          This routine returns the zone for the active region.
 java.lang.String getGISRC()
          Returns the name of GISRC file created by this class.
 int getpid()
          Returns the process ID of the process.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

libgis

public libgis(java.lang.String appname,
              java.lang.String gisbase,
              java.lang.String gisdbase,
              java.lang.String location,
              java.lang.String mapset)
       throws GRASSException
Initializes GIS library for stand-alone applications (i.e. ones not running from beyond GRASS). Writes rc file with application name in user's home directory, sets environmental variables, calls GIS library initialization routine.
Parameters:
appname - Application name, one that can be obtained in C from argv[0]
gisbase - Location of GRASS executable files. Same as value of GISBASE environmental variable while running GRASS.
gisdbase - Full path to GRASS database. Same as value of GISDBASE environmental variable while running GRASS.
location - Location name in GRASS database. Same as value of LOCATION_NAME environmental variable while running GRASS.
mapset - Mapset name in GRASS database under specified location. Same as value of MAPSET environmental variable while running GRASS.
Throws:
GRASSException - Exception with an appropriate message is thrown in cases when constructor fails to create/write rc file, set environmental variables or intialize GRASS library

libgis

public libgis(java.lang.String appname)
       throws GRASSException
Initializes GIS library for applications that run under GRASS. Assumes that .grassrc file exists and appropriate environmental variables are set by GRASS initialization script.
Parameters:
appname - Application name, one that can be obtained in C from argv[0]
Throws:
GRASSException - Always thrown with the message "Constructor not Implemented"
Method Detail

getpid

public int getpid()
Returns the process ID of the process. Wraps C function: 
 pid_t getpid(void);
Returns:
process ID

getGISRC

public java.lang.String getGISRC()
Returns the name of GISRC file created by this class.
Returns:
GISRC file name

G_sleep_on_error

public void G_sleep_on_error(boolean flag)
Sets/unsets pause on errors. Wraps GRASS library routine: 
 G_sleep_on_error (flag)  
               int flag;
See the GRASS 4.2 Programmer's Manual, Section 12.3 Diagnostic messages
Parameters:
flag - Pause flag: false -- no pause on errors; true -- pause will occur.

G_suppress_warnings

public void G_suppress_warnings(boolean flag)
Sets/unsets reporting warnings. Wraps GRASS library routine: 
 G_suppress_warnings (flag)  
               int flag;
See the GRASS 4.2 Programmer's Manual, Section 12.3 Diagnostic messages
Parameters:
flag - Warnings flag. false -- print warning messages, true -- suppress warnings.

G_location

public java.lang.String G_location()
Returns the name of the current database location. Wraps GRASS library routine: 
 char * 
 G_location ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
The name of the current database location.

G_mapset

public java.lang.String G_mapset()
Returns the name of the current mapset in current location. Wraps GRASS library routine: 
 char * 
 G_mapset ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
The name of the current mapset in current location.

G_myname

public java.lang.String G_myname()
Returns a one line title for the database location. Wraps GRASS library routine: 
 char * 
 G_myname ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
One line title for the database location.

G_gisbase

public java.lang.String G_gisbase()
Returns the full path name of the top level directory for GRASS programs. Wraps GRASS library routine: 
 char * 
 G_gisbase ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
Full path name of the top level directory for GRASS programs.

G_gisdbase

public java.lang.String G_gisdbase()
Returns the full UNIX path name of the directory which holds the database locations. Wraps GRASS library routine: 
 char * 
 G_gisdbase ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
Full UNIX path name of the directory which holds the database locations.

G_location_path

public java.lang.String G_location_path()
Returns the full UNIX path name of the current database location. Wraps GRASS library routine: 
 char * 
 G_location_path ()
See the GRASS 4.2 Programmer's Manual, Section 12.4 Environment and database information
Returns:
Full UNIX path name of the current database location.

G_get_window

public Cellhead G_get_window()
Reads the database region as stored in the WIND file in the user's current mapset. Wraps GRASS library routine: 
 G_get_window (region)
    struct Cell_head *region;
See the GRASS 4.2 Programmer's Manual, Section 12.7.1 The Database Region
Returns:
Database region.

G_get_default_window

public Cellhead G_get_default_window()
Reads the default region for the location. Wraps GRASS library routine: 
 G_get_default_window (region)
     struct Cell_head *region;
See the GRASS 4.2 Programmer's Manual, Section 12.7.1 The Database Region
Returns:
Default region.

G_window_rows

public int G_window_rows()
Returns the number of rows in the active program region. Wraps GRASS library routine: 
 G_window_rows ()
See the GRASS 4.2 Programmer's Manual, Section 12.7.2 The Active Program Region
Returns:
Number of rows in the active program region.

G_window_cols

public int G_window_cols()
Returns the number of columns in the active program region. Wraps GRASS library routine: 
 G_window_cols ()
See the GRASS 4.2 Programmer's Manual, Section 12.7.2 The Active Program Region
Returns:
Number of columns in the active program region.

G_set_window

public void G_set_window(Cellhead ch)
                  throws GRASSException
Sets the active region using parameters in Cellhead. Somewhat equivalent to GRASS library routine: 
 G_set_window (region)
        struct Cell_head *region;
See the GRASS 4.2 Programmer's Manual, Section 12.7.2 The Active Program Region
Parameters:
ch - Cellhead to use parameters to set region to.
Throws:
GRASSException - Exception with an appropriate message is thrown in cases when provided region is not valid.

G_put_window

public void G_put_window(Cellhead ch)
                  throws GRASSException
Writes the database region file (WIND) in the user's current mapset from cellhead. Somewhat equivalent to GRASS library routine: 
 G_put_window (region)
        struct Cell_head *region;
See the GRASS 4.2 Programmer's Manual, Section 12.7.1 The Active DatabaseRegion
Parameters:
ch - Cellhead to use parameters to set region to.
Throws:
GRASSException - Exception with an appropriate message is thrown in cases when provided region is not valid.

G_get_set_window

public Cellhead G_get_set_window()
Gets the values of currently active region into a new Cellhead object. Wraps GRASS library routine: 
 G_get_set_window (region)
        struct Cell_head *region;
See the GRASS 4.2 Programmer's Manual, Section 12.7.2 The Active Program Region
Returns:
Cellhead whose values are set.

G_begin_cell_area_calculations

public int G_begin_cell_area_calculations()
This routine must be called once before any call to G_area_of_cell_at_row. It can be used in either planimetric projections or the latitude-longitude projection. It returns 2 if the projection is latitude-longitude, 1 if the projection is planimetric, and 0 of the projection doesn't hav e a metric (e.g. imagery.) If the return value is 1 or 0, all the grid cells in the map have the same area. Otherwise the area of a grid cell varies with the row. Wraps GRASS library routine: 
   G_begin_cell_area_calculations ()
See the GRASS 4.2 Programmer's Manual, Section 12.8 Raster Area Calculations
Returns:
2 if the projection is latitude-longitude, 1 if the projection is planimetric, and 0 of the projection doesn't have a metric (e.g. imagery.)

G_area_of_cell_at_row

public double G_area_of_cell_at_row(int row)
This routine returns the area in square meters of a cell in the specified row. This value is constant for planimetric grids and varies with the row if the projection is latitude-longitude. Wraps GRASS library routine: 
 double
 G_area_of_cell_at_row (row)
    int row ;
See the GRASS 4.2 Programmer's Manual, Section 12.8 Raster Area Calculations
Parameters:
row - row to return area at
Returns:
area in square meters of a cell in the specified row

G_find_cell

public java.lang.String G_find_cell(java.lang.String name,
                                    java.lang.String mapset)
                             throws GRASSException
Looks for raster file name in the database. Wraps GRASS library routine: 
 char*
 G_find_cell (name, mapset)
      char *name;
      char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.9.2 Finding Raster File in Database
Parameters:
name - Raster file name to search for.
mapset - Name of mapset in which raster should reside. Can be empty string which means search all the mapsets in the user's current mapset search path.
Returns:
mapset where raster file resides
Throws:
GRASSException - if raster file was not found

G_open_cell_old

public FD G_open_cell_old(java.lang.String name,
                          java.lang.String mapset)
                   throws GRASSException
Opens existing raster file. Wraps GRASS library routine: 
 G_open_cell_old (name, mapset)
      char *name;
      char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.9.3 Opening an Existing Raster File
Parameters:
name - Raster file name to open.
mapset - Name of mapset in which raster should reside. It can be obtained by calling G_find_cell.
Returns:
file descriptor of the open raster
Throws:
GRASSException - is thrown if an error was returned by the GRASS routine

G_open_cell_new

public FD G_open_cell_new(java.lang.String name)
                   throws GRASSException
Opens a new raster file. Wraps GRASS library routine: 
 G_open_cell_new (name, mapset)
      char *name;
      char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.9.4 Creating and Opening Opening Raster Files
Parameters:
name - Raster file name to open.
Returns:
file descriptor of the open raster
Throws:
GRASSException - is thrown if an error was returned by the GRASS routine

G_open_cell_new_random

public FD G_open_cell_new_random(java.lang.String name)
                          throws GRASSException
Opens a new raster file for random writes by G_put_mpa_row. Wraps GRASS library routine: 
 G_open_cell_new_random (name, mapset)
      char *name;
      char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.9.4 Creating and Opening Opening Raster Files
Parameters:
name - Raster file name to open.
Returns:
file descriptor of the open raster or negative value if error occured
Throws:
GRASSException - is thrown if an error was returned by the GRASS routine

G_read_cats

public Categories G_read_cats(java.lang.String name,
                              java.lang.String mapset)
                       throws GRASSException
The category file for raster file name in mapset is read into the this object. Wraps GRASS library routine: 
 G_read_cats (name, mapset, cats)
     char *name;
     char *mapset;
     struct Categories *cats;
See the GRASS 4.2 Programmer's Manual, Section 12.10.2.1. Reading and Writing the Raster Category File
Parameters:
name - raster layer name
mapset - mapset name
Returns:
new instance of Categories
Throws:
GRASSException - is thrown with an appropriate message if there was an error reading category file

G_read_vector_cats

public Categories G_read_vector_cats(java.lang.String name,
                                     java.lang.String mapset)
                              throws GRASSException
The category file for vector file name in mapset is read into the new Categories object. Wraps GRASS library routine: 
 G_read_vector_cats (name, mapset, cats)
     char *name;
     char *mapset;
     struct Categories *cats;
See the GRASS 4.2 Programmer's Manual, Section 12.11.6 Vector Category File
Parameters:
name - vector layer name
mapset - mapset name
Returns:
new instance of Categories
Throws:
GRASSException - is thrown with an appropriate message if there was an error reading category file

G_find_sites

public java.lang.String G_find_sites(java.lang.String name,
                                     java.lang.String mapset)
                              throws GRASSException
Looks for stes list name in the database. This function is not documented in GRASS 4.2 Programmer's Manual.
Parameters:
name - Site list name to search for.
mapset - Name of mapset in which sitelist should reside. Can be empty string which means search all the mapsets in the user's current mapset search path.
Returns:
mapset where site list file resides
Throws:
GRASSException - if raster file was not found

G_fopen_sites_new

public FILE G_fopen_sites_new(java.lang.String name)
                       throws GRASSException
Creates an empty site list file name in the current mapset and opens it for writing. Wraps GRASS library routine: 
 FILE* 
 G_fopen_sites_new (name) 
       char *name;
See the GRASS 4.2 Programmer's Manual, Section 12.12.2 Opening Site List Files
Parameters:
name - GRASS site list file name
Returns:
A new GRASS.FD object to access site list
Throws:
GRASSException - Exception with an appropriate error message is thrown if some error occured while opening site list file.

G_fopen_sites_old

public FILE G_fopen_sites_old(java.lang.String name,
                              java.lang.String mapset)
                       throws GRASSException
Opens the site list file name in mapset for reading. Wraps GRASS library routine: 
 FILE *
 G_fopen_sites_old (name, mapset)
       char *name;
       char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.12.2 Opening Site List Files
Parameters:
name - GRASS site list file name
mapset - Name of mapset where site list file should reside
Returns:
A new GRASS.FD object to access site list
Throws:
GRASSException - Exception with an appropriate error message is thrown if some error occured while opening site list file.

G_find_vector

public java.lang.String G_find_vector(java.lang.String name,
                                      java.lang.String mapset)
                               throws GRASSException
Looks for vector file name in the database. Wraps GRASS library routine: 
 char*
 G_find_vector (name, mapset)
      char *name;
      char *mapset;
See the GRASS 4.2 Programmer's Manual, Section 12.11.2 Finding Vector File in Database
Parameters:
name - Vector file name to search for.
mapset - Name of mapset in which vector should reside. Can be empty string which means search all the mapsets in the user's current mapset search path.
Returns:
mapset where vector file resides
Throws:
GRASSException - if vector file was not found

G_projection

public int G_projection()
This routine returns a code indicating the projection for the active region. The current values are:
CodeProjection
0unreferenced x,y (imagery data)
1UTM
2State Plane
3Latitude-Longitude
Wraps GRASS library routine: 
 G_projection ( )
See the GRASS 4.2 Programmer's Manual, Section 12.7.3 Projection information
Returns:
code indicating the projection for the active region

G_database_projection_name

public java.lang.String G_database_projection_name()
Returns a string which is a printable name for projection in active region. Wraps GRASS library routine: 
 char*
 G_database_projection_name ()
See the GRASS 4.2 Programmer's Manual, Section 12.7.3 Projection information
Returns:
name for projection in active region

G_database_unit_name

public java.lang.String G_database_unit_name(boolean plural)
Returns a string describing the database grid units. Wraps GRASS library routine: 
 char *
 G_database_unit_name (plural)
    int plural
See the GRASS 4.2 Programmer's Manual, Section 12.7.3 Projection information
Parameters:
plural - return a plural form (eg. feet) if true.
Returns:
database grid units

G_database_units_to_meters_factor

public double G_database_units_to_meters_factor()
Returns a factor which converts the grid unit to meters (by multiplication). If the database is not metric (eg. imagery) then 0.0 is returned. Wraps GRASS library routine: 
 double
     G_database_units_to_meters_factor ()
See the GRASS 4.2 Programmer's Manual, Section 12.7.3 Projection information
Returns:
factor which converts the grid unit to meters

G_zone

public int G_zone()
This routine returns the zone for the active region. The meaning for the zone depends on the projection. Wraps GRASS library routine: 
 G_zone ()
See the GRASS 4.2 Programmer's Manual, Section 12.7.3 Projection information
Returns:
projection zone for the active region

close

public void close()
           throws GRASSException
Deletes rc file if one was created.
GRASS-JNI Home Page