wxGUI/rdigit: fix small error when polygon is not finished while saving; add manual page with instructions and screenshots

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@71803 15284696-431f-4ddb-bdfa-cd5b030d7da7

gui/wxpython/docs/wxGUI.components.html

@@ -30,6 +30,7 @@ List of available <em><a href="wxGUI.html">wxGUI</a></em> components:
      available also as a command line tool <em><a href="g.gui.tplot.html">g.gui.tplot</a></em></li>
   <li><a href="wxGUI.vdigit.html">Vector Digitizer</a>,
      available also as a command line tool <em><a href="g.gui.vdigit.html">g.gui.vdigit</a></em></li>
+  <li><a href="wxGUI.rdigit.html">Raster Digitizer</a></li>
   <li><a href="wxGUI.vnet.html">Vector Network Analysis Tool</a></li>
 </ul>
 

gui/wxpython/docs/wxGUI.rdigit.html

@@ -0,0 +1,79 @@
+<!-- meta page description: wxGUI Raster Digitizer -->
+<!-- meta page index: wxGUI -->
+
+<h2>DESCRIPTION</h2>
+
+<b>Raster Digitizer</b> is a simple tool to quickly
+to draw lines, areas, and circles and save these features in a raster map.
+It is accessible from Map Display toolbar (from the combo box on the right).
+
+<p>
+<em>Raster Digitizer</em> currently allows you to:
+
+<ul>
+  <li>draw polygons, lines and points</li>
+  <li>set category value of the feature you are drawing</li>
+  <li>set feature width (width of currently digitized line or diameter of a digitized point in map units)</li>
+  <li>create a new raster from scratch or from an already existing raster</li>
+  <li>undo edits and save edits before leaving the digitizer</li>
+</ul>
+
+<p>
+The typical workflow includes these steps:
+
+<ol>
+  <li>Set computational region as needed.</li>
+  <li>Switch to Raster Digitizer and select a map to create.
+      Select either a new raster or create a new raster from existing raster,
+  also select raster type (CELL, FCELL, DCELL)</li>
+  <li>Specify category value and width <em>before</em> drawing a feature</li>
+  <li>Specify digitizing tool (area, line, point)</li>
+  <li>Start digitizing and when you want to finish area or line, <em>use right click</em></li>
+  <li>Change color of temporary overlay depending on your needs</li>
+  <li>Set different category and repeat</li>
+  <li>At any point you can use <em>Undo</em> or <em>Save</em></li>
+  <li>If existing raster is used for the new raster, digitized areas will respect
+  the color table, but you can always set different color table.</li>
+</ol>
+
+<h2>NOTES</h2>
+Raster Digitizer respects computational region including the currently set resolution.
+
+<h2>EXAMPLES</h2>
+In the following figures we start with elev_lid792_1m raster map in North carolina sample dataset
+and digitize two buildings, one rectangular and one with circular footprint.
+Both buildings have the roof level at 130 m. We set the width when digitizing the point to 50 meters
+which results in the building having 50 m in diameter.
+When we are done with digitizing, we save the result and explore cast shadows of the buildings with
+<a href="r.sun.html">r.sun</a> module:
+
+<div class="code"><pre>
+g.region raster=elev_lid792_1m
+# now create elev_edited raster by digitizing and save
+r.slope.aspect elevation=elev_edited slope=elev_slope aspect=elev_aspect
+r.sun elevation=elev_edited aspect=elev_aspect slope=elev_slope beam_rad=beam day=172 time=6
+</pre></div>
+
+<div align="center">
+<a href="wxGUI_rdigit_step1.png"><img src="wxGUI_rdigit_step1.png" alt="Raster digitizer example step 1" width="400" height="310"></a>
+<a href="wxGUI_rdigit_step2.png"><img src="wxGUI_rdigit_step2.png" alt="Raster digitizer example step 2" width="400" height="310"></a>
+<a href="wxGUI_rdigit_step3.png"><img src="wxGUI_rdigit_step3.png" alt="Raster digitizer example step 3" width="400" height="310"></a>
+<a href="wxGUI_rdigit_step4.png"><img src="wxGUI_rdigit_step4.png" alt="Raster digitizer example step 4" width="400" height="310"></a>
+<a href="wxGUI_rdigit_step5.png"><img src="wxGUI_rdigit_step5.png" alt="Raster digitizer example step 5" width="400" height="310"></a>
+<br>
+<i>Figure: Steps to digitize new buildings on elev_lid792_1m raster map.</i>
+</div>
+
+<h2>SEE ALSO</h2>
+
+<em>
+  <a href="wxGUI.html">wxGUI</a><br>
+  <a href="wxGUI.components.html">wxGUI components</a><br>
+  <a href="r.in.poly.html">r.in.poly</a> (backend of digitizer)
+</em>
+
+<h2>AUTHOR</h2>
+Anna Petrasova, NCSU GeoForALL Laboratory
+
+<p>
+<i>$Date$</i>

