grassgis 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 299ce1dcdebe07da42c2207549ab9fdeacc9cb2b
-  data.tar.gz: 206df84d976c27567c4a5fe7fc3dd1949d5f92d6
+  metadata.gz: c0fd89fb91b60e769c7f1a29f2a683525a162480
+  data.tar.gz: ab57d26849db6fdbada05be7803b3c67df94f0ff
 SHA512:
-  metadata.gz: be5e141c19ebc4880733387277d61a47fca4993ba1b74e57de8461c52b93965d83d3380864acc3aa37ac9886c53674d463b098ee0b193f2b7742c843c49a845d
-  data.tar.gz: f9d883babf14d38607cc7430c964cfd10d017a246256b135ef6a26a6ba65db142481c94700744d975c081047506305aca059050870bb164355e8fc744ece2b29
+  metadata.gz: b35d3856bc5b77a5fd8eb104db5cddb113140841e59b840bfa99dc74625fa4cc3e97efbce586536b8005756b5ef4d894121d35f5b092258620c702d4e78c12fd
+  data.tar.gz: 4cd8093c0acb3c25556e1cefc01f0642c9220f76a7e17c3fe7c2b60a034904519d821b090bfc9ecb9f80196721bb8a87a6a5707dda20f3533115eb3cf65c064a

data/README.md

@@ -24,26 +24,361 @@ Or install it yourself as:
 This library can prepare environments to execute GRASS commands
 from Ruby scripts.
 
-Example:
+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/Cellar/grass-70/7.0.0/grass-7.0.0',
-  location: 'world'
+  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](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
-  r.resamp.stats '-n', input: "map1@mapset1", output: "map2"
   g.list 'vect'
-  puts output # output of last command
+  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
+```
+
+## Helper methods
+
+When writing a non-trivial program you'll probably
+find you want to define methods to avoid innecesary 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 aroung 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
+```
+
+### Options
+
+TODO: Explain options for error handling, echoing, logging, ...
+
+### 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.
+
 ## Roadmap
 
-* Write more documentation with examples.
+* Methods to create new locations and mapsets.
+* 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.
@@ -68,28 +403,7 @@ Example of intended recipe syntax:
 
 ```ruby
 recipe :resamp_average do |options = {}|
-  input_raster = options[:input]
-  input_res = options[:input_res] # TODO: extract from input_rater info
-  output_raster = options[:output]
-  output_res = options[:output_res] # TODO: extract from output_raster info
-  if options[:direction]
-    unless raster_exists?("#{input_raster}_sin")
-      g.region res: input_res
-      r.mapcalc "#{input_raster}_sin = sin(#{input_raster})"
-    end
-    unless raster_exists?("#{input_raster}_cos")
-      g.region res: input_res
-      r.mapcalc "#{input_raster}_cos = cos(#{input_raster})"
-    end
-    g.region res: output_res
-    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)"
-    g.remove rast: ["#{output_raster}_cos", "#{output_raster}_sin"]
-  else
-    g.region res: output_res
-    r.resamp.stats input: input_raster, output: output_raster
-  end
+  # ...
 end
 
 recipe :generate_working_dem do |...|

data/lib/grassgis/context.rb

@@ -161,7 +161,11 @@ module GrassGis
     #     end
     #
     def session(&blk)
-      instance_eval(&blk)
+      if blk.arity == 1
+        blk.call self
+      else
+        instance_eval &blk
+      end
     end
 
     def dry?
@@ -179,7 +183,7 @@ module GrassGis
         log log_file, cmd.to_s(with_input: true)
       end
       unless dry?
-        cmd.run error_output: :reparate
+        cmd.run error_output: :separate
       end
       if cmd.output
         puts cmd.output if @config[:echo] == :output
@@ -278,7 +282,9 @@ module GrassGis
   # :errors to define the behaviour when a GRASS command fails:
   # * :raise is the default and raises on errors
   # * :console shows standar error output of commands
-  # * :quiet error output is retained but not shown
+  # * :quiet error output is retained but not shown; no exceptions are
+  #   raise except when the command cannot be executed (e.g. when
+  #   the command name is ill-formed)
   #
   # If :errors is anything other than :raise, it is up to the user
   # to check each command for errors. With the :console option
@@ -297,6 +303,12 @@ module GrassGis
   # * :output show the output of commands too
   # * false don't echo anything
   #
+  # Testing/debugging options:
+  #
+  # * :dry prevents actual execution of any command
+  # * errors: :silent omits raising exceptions (as :quiet) even when
+  #   a command cannot be executed (usually because of an invalid command name)
+  #
   def self.session(config, &blk)
     context = Context.new(config)
     context.allocate
@@ -326,10 +338,13 @@ module GrassGis
 
   def self.error(command, error_mode = :raise)
     if command
-      if error_mode == :raise
-        if command.error
-          raise command.error
-        elsif (command.status_value && command.status_value != 0)
+      if command.error # :silent mode for testing/debugging?
+        # Errors that prevent command execution
+        # (usually ENOENT because the command does not exist)
+        # are always raised
+        raise command.error unless error_mode == :silent
+      elsif error_mode == :raise
+        if (command.status_value && command.status_value != 0)
           raise Error.new, error_info(command)
         end
       end

data/lib/grassgis/version.rb

@@ -1,3 +1,3 @@
 module GrassGis
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grassgis
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Javier Goizueta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-23 00:00:00.000000000 Z
+date: 2015-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sys_cmd
@@ -105,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Support for scripting GRASS GIS in Ruby