GRASS and Ruby: Difference between revisions
(Bew) |
⚠️Jgoizueta (talk | contribs) (Add instructions on how to use the grassgis Ruby gem) |
||
Line 1: | Line 1: | ||
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