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

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

@@ -13,6 +13,7 @@ private/
 docs/examples/*.md
 *.xml
 docs/examples/output/
+docs/examples/*.png
 
 # Distribution / packaging
 .Python

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: geoai-py
-Version: 0.2.3
+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

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.3 → 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 view_image, view_raster, dict_to_image\n",
+    "from geoai.utils import view_image, view_raster, dict_to_image\n",
     "from geoai.download import download_naip"
    ]
   },
@@ -82,7 +82,7 @@
     "- **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",
+    "- **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",

geoai_py-0.3.0/docs/utils.md

@@ -0,0 +1,3 @@
+# utils module
+
+::: geoai.utils

{geoai_py-0.2.3 → geoai_py-0.3.0}/geoai/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 
 
 import os