samgis_core 3.0.4__tar.gz → 3.0.6__tar.gz

{samgis_core-3.0.4 → samgis_core-3.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: samgis_core
-Version: 3.0.4
+Version: 3.0.6
 Summary: SamGIS CORE
 License: MIT
 Author: alessandro trinca tornidor

{samgis_core-3.0.4 → samgis_core-3.0.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "samgis_core"
-version = "3.0.4"
+version = "3.0.6"
 description = "SamGIS CORE"
 authors = ["alessandro trinca tornidor <alessandro@trinca.tornidor.com>"]
 license = "MIT license"
@@ -8,7 +8,7 @@ readme = "README.md"
 
 [metadata]
 name = "samgis_core"
-version = "3.0.4"
+version = "3.0.6"
 
 [tool.poetry.urls]
 Source = "https://gitlab.com/aletrn/samgis_core"

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/prediction_api/sam_onnx2.py

@@ -37,7 +37,7 @@ from samgis_core.utilities.utilities import convert_ndarray_to_pil, apply_coords
 
 class SegmentAnythingONNX2:
     """
-    Segmentation model using SegmentAnything.
+    Segmentation model using Segment Anything.
     Compatible with onnxruntime 1.17.x and later
     """
 
@@ -68,8 +68,17 @@ class SegmentAnythingONNX2:
         )
 
     @staticmethod
-    def get_input_points(prompt: ListDict):
-        """Get input points"""
+    def get_input_points(prompt: ListDict) -> tuple[ndarray]:
+        """
+        Get input points from a prompt dict list.
+
+        Args:
+            prompt: dict list
+
+        Returns:
+            tuple of points, labels ndarray ready for Segment Anything inference
+
+        """
         points = []
         labels = []
         for mark in prompt:
@@ -95,11 +104,12 @@ class SegmentAnythingONNX2:
 
         Returns:
             embedding image dict useful to store and cache image embeddings
+
         """
         resized_image = self.preprocess_image(img)
         padded_input_tensor = self.padding_tensor(resized_image)
 
-        # 2. GET IMAGE EMBEDDINGS USING IMAGE ENCODER
+        # 2. GET IMAGE EMBEDDINGS USING IMAGE ENCODER (`size` argument here is like ndarray `shape`)
         outputs = self.encoder_session.run(None, {"images": padded_input_tensor})
         image_embedding = outputs[0]
         img = convert_ndarray_to_pil(img)
@@ -109,9 +119,17 @@ class SegmentAnythingONNX2:
             "resized_size": resized_image.size
         }
 
-    def predict_masks(self, embedding: EmbeddingPILImage, prompt: ListDict):
+    def predict_masks(self, embedding: EmbeddingPILImage, prompt: ListDict) -> ndarray:
         """
         Predict masks for a single image.
+
+        Args:
+            embedding: input image embedding dict
+            prompt: Segment Anything input prompt
+
+        Returns:
+            prediction masks ndarray; this should have (1, 1, **image.shape) shape
+
         """
         input_points, input_labels = self.get_input_points(prompt)
 
@@ -136,8 +154,17 @@ class SegmentAnythingONNX2:
         })
         return output_masks
 
-    def preprocess_image(self, img: PIL_Image | ndarray):
-        """Resize image preserving aspect ratio using 'output_size_target' as a long side"""
+    def preprocess_image(self, img: PIL_Image | ndarray) -> ndarray:
+        """
+        Resize image preserving aspect ratio using `output_size_target` as a long side.
+
+        Args:
+            img: input ndarray/PIL image
+
+        Returns:
+            image ndarray
+
+        """
         from PIL import Image
 
         app_logger.info(f"image type:{type(img)}, shape/size:{img.size}.")
@@ -157,7 +184,17 @@ class SegmentAnythingONNX2:
         img = img.resize((resized_width, resized_height), Image.Resampling.BILINEAR)
         return img
 
-    def padding_tensor(self, img: PIL_Image | ndarray):
+    def padding_tensor(self, img: PIL_Image | ndarray) -> ndarray:
+        """
+        Pad an image ndarray/tensor to given instance self.target_size
+
+        Args:
+            img: input ndarray/PIL image
+
+        Returns:
+            image ndarray
+
+        """
         # Prepare input tensor from image
         tensor_input = np_array(img)
         resized_width, resized_height = img.size

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/prediction_api/sam_onnx_inference.py

@@ -20,6 +20,7 @@ def get_raster_inference(
 
     Returns:
         raster prediction mask, prediction number
+
     """
     np_img = np_array(img)
     app_logger.info(f"img type {type(np_img)}, prompt:{prompt}.")
@@ -49,6 +50,7 @@ def get_inference_embedding(
 
     Returns:
         raster dict
+
     """
     if embedding_key in embedding_dict:
         app_logger.info("found embedding in dict...")
@@ -68,7 +70,8 @@ def get_inference_embedding(
 
 
 def get_raster_inference_using_existing_embedding(
-        embedding: dict, prompt: ListDict, models_instance: SegmentAnythingONNX2) -> TupleNdarrayInt:
+        embedding: dict, prompt: ListDict, models_instance: SegmentAnythingONNX2, folder_write_tmp_on_disk: str = None,
+        key: str = None) -> TupleNdarrayInt:
     """
     Get inference output for a given image using a SegmentAnythingONNX model, using an existing embedding instead of a
     new ndarray or PIL image
@@ -77,9 +80,12 @@ def get_raster_inference_using_existing_embedding(
         embedding: dict
         prompt: list of prompt dict
         models_instance: SegmentAnythingONNX instance model
+        folder_write_tmp_on_disk: output folder where to write debug images
+        key: embedding key
 
     Returns:
         raster prediction mask, prediction number
+
     """
     app_logger.info(f"using existing embedding of type {type(embedding)}.")
     inference_out = models_instance.predict_masks(embedding, prompt)
@@ -87,16 +93,27 @@ def get_raster_inference_using_existing_embedding(
     app_logger.info(f"Created {len_inference_out} prediction_masks,"
                     f"shape:{inference_out.shape}, dtype:{inference_out.dtype}.")
     mask = zeros((inference_out.shape[2], inference_out.shape[3]), dtype=uint8)
+    write_tmp_img = bool(folder_write_tmp_on_disk)
     for n, m in enumerate(inference_out[0, :, :, :]):
         app_logger.debug(f"{n}th of prediction_masks shape {inference_out.shape}"
                          f" => mask shape:{mask.shape}, {mask.dtype}.")
         mask[m > 0.0] = 255
+        if write_tmp_img:
+            from pathlib import Path
+            from datetime import datetime
+            from samgis_core.utilities.utilities import convert_ndarray_to_pil, normalize_array
+            m_normalized = normalize_array(m, type_normalization="float")
+            m_out = convert_ndarray_to_pil(m_normalized)
+            now = datetime.now().isoformat()
+            if len(m.shape) == 2:
+                m_out = m_out.convert("L")
+            m_out.save(Path(folder_write_tmp_on_disk) / f"mask_{key}_{now}_n{n}.png")
     return mask, len_inference_out
 
 
 def get_raster_inference_with_embedding_from_dict(
         img: PIL_Image | ndarray, prompt: ListDict, models_instance: SegmentAnythingONNX2, model_name: str,
-        embedding_key: str, embedding_dict: dict) -> TupleNdarrayInt:
+        embedding_key: str, embedding_dict: dict, folder_write_tmp_on_disk: str = None) -> TupleNdarrayInt:
     """
     Get inference output using a SegmentAnythingONNX model, but get the image embedding from the given embedding dict
      instead of creating a new embedding. This function needs the img argument to update the embedding dict if necessary
@@ -108,9 +125,11 @@ def get_raster_inference_with_embedding_from_dict(
         model_name: model name string
         embedding_key: embedding id
         embedding_dict: embedding images dict
+        folder_write_tmp_on_disk: output folder where to write debug images
 
     Returns:
         raster prediction mask, prediction number
+
     """
     app_logger.info(f"handling embedding using key {embedding_key}.")
     embedding_dict = get_inference_embedding(img, models_instance, model_name, embedding_key, embedding_dict)
@@ -118,4 +137,5 @@ def get_raster_inference_with_embedding_from_dict(
     embedding = embedding_dict[embedding_key]
     n_keys = len(embedding_dict)
     app_logger.info(f"embedding created ({n_keys} keys in embedding dict), running predict_masks with prompt {prompt}.")
-    return get_raster_inference_using_existing_embedding(embedding, prompt, models_instance)
+    return get_raster_inference_using_existing_embedding(
+        embedding, prompt, models_instance, folder_write_tmp_on_disk=folder_write_tmp_on_disk, key=embedding_key)

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/utilities/create_folders_if_not_exists.py

@@ -10,6 +10,14 @@ def stats_pathname(pathname: Path | str):
 
 
 def create_folder_if_not_exists(pathname: Path | str):
+    """Create a folder given its path.
+
+    Args:
+        pathname: folder Path or string
+
+    Returns:
+
+    """
     current_pathname = Path(pathname)
     try:
         print(f"Pathname exists? {current_pathname.exists()}, That's a folder? {current_pathname.is_dir()}...")
@@ -32,6 +40,18 @@ def create_folder_if_not_exists(pathname: Path | str):
 
 
 def folders_creation(folders_map: dict | str = None, ignore_errors: bool = True):
+    """Create all folders listed within the folders_map argument (this argument can be a dict or a json string).
+    If folders_map is None the function will try to load the 'FOLDERS_MAP' env variable, then will load that json into
+    dict. Once loaded and parsed the folders_map variable, the function will loop over the dict to create the folders
+    using the `create_folder_if_not_exists()` function.
+
+    Args:
+        folders_map: dict or string map of folder string
+        ignore_errors: bool needed to eventually ignore errors on folder creation
+
+    Returns:
+
+    """
     enforce_validation_with_getenv = folders_map is None
     if enforce_validation_with_getenv:
         folders_map = os.getenv("FOLDERS_MAP")

samgis_core-3.0.6/samgis_core/utilities/plot_images.py

@@ -0,0 +1,99 @@
+import structlog.stdlib
+from numpy import ndarray
+from matplotlib import pyplot as plt
+
+from samgis_core.utilities.type_hints import ListStr, MatplotlibBackend
+
+FigAxes = tuple[plt.Figure, plt.Axes]
+
+
+logger = structlog.stdlib.get_logger(__file__)
+
+
+def helper_imshow_output_expected(
+        img_list: list[ndarray], titles_list: ListStr, cmap: str = "gist_rainbow", plot_size: int = 5,
+        show=False, debug: bool = False, close_after: float = 0.0) -> FigAxes:
+    """
+    Simple way to display a list of images with their titles, color map.
+    Should work also in an automate environments, like tests (use a `close_after` argument > 0)
+
+    Args:
+        img_list: ndarray images to display
+        titles_list: title images
+        cmap: color map
+        plot_size: figure plot size
+        show: fire plt.show() action if needed
+        debug: workaround useful in an interactive context, like Pycharm debugger
+        close_after: close after give seconds (useful in tests, contrasted to 'debug' option)
+
+    Returns:
+        tuple of matplotlib Figure, Axes
+
+    """
+    n = len(img_list)
+    assert len(titles_list) == n
+    fig, ax = plt.subplot_mosaic([
+        titles_list
+    ], figsize=(n * plot_size, plot_size))
+
+    for title, img in zip(titles_list, img_list):
+        ax[title].imshow(img, cmap=cmap)
+        ax[title].legend()
+    if show:
+        if debug:
+            plt.pause(0.01)
+            plt.show()
+        if close_after > 0:
+            plt.pause(close_after)
+            plt.show(block=False)
+            plt.close("all")
+    return fig, ax
+
+
+def imshow_raster(
+        raster, title, cmap: str = "gist_rainbow", interpolation: str = None, alpha=None, transform=None, plot_size=5,
+        show=False, debug: bool = False, close_after: float = 0.0, backend: MatplotlibBackend = None) -> FigAxes:
+    """
+    Displays raster images lists/arrays with titles, legend, alpha transparency, figure sizes
+    and geographic transformations, if not none (leveraging rasterio.plot)
+
+    Args:
+        raster: image to display
+        title: title image
+        cmap: color map
+        interpolation: interpolation type
+        alpha: alpha transparency
+        transform: geographic transform, eventually used for map representation by rasterio
+        plot_size: figure plot size
+        show: fire plt.show() action if needed
+        debug: workaround useful in an interactive context, like Pycharm debugger
+        close_after: close after give seconds (useful in tests, contrasted to 'debug' option)
+        backend: matplotlib backend string
+
+    Returns:
+        tuple of matplotlib Figure, Axes
+
+    """
+    from rasterio import plot
+
+    if not backend:
+        backend = plt.get_backend()
+        plt.rcParams["backend"] = backend
+    logger.info(f"use {backend} as matplotlib backend...")
+
+    fig, ax = plt.subplots(figsize=(plot_size, plot_size))
+    raster_ax = raster[0] if transform is not None else raster
+    image_hidden = ax.imshow(raster_ax, cmap=cmap, interpolation=interpolation, alpha=alpha)
+    if transform is not None:
+        plot.show(raster, transform=transform, ax=ax, cmap=cmap, interpolation=interpolation, alpha=alpha)
+    fig.colorbar(image_hidden, ax=ax)
+    ax.set_title(title)
+    if show:
+        if debug:
+            plt.pause(0.01)
+            plt.show()
+        if close_after > 0:
+            plt.pause(close_after)
+            plt.show(block=False)
+            plt.close("all")
+    return fig, ax

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/utilities/session_logger.py

@@ -27,6 +27,20 @@ def drop_color_message_key(_, __, event_dict: EventDict) -> EventDict:
 
 
 def setup_logging(json_logs: bool = False, log_level: str = "INFO"):
+    """Enhance the configuration of structlog.
+    Needed for correlation id injection with fastapi middleware in samgis-web.
+    After the use of logging_middleware() in samgis_web.web.middlewares, add also the CorrelationIdMiddleware from
+    'asgi_correlation_id' package. (See 'tests/web/test_middlewares.py' in samgis_web).
+    To change an input parameter like the log level, re-run the function changing the parameter
+    (no need to re-instantiate the logger instance: it's a hot change)
+
+    Args:
+        json_logs: set logs in json format
+        log_level: log level string
+
+    Returns:
+
+    """
     timestamper = structlog.processors.TimeStamper(fmt="iso")
 
     shared_processors: list[Processor] = [

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/utilities/type_hints.py

@@ -67,5 +67,32 @@ class EmbeddingPILImage(TypedDict):
     resized_size: TupleInt2
 
 
+class MatplotlibBackend(StrEnum):
+    gtk3agg = "gtk3agg"
+    gtk3cairo = "gtk3cairo"
+    gtk4agg = "gtk4agg"
+    gtk4cairo = "gtk4cairo"
+    macosx = "macosx"
+    nbagg = "nbagg"
+    notebook = "notebook"
+    qtagg = "qtagg"
+    qtcairo = "qtcairo"
+    qt5agg = "qt5agg"
+    qt5cairo = "qt5cairo"
+    tkagg = "tkagg"
+    tkcairo = "tkcairo"
+    webagg = "webagg"
+    wx = "wx"
+    wxagg = "wxagg"
+    wxcairo = "wxcairo"
+    agg = "agg"
+    cairo = "cairo"
+    pdf = "pdf"
+    pgf = "pgf"
+    ps = "ps"
+    svg = "svg"
+    template = "template"
+
+
 EmbeddingDict = dict[str, EmbeddingImage]
 EmbeddingPILDict = dict[str, EmbeddingPILImage]

{samgis_core-3.0.4 → samgis_core-3.0.6}/samgis_core/utilities/utilities.py

@@ -1,6 +1,7 @@
 """Various utilities (logger, time benchmark, args dump, numerical and stats info)"""
 from copy import deepcopy
 
+import numpy as np
 from numpy import ndarray, float32
 
 from samgis_core import app_logger
@@ -98,6 +99,16 @@ def hash_calculate(arr) -> str | bytes:
 
 
 def convert_ndarray_to_pil(pil_image: PIL_Image | ndarray):
+    """
+    Check if an image is a ndarray and then convert to a PIL Image instance.
+
+    Args:
+        pil_image: PIL image or ndarray
+
+    Returns:
+        PIL Image
+
+    """
     from PIL import Image
 
     if isinstance(pil_image, ndarray):
@@ -109,6 +120,14 @@ def apply_coords(coords: ndarray, embedding: EmbeddingPILImage):
     """
     Expects a numpy np_array of length 2 in the final dimension. Requires the
     original image size in (H, W) format.
+
+        Args:
+            coords: coordinates ndarray
+            embedding: PIL image embedding dict
+
+        Returns:
+            coordinates ndarray
+
     """
     orig_width, orig_height = embedding["original_size"]
     resized_width, resized_height = embedding["resized_size"]
@@ -118,3 +137,12 @@ def apply_coords(coords: ndarray, embedding: EmbeddingPILImage):
     coords[..., 1] = coords[..., 1] * (resized_height / orig_height)
 
     return coords.astype(float32)
+
+
+def normalize_array(arr: ndarray, new_h: int | float = 255., type_normalization: str = "int") -> ndarray:
+    arr = arr.astype(float)
+    arr_max = np.nanmax(arr)
+    arr_min = np.nanmin(arr)
+    scaled_arr = (arr - arr_min) / (arr_max - arr_min)
+    multiplied_arr = scaled_arr * new_h
+    return multiplied_arr.astype(int) if type_normalization == "int" else multiplied_arr

samgis_core-3.0.4/samgis_core/utilities/plot_images.py

@@ -1,11 +0,0 @@
-def helper_imshow_output_expected(img1, img2, title1, title2):
-    from matplotlib import pyplot as plt
-
-    fig, ax = plt.subplot_mosaic([
-        [title1, title2]
-    ], figsize=(15, 10))
-
-    ax[title1].imshow(img1)
-    ax[title2].imshow(img2)
-
-    plt.show()