Merge pull request #2034 from Esri/jy-rvw-geom-ops

update markdown headings and change hyperlinks to relative

Author: jyaistMap

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

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Previously, in <a href=\"part1_introduction_what_is_geometry.ipynb\">Part 1</a> of this guide series to the `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."
+    "Previously, in [Part 1](../part1-introduction-what-is-geometry/) of this guide series to the `arcgis.geometry` module, you have seen the introduction to the module and some foundational concepts. In [Part 2](../part2-working-with-geometries/), 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."
    ]
   },
   {
@@ -38,8 +38,8 @@
     "### 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 instantiating any geometry objects, e.g. the `from_geo_coordinate_string` or `to_geo_coordinate_string` methods, which take spatial data as input, analyze the data, then produce output data that is the derivative of the analysis performed on the input data.\n",
+    "- `Object Oriented Programming (OOP)` pattern - here you create a geometry object first, then call methods off the geometry object, and \n",
+    "- `Server-side Processing` - calling functions from `arcgis.geometry.functions` directly without instantiating any geometry objects, e.g. the `from_geo_coordinate_string` or `to_geo_coordinate_string` methods, which take spatial data as input, analyze the data, then produce 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",
@@ -50,7 +50,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### a. OOP Pattern - Uses local geometry engine\n",
+    "## OOP Pattern - Uses local geometry engine\n",
     "\n",
     "Before demonstrating spatial operations, let us first import the necessary libraries, and create a GIS instance that connects to ArcGIS Online.\n",
     "\n",
@@ -90,7 +90,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a1. Union\n",
+    "### Union\n",
     "\n",
     "The first method, `<first geom object>.union(<second_geometry>)`, can be called off from a geometry object to construct the geometry that is the set-theoretic union of the input geometries. You are going to see an example of how to create a union of two polygons (e.g. geometry1 and geometry2):"
    ]
@@ -217,7 +217,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a2. Difference\n",
+    "### Difference\n",
     "\n",
     "The, `difference(second_geometry)`, constructs the geometry that is composed only of the region unique to the base geometry but not part of the second geometry. The following illustration shows the results that are inside the source geometry, but not the second geometry."
    ]
@@ -299,7 +299,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a3. Symmetric difference\n",
+    "### Symmetric difference\n",
     "\n",
     "Similar to `difference()`, the method `symmetric_difference(second_geometry)` constructs the geometry that is the union of two geometries minus the intersection of those geometries. As told by the definition, the result of `difference()` should always be included/contained in the result of a `symmetric_difference()`."
    ]
@@ -357,7 +357,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a4. intersect() V.S. overlaps()\n",
+    "### intersect() V.S. overlaps()\n",
     "\n",
     "The `intersect()` method constructs a geometry that is the geometric intersection of the two input geometries. Different dimension values can be used to create different shape types. The intersection of two geometries of the same shape type is a geometry containing only the regions of overlap between the original geometries, and its arguments include:\n",
     "  - `second_geometry`: required `arcgis.geometry.Geometry`. \n",
@@ -453,7 +453,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a5. Equals\n",
+    "### Equals\n",
     "\n",
     "`equals()` compares the source geometry with the second to check if they are of the same shape type and define the same set of points in the plane. This is a `2D comparison` only; M and Z values are ignored."
    ]
@@ -502,7 +502,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a6. generalize() V.S. buffer()\n",
+    "### Generalize() V.S. buffer()\n",
     "\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",
@@ -807,7 +807,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a7. Find the nearest point\n",
+    "### Find the nearest point\n",
     "\n",
     "Imagine that you are jogging on a trail (drawn as the light blue line segment on the map) inside Central Park and looking for a water fountain. You know the water fountain is located inside the pavilion (as marked as the blue pin). You want to know: What is the shortest path from the trail to pavilion?\n",
     "\n",
@@ -1007,7 +1007,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a8. contains()\n",
+    "### Contains\n",
     "\n",
     "The method `contains(second_geometry, relation=None)` indicates if the base geometry contains the comparison geometry."
    ]
