Add first-class Polars DataFrame support

docs/installation.md

@@ -30,6 +30,33 @@ Optionally, you can install some [Jupyter notebook extensions](https://github.co
 conda install jupyter_contrib_nbextensions -c conda-forge
 ```
 
+## Optional Dependencies
+
+Leafmap has various optional dependencies to enable additional features. You can install them as needed:
+
+### Polars Support
+
+To enable Polars DataFrame support for modern, high-performance geospatial workflows:
+
+```bash
+pip install "leafmap[polars]"
+```
+
+This enables the `add_polars()` method for visualizing Polars DataFrames with geometry columns (e.g., from Polars-ST or polars-h3).
+
+### Other Optional Dependencies
+
+Install other optional features:
+
+```bash
+pip install "leafmap[vector]"     # Vector analysis tools
+pip install "leafmap[raster]"     # Raster data support
+pip install "leafmap[lidar]"      # LiDAR data analysis
+pip install "leafmap[backends]"   # All mapping backends
+pip install "leafmap[maplibre]"   # MapLibre GL backend
+pip install "leafmap[ai]"         # AI/ML features
+```
+
 ## Install from GitHub
 
 To install the development version from GitHub using [Git](https://git-scm.com/), run the following command in your terminal:

docs/notebooks/110_polars.ipynb

@@ -0,0 +1,236 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Polars DataFrame Support in Leafmap\n",
+    "\n",
+    "This notebook demonstrates first-class support for Polars-based geospatial workflows in leafmap.\n",
+    "\n",
+    "## Installation\n",
+    "\n",
+    "```bash\n",
+    "pip install leafmap polars geopandas\n",
+    "```\n",
+    "\n",
+    "For Polars-ST support:\n",
+    "```bash\n",
+    "pip install polars-st\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import leafmap\n",
+    "import polars as pl\n",
+    "import geopandas as gpd\n",
+    "from shapely.geometry import Point, Polygon, box\n",
+    "from shapely import wkb"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 1: Simple Point Data\n",
+    "\n",
+    "Create a Polars DataFrame with point geometries using WKT (Well-Known Text)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create sample data with WKT geometries\n",
+    "data = {\n",
+    "    \"city\": [\"New York\", \"Los Angeles\", \"Chicago\", \"Houston\", \"Phoenix\"],\n",
+    "    \"population\": [8336817, 3979576, 2693976, 2320268, 1680992],\n",
+    "    \"geometry\": [\n",
+    "        \"POINT(-74.0060 40.7128)\",  # New York\n",
+    "        \"POINT(-118.2437 34.0522)\",  # Los Angeles\n",
+    "        \"POINT(-87.6298 41.8781)\",  # Chicago\n",
+    "        \"POINT(-95.3698 29.7604)\",  # Houston\n",
+    "        \"POINT(-112.0740 33.4484)\",  # Phoenix\n",
+    "    ],\n",
+    "}\n",
+    "\n",
+    "df_polars = pl.DataFrame(data)\n",
+    "print(df_polars)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Visualize with leafmap\n",
+    "m = leafmap.Map(center=[37.0902, -95.7129], zoom=4)\n",
+    "m.add_polars(\n",
+    "    df_polars,\n",
+    "    geometry=\"geometry\",\n",
+    "    crs=\"EPSG:4326\",\n",
+    "    layer_name=\"US Cities\",\n",
+    "    zoom_to_layer=True,\n",
+    ")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 2: Converting from GeoDataFrame to Polars\n",
+    "\n",
+    "Read GeoJSON/GeoParquet and work with it in Polars"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Start with a GeoDataFrame\n",
+    "url = \"https://github.com/opengeos/datasets/releases/download/vector/cables.geojson\"\n",
+    "gdf = gpd.read_file(url)\n",
+    "\n",
+    "# Convert to Polars with WKB geometry\n",
+    "from shapely import wkb\n",
+    "\n",
+    "# Convert geometries to WKB bytes\n",
+    "gdf[\"geometry_wkb\"] = gdf[\"geometry\"].apply(lambda x: wkb.dumps(x))\n",
+    "df_polars = pl.DataFrame(gdf.drop(columns=[\"geometry\"]))\n",
+    "\n",
+    "print(df_polars.head())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Visualize the Polars DataFrame\n",
+    "m = leafmap.Map()\n",
+    "m.add_polars(\n",
+    "    df_polars,\n",
+    "    geometry=\"geometry_wkb\",\n",
+    "    crs=\"EPSG:4326\",\n",
+    "    layer_name=\"Submarine Cables\",\n",
+    "    zoom_to_layer=True,\n",
+    "    style={\"color\": \"blue\", \"weight\": 2},\n",
+    ")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 3: Polars Data Processing Pipeline\n",
+    "\n",
+    "Demonstrate Polars-first workflow with filtering and aggregation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from shapely.geometry import box\n",
+    "import numpy as np\n",
+    "\n",
+    "# Create sample polygon data\n",
+    "\n",
+    "# Create grid of rectangles\n",
+    "geometries = []\n",
+    "names = []\n",
+    "values = []\n",
+    "\n",
+    "\n",
+    "for i in range(-5, 5):\n",
+    "    for j in range(-5, 5):\n",
+    "        geometries.append(wkb.dumps(box(i, j, i + 0.8, j + 0.8)))\n",
+    "        names.append(f\"Cell_{i}_{j}\")\n",
+    "        values.append(np.random.randint(0, 100))\n",
+    "\n",
+    "df_grid = pl.DataFrame({\"name\": names, \"value\": values, \"geometry\": geometries})\n",
+    "\n",
+    "print(df_grid.head())\n",
+    "print(f\"\\nTotal cells: {len(df_grid)}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Filter high-value cells using Polars\n",
+    "df_filtered = df_grid.filter(pl.col(\"value\") > 75)\n",
+    "print(f\"High-value cells: {len(df_filtered)}\")\n",
+    "\n",
+    "# Visualize\n",
+    "m = leafmap.Map(center=[0, 0], zoom=6)\n",
+    "m.add_polars(\n",
+    "    df_filtered,\n",
+    "    geometry=\"geometry\",\n",
+    "    crs=\"EPSG:4326\",\n",
+    "    layer_name=\"High Value Cells\",\n",
+    "    zoom_to_layer=True,\n",
+    "    style={\"fillColor\": \"red\", \"fillOpacity\": 0.5, \"color\": \"darkred\"},\n",
+    ")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Benefits of Polars Integration\n",
+    "\n",
+    "1. **Performance**: Polars is significantly faster than Pandas for large datasets\n",
+    "2. **Memory Efficiency**: Better memory management with Apache Arrow backend\n",
+    "3. **Native Pipeline**: Stay in Polars-native workflow end-to-end\n",
+    "4. **Modern API**: Expressive and intuitive query syntax\n",
+    "5. **GeoParquet Support**: Native support for reading/writing GeoParquet files\n",
+    "\n",
+    "## Next Steps\n",
+    "\n",
+    "- Explore [Polars-ST](https://github.com/Oreilles/polars-st) for advanced spatial operations\n",
+    "- Try [polars-h3](https://github.com/Filimoa/polars-h3) for H3 indexing workflows\n",
+    "- Read GeoParquet files directly with Polars for maximum performance"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "geo",
+   "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.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}