GRASS and Ruby

From GRASS-Wiki
Jump to navigation Jump to search

The Ruby language can be easily used to write scripts that execute GRASS commands with this gem:

Writing a Ruby script that uses GRASS

Let's see how to write a Ruby program that executes GRASS commands. You won't need to start GRASS explicitly, the script will handle sessions internally as you will see.

First, you need to install the gem in your system:

gem install grassgis

If you're using Bundler you just need to add this to your <cod>Gemfile:

gem 'grassgis'

And then execute:

bundle

Then, in your Ruby source, you need to require the gem:

require 'grassgis'

To be able to use GRAS you need to open a GRASS session from your program; in order to do so you'll need to provide some configuration parameters.

Session Configuration

Before starting a GRASS session we need some configuration parameters to specify the path of the GRASS Installation to be used and the location/mapset to be used. We do this by using a Ruby Hash containing configuration parameters:

configuration = {
  gisbase: '/usr/local/grass-7.0.0',
  gisdbase: File.join(ENV['HOME'], 'grassdata'),
  location: 'nc_spm',
  mapset: 'user1'
}

So, you first need to know where is GRASS installed on your system to define the :gisbase option to point to the base directory of the GRASS installation.

In Windows, if installed with OSGeo4W it is typically of the form C:\OGeo4W\app\grass\grass-7.0.0 (the last directory will vary depending on the GRASS version).

Under Mac OS X, if using Homebrew (with the osgeo/osgeo4mac tap) it should be something like /usr/local/Cellar/grass-70/7.0.0/grass-7.0.0.

In general, you can find the :gisbase directory by executing the grass command of your system (which might be grass70, grass64, etc.) with the --config path option:

grass --config path

You must also specify the GISDBASE, LOCATION and MAPSET, to work with, just like when starting GRASS, through the :gisdbase, :location and :mapset configuration options.

You can omit :gisdbase which will default to a directory named grassdata>/code> in the user's home directory and :mapset/code> which defaults to PERMANENT.

Running a GRASS Session

With the proper configuration in place, we're ready to use it to create a GRASS Session and execute GRASS command from it:

GrassGis.session configuration do
  g.list 'vect'
  puts output # will print list of vector maps
end

In the example we execute a GRASS command (g.list 'vect') then print its output to the console.

Inside a GrassGis session we can execute GRASS commands just by using the command name as a Ruby method.

Command flags and options must be passed first as regular method arguments, then named parameters must be passed as a Ruby Hash:

g.region '-p', rast: 'elevation'
d.rast 'elevation'
d.vect 'streams', col: 'blue'

If you try to execute an invalid module name an `ENOENT` error will be raised:

g.this.module.does.not.exist '???'

If the command to be executed has no arguments you need to invoke `.run` on it to execute it:

d.erase.run
g.list.run

More Information