{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 36 Creating proj.crs.crs.CRS Objects for GemGIS\n",
    "\n",
    "``proj.crs.crs.CRS`` can be used in ``GemGIS`` to define the coordinate reference system (CRS) of ``GeoDataFrames`` or to specify the target CRS for coordinate transformations. The underlying ``pyproj`` package (https://pyproj4.github.io/pyproj/dev/index.html) is a Python interface to the ``PROJ`` package/library for cartographic projections and coordinate transformations (https://proj.org/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set File Paths and download Tutorial Data\n",
    "\n",
    "If you downloaded the latest `GemGIS` version from the Github repository, append the path so that the package can be imported successfully. Otherwise, it is recommended to install `GemGIS` via `pip install gemgis` and import `GemGIS` using `import gemgis as gg`. In addition, the file path to the folder where the data is being stored is set. The tutorial data is downloaded using Pooch (https://www.fatiando.org/pooch/latest/index.html) and stored in the specified folder. Use `pip install pooch` if Pooch is not installed on your system yet."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-03-17T11:59:05.091383Z",
     "start_time": "2021-03-17T11:59:05.079389Z"
    }
   },
   "outputs": [],
   "source": [
    "file_path ='data/36_creating_proj_crs_object_for_gemgis/'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating CRS Objects\n",
    "\n",
    "CRS objects/the CRS class can easily be initiated from a variety of inputs. The following shows a selection of these inputs. These objects can then be passed to functions that take a ``proj.crs.crs.CRS`` object as argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:21.110665Z",
     "start_time": "2020-12-24T15:22:21.007052Z"
    }
   },
   "outputs": [],
   "source": [
    "from pyproj import CRS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From Authority\n",
    "\n",
    "Making a CRS from an authority name and authority code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:21.235072Z",
     "start_time": "2020-12-24T15:22:21.114664Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_authority(auth_name='EPSG', code=4647)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:21.360361Z",
     "start_time": "2020-12-24T15:22:21.239399Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_authority(auth_name='EPSG', code='4647')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From a dict\n",
    "\n",
    "Making a CRS from a dictionary of PROJ parameters. The parameters were created using the ``to_dict`` function in the first place. You will likely lose important projection information when converting to a PROJ dict from another format!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.096194Z",
     "start_time": "2020-12-24T15:22:21.363365Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: +proj=tmerc +lat_0=0 +lon_0=9 +k=0.9996 +x_0=32500 ...>\n",
       "Name: unknown\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- undefined\n",
       "Coordinate Operation:\n",
       "- name: unknown\n",
       "- method: Transverse Mercator\n",
       "Datum: Unknown based on GRS80 ellipsoid\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_dict({'proj': 'tmerc',\n",
    "               'lat_0': 0,\n",
    "               'lon_0': 9,\n",
    "               'k': 0.9996,\n",
    "               'x_0': 32500000,\n",
    "               'y_0': 0,\n",
    "               'ellps': 'GRS80',\n",
    "               'units': 'm',\n",
    "               'no_defs': None,\n",
    "               'type': 'crs'})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From EPSG Code\n",
    "\n",
    "Making a CRS from an EPSG code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.205634Z",
     "start_time": "2020-12-24T15:22:23.101185Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_epsg(4647)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.300654Z",
     "start_time": "2020-12-24T15:22:23.214642Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_epsg('4647')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:15:10.000170Z",
     "start_time": "2020-12-24T15:15:08.913618Z"
    }
   },
   "source": [
    "### From User Input \n",
    "\n",
    "Initialize a CRS class instance with:\n",
    "  - PROJ string\n",
    "  - Dictionary of PROJ parameters\n",
    "  - PROJ keyword arguments for parameters\n",
    "  - JSON string with PROJ parameters\n",
    "  - CRS WKT string\n",
    "  - An authority string [i.e. 'epsg:4326']\n",
    "  - An EPSG integer code [i.e. 4326]\n",
    "  - A tuple of (\"auth_name\": \"auth_code\") [i.e ('epsg', '4326')]\n",
    "  - An object with a `to_wkt` method.\n",
    "  - A :class:`pyproj.crs.CRS` class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.424410Z",
     "start_time": "2020-12-24T15:22:23.312660Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_user_input('EPSG:4647')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.535331Z",
     "start_time": "2020-12-24T15:22:23.428773Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_user_input(('EPSG', '4647'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.630353Z",
     "start_time": "2020-12-24T15:22:23.538333Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Projected CRS: EPSG:4647>\n",
       "Name: ETRS89 / UTM zone 32N (zE-N)\n",
       "Axis Info [cartesian]:\n",
       "- E[east]: Easting (metre)\n",
       "- N[north]: Northing (metre)\n",
       "Area of Use:\n",
       "- name: Germany - 6°E to 12°E\n",
       "- bounds: (6.0, 47.27, 12.0, 55.47)\n",
       "Coordinate Operation:\n",
       "- name: UTM zone 32N with prefix\n",
       "- method: Transverse Mercator\n",
       "Datum: European Terrestrial Reference System 1989\n",
       "- Ellipsoid: GRS 1980\n",
       "- Prime Meridian: Greenwich"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CRS.from_user_input(4647)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-12-24T15:22:23.677379Z",
     "start_time": "2020-12-24T15:22:23.633335Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pyproj.crs.crs.CRS"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "crs = CRS.from_user_input('EPSG:4647')\n",
    "type(crs)"
   ]
  }
 ],
 "metadata": {
  "hide_input": false,
  "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.8.5"
  },
  "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
}