GRASS and Ruby: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(Bew)
 
(Add instructions on how to use the grassgis Ruby gem)
Line 1: Line 1:
For a Ruby gem (library) to support executing GRASS commands from Ruby scripts, see
The Ruby language can be easily used to write scripts that execute GRASS commands with this gem:


* https://github.com/jgoizueta/grassgis
* https://github.com/jgoizueta/grassgis


==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:
<source lang="bash">
gem install grassgis
</source>
If you're using [http://bundler.io/ Bundler] you just need to add this to your <cod>Gemfile</code>:
<source lang="ruby">
gem 'grass'gis'
</source>
And then execute:
<source lang="bash">
bundle
</source>
Then, in your Ruby source, you need to require the gem:
<source lang="ruby">
require 'grassgis'
</source>
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:
<source lang="ruby">
configuration = {
  gisbase: '/usr/local/grass-7.0.0',
  gisdbase: File.join(ENV['HOME'], 'grassdata'),
  location: 'nc_spm',
  mapset: 'user1'
}
</source>
So, you first need to know where is GRASS installed on your system
to define the <code>:gisbase</code> option to point to the base directory of the GRASS
installation.
In '''Windows''', if installed with
[http://trac.osgeo.org/osgeo4w/ OSGeo4W] it is typically of
the form <code>C:\OGeo4W\app\grass\grass-7.0.0</code> (the last directory will vary
depending on the GRASS version).
Under '''Mac OS X''', if using [http://brew.sh/ Homebrew]
(with the [https://github.com/OSGeo/homebrew-osgeo4mac osgeo/osgeo4mac] tap)
it should be something like <code>/usr/local/Cellar/grass-70/7.0.0/grass-7.0.0</code>.
In general, you can find the <code>:gisbase</code> directory by executing the
<code>grass</code> command of your system (which might be <code>grass70</code>, <code>grass64</code>, etc.)
with the <code>--config path</code> option:
<source lang="bash">
grass --config path
</source>
You must also specify the <code>GISDBASE</code>, <code>LOCATION</code> and <code>MAPSET</code>, to work with,
just like when starting GRASS, through the <code>:gisdbase</code>, <code>:location</code> and
<code>:mapset</code> configuration options.
You can omit <code>:gisdbase</code> which will default to a directory named <code>grassdata>/code> in the
user's home directory and <code>:mapset/code> which defaults to <code>PERMANENT</code>.
=== 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:
<source lang="ruby">
GrassGis.session configuration do
  g.list 'vect'
  puts output # will print list of vector maps
end
</source>
In the example we execute a GRASS command (<code>g.list 'vect'</code>) then print its output to the console.
Inside a <code>GrassGis</code> 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:
<source lang="ruby">
g.region '-p', rast: 'elevation'
d.rast 'elevation'
d.vect 'streams', col: 'blue'
</source>
If you try to execute an invalid module name an `ENOENT`
error will be raised:
<source lang="ruby">
g.this.module.does.not.exist '???'
</source>
If the command to be executed has no arguments you need
to invoke `.run` on it to execute it:
<source lang="ruby">
d.erase.run
g.list.run
</source>


[[Category:Linking to other languages]]
[[Category:Linking to other languages]]

Revision as of 13:50, 25 July 2015

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 'grass'gis'

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