gui/wxpython/mapdisp/frame.py

@@ -1503,7 +1503,7 @@ class MapFrame(SingleMapFrame):
         self.rdigit = RDigitController(self._giface,
                                        mapWindow=self.GetMapWindow())
         self.toolbars['rdigit'] = RDigitToolbar(
-            parent=self, controller=self.rdigit,
+            parent=self, giface=self._giface, controller=self.rdigit,
             toolSwitcher=self._toolSwitcher)
         # connect signals
         self.rdigit.newRasterCreated.connect(

gui/wxpython/rdigit/controller.py

@@ -304,6 +304,8 @@ class RDigitController(wx.EvtHandler):
             _("Save raster map changes"),
             wx.YES_NO)
         if dlg.ShowModal() == wx.ID_YES:
+            if self._drawing:
+                self._finish()
             self._thread.Run(callable=self._exportRaster,
                              ondone=lambda event: self._updateAndQuit())
         else:
@@ -311,6 +313,9 @@ class RDigitController(wx.EvtHandler):
 
     def Save(self):
         """Saves current edits to a raster map"""
+        if self._drawing:
+            self._finish()
+
         self._thread.Run(callable=self._exportRaster,
                          ondone=lambda event: self._update())
 
@@ -468,9 +473,6 @@ class RDigitController(wx.EvtHandler):
             return
         self._running = True
 
-        if self._drawing:
-            self._finish()
-
         if len(self._all) < 1:
             new = self._editedRaster
             if '@' in self._editedRaster:

gui/wxpython/rdigit/toolbars.py

@@ -31,6 +31,7 @@ rdigitIcons = {'area': MetaIcon(img='polygon-create',
                                  label=_('Digitize point')),
                'save': MetaIcon(img='save', label=_("Save raster map")),
                'undo': MetaIcon(img='undo', label=_("Undo")),
+               'help': MetaIcon(img='help', label=_("Raster Digitizer manual")),
                'quit': MetaIcon(img='quit', label=_("Quit raster digitizer"))}
 
 
@@ -38,11 +39,12 @@ class RDigitToolbar(BaseToolbar):
     """RDigit toolbar
     """
 
-    def __init__(self, parent, controller, toolSwitcher):
+    def __init__(self, parent, giface, controller, toolSwitcher):
         """RDigit toolbar constructor
         """
         BaseToolbar.__init__(self, parent, toolSwitcher)
         self._controller = controller
+        self._giface = giface
         self.InitToolbar(self._toolbarData())
 
         self._mapSelectionComboId = wx.NewId()
@@ -126,6 +128,8 @@ class RDigitToolbar(BaseToolbar):
               lambda event: self._controller.Undo()),
              ('save', rdigitIcons['save'],
               lambda event: self._controller.Save()),
+             ('help', rdigitIcons['help'],
+              lambda event: self._giface.Help('wxGUI.rdigit')),
              ('quit', rdigitIcons['quit'],
               lambda event: self._controller.Stop())))