@@ -1145,7 +1145,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### a9. Clip a geometry object\n",
+    "### Clip a geometry object\n",
     "\n",
     "The method `clip(envelope)` constructs the intersection of the geometry and the specified extent. Note that, if `ArcPy` is not installed, none is returned. The one and required input parameter is:\n",
     "  - `envelope`: required tuple. The tuple must be in the form of a tuple (XMin, YMin, XMax, YMax) where each value represents the lower left bound and upper right bound of the extent."
@@ -1288,7 +1288,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### b. `arcgis.geometry.functions` pattern: using the server-side geometry engine\n",
+    "## Server-side geometry engine:  Using `arcgis.geometry.functions`\n",
     "\n",
     "Besides calling methods off the geometry object as discussed in section (a), users can also call spatial operations directly from `arcgis.geometry.functions`. In the following section, you will see spatial operations such as `union` and `intersect` being performed with global functions."
    ]
@@ -1306,7 +1306,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b1. Union"
+    "### Union"
    ]
   },
   {
@@ -1415,7 +1415,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b2. intersect() V.S. overlaps()\n",
+    "### Intersect() V.S. overlaps()\n",
     "\n",
     "The intersect function `arcgis.geometry.functions.intersect(spatial_ref, geometries, geometry, gis=None)` is performed on a geometry service resource. This function constructs the set-theoretic intersection between an array of geometries and another geometry. The dimension of each resultant geometry is the minimum dimension of the input geometry in the geometries array and the other geometry specified by the geometry parameter. Inputs include:\n",
     "  - `spatial_ref` - The well-known ID or a spatial reference JSON object for the input geometries.\n",
@@ -1554,7 +1554,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b3. Difference\n",
+    "### Difference\n",
     "\n",
     "In order to construct the set-theoretic difference between each element of an array of geometries and another geometry (a.k.a. the so-called difference geometry), users need to perform a `difference` function on a geomtry service resource, which requires these inputs:\n",
     " - `geometries` - An array of points, multipoints, polylines or polygons. The structure of each geometry in the array is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API.\n",
@@ -1715,7 +1715,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b4. Symmetric difference\n",
+    "### Symmetric difference\n",
     "\n",
     "Again, there is no direct match of the aforementioned `symmetric_difference()` function in the `arcgis.geometry.functions`. In situations when the OOP pattern of this call is not applicable, you can construct your own customized function to create the geometry that is the union of two geometries minus the instersection of those geometries."
    ]
@@ -1833,7 +1833,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b5. Equals\n",
+    "### Equals\n",
     "\n",
     "There is no direct match of `equals()` function in the `arcgis.geometry.functions`. In situations when OOP pattern of this call is not applicable, you can construct your own customized function that checks if two geometries are equal."
    ]
@@ -1912,7 +1912,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b6. generalize() V.S. buffer()\n",
+    "### Generalize() V.S. buffer()\n",
     "\n",
     "In section (a6), we have already discussed the difference between these two spatial operations:\n",
     "  - `generalize(max_offset)` - Creates a new simplified geometry using a specified maximum offset tolerance.\n",
@@ -2544,7 +2544,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b7. Distance\n",
+    "### Distance\n",
     "\n",
     "From section (a7) we have figured out that `a_p` is the closest point on the trail from the pavilion, is there a way to confirm that the distance from `a_p` to the `access_point` is in fact the shortest?\n",
     "\n",
