Merge pull request #1074 from Esri/chun7642/add_use_case_areas_and_lengths

add b10 use cases for areas_and_lengths enhancement

Author: Atma Mani

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

@@ -21,7 +21,7 @@
    },
    "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=\"#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---Uses-local-geometry-engine\" data-toc-modified-id=\"a.-OOP-Pattern---Uses-local-geometry-engine-1.2\">a. OOP Pattern - Uses local geometry engine</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.-Pattern-using-arcgis.geometry.functions:-uses-server-side-geometry-engine\" data-toc-modified-id=\"b.-Pattern-using-arcgis.geometry.functions:-uses-server-side-geometry-engine-1.3\">b. Pattern using <code>arcgis.geometry.functions</code>: uses server-side geometry engine</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=\"#Conclusion\" data-toc-modified-id=\"Conclusion-2\">Conclusion</a></span></li></ul></div>"
+    "<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---Uses-local-geometry-engine\" data-toc-modified-id=\"a.-OOP-Pattern---Uses-local-geometry-engine-1.2\">a. OOP Pattern - Uses local geometry engine</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.-Pattern-using-arcgis.geometry.functions:-uses-server-side-geometry-engine\" data-toc-modified-id=\"b.-Pattern-using-arcgis.geometry.functions:-uses-server-side-geometry-engine-1.3\">b. Pattern using <code>arcgis.geometry.functions</code>: uses server-side geometry engine</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><li><span><a href=\"#b10.-Areas-and-Lengths\" data-toc-modified-id=\"b10.-Areas-and-Lengths-1.3.10\">b10. Areas and Lengths</a></span></li></ul></li></ul></li><li><span><a href=\"#Conclusion\" data-toc-modified-id=\"Conclusion-2\">Conclusion</a></span></li></ul></div>"
    ]
   },
   {
@@ -1048,7 +1048,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 131,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -1070,7 +1070,7 @@
        "   [-8234935.963979837, 4978263.2306637755]]]}"
       ]
      },
-     "execution_count": 131,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -3084,6 +3084,132 @@
     "                    })"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### b10. 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",
