feat: Optional imports (#420)

guillemc23 · Moreno Castaño, Guillermo · pre-commit-ci[bot] · web-flow · commit e54c3f00482f · 2025-09-22T13:50:51.000-04:00
* feat: First approach to optimizing imports * fix: Fixed OpenCV headless package name * fix: Added core imports to `requirements.txt` * fix: Added `samgeo2` missing import * fix: Validates SAMGeo 2 * chore: Refactor package requirements * fix: Optimized imports, code cleanup and notebooks to reflect changes * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * chore: Add docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix: Update tests with new syntax * fix: Update `requirements.txt` * fix: Add torchvision to `requirements.txt` * fix: Revert package version to 0.12.6 * Update segment-anything-fast dependency in pyproject.tom * Fix typo in fast dependencies list --------- Co-authored-by: Moreno Castaño, Guillermo <gmcastano@indra.es> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Qiusheng Wu <giswqs@gmail.com>
diff --git a/README.md b/README.md
@@ -42,11 +42,28 @@ The **segment-geospatial** package draws its inspiration from [segment-anything-
 
 ### Install from PyPI
 
-**segment-geospatial** is available on [PyPI](https://pypi.org/project/segment-geospatial/). To install **segment-geospatial**, run this command in your terminal:
+**segment-geospatial** is available on [PyPI](https://pypi.org/project/segment-geospatial/) and can be installed in several ways so that its dependencies can be controlled more granularly. This reduces package size for CI environments, since not every time all of the models will be used.
+
+Depending on what tools you need to use, you might want to do:
+* `segment-geospatial` or `segment-geospatial[samgeo]`: Installs only the minimum required dependencies to run SAMGeo
+* `segment-geospatial[samgeo2]`: Installs the dependencies to run SAMGeo 2
+* `segment-geospatial[fast]`: Installs the dependencies to run Fast SAM
+* `segment-geospatial[hq]`: Installs the dependencies to run HQ-SAM
+* `segment-geospatial[text]`: Installs Grounding DINO to use SAMGeo 1 and 2 with text prompts
+* `segment-geospatial[fer]`: Installs the dependencies to run the feature
+edge reconstruction algorithm
+
+Additionally, these other two optional imports are defined:
+* `segment-geospatial[all]`: Installs the dependencies to run all of the SAMGeo models
+* `segment-geospatial[extra]`: Installs the dependencies to run all of the SAMGeo models and other utilities to run the examples like Jupyter notebook support, `leafmap`, etc.
+
+Simply running the following should install the dependencies for each use case:
 
 ```bash
-pip install segment-geospatial
+pip install segment-geospatial[samgeo2] # Or any other choice of the above
 ```
+To see more in detail what packages come with each choice, please refer to `pyproject.toml`.
+
 
 ### Install from conda-forge
 
diff --git a/docs/examples/automatic_mask_generator.ipynb b/docs/examples/automatic_mask_generator.ipynb
@@ -40,9 +40,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo import SamGeo, show_image, download_file, overlay_images, tms_to_geotiff"
+    "from samgeo import SamGeo\n",
+    "from samgeo.common import overlay_images, tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/automatic_mask_generator_hq.ipynb b/docs/examples/automatic_mask_generator_hq.ipynb
@@ -36,15 +36,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo.hq_sam import (\n",
-    "    SamGeo,\n",
-    "    show_image,\n",
-    "    download_file,\n",
-    "    overlay_images,\n",
-    "    tms_to_geotiff,\n",
-    ")"
+    "from samgeo.hq_sam import SamGeo\n",
+    "from samgeo.common import overlay_images, tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/box_prompts.ipynb b/docs/examples/box_prompts.ipynb
@@ -39,7 +39,7 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import tms_to_geotiff\n",
+    "from samgeo.common import tms_to_geotiff\n",
     "from samgeo import SamGeo"
    ]
   },
diff --git a/docs/examples/fast_sam.ipynb b/docs/examples/fast_sam.ipynb
@@ -39,8 +39,7 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import tms_to_geotiff\n",
-    "from samgeo.fast_sam import SamGeo"
+    "from samgeo.common import tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/input_prompts.ipynb b/docs/examples/input_prompts.ipynb
@@ -40,9 +40,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo import SamGeo, tms_to_geotiff"
+    "from samgeo import SamGeo\n",
+    "from samgeo.common import tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/input_prompts_hq.ipynb b/docs/examples/input_prompts_hq.ipynb
@@ -38,9 +38,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo.hq_sam import SamGeo, tms_to_geotiff"
+    "from samgeo.hq_sam import SamGeo\n",
+    "from samgeo.common import tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/maxar_open_data.ipynb b/docs/examples/maxar_open_data.ipynb
@@ -41,9 +41,9 @@
    },
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo import SamGeo, raster_to_vector, overlay_images"
+    "from samgeo import SamGeo\n",
+    "from samgeo.common import raster_to_vector, overlay_images"
    ]
   },
   {
diff --git a/docs/examples/sam2_box_prompts.ipynb b/docs/examples/sam2_box_prompts.ipynb
@@ -39,7 +39,8 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import SamGeo2, raster_to_vector, regularize"
+    "from samgeo import SamGeo2\n",
+    "from samgeo.common import raster_to_vector, regularize"
    ]
   },
   {
diff --git a/docs/examples/sam2_point_prompts.ipynb b/docs/examples/sam2_point_prompts.ipynb
@@ -46,7 +46,8 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import SamGeo2, regularize"
+    "from samgeo import SamGeo2\n",
+    "from samgeo.common import regularize"
    ]
   },
   {
diff --git a/docs/examples/satellite-predictor.ipynb b/docs/examples/satellite-predictor.ipynb
@@ -54,7 +54,8 @@
    "source": [
     "import os\n",
     "import leafmap\n",
-    "from samgeo import SamGeoPredictor, tms_to_geotiff, get_basemaps\n",
+    "from samgeo import SamGeoPredictor\n",
+    "from samgeo.common import tms_to_geotiff\n",
     "from segment_anything import sam_model_registry"
    ]
   },
