diff --git a/guide/15-working-with-geometries/part1_introduction_what_is_geometry.ipynb b/guide/15-working-with-geometries/part1_introduction_what_is_geometry.ipynb index fb8893a08e..efe6fe7ccc 100644 --- a/guide/15-working-with-geometries/part1_introduction_what_is_geometry.ipynb +++ b/guide/15-working-with-geometries/part1_introduction_what_is_geometry.ipynb @@ -1 +1,332 @@ -{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Part 1 - Introduction - what is geometry?"]}, {"cell_type": "markdown", "metadata": {"toc": true}, "source": ["

Table of Contents

\n", "
"]}, {"cell_type": "markdown", "metadata": {}, "source": ["## What is geometry?"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Geometry is the branch of mathematics dealing with spatial relationships, measures, and properties of points, lines, and surfaces. In GIS applications, vector geometry is used to represent the spatial component of geographic features with discrete boundaries such as wells, rivers, states, streets, and parcels."]}, {"cell_type": "markdown", "metadata": {}, "source": ["In GIS, a geometry could be of the following types:\n", "\n", ""]}, {"cell_type": "markdown", "metadata": {}, "source": ["1. **Points** - these are the simplest forms of geometries. They define a single location, such as the user's GPS coordinates, locations of earthquakes, location of your parked car etc.\n", "\n", "2. **Polylines** define a series of points representing a line, such as a road or a river or an oil pipeline.\n", "\n", "3. **Polygons** define a closed shape (consisting of a series of polylines), such as the outline of a property parcel, outline of a lake or school campus.\n", "\n", "\n", "The topic [Features and Geometries](https://developers.arcgis.com/documentation/core-concepts/features-and-geometries/) provides you more information and examples of geometries and how it relates to the ArcGIS developer ecosystem. The `geometry` module of the ArcGIS API for Python provides a pythonic model to construct, visualize and work with geometries. Before we get any further into these individual geometry types, we need to discuss about an important concept called **spatial reference**"]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Spatial Reference and Coordinate Systems"]}, {"cell_type": "markdown", "metadata": {}, "source": ["**Spatial reference** defines the measurement system used to locate the geometry on a model of the Earth. For people that are new to GIS, this may come as a surprise, there are several such models to represent Earth. These models are a mathematical approximations of Earth and as such, each model is designed to suit a specific purpose - such as for navigation, area calculation, large area display etc. ArcGIS supports over a [thousand such systems](https://desktop.arcgis.com/en/arcmap/latest/map/projections/pdf/geographic_coordinate_systems.pdf), called **coordinate systems** or **coordinate reference systems**.\n", "\n", "\n", "When spatial data is created, it is often specified with a spatial reference in the form a particular **coordinate system**. Most spatial references fall into one of two categories - **geographic coordinate systems** and **projected coordinate systems**. To integrate spatial data from various sources, the data must be transformed to a common coordinate system. Thus spatial reference system must be clearly defined not only to verify the integrity of geometric calculations between shapes, but also to allow transformations to take place between shapes in different coordinate systems."]}, {"cell_type": "markdown", "metadata": {}, "source": [""]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Geographic coordinate system"]}, {"cell_type": "markdown", "metadata": {}, "source": ["A geographic coordinate system (GCS) treats the Earth as a 3D spherical surface. It uses an ellipsoidal surface for approximation and uses angular units to define locations on the Earth. There are three parts to a geographic coordinate system:\n", "\n", "- A datum, which is an ellipsoidal (spheroid) model of the Earth\n", "- A prime meridian\n", "- An angular unit of measure\n", "\n", "Common datums include *WGS84* (used in GPS) and *NAD83* (used in surveying and mapping in North America).\n", "\n", "The following example is a string representing a geographic coordinate system (GCS) based on the WGS 1984 datum. The name for this system is `GCS_WGS_1984`. Each GCS has a well-known text (`wkt`), representing the details and a well-known id (`wkid`),`4326` in this example, which is used in developer APIs such as the REST API and in the Python API.\n", "\n", "```\n", "GEOGCS[\"GCS_WGS_1984\",\n", "\t\tDATUM[\"D_WGS_1984\", \n", "\t\t\tSPHEROID[\"WGS_1984\",6378137, 298.257223563]\n", "\t\t\t],\n", "\t\tPRIMEM[\"Greenwich\",0],\n", " UNIT[\"Degree\",0.0174532925199433]\n", " ]\n", "```\n", "The `wkt` of a GCS has 3 main parts: a DATUM, SPHEROID and a PRIMEM (prime meridian). To see the list of supported GCS, their `wkt` and `wkid` (explained below), go [here](https://developers.arcgis.com/rest/services-reference/geographic-coordinate-systems.htm)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Projected coordinate system"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Projected Coordinate Systems (PCS) define a flat 2D Cartesian surface. To draw / display any geographic data on a flat map or surface such as the computer screen, it needs to be in a PCS. Unlike a geographic coordinate system, a projected coordinate system has constant lengths, angles, and areas across the two dimensions. A projected coordinate system is always based on a geographic coordinate system that references a specific datum. When your data is in a GCS, ArcGIS can still draw it on a flat surface (such as the map-widget) by projecting to an appropriate PCS on-the-fly for the purpose of display.\n", "\n", "Further, many types of analyses and data are designed for two-dimensional or planar coordinates. Three-dimensional geographic data is converted to planar coordinates via a map projection. A map projection is a set of mathematical equations to convert from longitude and latitude (i, j) to planar coordinates (x, y). Converting from three to two dimensions causes distortions. A map projection is designed to minimize the distortion caused by flattening the Earth's surface. **A projected coordinate system consists of a linear unit of measure (usually meters or feet), a map projection, the specific parameters used by the map projection, and a geographic coordinate system**. \n", "\n", "The following example is the string representation of the California State Plane Zone, which is a projected coordinate system (PCS), with a `wkid` of `3857`. You can see that it references the same DATUM, SPHEROID, PRIMEM and UNIT fields as the `4236` projection expalaind in the GCS section earlier. It also defines a PROJECTION (Mercator_Auxiliary_Sphere) which defines how to project the 3D GEOGCS coordinates into 2D coordinates:\n", "\n", "```\n", "PROJCS[\"WGS_1984_Web_Mercator_Auxiliary_Sphere\",\n", " GEOGCS[\"GCS_WGS_1984\",\n", " DATUM[\"D_WGS_1984\", SPHEROID[\"WGS_1984\",6378137.0,298.257223563]],\n", " PRIMEM[\"Greenwich\",0],\n", " UNIT[\"Degree\",0.017453292519943295]],\n", " PROJECTION[\"Mercator_Auxiliary_Sphere\"], PARAMETER[\"False_Easting\",0.0],\n", " PARAMETER[\"False_Northing\",0.0],\n", " PARAMETER[\"Central_Meridian\",0.0],\n", " PARAMETER[\"Standard_Parallel_1\",0.0],\n", " PARAMETER[\"Auxiliary_Sphere_Type\",0.0],\n", " UNIT[\"Meter\",1.0]]\n", "```\n", "To see the list of supported PCS, their `wkt` and `wkid` (explained below) go [here](https://developers.arcgis.com/rest/services-reference/projected-coordinate-systems.htm)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["If projections and coordinate systems fascinate you and you would like to learn more, checkout this lively [blog on Geographic vs Projected Coordinate Systems](https://www.esri.com/arcgis-blog/products/arcgis-pro/mapping/gcs_vs_pcs/) and this [developer guide for coordinate systems](https://developers.arcgis.com/documentation/spatial-references/#coordinate-systems-and-projections)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Vertical coordinate system\n", "A Vertical Coordinate System (VCS) defines the origin for height or depth values. Like a horizontal coordinate system (GCS, PCS), a vertical coordinate system ensures that data is spatially located accurately in relation to other data. This is especially important if you will edit the data, create new data, or perform analysis."]}, {"cell_type": "markdown", "metadata": {}, "source": [""]}, {"cell_type": "markdown", "metadata": {}, "source": ["A vertical coordinate system includes unit of measure. This is always a linear unit, usually feet or meters. (for example, international feet or meters). A vertical coordinate system also includes a direction. This specifies whether values are \"positive up\", representing heights above a surface, or \"positive down\", indicating that values are depths below a surface. Depths are always displayed as positive values. The following diagram shows two vertical coordinate systems: mean sea level and mean low water. In this example, mean sea level is used as the zero level for height values. Mean low water is a depth-based vertical coordinate system."]}, {"cell_type": "markdown", "metadata": {}, "source": [" Also, a VCS can be referenced to two different types of surfaces - spheroidal (ellipsoidal) or gravity-related (geoidal):"]}, {"cell_type": "markdown", "metadata": {}, "source": [""]}, {"cell_type": "markdown", "metadata": {}, "source": ["- **spheroidal (ellipsoidal)**: A spheroidal VCS defines heights that are referenced to a spheroid of a GCS. GPS natively reports heights relative to the WGS84 ellipsoid. A spheroidal height is a geometry quantity and does not have a physical sense because a GCS's spheroid may fall above or below the actual earth surface (as seen in the illustration above). Spheroidal heights for an area may not reflect movement due to gravity, that is, the flow of water. A VCS with heights or depths that are referenced to the spheroid will include a datum , rather than a vertical datum definition. An example is shown below.\n", "```\n", "VERTCS[\"WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",6378137.0,298.257223563]],\n", " PARAMETER[\"Vertical_Shift\",0.0],PARAMETER[\"Direction\",1.0],UNIT[\"Meter\",1.0]]\n", "```\n", "\n", "- **gravity-related (geoidal)**: Most VCS are gravity-related. A gravity-related VCS is often only loosely connected to a particular GCS. Any particular VCS may be used with different horizontal coordinate systems. A gravity-related VCS may set its zero point through a local mean sea level or a benchmark. Mean sea level will vary at different places due to topography, atmospheric effects, etc. A gravity-related VCS will include a vertical datum as part of its definition. An example is shown below.\n", "```\n", "VERTCS[\"National_Geodetic_Vertical_Datum_1929\",VDATUM[\"NGVD_1929\"],\n", " PARAMETER[\"Vertical_Shift\",0.0],PARAMETER[\"Direction\",1.0],UNIT[\"Meter\",1.0]]\n", "```\n", "\n", "All VCS are mathematical approximations, just like GCS and PCS systems explained earlier. Such approximations are required to represent locations on a GIS. To learn more about VCS, their `wkt` and `wkid` (explained below), visit [here](https://pro.arcgis.com/en/pro-app/help/mapping/properties/vertical-coordinate-systems.htm). To see the list of supported VCS, go [here](https://developers.arcgis.com/rest/services-reference/vertical-coordinate-systems.htm)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Datum transformations\n", "Datum transformations are a set of mathematical formulas that convert geometries from one coordinate system to another. Similar to the coordinate systems explained earlier, there are two sets of transformations - geographic datum transformations and vertical datum transformations. Similar to coordinate systems, transformations have a `wkt` and a `wkid`. The example below represent the transformation used to convert a NAD 1983 coordinate system to a WGS 84 coordinate system, two popular systems used in the US. The `wkid` of this transformation is `1188` and the `wkt` is shown below:\n", "\n", "```\n", "GEOGTRAN[\"NAD_1983_To_WGS_1984_1\",\n", "\t\tGEOGCS[\"GCS_North_American_1983\",\n", "\t\t\t\tDATUM[\"D_North_American_1983\",\n", "\t\t\t\t\tSPHEROID[\"GRS_1980\",6378137.0,298.257222101]\n", "\t\t\t\t\t],\n", "\t\t\t\tPRIMEM[\"Greenwich\",0.0],\n", "\t\t\t\tUNIT[\"Degree\",0.0174532925199433]\n", "\t\t\t],\n", "\t\tGEOGCS[\"GCS_WGS_1984\",\n", "\t\t\t\tDATUM[\"D_WGS_1984\",\n", "\t\t\t\t\tSPHEROID[\"WGS_1984\",6378137.0,298.257223563]\n", "\t\t\t\t\t],\n", "\t\t\t\tPRIMEM[\"Greenwich\",0.0],\n", "\t\t\t\tUNIT[\"Degree\",0.0174532925199433]\n", "\t\t\t],\n", "\t\tMETHOD[\"Geocentric_Translation\"],\n", "\t\tPARAMETER[\"X_Axis_Translation\",0.0],\n", "\t\tPARAMETER[\"Y_Axis_Translation\",0.0],\n", "\t\tPARAMETER[\"Z_Axis_Translation\",0.0]\n", "\t\t]\n", "```\n", "In reality, there are 2 other transformations for the same two coordinate systems with `wkid`s `1251` and `1252`. ArcGIS supports a number of such transformations and you can look them up [here](https://developers.arcgis.com/rest/services-reference/datum-transformations.htm)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Spatial reference when using the Python API - `wkid` and `latestWkid`"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The sections above provide the theoretical background behind geometry in general. While using the ArcGIS API for Python, we primarily work with well-known IDs called as `wkid`. For instance, the `wkid` of Web Mercator PCS explained above is `3857`.\n", "\n", "Occasionally, you might see a `latestWkid` being used. The `latestWkid` represents the current `wkid` value associated with the same spatial reference. For example, older versions of ArcGIS reference the same Web Mercator projection with a `wkid` of `102100`. In this case, the `latestWkid` key would reference the current id, which is `3857`.\n", "\n", "The pages below give you the list of all coordinate systems, transformations, their names, `wkid` and `wkt` for your reference.\n", "\n", " - [Geographic Coordinate Systems Listing](https://developers.arcgis.com/rest/services-reference/geographic-coordinate-systems.htm)\n", " - [Projected Coordinate Systems Listing](https://developers.arcgis.com/rest/services-reference/projected-coordinate-systems.htm)\n", " - [Vertical Coordinate Systems Listing](https://developers.arcgis.com/rest/services-reference/vertical-coordinate-systems.htm)\n", " - [Datum Transformations Listing](https://developers.arcgis.com/rest/services-reference/datum-transformations.htm)\n", " - [Grid-based Datum Transformations Listing](https://developers.arcgis.com/rest/services-reference/grid-based-datum-transformations.htm)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Conclusion\n", "Geometry is a core concept in GIS which specifies how features on the Earth are stored and represented on a map. A foundational understanding of geometry will help GIS developers navigate the geospatial technology spectrum with ease. This page provided a high-level overview of different types of geometries and coordinate systems. In the subsequent pages, you will learn about how to create and work with geometries using the Python API."]}], "metadata": {"anaconda-cloud": {}, "kernelspec": {"display_name": "Python 3", "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.6.10"}, "toc": {"base_numbering": 1, "nav_menu": {}, "number_sections": false, "sideBar": true, "skip_h1_title": true, "title_cell": "Table of Contents", "title_sidebar": "Contents", "toc_cell": true, "toc_position": {}, "toc_section_display": true, "toc_window_display": false}, "varInspector": {"cols": {"lenName": 16, "lenType": 16, "lenVar": 40}, "kernels_config": {"python": {"delete_cmd_postfix": "", "delete_cmd_prefix": "del ", "library": "var_list.py", "varRefreshCmd": "print(var_dic_list())"}, "r": {"delete_cmd_postfix": ") ", "delete_cmd_prefix": "rm(", "library": "var_list.r", "varRefreshCmd": "cat(var_dic_list()) "}}, "types_to_exclude": ["module", "function", "builtin_function_or_method", "instance", "_Feature"], "window_display": false}}, "nbformat": 4, "nbformat_minor": 1} \ No newline at end of file +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Part 1 - Introduction - what is geometry?" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "toc": true + }, + "source": [ + "

Table of Contents

\n", + "
" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What is geometry?" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Geometry is the branch of mathematics dealing with spatial relationships, measures, and properties of points, lines, and surfaces. In GIS applications, vector geometry is used to represent the spatial component of geographic features with discrete boundaries such as wells, rivers, states, streets, and parcels." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In GIS, a geometry could be of the following types:\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "1. **Points** - these are the simplest forms of geometries. They define a single location, such as the user's GPS coordinates, locations of earthquakes, location of your parked car etc.\n", + "\n", + "2. **Polylines** define a series of points representing a line, such as a road or a river or an oil pipeline.\n", + "\n", + "3. **Polygons** define a closed shape (consisting of a series of polylines), such as the outline of a property parcel, outline of a lake or school campus.\n", + "\n", + "\n", + "The topic [Geometry Objects](https://developers.arcgis.com/rest/services-reference/enterprise/geometry-objects/) provides you more information on the types of geometries and their different components. The `geometry` module of the ArcGIS API for Python provides a pythonic model to construct, visualize and work with geometries. Before we get any further into these individual geometry types, we need to discuss about an important concept called **spatial reference**" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Spatial Reference and Coordinate Systems" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Spatial reference** defines the measurement system used to locate the geometry on a model of the Earth. For people that are new to GIS, this may come as a surprise: there are several such models to represent Earth. These models are a mathematical approximations of Earth and as such, each model is designed to suit a specific purpose - such as for navigation, area calculation, large area display etc. ArcGIS supports over a [thousand such systems](https://desktop.arcgis.com/en/arcmap/latest/map/projections/pdf/geographic_coordinate_systems.pdf), called **coordinate systems** or **coordinate reference systems**.\n", + "\n", + "\n", + "When spatial data is created, it is often specified with a spatial reference in the form of a particular **coordinate system**. Most spatial references fall into one of two categories - **geographic coordinate systems** and **projected coordinate systems**. To integrate spatial data from various sources, the data must be transformed to a common coordinate system. Thus spatial reference system must be clearly defined not only to verify the integrity of geometric calculations between shapes, but also to allow transformations to take place between shapes in different coordinate systems." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Geographic coordinate system" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A geographic coordinate system (GCS) treats the Earth as a 3D spherical surface. It uses an ellipsoidal surface for approximation and uses angular units to define locations on the Earth. There are three parts to a geographic coordinate system:\n", + "\n", + "- A datum, which is an ellipsoidal (spheroid) model of the Earth\n", + "- A prime meridian\n", + "- An angular unit of measure\n", + "\n", + "Common datums include *WGS84* (used in GPS) and *NAD83* (used in surveying and mapping in North America).\n", + "\n", + "The following example is a string representing a geographic coordinate system (GCS) based on the WGS 1984 datum. The name for this system is `GCS_WGS_1984`. Each GCS has a well-known text (`wkt`), representing the details and a well-known id (`wkid`)- `4326` in this example, which is used in developer APIs such as the REST API and in the Python API.\n", + "\n", + "```\n", + "GEOGCS[\"GCS_WGS_1984\",\n", + "\t\tDATUM[\"D_WGS_1984\", \n", + "\t\t\tSPHEROID[\"WGS_1984\",6378137, 298.257223563]\n", + "\t\t\t],\n", + "\t\tPRIMEM[\"Greenwich\",0],\n", + " UNIT[\"Degree\",0.0174532925199433]\n", + " ]\n", + "```\n", + "The `wkt` of a GCS has 3 main parts: a DATUM, SPHEROID and a PRIMEM (prime meridian). To see the list of supported GCS, their `wkt` and `wkid` (explained below), go [here](https://developers.arcgis.com/rest/services-reference/geographic-coordinate-systems.htm)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Projected coordinate system" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Projected Coordinate Systems (PCS) define a flat 2D Cartesian surface. To draw / display any geographic data on a flat map or surface such as the computer screen, it needs to be in a PCS. Unlike a geographic coordinate system, a projected coordinate system has constant lengths, angles, and areas across the two dimensions. A projected coordinate system is always based on a geographic coordinate system that references a specific datum. When your data is in a GCS, ArcGIS can still draw it on a flat surface (such as the map-widget) by projecting to an appropriate PCS on-the-fly for the purpose of display.\n", + "\n", + "Further, many types of analyses and data are designed for two-dimensional or planar coordinates. Three-dimensional geographic data is converted to planar coordinates via a map projection. A map projection is a set of mathematical equations to convert from longitude and latitude (i, j) to planar coordinates (x, y). Converting from three to two dimensions causes distortions. A map projection is designed to minimize the distortion caused by flattening the Earth's surface. **A projected coordinate system consists of a linear unit of measure (usually meters or feet), a map projection, the specific parameters used by the map projection, and a geographic coordinate system**. \n", + "\n", + "The following example is the string representation of the California State Plane Zone, which is a projected coordinate system (PCS), with a `wkid` of `3857`. You can see that it references the same DATUM, SPHEROID, PRIMEM and UNIT fields as the `4236` projection expalaind in the GCS section earlier. It also defines a PROJECTION (Mercator_Auxiliary_Sphere) which defines how to project the 3D GEOGCS coordinates into 2D coordinates:\n", + "\n", + "```\n", + "PROJCS[\"WGS_1984_Web_Mercator_Auxiliary_Sphere\",\n", + " GEOGCS[\"GCS_WGS_1984\",\n", + " DATUM[\"D_WGS_1984\", SPHEROID[\"WGS_1984\",6378137.0,298.257223563]],\n", + " PRIMEM[\"Greenwich\",0],\n", + " UNIT[\"Degree\",0.017453292519943295]],\n", + " PROJECTION[\"Mercator_Auxiliary_Sphere\"], PARAMETER[\"False_Easting\",0.0],\n", + " PARAMETER[\"False_Northing\",0.0],\n", + " PARAMETER[\"Central_Meridian\",0.0],\n", + " PARAMETER[\"Standard_Parallel_1\",0.0],\n", + " PARAMETER[\"Auxiliary_Sphere_Type\",0.0],\n", + " UNIT[\"Meter\",1.0]]\n", + "```\n", + "To see the list of supported PCS, their `wkt` and `wkid` (explained below) go [here](https://developers.arcgis.com/rest/services-reference/projected-coordinate-systems.htm)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "If projections and coordinate systems fascinate you and you would like to learn more, checkout this lively [blog on Geographic vs Projected Coordinate Systems](https://www.esri.com/arcgis-blog/products/arcgis-pro/mapping/gcs_vs_pcs/) and this [developer guide for coordinate systems](https://developers.arcgis.com/documentation/spatial-references/#coordinate-systems-and-projections)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Vertical coordinate system\n", + "A Vertical Coordinate System (VCS) defines the origin for height or depth values. Like a horizontal coordinate system (GCS, PCS), a vertical coordinate system ensures that data is spatially located accurately in relation to other data. This is especially important if you will edit the data, create new data, or perform analysis." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "A vertical coordinate system includes unit of measure. This is always a linear unit, usually feet or meters. A vertical coordinate system also includes a direction. This specifies whether values are \"positive up\", representing heights above a surface, or \"positive down\", indicating that values are depths below a surface. Depths are always displayed as positive values. The following diagram shows two vertical coordinate systems: mean sea level and mean low water. In this example, mean sea level is used as the zero level for height values. Mean low water is a depth-based vertical coordinate system." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + " Also, a VCS can be referenced to two different types of surfaces - spheroidal (ellipsoidal) or gravity-related (geoidal):" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "- **spheroidal (ellipsoidal)**: A spheroidal VCS defines heights that are referenced to a spheroid of a GCS. GPS natively reports heights relative to the WGS84 ellipsoid. A spheroidal height is a geometry quantity and does not have a physical sense because a GCS's spheroid may fall above or below the actual earth surface (as seen in the illustration above). Spheroidal heights for an area may not reflect movement due to gravity, that is, the flow of water. A VCS with heights or depths that are referenced to the spheroid will include a datum , rather than a vertical datum definition. An example is shown below.\n", + "```\n", + "VERTCS[\"WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_1984\",6378137.0,298.257223563]],\n", + " PARAMETER[\"Vertical_Shift\",0.0],PARAMETER[\"Direction\",1.0],UNIT[\"Meter\",1.0]]\n", + "```\n", + "\n", + "- **gravity-related (geoidal)**: Most VCS are gravity-related. A gravity-related VCS is often only loosely connected to a particular GCS. Any particular VCS may be used with different horizontal coordinate systems. A gravity-related VCS may set its zero point through a local mean sea level or a benchmark. Mean sea level will vary at different places due to topography, atmospheric effects, etc. A gravity-related VCS will include a vertical datum as part of its definition. An example is shown below.\n", + "```\n", + "VERTCS[\"National_Geodetic_Vertical_Datum_1929\",VDATUM[\"NGVD_1929\"],\n", + " PARAMETER[\"Vertical_Shift\",0.0],PARAMETER[\"Direction\",1.0],UNIT[\"Meter\",1.0]]\n", + "```\n", + "\n", + "All VCS are mathematical approximations, just like GCS and PCS systems explained earlier. Such approximations are required to represent locations on a GIS. To learn more about VCS, their `wkt` and `wkid` (explained below), visit [here](https://pro.arcgis.com/en/pro-app/help/mapping/properties/vertical-coordinate-systems.htm). To see the list of supported VCS, go [here](https://developers.arcgis.com/rest/services-reference/vertical-coordinate-systems.htm)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Datum transformations\n", + "Datum transformations are a set of mathematical formulas that convert geometries from one coordinate system to another. Similar to the coordinate systems explained earlier, there are two sets of transformations - geographic datum transformations and vertical datum transformations. Similar to coordinate systems, transformations have a `wkt` and a `wkid`. The example below represent the transformation used to convert a NAD 1983 coordinate system to a WGS 84 coordinate system, two popular systems used in the US. The `wkid` of this transformation is `1188` and the `wkt` is shown below:\n", + "\n", + "```\n", + "GEOGTRAN[\"NAD_1983_To_WGS_1984_1\",\n", + "\t\tGEOGCS[\"GCS_North_American_1983\",\n", + "\t\t\t\tDATUM[\"D_North_American_1983\",\n", + "\t\t\t\t\tSPHEROID[\"GRS_1980\",6378137.0,298.257222101]\n", + "\t\t\t\t\t],\n", + "\t\t\t\tPRIMEM[\"Greenwich\",0.0],\n", + "\t\t\t\tUNIT[\"Degree\",0.0174532925199433]\n", + "\t\t\t],\n", + "\t\tGEOGCS[\"GCS_WGS_1984\",\n", + "\t\t\t\tDATUM[\"D_WGS_1984\",\n", + "\t\t\t\t\tSPHEROID[\"WGS_1984\",6378137.0,298.257223563]\n", + "\t\t\t\t\t],\n", + "\t\t\t\tPRIMEM[\"Greenwich\",0.0],\n", + "\t\t\t\tUNIT[\"Degree\",0.0174532925199433]\n", + "\t\t\t],\n", + "\t\tMETHOD[\"Geocentric_Translation\"],\n", + "\t\tPARAMETER[\"X_Axis_Translation\",0.0],\n", + "\t\tPARAMETER[\"Y_Axis_Translation\",0.0],\n", + "\t\tPARAMETER[\"Z_Axis_Translation\",0.0]\n", + "\t\t]\n", + "```\n", + "In reality, there are 2 other transformations for the same two coordinate systems with `wkid`s `1251` and `1252`. ArcGIS supports a number of such transformations, which you can look up [here](https://developers.arcgis.com/rest/services-reference/datum-transformations.htm)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Spatial reference when using the Python API - `wkid` and `latestWkid`" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The sections above provide the theoretical background behind geometry in general. While using the ArcGIS API for Python, we primarily work with well-known IDs called as `wkid`. For instance, the `wkid` of Web Mercator PCS explained above is `3857`.\n", + "\n", + "Occasionally, you might see a `latestWkid` being used. The `latestWkid` represents the current `wkid` value associated with the same spatial reference. For example, older versions of ArcGIS reference the same Web Mercator projection with a `wkid` of `102100`. In this case, the `latestWkid` key would reference the current id, which is `3857`.\n", + "\n", + "[This page](https://developers.arcgis.com/rest/services-reference/enterprise/using-spatial-references/) (referenced multiple times earlier) gives you the list of all coordinate systems, transformations, their names, `wkid` and `wkt` for your reference." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Conclusion\n", + "Geometry is a core concept in GIS which specifies how features on the Earth are stored and represented on a map. A foundational understanding of geometry will help GIS developers navigate the geospatial technology spectrum with ease. This page provided a high-level overview of different types of geometries and coordinate systems. In the subsequent guides, you will learn about how to create and work with geometries using the Python API." + ] + } + ], + "metadata": { + "anaconda-cloud": {}, + "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.10.14" + }, + "toc": { + "base_numbering": 1, + "nav_menu": {}, + "number_sections": false, + "sideBar": true, + "skip_h1_title": true, + "title_cell": "Table of Contents", + "title_sidebar": "Contents", + "toc_cell": true, + "toc_position": {}, + "toc_section_display": true, + "toc_window_display": false + }, + "varInspector": { + "cols": { + "lenName": 16, + "lenType": 16, + "lenVar": 40 + }, + "kernels_config": { + "python": { + "delete_cmd_postfix": "", + "delete_cmd_prefix": "del ", + "library": "var_list.py", + "varRefreshCmd": "print(var_dic_list())" + }, + "r": { + "delete_cmd_postfix": ") ", + "delete_cmd_prefix": "rm(", + "library": "var_list.r", + "varRefreshCmd": "cat(var_dic_list()) " + } + }, + "types_to_exclude": [ + "module", + "function", + "builtin_function_or_method", + "instance", + "_Feature" + ], + "window_display": false + } + }, + "nbformat": 4, + "nbformat_minor": 4 +}