geoai-py 0.2.2__tar.gz → 0.3.0__tar.gz

{geoai_py-0.2.2 → geoai_py-0.3.0}/.gitignore

@@ -11,6 +11,9 @@ private/
 **/*.las
 *.geojson
 docs/examples/*.md
+*.xml
+docs/examples/output/
+docs/examples/*.png
 
 # Distribution / packaging
 .Python

{geoai_py-0.2.2 → geoai_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: geoai-py
-Version: 0.2.2
+Version: 0.3.0
 Summary: A Python package for using Artificial Intelligence (AI) with geospatial data
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT License
@@ -18,11 +18,13 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: albumentations
+Requires-Dist: contextily
 Requires-Dist: geopandas
 Requires-Dist: huggingface_hub
 Requires-Dist: jupyter-server-proxy
 Requires-Dist: leafmap
 Requires-Dist: localtileserver
+Requires-Dist: mapclassify
 Requires-Dist: overturemaps
 Requires-Dist: planetary-computer
 Requires-Dist: pystac-client

geoai_py-0.3.0/docs/examples/building_footprints_usa.ipynb

@@ -0,0 +1,278 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Building Footprint Extraction for the USA\n",
+    "\n",
+    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/geoai/blob/main/docs/examples/building_footprints_usa.ipynb)\n",
+    "\n",
+    "## Install package\n",
+    "To use the `geoai-py` package, ensure it is installed in your environment. Uncomment the command below if needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# %pip install geoai-py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import geoai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download sample data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "raster_url = (\n",
+    "    \"https://huggingface.co/datasets/giswqs/geospatial/resolve/main/naip_train.tif\"\n",
+    ")\n",
+    "vector_url = \"https://huggingface.co/datasets/giswqs/geospatial/resolve/main/naip_train_buildings.geojson\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "raster_path = geoai.download_file(raster_url)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "vector_path = geoai.download_file(vector_url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize building footprint extraction pretrained model\n",
+    "\n",
+    "The pretained model is adapted from the Esri [building footprint extraction](https://www.arcgis.com/home/item.html?id=a6857359a1cd44839781a4f113cd5934) model for the USA. Credits to Esri for the model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "extractor = geoai.BuildingFootprintExtractor()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Extract building footprints\n",
+    "\n",
+    "### Option 1: Extract building footprints as raster"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mask_path = extractor.save_masks_as_geotiff(\n",
+    "    raster_path=raster_path,\n",
+    "    output_path=\"building_masks.tif\",\n",
+    "    confidence_threshold=0.5,\n",
+    "    mask_threshold=0.5,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Convert raster to vector"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf = extractor.masks_to_vector(\n",
+    "    mask_path=mask_path,\n",
+    "    output_path=\"building_masks.geojson\",\n",
+    "    simplify_tolerance=1.0,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Option 2: Extract building footprints as vector"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "output_path = \"naip_buildings.geojson\"\n",
+    "gdf = extractor.process_raster(\n",
+    "    raster_path,\n",
+    "    output_path=\"buildings.geojson\",\n",
+    "    batch_size=4,\n",
+    "    confidence_threshold=0.5,\n",
+    "    overlap=0.25,\n",
+    "    nms_iou_threshold=0.5,\n",
+    "    small_building_area=100,\n",
+    "    mask_threshold=0.5,\n",
+    "    simplify_tolerance=1.0,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Regularize building footprints"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf_regularized = extractor.regularize_buildings(\n",
+    "    gdf=gdf,\n",
+    "    min_area=100,\n",
+    "    angle_threshold=15,\n",
+    "    orthogonality_threshold=0.3,\n",
+    "    rectangularity_threshold=0.7,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize building footprints"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf, column=\"confidence\", layer_name=\"Building\", tiles=\"Satellite\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf, column=\"confidence\", layer_name=\"Building\", tiles=raster_url\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf_regularized, column=\"confidence\", layer_name=\"Building\", tiles=raster_url\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "extractor.visualize_results(raster_path, gdf, output_path=\"naip_buildings.png\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "extractor.visualize_results(\n",
+    "    raster_path, gdf_regularized, output_path=\"naip_buildings_regularized.png\"\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "torch",
+   "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.11.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

geoai_py-0.3.0/docs/examples/building_regularization.ipynb

@@ -0,0 +1,257 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Building Regularization\n",
+    "\n",
+    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/geoai/blob/main/docs/examples/building_regularization.ipynb)\n",
+    "\n",
+    "## Install package\n",
+    "To use the `geoai-py` package, ensure it is installed in your environment. Uncomment the command below if needed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# %pip install geoai-py"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Import package"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import geoai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download sample data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "raster_url = \"https://huggingface.co/datasets/giswqs/geospatial/resolve/main/naip_building_masks.tif\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "raster_path = geoai.download_file(raster_url)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_image(raster_path, figsize=(18, 10))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Convert raster to vector"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf = geoai.raster_to_vector(raster_path, output_path=\"naip_building_masks.geojson\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf, style_kwds={\"color\": \"blue\", \"fillOpacity\": 0}, tiles=\"Satellite\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Building regularization"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf_regularized = geoai.regularization(\n",
+    "    building_polygons=gdf,\n",
+    "    angle_tolerance=10,\n",
+    "    simplify_tolerance=0.5,\n",
+    "    orthogonalize=True,\n",
+    "    preserve_topology=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf_regularized, style_kwds={\"color\": \"red\", \"fillOpacity\": 0}, tiles=\"Satellite\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Hybrid regularization"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf_hybrid = geoai.hybrid_regularization(gdf)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf_hybrid, style_kwds={\"color\": \"green\", \"fillOpacity\": 0}, tiles=\"Satellite\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Adaptive regularization"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf_adaptive = geoai.adaptive_regularization(\n",
+    "    building_polygons=gdf,\n",
+    "    simplify_tolerance=0.5,\n",
+    "    area_threshold=0.9,\n",
+    "    preserve_shape=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "geoai.view_vector_interactive(\n",
+    "    gdf_adaptive, style_kwds={\"color\": \"yellow\", \"fillOpacity\": 0}, tiles=\"Satellite\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Compare regularization methods"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import leafmap.foliumap as leafmap"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = leafmap.Map()\n",
+    "m.add_basemap(\"SATELLITE\")\n",
+    "m.add_gdf(gdf, layer_name=\"Original\")\n",
+    "m.add_gdf(\n",
+    "    gdf_regularized, style={\"color\": \"red\", \"fillOpacity\": 0}, layer_name=\"Regularized\"\n",
+    ")\n",
+    "m.add_gdf(gdf_hybrid, style={\"color\": \"green\", \"fillOpacity\": 0}, layer_name=\"Hybrid\")\n",
+    "m.add_gdf(\n",
+    "    gdf_adaptive, style={\"color\": \"yellow\", \"fillOpacity\": 0}, layer_name=\"Adaptive\"\n",
+    ")\n",
+    "legend = {\n",
+    "    \"Original\": \"blue\",\n",
+    "    \"Regularized\": \"red\",\n",
+    "    \"Hybrid\": \"green\",\n",
+    "    \"Adaptive\": \"yellow\",\n",
+    "}\n",
+    "m.add_legend(title=\"Building Footprints\", legend_dict=legend)\n",
+    "m"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "torch",
+   "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.11.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

{geoai_py-0.2.2 → geoai_py-0.3.0}/docs/examples/data_visualization.ipynb

@@ -40,7 +40,7 @@
    "source": [
     "from torchgeo.datasets import NAIP\n",
     "from torchgeo.samplers import RandomGeoSampler, GridGeoSampler\n",
-    "from geoai.common import viz_image, viz_raster, dict_to_image\n",
+    "from geoai.utils import view_image, view_raster, dict_to_image\n",
     "from geoai.download import download_naip"
    ]
   },
@@ -82,9 +82,9 @@
     "- **torchgeo.samplers**: Contains sampling strategies for geospatial data:\n",
     "  - **RandomGeoSampler**: Samples random patches from the dataset\n",
     "  - **GridGeoSampler**: Samples patches in a grid pattern with specified stride\n",
-    "- **geoai.common**: Custom utility functions for visualization:\n",
-    "  - **viz_image**: Visualizes tensor images\n",
-    "  - **viz_raster**: Displays georeferenced data on an interactive map\n",
+    "- **geoai.utils**: Custom utility functions for visualization:\n",
+    "  - **view_image**: Visualizes tensor images\n",
+    "  - **view_raster**: Displays georeferenced data on an interactive map\n",
     "  - **dict_to_image**: Converts dictionary representation to image format\n",
     "\n",
     "## Setting Up the Dataset"
@@ -230,7 +230,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "viz_image(\n",
+    "view_image(\n",
     "    train_image, transpose=True, scale_factor=(1 / 250), title=\"Random GeoSampler\"\n",
     ")"
    ]
@@ -307,7 +307,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "viz_image(test_image, transpose=True, scale_factor=(1 / 250), title=\"Grid GeoSampler\")"
+    "view_image(test_image, transpose=True, scale_factor=(1 / 250), title=\"Grid GeoSampler\")"
    ]
   },
   {
@@ -343,7 +343,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "viz_raster(data, basemap=\"Google Satellite\")"
+    "view_raster(data, basemap=\"Google Satellite\")"
    ]
   },
   {
@@ -356,7 +356,7 @@
     "\n",
     "1. **TorchGeo** provides a flexible framework for working with geospatial datasets like NAIP.\n",
     "2. Different sampling strategies (random vs. grid) serve different purposes in geospatial machine learning workflows.\n",
-    "3. Visualization tools help understand the data in both pixel space (viz_image) and geographic space (viz_raster).\n",
+    "3. Visualization tools help understand the data in both pixel space (view_image) and geographic space (view_raster).\n",
     "4. Working with geospatial data requires attention to coordinate reference systems (CRS) and proper handling of georeferenced data."
    ]
   }