RubyGems - grassgis - Versions diffs - 0.4.3 → 0.5.0 - Mend

grassgis 0.4.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31603b3573329e791fb150b29bdbc2431ac67b73
-  data.tar.gz: 22cef2943a628277b2811565625be816400a5cfa
+  metadata.gz: cf52083bd1c17e88f35637c33190bb5118c315ae
+  data.tar.gz: d839e49ddad296eaf6571b7c84accc7afeb91222
 SHA512:
-  metadata.gz: b5f0bc0d8e6f86f97e25ffb8d70ad2ba7dc34b699be10350e0f72ffd67162760ff08c0fa5477ecd63829386e3c3f4d82c2d248ab2aa9972880ca1b26346e54b6
-  data.tar.gz: 9f652b3f652615c98ab606fee366546d6c4cac5ca5c47e69b87eed9479496c9f9bc9110ec94e435b7fd1295a20aa68fb9170f655bcc9e032f23bae571a73301b
+  metadata.gz: bd781b3d5cbb21cd66512b72aa8146beed1f7488c7683ecee4c3af8e0988de0939e660cfe9658051f6a01c71694deb521fa1c3247f89de6d8381e28ba5930a09
+  data.tar.gz: 54d0b9056cee6f5382bdbc3dfc690bd6b2aa79a4777c88ef00dc153cc6b20e2d0bb10676e1253361e200371829ca5850f76e23315f57676f4fea7465f8000698

data/.gitignore CHANGED

@@ -1,22 +1,22 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml CHANGED

@@ -1,7 +1,7 @@
-language: ruby
-rvm:
-  - 2.2.2
-  - 2.1.6
-  - 1.9.3
-before_install:
-  - gem update bundler
+language: ruby
+rvm:
+  - 2.2.2
+  - 2.1.6
+  - 1.9.3
+before_install:
+  - gem update bundler

data/Gemfile CHANGED

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
-# Specify your gem's dependencies in grassgis.gemspec
-gemspec
+source 'https://rubygems.org'
+# Specify your gem's dependencies in grassgis.gemspec
+gemspec

data/LICENSE.txt CHANGED

@@ -1,22 +1,22 @@
-Copyright (c) 2015 Javier Goizueta
-MIT License
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2015 Javier Goizueta
+MIT License
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md CHANGED