@@ -2679,9 +2679,17 @@
    "outputs": [],
    "source": [
     "map3.content.draw(access_point, \n",
-    "          symbol = PictureMarkerSymbolEsriPMS(**{\"angle\":0,\"xoffset\":2,\"yoffset\":8,\"type\":\"esriPMS\",\n",
-    "                    \"url\":\"http://static.arcgis.com/images/Symbols/Basic/BlueShinyPin.png\",\n",
-    "                    \"contentType\":\"image/png\",\"width\":24,\"height\":24}))"
+    "          symbol = PictureMarkerSymbolEsriPMS(**{\"angle\":0,\n",
+    "                                                 \"xoffset\":2,\n",
+    "                                                 \"yoffset\":8,\n",
+    "                                                 \"type\":\"esriPMS\",\n",
+    "                                                 \"url\":\"http://static.arcgis.com/images/Symbols/Basic/BlueShinyPin.png\",\n",
+    "                                                 \"contentType\":\"image/png\",\n",
+    "                                                 \"width\":24,\n",
+    "                                                 \"height\":24\n",
+    "                                                }\n",
+    "                                             )\n",
+    "                 )"
    ]
   },
   {
@@ -2691,9 +2699,17 @@
    "outputs": [],
    "source": [
     "map3.content.draw(a_p, \n",
-    "          symbol = PictureMarkerSymbolEsriPMS(**{\"angle\":0,\"xoffset\":2,\"yoffset\":8,\"type\":\"esriPMS\",\n",
-    "                    \"url\":\"http://static.arcgis.com/images/Symbols/Basic/GreenShinyPin.png\",\n",
-    "                    \"contentType\":\"image/png\",\"width\":24,\"height\":24}))"
+    "          symbol = PictureMarkerSymbolEsriPMS(**{\"angle\":0,\n",
+    "                                                 \"xoffset\":2,\n",
+    "                                                 \"yoffset\":8,\n",
+    "                                                 \"type\":\"esriPMS\",\n",
+    "                                                 \"url\":\"http://static.arcgis.com/images/Symbols/Basic/GreenShinyPin.png\",\n",
+    "                                                 \"contentType\":\"image/png\",\n",
+    "                                                 \"width\":24,\n",
+    "                                                 \"height\":24\n",
+    "                                                }\n",
+    "                                             )\n",
+    "                 )"
    ]
   },
   {
@@ -2707,7 +2723,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b8. Determine the spatial relation between two geometries\n",
+    "### Determine the spatial relation between two geometries\n",
     "\n",
     "The relation function `arcgis.geometry.functions.relation(geometries1, geometries2, spatial_ref, spatial_relation='esriGeometryRelationIntersection', relation_param='', gis=None)` is performed on a geometry service resource. This function determines the pairs of geometries from the input geometry arrays that participate in the specified spatial relation. Both arrays are assumed to be in the spatial reference specified by `spatial_ref`, which is a required parameter. Geometry types cannot be mixed within an array. The relations are evaluated in 2D. In other words, z coordinates are not used.\n",
     "\n",
@@ -3001,7 +3017,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b9. Clip a geometry object\n",
+    "### Clip a geometry object\n",
     "\n",
     "There is no direct match in the `arcgis.geometry.functions` that is equivalent to `clips()`, but we can take advantage of `intersect()` and write our own customized function that creates the `envelope` object to clip with, and performs `intersect()` with source geometry to generate the equivalent clipped result."
    ]
@@ -3132,7 +3148,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### b10. Areas and Lengths\n",
+    "### Areas and Lengths\n",
     "\n",
     "The `areas_and_lengths` function calculates areas and perimeter lengths for each `Polygon` object specified in the input array. The input parameters include:\n",
     "  - `polygons` - The array of polygons whose areas and lengths are to be computed.\n",
@@ -3266,8 +3282,8 @@
    "metadata": {},
    "source": [
     "In this notebook, we explored the two approaches to performing spatial operations: \n",
-    "- (a) Object Oriented Programming (OOP) pattern (calling operations directly off Geometry object). This pattern utilizes local geometry engines (ArcPy or Shapely) and performs the computation on the machine running the Python kernel \n",
-    "- (b) calling functions from `arcgis.geometry.functions`, which sends the spatial data over to a Geometry Service running on the active GIS connection, performs the operations remotely, and returns the results as Geometry objects.\n",
+    "- Object Oriented Programming (OOP) pattern (calling operations directly off Geometry object). This pattern utilizes local geometry engines (ArcPy or Shapely) and performs the computation on the machine running the Python kernel \n",
+    "- Server-side Processing by calling functions from `arcgis.geometry.functions`, which sends the spatial data over to a Geometry Service running on the active GIS connection, performs the operations remotely, and returns the results as Geometry objects.\n",
     "\n",
     "In most cases, approach (a) is simpler and more staightforward, and is recommended for users getting to use the ArcGIS API for Python. Additionally, another advantage of (a) is that it does not consume credits and is performant for larger datasets. However, (a) uses local geometry engines such as `shapely` or `arcpy`- in situations where neither shapely nor arcpy is installed on the execution environment, approach (b) is the alternative."
    ]
@@ -3289,7 +3305,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.11.0"
   },
   "toc": {
    "base_numbering": 1,