added documentation on geometries

Author: claxn

docs/guides/geometry.ipynb

@@ -0,0 +1,139 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "50f502bd",
+   "metadata": {
+    "tags": [
+     "remove-input"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import warnings\n",
+    "\n",
+    "warnings.filterwarnings(\"ignore\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2ee126e9",
+   "metadata": {},
+   "source": [
+    "# Geometries\n",
+    "\n",
+    "`pytileproj` does not have GDAL and OGR as a direct dependency and instead defines its own classes to store geospatial geometries. These geometries are used as an interface to and from many functions and class methods within `pytileproj`. \n",
+    "\n",
+    "Several geospatial geometry classes are declared in `pytileproj`'s `projgeom` module and are defined by two properties:\n",
+    "\n",
+    "- `geom`: a `shapely.Geometry` instance, e.g. `shapely.Point`, `shapely.Polygon`, and `shapely.MultiPolygon` \n",
+    "- `crs`: a `pyproj.CRS` instance\n",
+    "\n",
+    "The simplest class, is the `ProjCoord` class defining a projected coordinate tuple."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ad748924",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pyproj\n",
+    "\n",
+    "from pytileproj import ProjCoord\n",
+    "\n",
+    "proj_coord = ProjCoord(x=25, y=10, crs=pyproj.CRS.from_epsg(3857))\n",
+    "proj_coord"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4bb1a565",
+   "metadata": {},
+   "source": [
+    "For geographical (longitude and latitude) coordinates, there is a child class `GeogCoord`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f4c43c7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytileproj import GeogCoord\n",
+    "\n",
+    "geog_coord = GeogCoord(25, 10)\n",
+    "geog_coord"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6c1e7c00",
+   "metadata": {},
+   "source": [
+    "All other geometries can be defined with the basic class `ProjGeom`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d9299ecf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from shapely import Polygon\n",
+    "\n",
+    "from pytileproj import ProjGeom\n",
+    "\n",
+    "geom = Polygon([(1, 1), (10, 2), (8, 7), (2, 4)])\n",
+    "proj_geom = ProjGeom(geom=geom, crs=pyproj.CRS.from_epsg(27701))\n",
+    "proj_geom"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6651a3a2",
+   "metadata": {},
+   "source": [
+    "Also here we can use a special class for geographic coordinates:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2da28e68",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pytileproj import GeogGeom\n",
+    "\n",
+    "geog_geom = GeogGeom(geom=geom)\n",
+    "geog_geom"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "pytileproj",
+   "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.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/guides/grid.ipynb

@@ -426,7 +426,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,

docs/index.md

@@ -9,6 +9,7 @@ readme
 :hidden:
 :caption: 📚 Guides
 
+guides/geometry.ipynb
 guides/tile.ipynb
 guides/tiling_system.ipynb
 guides/grid.ipynb