@@ -1,578 +1,722 @@
-# GrassGis
-[![Gem Version](https://badge.fury.io/rb/grassgis.svg)](http://badge.fury.io/rb/grassgis)
-[![Build Status](https://travis-ci.org/jgoizueta/grassgis.svg)](https://travis-ci.org/jgoizueta/grassgis)
-Support for scripting GRASS with Ruby.
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Configuration](#configuration)
-  - [Running a GRASS Session](#running-a-grass-session)
-  - [Creating new locations and mapsets](#creating-new-locations-and-mapsets)
-  - [History](#history)
-  - [Options](#options)
-    - [Echo](#echo)
-    - [Errors](#errors)
-    - [Logging](#logging)
-  - [Technicalities](#technicalities)
-    - [Session scopes](#session-scopes)
-    - [Invalid commands](#invalid-commands)
-- [Helper methods](#helper-methods)
-  - [Examples](#examples)
-    - [1. Map existence](#1-map-existence)
-    - [2. Information as Hashes](#2-information-as-hashes)
-    - [3. Average angle](#3-average-angle)
-- [Roadmap](#roadmap)
-  - [GRASS cooking DSL](#grass-cooking-dsl)
-- [Contributing](#contributing)
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-## Installation
-Add this line to your application's Gemfile:
-    gem 'grassgis'
-And then execute:
-    $ bundle
-Or install it yourself as:
-    $ gem install grassgis
-## Usage
-This library can prepare environments to execute GRASS commands
-from Ruby scripts.
-First we require the library:
-```ruby
-require 'grassgis'
-```
-### Configuration
-A GRASS session operates on a given location and mapset.
-Before starting a GRASS session we need some configuration
-parameters to specify the location of the GRASS Installation
-to be used and the location/mapset. We do this by using
-a Ruby Hash containing configuration parameters:
-```ruby
-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.
-For *Ubuntu* it will typically be `/usr/lib/grass70` for version 7 of GRASS.
-In *Windows*, if installed with
-[OSGeo4W](http://trac.osgeo.org/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](http://brew.sh/)
-(with the [osgeo/osgeo4mac](https://github.com/OSGeo/homebrew-osgeo4mac) tap)
-it should bd something like `/usr/local/Cellar/grass-70/7.0.0/grass-7.0.0`.
-You can find the `:gisbase` directory by executing the
-`grass` command of your system (which may 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` in the
-user's home directory and `:mapset` which defaults to `PERMANENT`.
-### Running a GRASS Session
-With the proper configuration in place, we can use it to
-create a GRASS Session and execute GRASS command from it:
-```ruby
-GrassGis.session configuration do
-  g.list 'vect'
-  puts output # will print list of vector maps
-end
-```
-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:
-```ruby
-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:
-```ruby
-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:
-```ruby
-d.erase.run
-g.list.run
-```
-### Creating new locations and mapsets
-To create a new location and/or mapset, open a session to it
-and use a `:create` parameter like this:
-```ruby
-options = configuration.merge(
-  location: 'new_location',
-  mapset: 'new_mapset',
-  create: {
-    epsg: 4326               # coordinate system for the new location
-    limits: [-5, 30, 5, 50], # optional E, S, W, N limits
-    res: 2                   # optional resolution
-  }
-)
-GrassGis.session options do
-  g.region '-p'
-  puts output
-end
-```
-Use `nil` or `PERMANENT` for the mapset to avoid creating a new mapset.
-Existing locations or mapsets are not changed.
-### History
-The return value of a GRASS command invocation inside a session is
-a `SysCmd::Command`
-(see the [sys_cmd gem](https://github.com/jgoizueta/sys_cmd)).
-```ruby
-GrassGis.session configuration do+
-  cmd = g.region '-p'
-  puts cmd.output # command output is kept in the Command object
-  puts cmd.status_value # 0 for success
-end
-```
-You don't need to assign commands to variables as in the example
-to access them, because they're all kept in an array accesible
-through the `history` method of the session:
-```ruby
-GrassGis.session configuration do+
-  r.info 'slope'
-  g.region '-p'
-  puts history.size       # 2
-  puts history[-1].output # output of g.region
-  puts history[-2].output # output of r.info
-end
-```
-The last executed command (`history[-1]`) is also accessible through
-the `last` method and its output through `output`:
-```ruby
-GrassGis.session configuration do+
-  r.info 'slope'
-  g.region '-p'
-  puts output # output of g.region (same as last.output)
-  puts last.status_value # result status of g.region
-end
-```
-### Options
-By default the commands executed in a session are echoed to standard output
-(just the command, not its output) and error return status causes
-an exception to be raised.
-This behaviour can be changed with some options:
-#### Echo
-Pass `false` as the `:echo` option it you don't want to output
-command names and `:output` if you want to output both
-the command name and its output.
-```ruby
-GrassGis.session configuration.merge(echo: false) do
-  # Command names not echoed now ...
-end
-GrassGis.session configuration.merge(echo: :output) do
-  # Command names and its output echoed ...
-end
-```
-#### Errors
-To avoid raising exceptions when commands return an error status you can pass
-`:quiet` to the `:errors` option. In that case the `error?` method of the
-session can be used to check if the previous messatge returned an error status;
-`error_info` to get its error message and the status of the command
-of the command can be obtained through the `last` command method.
-```ruby
-GrassGis.session configuration.merge(errors: :quiet) do
-  r.surf.rst 'randpts', elev: 'rstdef', zcol: 'value'
-  if error?
-    puts "Last command didn't go well..."
-    puts "It returned the code: #{last.status_value}"
-    puts "Here's what it said about the problem:"
-    puts error_info
-  end
-end
-```
-With the `:quiet` option errors during command execution are not raised,
-but if a problem prevents the command from being executed (e.g. the
-module does not exist) an exception is still generated. This exception
-can be avoided too, with the `:silent` option, intended for tests and
-debugging.
-Passing the `:console` value to the `:errors` option is like `:quiet`,
-with the additional effect of relaying the command standard error output
-to the error output of the script.
-#### Logging
-With the `:log` option you can specify the name of a file
-where to record the commands executed and its output.
-### Technicalities
-#### Session scopes
-In a session block, the Ruby `self` object is altered to
-refer to a `GrassGis::Context` object. That means that in addition
-to the enclosing `self`, any instance variables of the enclosing
-scope are not directly available. This may cause some surprises
-but is easy to overcome.
-```ruby
-@value = 10
-GrassGis.session configuration do
-  puts @value # nil!
-end
-```
-A possible workaround is to assign instance variables that we need
-in the session to local variables:
-```ruby
-@value = 10
-value = @value
-GrassGis.session configuration do
-  puts value # 10
-end
-```
-To avoid defining these variables you can pass a `:locals` Hash
-in the configuration to define values that you need to access
-in the session (but you won't be able to assign to them, because
-they're not local variables!)
-```ruby
-@value = 10
-GrassGis.session configuration.merge(locals: { value: @value }) do
-  puts value # 10
-  value = 11 # don't do this: you're creating a local in the session
-end
-```
-A different approach is prevent the session block from using a special
-`self` by defining a parameter to the block. This parameter will have
-the value of a `GrassGis::Context` which you'll need to explicitly use
-to execute any commands:
-```ruby
-@value = 10
-GrassGis.session configuration do |grass|
-  puts @value # 10
-  grass.g.region res: 10 # now you need to use the object to issue commans
-end
-```
-#### Invalid commands
-Currently the generation of GRASS commands inside a session is
-implemented in a versy simple way which allows to generate any command
-name even if it is invalid or does not exist. This has the advantage
-of supporting any version of GRASS, but doesn't allow for early
-detection of invalid commands (e.g. due to typos) or invalid command
-parameters.
-```ruby
-GrassGis.session configuration do |grass|
-  g.regoin res: 10     # Oops (runtime error)
-  g.anything.goes.run  # another runtime error
-end
-```
-If the command generated does not exist a runtime `ENOENT` exception will
-occur.
-If the command exists, then if parameters are not valid, the command
-will execute but will return an error status. This will be handled
-as explaned above.
-## Helper methods
-When writing a non-trivial program you'll probably
-find you want to define methods to avoid unnecessary repetition.
-Let's see how you can call methdos from your session and be
-able to execute GRASS commands from the method in the context of the session.
-Inside a session, `self` refers to an object of class
-`GrassGis::Context` which represents the current GRASS session.
-You can invoke grass commands directly on this object, so, if you pass
-this object around you can use it to execute GRASS commands:
-```ruby
-def helper_method(grass)
-  # ...
-end
-GrassGis.session configuration do
-  helper_method self
-end
-```
-In the helper method you can use the grass object like this;
-```ruby
-def helper_method(grass)
-  # change the current region resolution
-  grass.g.region res: 10
-end
-```
-To avoid having to prepend each command with `grapss.` you can
-use the `session` method like this:
-```ruby
-def helper_method(grass)
-  grass.session do
-    g.region res: 10
-    g.region '-p'
-    puts output
-  end
-end
-```
-### Examples
-#### 1. Map existence
-Helper methods to check for the existence of maps.
-Often we may want to know if a map exists. Next methods can be used to
-check for it.
-```ruby
-def map_exists?(grass, type, map)
-  grass.g.list type
-  maps = grass.output.split
-  maps.include?(map)
-end
-def raster_exists?(grass, map)
-  map_exists? grass, 'rast', map
-end
-def vector_exists?(grass, map)
-  map_exists? grass, 'vect', map
-end
-```
-We can use these methods like this:
-```ruby
-GrassGis.session configuration do
-  unless raster_exists?(self, 'product')
-    r.mapcalc "product = factor1*factor2"
-  end
-end
-```
-#### 2. Information as Hashes
-Following methods show how to obtain information about a raster map
-and the current region as a Hash:
-```ruby
-def raster_info(grass, map)
-  grass.r.info '-g', map
-  shell_to_hash grass
-end
-def region_info(grass)
-  grass.g.region '-m'
-  shell_to_hash grass
-end
-def shell_to_hash(grass)
-  Hash[grass.output.lines.map{|l| l.strip.split('=')}]
-end
-# Now, for example, we can easily obtain the resolution of a raster:
-def raster_res(grass, map)
-  info = raster_info(grass, map)
-  info.values_at('ewres', 'nsres').map(&:to_i)
-end
-def region_res(grass)
-  info = region_info(grass)
-  info.values_at('ewres', 'nsres').map(&:to_i)
-end
-```
-#### 3. Average angle
-Let's assume we have a raster map `aspect` which is
-a direction angle (i.e. a cyclic value from 0 to 360).
-Now imagine that we need to compute a coarser raster grid with
-average values per cell. We can't just resample the angle
-(we want the average of 359 and 1 be 0, not 180);
-we would need an unitary vector or complex number to take averages.
-The next method will perform the average correctly using
-auxiliary raster maps for two cartesian components (that represent
-the angle as a vector).
-```ruby
-def resample_average_angle(grass, options = {})
-  input_raster = options[:input]
-  raise "Raster #{input_raster} not found" unless raster_exists?(grass, input_raster)
-  input_res = raster_res(grass, input_raster)
-  if options[:output_res]
-    output_res = options[:output_res]
-    unless output_res.is_a?(Array)
-      output_res = [output_res, output_res]
-    end
-  else
-    output_res = region_res(grass)
-  end
-  output_raster = options[:output]
-  grass.session do
-    unless raster_exists?(self, "#{input_raster}_sin")
-      g.region ewres: input_res[0], nsres: input_res[1]
-      r.mapcalc "#{input_raster}_sin = sin(#{input_raster})"
-    end
-    unless raster_exists?(self, "#{input_raster}_cos")
-      g.region ewres: input_res[0], nsres: input_res[1]
-      r.mapcalc "#{input_raster}_cos = cos(#{input_raster})"
-    end
-    g.region ewres: output_res[0], nsres: output_res[1]
-    r.resamp.stats input: "#{input_raster}_cos", output: "#{output_raster}_cos"
-    r.resamp.stats input: "#{input_raster}_sin", output: "#{output_raster}_sin"
-    r.mapcalc "#{output_raster} = atan(#{output_raster}_cos,#{output_raster}_sin)"
-    r.colors map: ouput_raster, raster: input_raster
-    g.remove '-f', type: 'raster', name: ["#{output_raster}_cos", "#{output_raster}_sin"]
-    g.remove -f type=raster name=aspect_sin@landscape,aspect_cos@landscape
-  end
-end
-```
-Now, to resample a (cyclic angular) map `aspect_hires` to a lower resolution 10:
-```ruby
-GrassGis.session configuration do
-  resamp_average self,
-    input: 'aspect_hires',
-    output: 'aspect_lowres', output_res: 10
-  end
-end
-```
-## Roadmap
-* Change Module to define explicitly available GRASS commands instead of
-  accepting anything with `method_missing`. Declare commands with permitted
-  arguments and options, etc.
-* Add some session helpers:
-  - Method to clean GRASS temporaries ($GISBASE/etc/clean_temp), or do
-    it automatically when disposing the session.
-  - Methods to check if maps exist
-  - Methods that return information as objects (arrays, hashes), e.g.
-    values returned by r.what, the current region, etc.
-  - Methods that execute operations in a GRASS-version independent
-    manner (higher level, version independent interface to modules).
-### GRASS cooking DSL
-Create a DSL to define GRASS processing recipes.
-It should handle errors gracefully during recipe execution,
-take care of logging, parsing command output, temporary files, etc.
-A recipe could have requirements such as which other recipes it depends
-upon (so must be executed first), which map layers must exist, etc.
-It could also define what map layers or other files are generated by the
-recipe.
-Example of intended recipe syntax:
-```ruby
-recipe :resamp_average do |options = {}|
-  # ...
-end
-recipe :generate_working_dem do |...|
-  define :working_dem, 'dem'
-  define :working_slope, 'slope'
-  define :working_aspect, 'aspect'
-  g.region res: working_res
-  apply :resamp_average, input: base_dem, output: working_dem, input_res: base_dem_res, output_res: working_res
-  apply :resamp_average, input: base_slope, output: working_slope, input_res: base_dem_res, output_res: working_res
-  apply :resamp_average, input: base_aspect, output: working_aspect, input_res: base_dem_res, output_res: working_res, direction: true
-  describe working_slope, "Pendiente en grados a #{working_res} #{region_units}"
-  # ...
-end
-```
-## Contributing
-1. Fork it ( https://github.com/[my-github-username]/grassgis/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+# GrassGis
+[![Gem Version](https://badge.fury.io/rb/grassgis.svg)](http://badge.fury.io/rb/grassgis)
+[![Build Status](https://travis-ci.org/jgoizueta/grassgis.svg)](https://travis-ci.org/jgoizueta/grassgis)
+Support for scripting GRASS with Ruby.
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Configuration](#configuration)
+  - [Running a GRASS Session](#running-a-grass-session)
+  - [Creating new locations and mapsets](#creating-new-locations-and-mapsets)
+  - [History](#history)
+  - [Options](#options)
+    - [Echo](#echo)
+    - [Errors](#errors)
+    - [Logging](#logging)
+  - [Recipes](#recipes)
+  - [Technicalities](#technicalities)
+    - [Session scopes](#session-scopes)
+    - [Invalid commands](#invalid-commands)
+- [Helper methods](#helper-methods)
+  - [Examples](#examples)
+    - [1. Map existence](#1-map-existence)
+    - [2. Information as Hashes](#2-information-as-hashes)
+    - [3. Average angle](#3-average-angle)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+## Installation
+Add this line to your application's Gemfile:
+    gem 'grassgis'
+And then execute:
+    $ bundle
+Or install it yourself as:
+    $ gem install grassgis
+## Usage
+This library can prepare environments to execute GRASS commands
+from Ruby scripts.
+First we require the library:
+```ruby
+require 'grassgis'
+```
+### Configuration
+A GRASS session operates on a given location and mapset.
+Before starting a GRASS session we need some configuration
+parameters to specify the location of the GRASS Installation
+to be used and the location/mapset. We do this by using
+a Ruby Hash containing configuration parameters:
+```ruby
+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.
+For *Ubuntu* it will typically be `/usr/lib/grass70` for version 7 of GRASS.
+In *Windows*, if installed with
+[OSGeo4W](http://trac.osgeo.org/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](http://brew.sh/)
+(with the [osgeo/osgeo4mac](https://github.com/OSGeo/homebrew-osgeo4mac) tap)
+it should bd something like `/usr/local/Cellar/grass-70/7.0.0/grass-7.0.0`.
+You can find the `:gisbase` directory by executing the
+`grass` command of your system (which may 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` in the
+user's home directory and `:mapset` which defaults to `PERMANENT`.
+### Running a GRASS Session
+With the proper configuration in place, we can use it to
+create a GRASS Session and execute GRASS command from it:
+```ruby
+GrassGis.session configuration do
+  g.list 'vect'
+  puts output # will print list of vector maps
+end
+```
+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:
+```ruby
+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:
+```ruby
+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:
+```ruby
+d.erase.run
+g.list.run
+```
+### Creating new locations and mapsets
+To create a new location and/or mapset, open a session to it
+and use a `:create` parameter like this:
+```ruby
+options = configuration.merge(
+  location: 'new_location',
+  mapset: 'new_mapset',
+  create: {
+    epsg: 4326               # coordinate system for the new location
+    limits: [-5, 30, 5, 50], # optional E, S, W, N limits
+    res: 2                   # optional resolution
+  }
+)
+GrassGis.session options do
+  g.region '-p'
+  puts output
+end
+```
+Use `nil` or `PERMANENT` for the mapset to avoid creating a new mapset.
+Existing locations or mapsets are not changed.
+### History
+The return value of a GRASS command invocation inside a session is
+a `SysCmd::Command`
+(see the [sys_cmd gem](https://github.com/jgoizueta/sys_cmd)).
+```ruby
+GrassGis.session configuration do+
+  cmd = g.region '-p'
+  puts cmd.output # command output is kept in the Command object
+  puts cmd.status_value # 0 for success
+end
+```
+You don't need to assign commands to variables as in the example
+to access them, because they're all kept in an array accesible
+through the `history` method of the session:
+```ruby
+GrassGis.session configuration do+
+  r.info 'slope'
+  g.region '-p'
+  puts history.size       # 2
+  puts history[-1].output # output of g.region
+  puts history[-2].output # output of r.info
+end
+```
+The last executed command (`history[-1]`) is also accessible through
+the `last` method and its output through `output`:
+```ruby
+GrassGis.session configuration do+
+  r.info 'slope'
+  g.region '-p'
+  puts output # output of g.region (same as last.output)
+  puts last.status_value # result status of g.region
+end
+```
+### Options
+By default the commands executed in a session are echoed to standard output
+(just the command, not its output) and error return status causes
+an exception to be raised.
+This behaviour can be changed with some options:
+#### Echo
+Pass `false` as the `:echo` option it you don't want to output
+command names and `:output` if you want to output both
+the command name and its output.
+```ruby
+GrassGis.session configuration.merge(echo: false) do
+  # Command names not echoed now ...
+end
+GrassGis.session configuration.merge(echo: :output) do
+  # Command names and its output echoed ...
+end
+```
+#### Errors
+To avoid raising exceptions when commands return an error status you can pass
+`:quiet` to the `:errors` option. In that case the `error?` method of the
+session can be used to check if the previous messatge returned an error status;
+`error_info` to get its error message and the status of the command
+of the command can be obtained through the `last` command method.
+```ruby
+GrassGis.session configuration.merge(errors: :quiet) do
+  r.surf.rst 'randpts', elev: 'rstdef', zcol: 'value'
+  if error?
+    puts "Last command didn't go well..."
+    puts "It returned the code: #{last.status_value}"
+    puts "Here's what it said about the problem:"
+    puts error_info
+  end
+end
+```
+With the `:quiet` option errors during command execution are not raised,
+but if a problem prevents the command from being executed (e.g. the
+module does not exist) an exception is still generated. This exception
+can be avoided too, with the `:silent` option, intended for tests and
+debugging.
+Passing the `:console` value to the `:errors` option is like `:quiet`,
+with the additional effect of relaying the command standard error output
+to the error output of the script.
+#### Logging
+With the `:log` option you can specify the name of a file
+where to record the commands executed and its output.
+### Recipes
+The `GrassCookbook` interface can be used to define geoprocessing
+"recipes", each one specifying which data is required and
+produced by the process.
+A recipe is defined by calling `GrassCookbook.recipe` with a block
+that provides the recipe definition in a declarative way, using
+methods such as `description`, `required_parameters`, `required_files`,
+`required_raster_maps`, `generated_rater_maps`, etc.
+The `process` method defines, by using a block, the recipes's procedure.
+The arguments to this block will be taken auto-magically from parameters
+of the same name (parameters are provided to a recipe-executing environment
+through a Hash).
+The available `GrassCookbook` methods can be used to determine which recipes need
+to be executed, in which order, and which products will be generated
+based on available data.
+For example, given this three recipes:
+```ruby
+GrassCookbook.recipe :dem_base_from_mdt05 do
+  description %{
+    Generate a DEM for the location region at fixed 5m resolution
+    from CNIG's MDT05 data.
+  }
+  required_files 'data/MDT05'
+  generated_raster_maps 'dem_base'
+  process do |mdt05_sheets|
+    # Import MDT05 sheets and generate dem_base
+    mdt05_sheets = mdt05_sheets.map { |n| "MDT05-#{n}-H30-LIDAR.asc"}
+    sheet_maps = Hash[mdt05_sheets.map { |s| [s, File.basename(s, '.asc')]}]
+    mdt05_sheets.each do |sheet|
+      map = sheet_maps[sheet]
+      r.in.gdal '-o', '--overwrite',
+        input: File.join('data', 'MDT05', sheet),
+        output: map
+      r.colors map: map, color: 'elevation'
+    end
+    # Keep previous resolution
+    ewres, nsres = region_res
+    # Patch sheets and crop
+    g.region res: 5
+    r.patch input: sheet_maps.values, output: 'dem_base'
+    r.colors map: 'dem_base', color: 'elevation'
+    # Restore previous resolution
+    g.region nsres: nsres, ewres: ewres
+    g.remove '-f', type: 'raster', name: sheet_maps.values
+  end
+end
+GrassCookbook.recipe :dem_base_derived do
+  description %{
+    Generate DEM-derived maps from the 5m dem base:
+    slope, aspect and relief shading
+  }
+  required_raster_maps 'dem_base'
+  generated_raster_maps 'shade_base', 'slope_base', 'aspect_base'
+  process do
+    r.relief input: 'dem_base', output: 'shade_base'
+    r.slope.aspect elevation: 'dem_base',
+                   slope:     'slope_base',
+                   aspect:    'aspect_base'
+  end
+end
+GrassCookbook.recipe :working_dem do
+  description %{
+    Generate DEM data at working resolution
+  }
+  required_raster_maps 'dem_base', 'slope_base', 'aspect_base'
+  generated_raster_maps 'dem', 'slope', 'aspect'
+  process do |resolution|
+    # Keep previous resolution
+    ewres, nsres = region_res
+    resamp_average input: 'dem_base', output: 'dem', output_res: resolution
+    resamp_average input: 'slope_base', output: 'slope', output_res: resolution
+    resamp_average input: 'aspect_base', output: 'aspect', output_res: resolution, direction: true
+    # Restore previous resolution
+    g.region nsres: nsres, ewres: ewres
+  end
+end
+```
+We could now use those recipes to compute some permanent base maps and
+then maps for alternative scenarios by varying some parameter.
+In this example the fixed parameter defines the available data
+we have to create a base DEM at a resolution of 5 meters,
+which will be kept in the PERMANENT mapset.
+Then we vary the `resolution` parameter to compute derived information
+(topography information at the given resolution) for two values
+of the parameter (10m and 25m) which will produce two mapsets with the
+name assigned to the variant scenario ('10m' and '25m')
+and all the maps that depend on the varying parameter in each of them.
+```ruby
+GrassGis.session grass_config do
+  # First generate maps using fixed parameters and move them to PERMANENT
+  fixed_parameters = { mdt05_sheets: %w(0244 0282) }
+  fixed_data = primary = GrassCookbook::Data[
+    parameters: fixed_parameters.keys,
+    files: GrassCookbook.existing_external_input_files
+  ]
+  plan = GrassCookbook.plan(fixed_data)
+  permanent = plan.last
+  GrassCookbook.replace_existing_products self, plan
+  GrassCookbook.execute self, fixed_parameters, plan
+  permanent.maps.each do |map, type|
+    move_map(map, type: type, to: 'PERMANENT')
+  end
+  # Then define some variations of other parameters and create a mapset
+  # for each variation, where maps dependent on the varying parameters
+  # will be put
+  variants = {
+    '10m' => { resolution: 10 },
+    '25m' => { resolution: 25 }
+  }
+  for variant_name, variant_parameters in variants
+    data = GrassCookbook::Data[parameters: variant_parameters.keys] + permanent
+    plan = GrassCookbook.plan(data)
+    GrassCookbook.replace_existing_products self, plan
+    GrassCookbook.execute self, fixed_parameters.merge(variant_parameters), plan
+    variant_maps = (plan.last - data).maps
+    create_mapset variant_name
+    variant_maps.each do |map, type|
+      move_map(map, type: type, to: variant_name)
+    end
+  end
+end
+```
+### Technicalities
+#### Session scopes
+In a session block, the Ruby `self` object is altered to
+refer to a `GrassGis::Context` object. That means that in addition
+to the enclosing `self`, any instance variables of the enclosing
+scope are not directly available. This may cause some surprises
+but is easy to overcome.
+```ruby
+@value = 10
+GrassGis.session configuration do
+  puts @value # nil!
+end
+```
+A possible workaround is to assign instance variables that we need
+in the session to local variables:
+```ruby
+@value = 10
+value = @value
+GrassGis.session configuration do
+  puts value # 10
+end
+```
+To avoid defining these variables you can pass a `:locals` Hash
+in the configuration to define values that you need to access
+in the session (but you won't be able to assign to them, because
+they're not local variables!)
+```ruby
+@value = 10
+GrassGis.session configuration.merge(locals: { value: @value }) do
+  puts value # 10
+  value = 11 # don't do this: you're creating a local in the session
+end
+```
+A different approach is prevent the session block from using a special
+`self` by defining a parameter to the block. This parameter will have
+the value of a `GrassGis::Context` which you'll need to explicitly use
+to execute any commands:
+```ruby
+@value = 10
+GrassGis.session configuration do |grass|
+  puts @value # 10
+  grass.g.region res: 10 # now you need to use the object to issue commands
+end
+```
+The GRASS command `g.mapset` should not be used to change
+the current mapset, use the `change_mapset` method in a GrassGis
+session instead:
+```ruby
+GrassGis.session configuration do
+  # Get the name of the current mapset
+  g.mapsets '-p'
+  mapset = output.lines.last.split.first.inspect
+  # Copy 'some_map' raster map to PERMANENT
+  change_mapset 'PERMANENT'
+  g.copy rast: "some_map@#{original_mapset},some_map"
+  # Get back to our mapset
+  change_mapset mapset
+end
+```
+#### Invalid commands
+Currently the generation of GRASS commands inside a session is
+implemented in a very simple way which allows to generate any command
+name even if it is invalid or does not exist. This has the advantage
+of supporting any version of GRASS, but doesn't allow for early
+detection of invalid commands (e.g. due to typos) or invalid command
+parameters.
+```ruby
+GrassGis.session configuration do |grass|
+  g.region res: 10     # Oops (runtime error)
+  g.anything.goes.run  # another runtime error
+end
+```
+If the command generated does not exist a runtime `ENOENT` exception will
+occur.
+If the command exists, then if parameters are not valid, the command
+will execute but will return an error status. This will be handled
+as explained above.
+## Helper methods
+When writing a non-trivial program you'll probably
+find you want to define methods to avoid unnecessary repetition.
+Let's see how you can call methods from your session and be
+able to execute GRASS commands from the method in the context of the session.
+Inside a session, `self` refers to an object of class
+`GrassGis::Context` which represents the current GRASS session.
+You can invoke grass commands directly on this object, so, if you pass
+this object around you can use it to execute GRASS commands:
+```ruby
+def helper_method(grass)
+  # ...
+end
+GrassGis.session configuration do
+  helper_method self
+end
+```
+In the helper method you can use the grass object like this;
+```ruby
+def helper_method(grass)
+  # change the current region resolution
+  grass.g.region res: 10
+end
+```
+To avoid having to prepend each command with `grass.` you can
+use the `session` method like this:
+```ruby
+def helper_method(grass)
+  grass.session do
+    g.region res: 10
+    g.region '-p'
+    puts output
+  end
+end
+```
+An alternative is to use a Ruby module and extend the session with it:
+```ruby
+module Helpers
+  def helper_method
+    g.region res: 10
+    g.region '-p'
+    puts output
+  end
+end
+GrassGis.session configuration do
+  extend Helpers
+  helper_method
+end
+```
+### Examples
+Note: the functionality of these examples is now provided by
+a Tools module which is included by default in GrassGis sessions.
+#### 1. Map existence
+Helper methods to check for the existence of maps.
+Often we may want to know if a map exists. Next methods can be used to
+check for it.
+```ruby
+def map_exists?(grass, type, map)
+  grass.g.list type
+  maps = grass.output.split
+  maps.include?(map)
+end
+def raster_exists?(grass, map)
+  map_exists? grass, 'rast', map
+end
+def vector_exists?(grass, map)
+  map_exists? grass, 'vect', map
+end
+```
+We can use these methods like this:
+```ruby
+GrassGis.session configuration do
+  unless raster_exists?(self, 'product')
+    r.mapcalc "product = factor1*factor2"
+  end
+end
+```
+#### 2. Information as Hashes
+Following methods show how to obtain information about a raster map
+and the current region as a Hash:
+```ruby
+def raster_info(grass, map)
+  grass.r.info '-g', map
+  shell_to_hash grass
+end
+def region_info(grass)
+  grass.g.region '-m'
+  shell_to_hash grass
+end
+def shell_to_hash(grass)
+  Hash[grass.output.lines.map{|l| l.strip.split('=')}]
+end
+# Now, for example, we can easily obtain the resolution of a raster:
+def raster_res(grass, map)
+  info = raster_info(grass, map)
+  info.values_at('ewres', 'nsres').map(&:to_i)
+end
+def region_res(grass)
+  info = region_info(grass)
+  info.values_at('ewres', 'nsres').map(&:to_i)
+end
+```
+#### 3. Average angle
+Let's assume we have a raster map `aspect` which is
+a direction angle (i.e. a cyclic value from 0 to 360).
+Now imagine that we need to compute a coarser raster grid with
+average values per cell. We can't just resample the angle
+(we want the average of 359 and 1 be 0, not 180);
+we would need an unitary vector or complex number to take averages.
+The next method will perform the average correctly using
+auxiliary raster maps for two cartesian components (that represent
+the angle as a vector).
+```ruby
+def resample_average_angle(grass, options = {})
+  input_raster = options[:input]
+  raise "Raster #{input_raster} not found" unless raster_exists?(grass, input_raster)
+  input_res = raster_res(grass, input_raster)
+  if options[:output_res]
+    output_res = options[:output_res]
+    unless output_res.is_a?(Array)
+      output_res = [output_res, output_res]
+    end
+  else
+    output_res = region_res(grass)
+  end
+  output_raster = options[:output]
+  grass.session do
+    unless raster_exists?(self, "#{input_raster}_sin")
+      g.region ewres: input_res[0], nsres: input_res[1]
+      r.mapcalc "#{input_raster}_sin = sin(#{input_raster})"
+    end
+    unless raster_exists?(self, "#{input_raster}_cos")
+      g.region ewres: input_res[0], nsres: input_res[1]
+      r.mapcalc "#{input_raster}_cos = cos(#{input_raster})"
+    end
+    g.region ewres: output_res[0], nsres: output_res[1]
+    r.resamp.stats input: "#{input_raster}_cos", output: "#{output_raster}_cos"
+    r.resamp.stats input: "#{input_raster}_sin", output: "#{output_raster}_sin"
+    r.mapcalc "#{output_raster} = atan(#{output_raster}_cos,#{output_raster}_sin)"
+    r.colors map: ouput_raster, raster: input_raster
+    g.remove '-f', type: 'raster', name: ["#{output_raster}_cos", "#{output_raster}_sin"]
+    g.remove -f type=raster name=aspect_sin@landscape,aspect_cos@landscape
+  end
+end
+```
+Now, to resample a (cyclic angular) map `aspect_hires` to a lower resolution 10:
+```ruby
+GrassGis.session configuration do
+  resamp_average self,
+    input: 'aspect_hires',
+    output: 'aspect_lowres', output_res: 10
+  end
+end
+```
+## Roadmap
+* Change Module to define explicitly available GRASS commands instead of
+  accepting anything with `method_missing`. Declare commands with permitted
+  arguments and options, etc.
+* Add some session helpers:
+  - Method to clean GRASS temporaries ($GISBASE/etc/clean_temp), or do
+    it automatically when disposing the session.
+  - Methods that execute operations in a GRASS-version independent
+    manner (higher level, version independent interface to modules).
+## Contributing
+1. Fork it ( https://github.com/[my-github-username]/grassgis/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request