Add documentation including an image and a notebook to generate the i…

…mage

vector/v.fill.holes/examples.ipynb

@@ -0,0 +1,151 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Graphics for Description of r.series\n",
+    "\n",
+    "Requires _pngquant_, _optipng_ and ImageMagic _mogrify_."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "from IPython.display import Image\n",
+    "\n",
+    "import grass.script as gs\n",
+    "import grass.jupyter as gj"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gj.init(\"~/grassdata/nc_spm_08_grass7/user1\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!v.extract --overwrite input=lakes where=\"FTYPE != 'ROCK/ISLAND'\" output=lakes_only --qq"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!g.region n=243500 s=242800 w=647099 e=648152"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot = gj.Map(use_region=True, width=700)\n",
+    "plot.d_background(color=\"white\")\n",
+    "plot.d_vect(map=\"lakes_only\", legend_label=\"Original\")\n",
+    "plot.d_legend_vect(flags=\"b\", at=(60,10))\n",
+    "plot.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!v.fill.holes input=lakes_only output=lakes_filled"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot = gj.Map(use_region=True, width=700)\n",
+    "plot.d_background(color=\"white\")\n",
+    "plot.d_vect(map=\"lakes_filled\", legend_label=\"Filled\")\n",
+    "plot.d_legend_vect(flags=\"b\", at=(60,10))\n",
+    "plot.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!v.dissolve input=lakes_filled column=NAME output=lakes_dissolved --qq"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot = gj.Map(use_region=True, width=700)\n",
+    "plot.d_background(color=\"white\")\n",
+    "plot.d_vect(map=\"lakes_dissolved\", legend_label=\"Dissolved\")\n",
+    "plot.d_legend_vect(flags=\"b\", at=(60,10))\n",
+    "plot.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot = gj.Map(use_region=True, width=700)\n",
+    "plot.d_background(color=\"white\")\n",
+    "plot.d_vect(map=\"lakes_filled\", color=\"none\", legend_label=\"Filled\")\n",
+    "plot.d_vect(map=\"lakes_only\", color=\"#33BBEE\", fill_color=\"none\", width=2, legend_label=\"Original\")\n",
+    "plot.d_legend_vect(flags=\"b\", at=(60,15))\n",
+    "filename = \"v_fill_holes.png\"\n",
+    "plot.save(filename)\n",
+    "!mogrify -trim {filename}\n",
+    "!pngquant --ext \".png\" -f {filename}\n",
+    "!optipng -o7 {filename}\n",
+    "Image(filename)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

vector/v.fill.holes/v.fill.holes.html

@@ -1,21 +1,46 @@
 <h2>DESCRIPTION</h2>
 
-<em>v.fill.holes</em>
+<em>v.fill.holes</em> fills empty spaces inside areas (closed boundaries with centroids).
+Preseves only areas with centroids while areas without centroids
+which typically represent holes are removed.
+
 
 <h2>EXAMPLE</h2>
 
- (North Carolina sample dataset):
+The <em>lakes</em> vector map in the North Carolina sample dataset
+contains islands inside lakes. To demonstarate <em>v.fill.holes</em>
+we will first remove the islands and then we will fill the holes
+created in the lakes to get the whole perimeter of the lakes
+including islands.
+
+Remove the islands (results in holes):
 
 <div class="code"><pre>
-v.fill.holes input= output=
+v.extract input=lakes where="FTYPE != 'ROCK/ISLAND'" output=lakes_only
 </pre></div>
 
+Remove the holes:
+
+<div class="code"><pre>
+v.fill.holes input=lakes_only output=lakes_filled
+</pre></div>
+
+<div align="center" style="margin: 10px">
+    <a href="v_fill_holes.png">
+    <img src="v_fill_holes.png" width="600" height="600" alt="Lake without holes overlapping with the lines marking the original" border="0">
+    </a><br>
+    <i>
+      Figure: The filled lake (blue) and borders of the original lakes with islands removed (light blue)
+    </i>
+</div>
+
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="v.clean.html">v.clean</a>,
+    <a href="v.dissolve.html">v.dissolve</a>,
+    <a href="v.clean.html">v.clean</a>
 </em>
 
 <h2>AUTHOR</h2>
 
-Vaclav Petras
+Vaclav Petras, <a href="http://geospatial.ncsu.edu/">NCSU Center for Geospatial Analytics, GeoForAll Lab</a>