diff --git a/docs/examples/satellite.ipynb b/docs/examples/satellite.ipynb
@@ -50,9 +50,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import leafmap\n",
-    "from samgeo import SamGeo, tms_to_geotiff, get_basemaps"
+    "from samgeo import SamGeo\n",
+    "from samgeo.common import tms_to_geotiff"
    ]
   },
   {
diff --git a/docs/examples/text_prompts.ipynb b/docs/examples/text_prompts.ipynb
@@ -39,7 +39,7 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import tms_to_geotiff\n",
+    "from samgeo.common import tms_to_geotiff\n",
     "from samgeo.text_sam import LangSAM"
    ]
   },
diff --git a/docs/examples/text_prompts_batch.ipynb b/docs/examples/text_prompts_batch.ipynb
@@ -39,7 +39,7 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import tms_to_geotiff, split_raster\n",
+    "from samgeo.common import tms_to_geotiff, split_raster\n",
     "from samgeo.text_sam import LangSAM"
    ]
   },
diff --git a/docs/examples/text_swimming_pools.ipynb b/docs/examples/text_swimming_pools.ipynb
@@ -39,7 +39,7 @@
    "outputs": [],
    "source": [
     "import leafmap\n",
-    "from samgeo import tms_to_geotiff\n",
+    "from samgeo.common import tms_to_geotiff\n",
     "from samgeo.text_sam import LangSAM"
    ]
   },
