samgis_core 3.0.4__tar.gz → 3.0.5__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "samgis_core"
-version = "3.0.4"
+version = "3.0.5"
 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.5"
 
 [tool.poetry.urls]
 Source = "https://gitlab.com/aletrn/samgis_core"

{samgis_core-3.0.4 → samgis_core-3.0.5}/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.5}/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...")
@@ -80,6 +82,7 @@ def get_raster_inference_using_existing_embedding(
 
     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)
@@ -111,6 +114,7 @@ def get_raster_inference_with_embedding_from_dict(
 
     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)

{samgis_core-3.0.4 → samgis_core-3.0.5}/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.5/samgis_core/utilities/plot_images.py

@@ -0,0 +1,91 @@
+from numpy import ndarray
+from matplotlib import pyplot as plt
+
+from samgis_core.utilities.type_hints import ListStr, TupleInt
+
+
+FigAxes = tuple[plt.Figure, plt.Axes]
+
+
+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) -> 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)
+
+    Returns:
+        tuple of matplotlib Figure, Axes
+
+    """
+    from rasterio import plot
+
+    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.5}/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.5}/samgis_core/utilities/utilities.py

@@ -98,6 +98,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 +119,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"]

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()