geom part 3 - wip

Author: Atma Mani

guide/15-working-with-geometries/part3_spatial_operations_on_geometries.ipynb

@@ -4,24 +4,24 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Guide to arcgis.geometry module (Part 2)"
+    "# Part 3: Spatial operations on geometries"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "toc": true
-   },
+   "metadata": {},
    "source": [
-    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
-    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Spatial-Operations\" data-toc-modified-id=\"Spatial-Operations-1\">Spatial Operations</a></span><ul class=\"toc-item\"><li><span><a href=\"#a.-OOP-Pattern\" data-toc-modified-id=\"a.-OOP-Pattern-1.1\">a. OOP Pattern</a></span><ul class=\"toc-item\"><li><span><a href=\"#a1.-Union\" data-toc-modified-id=\"a1.-Union-1.1.1\">a1. Union</a></span></li><li><span><a href=\"#a2.-Difference\" data-toc-modified-id=\"a2.-Difference-1.1.2\">a2. Difference</a></span></li><li><span><a href=\"#a3.-Symmetric-difference\" data-toc-modified-id=\"a3.-Symmetric-difference-1.1.3\">a3. Symmetric difference</a></span></li><li><span><a href=\"#a4.-intersect()-V.S.-overlaps()\" data-toc-modified-id=\"a4.-intersect()-V.S.-overlaps()-1.1.4\">a4. intersect() V.S. overlaps()</a></span></li><li><span><a href=\"#a5.-Equals\" data-toc-modified-id=\"a5.-Equals-1.1.5\">a5. Equals</a></span></li><li><span><a href=\"#a6.-generalize()-V.S.-buffer()\" data-toc-modified-id=\"a6.-generalize()-V.S.-buffer()-1.1.6\">a6. generalize() V.S. buffer()</a></span></li><li><span><a href=\"#a7.-Find-the-nearest-point\" data-toc-modified-id=\"a7.-Find-the-nearest-point-1.1.7\">a7. Find the nearest point</a></span></li><li><span><a href=\"#a8.-contains()\" data-toc-modified-id=\"a8.-contains()-1.1.8\">a8. contains()</a></span></li><li><span><a href=\"#a9.-Clip-a-geometry-object\" data-toc-modified-id=\"a9.-Clip-a-geometry-object-1.1.9\">a9. Clip a geometry object</a></span></li></ul></li><li><span><a href=\"#b.-Spatial-operations-called-from-arcgis.geometry.functions\" data-toc-modified-id=\"b.-Spatial-operations-called-from-arcgis.geometry.functions-1.2\">b. Spatial operations called from <code>arcgis.geometry.functions</code></a></span><ul class=\"toc-item\"><li><span><a href=\"#b1.-Union\" data-toc-modified-id=\"b1.-Union-1.2.1\">b1. Union</a></span></li><li><span><a href=\"#b2.-intersect()-V.S.-overlaps()\" data-toc-modified-id=\"b2.-intersect()-V.S.-overlaps()-1.2.2\">b2. intersect() V.S. overlaps()</a></span></li><li><span><a href=\"#b3.-Difference\" data-toc-modified-id=\"b3.-Difference-1.2.3\">b3. Difference</a></span></li><li><span><a href=\"#b4.-Symmetric-difference\" data-toc-modified-id=\"b4.-Symmetric-difference-1.2.4\">b4. Symmetric difference</a></span></li><li><span><a href=\"#b5.-Equals\" data-toc-modified-id=\"b5.-Equals-1.2.5\">b5. Equals</a></span></li><li><span><a href=\"#b6.-generalize()-V.S.-buffer()\" data-toc-modified-id=\"b6.-generalize()-V.S.-buffer()-1.2.6\">b6. generalize() V.S. buffer()</a></span></li><li><span><a href=\"#b7.-Distance\" data-toc-modified-id=\"b7.-Distance-1.2.7\">b7. Distance</a></span></li><li><span><a href=\"#b8.-Determine-the-spatial-relation-between-two-geometries\" data-toc-modified-id=\"b8.-Determine-the-spatial-relation-between-two-geometries-1.2.8\">b8. Determine the spatial relation between two geometries</a></span></li><li><span><a href=\"#b9.-Clip-a-geometry-object\" data-toc-modified-id=\"b9.-Clip-a-geometry-object-1.2.9\">b9. Clip a geometry object</a></span></li></ul></li></ul></li><li><span><a href=\"#Conclusions\" data-toc-modified-id=\"Conclusions-2\">Conclusions</a></span></li></ul></div>"
+    "Previously, in <a href=\"./part1_introduction_what_is_geometry.ipynb\">Part 1</a> of this guide series to `arcgis.geometry` module, you have seen the introduction to the module and some foundational concepts. In <a href=\"part2_working_with_geometries.ipynb\">Part 2</a>, you learned how to create geometry objects, their properties, and how to work with one, including its interactions with map widgets.  In this part, let's continue to explore  spatial operations of geometry objects using two different usage patterns."
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "toc": true
+   },
    "source": [
-    "Previously, in <a href=\"./guide_to_geometry_part1.ipynb\">Part 1</a> of this guide series to `arcgis.geometry` module, you have seen the introduction to the module, how to create geometry objects, what are the basic properties, and how to work with one, including its interactions with map widgets. Let's now continue to explore the spatial operations of geometry objects, and how to process through geometry services."
+    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
+    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Spatial-Operations\" data-toc-modified-id=\"Spatial-Operations-1\">Spatial Operations</a></span><ul class=\"toc-item\"><li><span><a href=\"#Two-patterns-of-applying-spatial-operations\" data-toc-modified-id=\"Two-patterns-of-applying-spatial-operations-1.1\">Two patterns of applying spatial operations</a></span></li><li><span><a href=\"#a.-OOP-Pattern\" data-toc-modified-id=\"a.-OOP-Pattern-1.2\">a. OOP Pattern</a></span><ul class=\"toc-item\"><li><span><a href=\"#a1.-Union\" data-toc-modified-id=\"a1.-Union-1.2.1\">a1. Union</a></span></li><li><span><a href=\"#a2.-Difference\" data-toc-modified-id=\"a2.-Difference-1.2.2\">a2. Difference</a></span></li><li><span><a href=\"#a3.-Symmetric-difference\" data-toc-modified-id=\"a3.-Symmetric-difference-1.2.3\">a3. Symmetric difference</a></span></li><li><span><a href=\"#a4.-intersect()-V.S.-overlaps()\" data-toc-modified-id=\"a4.-intersect()-V.S.-overlaps()-1.2.4\">a4. intersect() V.S. overlaps()</a></span></li><li><span><a href=\"#a5.-Equals\" data-toc-modified-id=\"a5.-Equals-1.2.5\">a5. Equals</a></span></li><li><span><a href=\"#a6.-generalize()-V.S.-buffer()\" data-toc-modified-id=\"a6.-generalize()-V.S.-buffer()-1.2.6\">a6. generalize() V.S. buffer()</a></span></li><li><span><a href=\"#a7.-Find-the-nearest-point\" data-toc-modified-id=\"a7.-Find-the-nearest-point-1.2.7\">a7. Find the nearest point</a></span></li><li><span><a href=\"#a8.-contains()\" data-toc-modified-id=\"a8.-contains()-1.2.8\">a8. contains()</a></span></li><li><span><a href=\"#a9.-Clip-a-geometry-object\" data-toc-modified-id=\"a9.-Clip-a-geometry-object-1.2.9\">a9. Clip a geometry object</a></span></li></ul></li><li><span><a href=\"#b.-Spatial-operations-called-from-arcgis.geometry.functions\" data-toc-modified-id=\"b.-Spatial-operations-called-from-arcgis.geometry.functions-1.3\">b. Spatial operations called from <code>arcgis.geometry.functions</code></a></span><ul class=\"toc-item\"><li><span><a href=\"#b1.-Union\" data-toc-modified-id=\"b1.-Union-1.3.1\">b1. Union</a></span></li><li><span><a href=\"#b2.-intersect()-V.S.-overlaps()\" data-toc-modified-id=\"b2.-intersect()-V.S.-overlaps()-1.3.2\">b2. intersect() V.S. overlaps()</a></span></li><li><span><a href=\"#b3.-Difference\" data-toc-modified-id=\"b3.-Difference-1.3.3\">b3. Difference</a></span></li><li><span><a href=\"#b4.-Symmetric-difference\" data-toc-modified-id=\"b4.-Symmetric-difference-1.3.4\">b4. Symmetric difference</a></span></li><li><span><a href=\"#b5.-Equals\" data-toc-modified-id=\"b5.-Equals-1.3.5\">b5. Equals</a></span></li><li><span><a href=\"#b6.-generalize()-V.S.-buffer()\" data-toc-modified-id=\"b6.-generalize()-V.S.-buffer()-1.3.6\">b6. generalize() V.S. buffer()</a></span></li><li><span><a href=\"#b7.-Distance\" data-toc-modified-id=\"b7.-Distance-1.3.7\">b7. Distance</a></span></li><li><span><a href=\"#b8.-Determine-the-spatial-relation-between-two-geometries\" data-toc-modified-id=\"b8.-Determine-the-spatial-relation-between-two-geometries-1.3.8\">b8. Determine the spatial relation between two geometries</a></span></li><li><span><a href=\"#b9.-Clip-a-geometry-object\" data-toc-modified-id=\"b9.-Clip-a-geometry-object-1.3.9\">b9. Clip a geometry object</a></span></li></ul></li></ul></li><li><span><a href=\"#Conclusions\" data-toc-modified-id=\"Conclusions-2\">Conclusions</a></span></li></ul></div>"
    ]
   },
   {
@@ -34,9 +34,16 @@
     "\n",
     "Chained operations are even more powerful. For example, in order to identify food deserts within an urban area, the analysis might begin by performing a `union` operation to the service areas of grocery stores, farmer's markets, and food co-ops. Then, taking the `difference` between this single geometry of all services areas and that of a polygon delineating a neighborhood would reveal the areas within that neighborhood where access to healthy, whole foods may not exist.\n",
     "\n",
-    "Usually there are two ways of performing spatial operations - (a) `Object Oriented Programming (OOP)` pattern - through creating an geometry object first, then calling methods off the geometry object, or (b) calling functions from `arcgis.geometry.functions` directly without initating any geometry objects, e.g. the `from_geo_coordinate_string` or `to_geo_coordinate_string` methods, which takes spatial data as input, analyzes the data, then produces output data that is the derivative of the analysis performed on the input data.\n",
     "\n",
-    "The major difference between these two is that the OOP pattern uses local geom engines such as shapely or arcpy, while calling from functions will send geometries over to server using geometry service, which requires credits and is not performant for larger datasets. Users are recommended to only use (b) if they do not have access to either of the local engines. Further more, if you want to process geometries on the server, rather than applying (b), you can also publish the data as feature service and then process as input data using `arcgis.feature` module."
+    "### Two patterns of applying spatial operations\n",
+    "There are two ways of performing spatial operations \n",
+    "\n",
+    "- (a) `Object Oriented Programming (OOP)` pattern - here you create a geometry object first, then call methods off the geometry object, and \n",
+    "- (b) calling functions from `arcgis.geometry.functions` directly without initiating any geometry objects, e.g. the `from_geo_coordinate_string` or `to_geo_coordinate_string` methods, which takes spatial data as input, analyzes the data, then produces output data that is the derivative of the analysis performed on the input data.\n",
+    "\n",
+    "The major difference between these two is that the **OOP pattern uses local geometry engines** such as `shapely` or `arcpy`, while calling **functions from `arcgis.geometry.functions` will use server-side geometry engine** by sending the geometries over to the [Geometry Service](https://developers.arcgis.com/rest/services-reference/geometry-service.htm) configured with your web GIS server. If your web GIS is ArcGIS Online, the latter pattern requires credits. Further, the latter pattern is not performant for larger datasets. Users are recommended to only use (b) if they do not have access to either of the local geometry engines. Further more, if you want to process geometries on the server, rather than applying (b), you can also publish the data as feature service and then run analyses using `arcgis.feature` module.\n",
+    "\n",
+    "The rest of this page demonstrates a set of spatial operations performed using both these patterns."
    ]
   },
   {
@@ -57,7 +64,7 @@
     "from arcgis.gis import GIS\n",
     "from arcgis.geometry import Polygon, Geometry, Point, Polyline\n",
     "from arcgis.geocoding import geocode\n",
-    "import arcpy"
+    "# import arcpy"
    ]
   },
   {
@@ -66,7 +73,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "gis = GIS(\"https://www.arcgis.com\", \"arcgis_python\", \"P@ssword123\", verify_cert=False)"
+    "gis = GIS(profile='your_online_profile')"
    ]
   },
   {
@@ -362,16 +369,21 @@
     "\n",
     "Next, you will see the difference between these two spatial operations:\n",
     "  - `generalize(max_offset)` - Creates a new simplified geometry using a specified maximum offset tolerance (as shown in Figs 1 and 2). The result of the `generalize()` operation against a polyline object is a new polyline, while that against a polygon object is a new polygon.\n",
-    "  - `buffer(distance)` - Constructs a polygon at a specified distance from the geometry. The buffering process merges buffer polygons that overlap. Negative distances greater than one-half the maximum interior width of a polygon result in an empty geometry. Illustration of `buffer()` operations against different geomtry types can be found in Fig 3, which also shows that results of `buffer()` are always polygon objects.\n",
-    "  \n",
+    "  - `buffer(distance)` - Constructs a polygon at a specified distance from the geometry. The buffering process merges buffer polygons that overlap. Negative distances greater than one-half the maximum interior width of a polygon result in an empty geometry. Illustration of `buffer()` operations against different geomtry types can be found in Fig 3, which also shows that results of `buffer()` are always polygon objects."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "<img src=\"https://desktop.arcgis.com/en/arcmap/10.3/tools/editing-toolbox/GUID-BA4E50F7-938B-4695-9E96-B9C3B7B96365-web.gif\"  />\n",
-    "<h5><center>Fig 1. Generialize operation against a polyline object (Source: <a href=\"https://desktop.arcgis.com/en/arcmap/10.3/tools/editing-toolbox/generalize.htm\">ArcMap Toolbox Help</a>)</center></h5>\n",
+    "<b><center>Fig 1. Generialize operation against a polyline object (Source: <a href=\"https://desktop.arcgis.com/en/arcmap/10.3/tools/editing-toolbox/generalize.htm\">ArcMap Toolbox Help</a>)</center></b>\n",
     "  \n",
     "<img src=\"https://desktop.arcgis.com/en/arcmap/latest/tools/cartography-toolbox/GUID-128637E4-C21F-436E-9D37-62741C3B9E93-web.png\"  />\n",
-    "<h5><center>Fig 2. Generialize operation against a polygon object (Source: <a href=\"https://desktop.arcgis.com/en/arcmap/latest/tools/cartography-toolbox/simplify-polygon.htm\">ArcMap Toolset Help</a>)</center></h5>\n",
+    "<b><center>Fig 2. Generialize operation against a polygon object (Source: <a href=\"https://desktop.arcgis.com/en/arcmap/latest/tools/cartography-toolbox/simplify-polygon.htm\">ArcMap Toolset Help</a>)</center><b>\n",
     "  \n",
     "<img src=\"http://webhelp.esri.com/arcgisdesktop/9.2/published_images/ST_Buffer.gif\" />\n",
-    "<h5><center>Fig 3. Buffer operation (Source: <a href=\"http://webhelp.esri.com/arcgisdesktop/9.2/index.cfm?TopicName=Spatial_operations\">ArcGIS Desktop Help</a>)</center></h5>"
+    "<b><center>Fig 3. Buffer operation (Source: <a href=\"http://webhelp.esri.com/arcgisdesktop/9.2/index.cfm?TopicName=Spatial_operations\">ArcGIS Desktop Help</a>)</center></b>"
    ]
   },
   {
@@ -2185,9 +2197,14 @@
    "title_cell": "Table of Contents",
    "title_sidebar": "Contents",
    "toc_cell": true,
-   "toc_position": {},
+   "toc_position": {
+    "height": "calc(100% - 180px)",
+    "left": "10px",
+    "top": "150px",
+    "width": "364.2px"
+   },
    "toc_section_display": true,
-   "toc_window_display": false
+   "toc_window_display": true
   },
   "varInspector": {
    "cols": {