[GRASS-SVN] r71819 - grass-addons/grass7/raster/r.clip

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2017-11-24 07:46:40 -0800 (Fri, 24 Nov 2017)
New Revision: 71819

Modified:
   grass-addons/grass7/raster/r.clip/r.clip.html
Log:
r.clip: notes and examples explaining details

Modified: grass-addons/grass7/raster/r.clip/r.clip.html
===================================================================
--- grass-addons/grass7/raster/r.clip/r.clip.html	2017-11-24 04:18:25 UTC (rev 71818)
+++ grass-addons/grass7/raster/r.clip/r.clip.html	2017-11-24 15:46:40 UTC (rev 71819)
@@ -1,8 +1,10 @@
 <h2>DESCRIPTION</h2>
 
-The module extracts portion of the input raster map according to the
-current computational region. The areas outside of the computational
+The module extracts portion of the <b>input</b> raster map according to
+the current computational region. The areas outside of the computational
 region are clipped and only the inner part is kept.
+The <b>input</b> raster map is left intact and a new (clipped)
+<b>output</b> raster map is created in the process.
 
 <p>
 By default the cell size and the cell alignment of the original raster
@@ -21,11 +23,161 @@
 If mask (<em><a href="r.mask.html">r.mask</a></em>) is active, it is
 respected and the output raster map will contain NULL (no data) values
 according to the mask.
+Otherwise, values in the <b>input</b> raster map are simply transfered
+to the <b>output</b> raster map.
 
 <p>
 The color table of the output raster map is set according to the
 input raster map, so that the colors in both raster maps will match.
 
+<h2>NOTES</h2>
+
+<ul>
+
+<li>
+In GRASS GIS, clipping of rasters is usually not needed because
+modules respect the current computational region and clipping
+(with possible resampling) is done automatically.
+
+<li>
+If the user needs to clip raster map according to another raster map or
+according to a vector map,
+the <em><a href="g.region.html">g.region</a></em> should be used first
+before running the <em>r.clip</em> module.
+
+<li>
+The extent of the resulting map might be slightly different based on how
+the cells of the input raster align with the cells of the computational
+region. The mechanism for aligning in the background is the one used in
+<em><a href="g.region.html">g.region</a></em>. If exact match is
+desired, user is advised to resolve the cell alignment ahead using
+<em><a href="g.region.html">g.region</a></em> and then use
+<em>r.clip</em> with the <b>-r</b> flag.
+
+
+</ul>
+
+<h2>EXAMPLES</h2>
+
+The following examples are using the full North Carolina sample
+location.
+
+<h3>Clip according to a raster map</h3>
+
+First we set the computational region to match the raster map called
+<em>elev_lid792_1m</em> which we want to use for clipping:
+
+<div class="code"><pre>
+g.region raster=elev_lid792_1m
+</pre></div>
+
+Now, the following will clip raster map called <em>elevation</em>
+according to the extent of <em>elev_lid792_1m</em> raster map creating
+a new raster map called <em>elevation_clipped</em>:
+
+<div class="code"><pre>
+r.clip input=elevation output=elevation_clipped
+</pre></div>
+
+<h3>Clip and then compare the resolutions</h3>
+
+The following example clips (crops) raster map called <em>elevation</em>
+according to the current region resulting in a new raster map called
+<em>clipped_elevation</em>.
+The computational region will be set match raster map called
+<em>elev_lid792_1m</em> since this the extent we want to work with
+in this example.
+
+<p>
+First we set the computational region to match a raster map called
+<em>elev_lid792_1m</em>:
+
+<div class="code"><pre>
+g.region raster=elev_lid792_1m
+</pre></div>
+
+This is the computational region we want t
+Now we check the new region using:
+
+<div class="code"><pre>
+g.region -g
+</pre></div>
+
+In the output, we can see extent, resolution in both directions,
+and number of rows and columns:
+
+<pre>
+...
+n=220750
+s=220000
+w=638300
+e=639000
+nsres=1
+ewres=1
+rows=750
+cols=700
+cells=525000
+...
+</pre>
+
+Now we perform the clipping:
+
+<div class="code"><pre>
+r.clip input=elevation output=clipped_elevation
+</pre></div>
+
+Finally, we check the size of the new raster map using:
+
+<div class="code"><pre>
+r.info map=clipped_elevation -g
+</pre></div>
+
+In the output, we can see that the extent is the same as the
+computational region in this case while the resolution and number of
+cells is different:
+
+<pre>
+...
+north=220750
+south=220000
+east=639000
+west=638300
+nsres=10
+ewres=10
+rows=75
+cols=70
+cells=5250
+...
+</pre>
+
+The reason for this is that the <em>elevation</em> map was not
+resampled, instead the cell values and positions were preserved.
+The number of cells depends on the resolution which was derived from
+the original <em>elevation</em> map. To see it, we can use the
+following:
+
+<div class="code"><pre>
+r.info map=elevation -g
+</pre></div>
+
+The output shows the resolution used for the new
+<em>clipped_elevation</em> as well as much higher number of cells and
+larger extent of the original map:
+
+<pre>
+...
+north=228500
+south=215000
+east=645000
+west=630000
+nsres=10
+ewres=10
+rows=1350
+cols=1500
+cells=2025000
+...
+</pre>
+
 <h2>SEE ALSO</h2>
 
 <a href="g.region.html">g.region</a>,