+    "  - `length_unit` - The length unit in which the perimeters of polygons will be calculated. \n",
+    "    - If `calculation_type` is `planar`, then length_unit can be any `esriUnits` constant. \n",
+    "    - If `calculation_type` is not `planar`, then `length_unit` must be a linear `esriUnits` constant, such as `esriSRUnit_Meter`(i.e. `9001`|`LengthUnits.METER`) or `esriSRUnit_SurveyMile`(i.e. `9035`|`LengthUnits.SURVEYMILE`). \n",
+    "    - If `length_unit` is not specified, the units are derived from `spatial_ref` parameter. If ``spatial_ref`` is not specified, the units are in meters. \n",
+    "    - For a list of valid units, see <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriGeometry/esriSRUnitType/\">`esriSRUnitType Constants`</a> and <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriGeometry/esriSRUnitType/\">`esriSRUnit2Type Constants`</a>.\n",
+    "  - `area_unit` - The area unit in which areas of polygons will be calculated. \n",
+    "    - If `calculation_type` is `planar`, then `area_unit` can be any `esriAreaUnits` constant. \n",
+    "    - If `calculation_type` is not `planar`, then `area_unit` must be a linear esriUnits constant such as `AreaUnits.SQUAREMETERS` (i.e. `{\"areaUnit\": \"esriSquareMeters\"}`) or `AreaUnits.SQUAREMILES` (i.e. `{\"areaUnit\": \"esriSquareMiles\"}`).\n",
+    "    - If `area_unit` is not specified, the units are derived from `spatial_ref`. If `spatial_ref` is not specified, then the units are meters.\n",
+    "    - For a list of valid units, see <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriSystem/esriAreaUnits/\">`esriAreaUnits Constants`</a>. The list of valid `esriAreaUnits constants` include, esriSquareInches | esriSquareFeet | esriSquareYards | esriAcres | esriSquareMiles | esriSquareMillimeters | esriSquareCentimeters | esriSquareDecimeters | esriSquareMeters | esriAres | esriHectares | esriSquareKilometers.\n",
+    "  - `calculation_type` - The type defined for the area and length calculation of the input geometries. The type can be one of the following values:\n",
+    "    - `planar` - Planar measurements use 2D Euclidean distance to calculate area and length. This should only be used if the area or length needs to be calculated in the given `SpatialReference`. Otherwise, use ``preserveShape``.\n",
+    "    - `geodesic` - Use this type if you want to calculate an area or length using only the vertices of the `Polygon` and define the lines between the points as geodesic segments independent of the actual shape of the `Polygon`. A geodesic segment is the shortest path between two points on an ellipsoid.\n",
+    "    - `preserveShape` - This type calculates the area or length of the geometry on the surface of the Earth ellipsoid. The shape of the geometry in its coordinate system is preserved.\n",
+    "    \n",
+    "There are other optional parameters to be specify in the input arguments. For more information, check out the <a href=\"https://developers.arcgis.com/python/api-reference/arcgis.geometry.functions.html?highlight=areas_and_lengths#arcgis.geometry.functions.areas_and_lengths\">API ref</a>. Now let's look at two use cases below:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### The traditional use case\n",
+    "\n",
+    "For API version <= 1.9.0, `length_unit` shall be input as constant integer value (as found in <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriSystem/esriAreaUnits/\">esriSRUnitType Constants</a> or <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriGeometry/esriSRUnitType/\">`esriSRUnit2Type Constants`</a>) while `area_unit` only accepts a `dict` object where the a list of valid units can be found in <a href=\"https://developers.arcgis.com/enterprise-sdk/api-reference/net/esriSystem/esriAreaUnits/\">`esriAreaUnits Constants`</a>."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'areas': [266.67415681137567], 'lengths': [720.7725858813257]}"
+      ]
+     },
+     "execution_count": 26,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from arcgis.geometry.functions import areas_and_lengths\n",
+    "\n",
+    "areas_and_lengths(polygons =[access_polygon],\n",
+    "                  length_unit = 9001,\n",
+    "                  spatial_ref=3857,\n",
+    "                  area_unit = {\"areaUnit\": \"esriSquareMeters\"},\n",
+    "                  calculation_type = \"planar\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### The enhanced use case\n",
+    "\n",
+    "After 1.9.0, there is an easier way to represent `length_unit` and `area_unit`. Users can use `enum` declared in the `arcgis.geometry.functions.AreaUnits` and `arcgis.geometry.functions.LengthUnits` as input, e.g. \n",
+    "  - the `length_unit` parameter can be represented by `LengthUnits.BRITISH1936FOOT | LengthUnits.GOLDCOASTFOOT | LengthUnits.INTERNATIONALCHAIN | LengthUnits.INTERNATIONALLINK | LengthUnits.INTERNATIONALYARD | LengthUnits.METER | LengthUnits.FOOT | LengthUnits.SURVEYFOOT | LengthUnits.CLARKEFOOT | LengthUnits.FATHOM | etc.`\n",
+    "  - while the `area_unit` parameter can be represented by `AreaUnits.SQUAREINCHES | AreaUnits.SQUAREFEET | AreaUnits.SQUAREYARDS | AreaUnits.ACRES  | AreaUnits.SQUAREMILES  | AreaUnits.SQUAREMILLIMETERS  | AreaUnits.SQUARECENTIMETERS  | AreaUnits.SQUAREDECIMETERS  | AreaUnits.SQUAREMETERS  | AreaUnits.ARES  | AreaUnits.HECTARES  | AreaUnits.SQUAREKILOMETERS | etc.`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<areas_and_lengths job c9721c39d3bf4da98eb37423f8486608>"
+      ]
+     },
+     "execution_count": 27,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from arcgis.geometry.functions import LengthUnits, AreaUnits\n",
+    "\n",
+    "res = areas_and_lengths(polygons =[access_polygon],\n",
+    "                        length_unit = LengthUnits.METER,\n",
+    "                        area_unit = AreaUnits.SQUAREMETERS,\n",
+    "                        calculation_type = \"planar\",\n",
+    "                        future = True)\n",
+    "res"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Also note that, when `future` is set to True, the `areas_and_lengths` function will return a `GeometryJob` object which indicates the job is processed asynchronously. When the job is done, querying its result will bring out a `dict` object of `areas`, and `lengths` for the list of polygons."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 29,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'areas': [266.67415681137567], 'lengths': [720.7725858813257]}"
+      ]
+     },
+     "execution_count": 29,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "res.result()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -3117,7 +3243,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.10"
+   "version": "3.7.10"
   },
   "toc": {
    "base_numbering": 1,