diff --git a/pyproject.toml b/pyproject.toml
@@ -26,7 +26,62 @@ classifiers = [
 authors = [{name = "Qiusheng Wu", email = "giswqs@gmail.com"}]
 
 [project.optional-dependencies]
-all = ["groundingdino-py"]
+core = [
+    "gdown",
+    "geopandas",
+    "numpy",
+    "opencv-python-headless",
+    "patool",
+    "Pillow",
+    "pyproj>=3.7.2",
+    "rasterio",
+    "segment_anything",
+    "shapely",
+    "torch",
+    "tqdm",
+]
+fast = [
+    "segment_geospatial[core]",
+    "segment-anything-fast",
+    "sam2",
+    ]
+fer = [
+    "segment_geospatial[core]",
+    "gdal",
+    ]
+hq = [
+    "segment_geospatial[core]",
+    "segment_anything_hq",
+    "sam2",
+    "timm",
+    ]
+samgeo = [
+    "segment_geospatial[core]",
+    "huggingface_hub",
+]
+samgeo2 = [
+    "segment_geospatial[samgeo]",
+    "sam2",
+    "xarray",
+    "rioxarray",
+    "scikit-image",
+    "scipy",
+]
+text = [
+    "segment_geospatial[samgeo2]",
+    "groundingdino-py",
+]
+all = [
+    "segment-geospatial[fast, hq, fer, samgeo, samgeo2, text]",
+]
+extra = [
+    "leafmap",
+    "segment-geospatial[all]",
+    "localtileserver",
+    "ipykernel",
+    "fiona",
+    "matplotlib",
+]
 
 [tool]
 [tool.setuptools.packages.find]
@@ -64,4 +119,4 @@ max-line-length = 88
 [tool.setuptools_scm]
 
 [project.urls]
-Homepage = "https://github.com/opengeos/segment-geospatial"
+Homepage = "https://github.com/opengeos/segment-geospatial"
diff --git a/requirements.txt b/requirements.txt
@@ -1,23 +1,15 @@
-fiona
 gdown
 geopandas
 huggingface_hub
-ipympl
-leafmap
-localtileserver
-matplotlib
+numpy
 opencv-python-headless
 patool
-pycocotools
+Pillow
 pyproj
 rasterio
-rioxarray
-sam2
-scikit-image
-scikit-learn
-segment-anything-hq
-segment-anything-py
-timm
+segment_anything
+shapely
+torch
+torchvision
 tqdm
-xarray
 xyzservices
diff --git a/samgeo/__init__.py b/samgeo/__init__.py
@@ -5,6 +5,5 @@
 __version__ = "0.12.6"
 
 
-from .samgeo import *
-from .samgeo2 import *
-from .common import show_image_gui
+from .samgeo import *  # noqa: F403
+from .samgeo2 import *  # noqa: F403
diff --git a/samgeo/common.py b/samgeo/common.py
diff --git a/samgeo/fast_sam.py b/samgeo/fast_sam.py
diff --git a/samgeo/fer.py b/samgeo/fer.py
diff --git a/samgeo/hq_sam.py b/samgeo/hq_sam.py
diff --git a/samgeo/samgeo.py b/samgeo/samgeo.py
diff --git a/samgeo/samgeo2.py b/samgeo/samgeo2.py
diff --git a/samgeo/text_sam.py b/samgeo/text_sam.py
diff --git a/tests/test_common.py b/tests/test_common.py
diff --git a/tests/test_samgeo.py b/tests/test_samgeo.py

Original file line number	Diff line number	Diff line change
`@@ -40,9 +40,9 @@`
`40`	`40`	`"metadata": {},`
`41`	`41`	`"outputs": [],`
`42`	`42`	`"source": [`
`43`		`- "import os\n",`
`44`	`43`	`"import leafmap\n",`
`45`		`- "from samgeo import SamGeo, show_image, download_file, overlay_images, tms_to_geotiff"`
	`44`	`+ "from samgeo import SamGeo\n",`
	`45`	`+ "from samgeo.common import overlay_images, tms_to_geotiff"`
`46`	`46`	`]`
`47`	`47`	`},`
`48`	`48`	`{`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@`
`39`	`39`	`"outputs": [],`
`40`	`40`	`"source": [`
`41`	`41`	`"import leafmap\n",`
`42`		`- "from samgeo import tms_to_geotiff\n",`
	`42`	`+ "from samgeo.common import tms_to_geotiff\n",`
`43`	`43`	`"from samgeo import SamGeo"`
`44`	`44`	`]`
`45`	`45`	`},`
Original file line number	Diff line number	Diff line change
`@@ -39,8 +39,7 @@`
`39`	`39`	`"outputs": [],`
`40`	`40`	`"source": [`
`41`	`41`	`"import leafmap\n",`
`42`		`- "from samgeo import tms_to_geotiff\n",`
`43`		`- "from samgeo.fast_sam import SamGeo"`
	`42`	`+ "from samgeo.common import tms_to_geotiff"`
`44`	`43`	`]`
`45`	`44`	`},`
`46`	`45`	`{`
Original file line number	Diff line number	Diff line change
`@@ -38,9 +38,9 @@`
`38`	`38`	`"metadata": {},`
`39`	`39`	`"outputs": [],`
`40`	`40`	`"source": [`
`41`		`- "import os\n",`
`42`	`41`	`"import leafmap\n",`
`43`		`- "from samgeo.hq_sam import SamGeo, tms_to_geotiff"`
	`42`	`+ "from samgeo.hq_sam import SamGeo\n",`
	`43`	`+ "from samgeo.common import tms_to_geotiff"`
`44`	`44`	`]`
`45`	`45`	`},`
`46`	`46`	`{`
Original file line number	Diff line number	Diff line change
`@@ -41,9 +41,9 @@`
`41`	`41`	`},`
`42`	`42`	`"outputs": [],`
`43`	`43`	`"source": [`
`44`		`- "import os\n",`
`45`	`44`	`"import leafmap\n",`
`46`		`- "from samgeo import SamGeo, raster_to_vector, overlay_images"`
	`45`	`+ "from samgeo import SamGeo\n",`
	`46`	`+ "from samgeo.common import raster_to_vector, overlay_images"`
`47`	`47`	`]`
`48`	`48`	`},`
`49`	`49`	`{`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,8 @@`
`39`	`39`	`"outputs": [],`
`40`	`40`	`"source": [`
`41`	`41`	`"import leafmap\n",`
`42`		`- "from samgeo import SamGeo2, raster_to_vector, regularize"`
	`42`	`+ "from samgeo import SamGeo2\n",`
	`43`	`+ "from samgeo.common import raster_to_vector, regularize"`
`43`	`44`	`]`
`44`	`45`	`},`
`45`	`46`	`{`
Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,8 @@`
`46`	`46`	`"outputs": [],`
`47`	`47`	`"source": [`
`48`	`48`	`"import leafmap\n",`
`49`		`- "from samgeo import SamGeo2, regularize"`
	`49`	`+ "from samgeo import SamGeo2\n",`
	`50`	`+ "from samgeo.common import regularize"`
`50`	`51`	`]`
`51`	`52`	`},`
`52`	`53`	`{`