Merge pull request #802 from henrykironde/predict-docs

Predict docs should state returns a Pandas DataFram

deepforest/_version.py

@@ -1 +1 @@
-__version__ = '1.4.0-dev0'
+__version__ = '1.4.0-dev0'

deepforest/main.py

@@ -501,12 +501,19 @@ def predict_tile(self,
             (deprecated) color: color of the bounding box as a tuple of BGR color, e.g. orange annotations is (0, 165, 255)
             (deprecated) thickness: thickness of the rectangle border line in px
 
-        Deprecation: The return_plot argument is deprecated and will be removed in 2.0. Use visualize.plot_results on the result instead.
+        Deprecated Args:
+            - return_plot: Deprecated in favor of using `visualize.plot_results` for
+              rendering predictions. Will be removed in version 2.0.
+            - color: Deprecated bounding box color for visualizations.
+            - thickness: Deprecated bounding box thickness for visualizations.
 
         Returns:
-            boxes (array): if return_plot, an image.
-            Otherwise a numpy array of predicted bounding boxes, scores and labels
-            If no predictions are made, returns None
+            - If `return_plot` is True, returns an image with predictions overlaid (deprecated).
+            - If `mosaic` is True, returns a Pandas DataFrame containing the predicted
+              bounding boxes, scores, and labels.
+            - If `mosaic` is False, returns a list of tuples where each tuple contains
+              a DataFrame of predictions and its corresponding image crop.
+            - Returns None if no predictions are made.
         """
         self.model.eval()
         self.model.nms_thresh = self.config["nms_thresh"]
@@ -553,9 +560,8 @@ def predict_tile(self,
                 results["image_path"] = os.path.basename(raster_path)
             if return_plot:
                 # Add deprecated warning
-                warnings.warn(
-                    "return_plot is deprecated and will be removed in 2.0. Use visualize.plot_results on the result instead."
-                )
+                warnings.warn("return_plot is deprecated and will be removed in 2.0. "
+                              "Use visualize.plot_results on the result instead.")
                 # Draw predictions on BGR
                 if raster_path:
                     tile = rio.open(raster_path).read()

docs/conf.py

@@ -29,22 +29,28 @@
 """
 
 file_path = 'user_guide/deepforestr.md'
+json_url = 'https://raw.githubusercontent.com/weecology/DeepForest/refs/heads/main/version_switcher.json'
 readme_url = 'https://raw.githubusercontent.com/weecology/deepforestr/main/README.md'
 
 with open(file_path, 'w') as file_obj:
     file_obj.write(deepforestr_title)
 
-    with urllib.request.urlopen(readme_url) as response:
-        lines = response.readlines()
-        badge_section = True
-        for line in lines:
-            line = line.decode("utf-8")
-            if "## Installation" in line:
-                badge_section = False
-            if not badge_section:
-                file_obj.write(line)
-
-# Sphinx configuration
+    try:
+        with urllib.request.urlopen(readme_url) as response:
+            lines = response.readlines()
+            badge_section = True
+            for line in lines:
+                line = line.decode("utf-8")
+                if "## Installation" in line:
+                    badge_section = False
+                if not badge_section:
+                    file_obj.write(line)
+    except Exception as e:
+        print(f"Could not retrieve the deepforestr README, skipping")
+        json_url = "../version_switcher.json"
+
+
+    # Sphinx configuration
 needs_sphinx = "1.8"
 autodoc_default_options = {'members': None, 'show-inheritance': None}
 autodoc_member_order = 'groupwise'
@@ -76,7 +82,6 @@
 
 # HTML output options
 html_theme = 'pydata_sphinx_theme'
-json_url = 'https://raw.githubusercontent.com/weecology/DeepForest/refs/heads/main/version_switcher.json'
 
 if ".dev" in version:
     switcher_version = "dev"

docs/getting_started/intro_tutorials/04_predict_large_tile.rst

@@ -21,11 +21,8 @@ Let’s show an example with a small image. For larger images, patch_size should
    model.load_model(model_name="weecology/deepforest-tree", revision="main")
    # Predict on large geospatial tiles using overlapping windows
    raster_path = get_data("OSBS_029.tif")
-   predicted_raster = model.predict_tile(raster_path, return_plot=True, patch_size=300, patch_overlap=0.25)
-
-   # View boxes overlaid when return_plot=True; otherwise, boxes are returned
-   plt.imshow(predicted_raster)
-   plt.show()
+   predicted_raster = model.predict_tile(raster_path, patch_size=300, patch_overlap=0.25)
+   plot_results(results)
 
 .. note::