[docs] add more docs content

README.md

@@ -72,10 +72,10 @@ extension, document a whole package in the style of other automatic API document
 Run the command from the project root:
 
 ```bash
-# missing docs folder
-sphinx-quickstart -p SamGIS -a "alessandro trinca tornidor" -r 1.0.0 -l python --master index
+# missing docs folder (run from project root)
+cd docs && sphinx-quickstart -p SamGIS -a "alessandro trinca tornidor" -r 1.0.0 -l python --master index
 
-# update docs folder
+# update docs folder (from project root)
 sphinx-apidoc -f -o docs src
 ```
 

dockerfiles/dockerfile-lambda-fastsam-api

@@ -7,7 +7,7 @@ ARG PYTHONPATH="${LAMBDA_TASK_ROOT}:${PYTHONPATH}:/usr/local/lib/python3/dist-pa
 # Set working directory to function root directory
 WORKDIR ${LAMBDA_TASK_ROOT}
 COPY ./src ${LAMBDA_TASK_ROOT}/src
-COPY ./models ${LAMBDA_TASK_ROOT}/models
+COPY ./machine_learning_models ${LAMBDA_TASK_ROOT}/machine_learning_models
 
 RUN ls -l /usr/bin/which
 RUN /usr/bin/which python
@@ -17,7 +17,7 @@ RUN echo "PATH: ${PATH}."
 RUN echo "LAMBDA_TASK_ROOT: ${LAMBDA_TASK_ROOT}."
 RUN ls -l ${LAMBDA_TASK_ROOT}
 RUN ls -ld ${LAMBDA_TASK_ROOT}
-RUN ls -l ${LAMBDA_TASK_ROOT}/models
+RUN ls -l ${LAMBDA_TASK_ROOT}/machine_learning_models
 RUN python -c "import sys; print(sys.path)"
 RUN python -c "import cv2"
 RUN python -c "import geopandas"

docs/conf.py

@@ -39,7 +39,9 @@ napoleon_google_docstring = True
 # napoleon_attr_annotations = True
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'build/*']
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store', 'build/*', 'machine_learning_models', 'machine_learning_models/*'
+]
 
 source_suffix = {
     '.rst': 'restructuredtext',

docs/src.io.rst

@@ -0,0 +1,45 @@
+src.io package
+==============
+
+Submodules
+----------
+
+src.io.coordinates\_pixel\_conversion module
+--------------------------------------------
+
+.. automodule:: src.io.coordinates_pixel_conversion
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.io.geo\_helpers module
+--------------------------
+
+.. automodule:: src.io.geo_helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.io.lambda\_helpers module
+-----------------------------
+
+.. automodule:: src.io.lambda_helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.io.tms2geotiff module
+-------------------------
+
+.. automodule:: src.io.tms2geotiff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: src.io
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src.rst

@@ -7,6 +7,7 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   src.io
    src.prediction_api
    src.utilities
 

src/__init__.py

@@ -7,5 +7,5 @@ from src.utilities.constants import SERVICE_NAME
 
 
 PROJECT_ROOT_FOLDER = Path(globals().get("__file__", "./_")).absolute().parent.parent
-MODEL_FOLDER = Path(os.path.join(PROJECT_ROOT_FOLDER, "models"))
+MODEL_FOLDER = Path(PROJECT_ROOT_FOLDER / "machine_learning_models")
 app_logger = Logger(service=SERVICE_NAME)

src/io/__init__.py

@@ -0,0 +1 @@
+"""input/output helpers functions"""

src/io/coordinates_pixel_conversion.py

@@ -1,17 +1,13 @@
+"""functions useful to convert to/from latitude-longitude coordinates to pixel image coordinates"""
 import math
-from typing import TypedDict
 
 from src import app_logger
 from src.utilities.constants import TILE_SIZE
 from src.utilities.type_hints import LatLngDict
+from src.utilities.type_hints import ImagePixelCoordinates
 
 
-class PixelCoordinate(TypedDict):
-    x: int
-    y: int
-
-
-def get_latlng2pixel_projection(latlng: LatLngDict) -> PixelCoordinate:
+def _get_latlng2pixel_projection(latlng: LatLngDict) -> ImagePixelCoordinates:
     app_logger.debug(f"latlng: {type(latlng)}, value:{latlng}.")
     app_logger.debug(f'latlng lat: {type(latlng.lat)}, value:{latlng.lat}.')
     app_logger.debug(f'latlng lng: {type(latlng.lng)}, value:{latlng.lng}.')
@@ -31,13 +27,13 @@ def get_latlng2pixel_projection(latlng: LatLngDict) -> PixelCoordinate:
         raise e_get_latlng2pixel_projection
 
 
-def get_point_latlng_to_pixel_coordinates(latlng: LatLngDict, zoom: int | float) -> PixelCoordinate:
+def _get_point_latlng_to_pixel_coordinates(latlng: LatLngDict, zoom: int | float) -> ImagePixelCoordinates:
     try:
-        world_coordinate: PixelCoordinate = get_latlng2pixel_projection(latlng)
+        world_coordinate: ImagePixelCoordinates = _get_latlng2pixel_projection(latlng)
         app_logger.debug(f"world_coordinate:{world_coordinate}.")
         scale: int = pow(2, zoom)
         app_logger.debug(f"scale:{scale}.")
-        return PixelCoordinate(
+        return ImagePixelCoordinates(
             x=math.floor(world_coordinate["x"] * scale),
             y=math.floor(world_coordinate["y"] * scale)
         )
@@ -52,14 +48,27 @@ def get_latlng_to_pixel_coordinates(
         latlng_current_point: LatLngDict,
         zoom: int | float,
         k: str
-):
+) -> ImagePixelCoordinates:
+    """
+    Parse the input request lambda event.
+
+    Args:
+        latlng_origin_ne: NE latitude-longitude origin point
+        latlng_origin_sw: SW latitude-longitude origin point
+        latlng_current_point: latitude-longitude prompt point
+        zoom: zoom value
+        k: prompt type
+
+    Returns:
+        ImagePixelCoordinates: pixel image coordinate point
+    """
     app_logger.debug(f"latlng_origin - {k}: {type(latlng_origin_ne)}, value:{latlng_origin_ne}.")
     app_logger.debug(f"latlng_current_point - {k}: {type(latlng_current_point)}, value:{latlng_current_point}.")
-    latlng_map_origin_ne = get_point_latlng_to_pixel_coordinates(latlng_origin_ne, zoom)
-    latlng_map_origin_sw = get_point_latlng_to_pixel_coordinates(latlng_origin_sw, zoom)
-    latlng_map_current_point = get_point_latlng_to_pixel_coordinates(latlng_current_point, zoom)
+    latlng_map_origin_ne = _get_point_latlng_to_pixel_coordinates(latlng_origin_ne, zoom)
+    latlng_map_origin_sw = _get_point_latlng_to_pixel_coordinates(latlng_origin_sw, zoom)
+    latlng_map_current_point = _get_point_latlng_to_pixel_coordinates(latlng_current_point, zoom)
     diff_coord_x = abs(latlng_map_origin_sw["x"] - latlng_map_current_point["x"])
     diff_coord_y = abs(latlng_map_origin_ne["y"] - latlng_map_current_point["y"])
-    point = PixelCoordinate(x=diff_coord_x, y=diff_coord_y)
+    point = ImagePixelCoordinates(x=diff_coord_x, y=diff_coord_y)
     app_logger.debug(f"point type - {k}: {point}.")
     return point

src/io/geo_helpers.py

@@ -1,14 +1,22 @@
-"""Async download raster tiles"""
+"""handle geo-referenced raster images"""
 from pathlib import Path
-from typing import List
+from typing import List, Tuple, Dict
 
+from affine import Affine
 import numpy as np
 
 from src import app_logger, PROJECT_ROOT_FOLDER
 
 
-def load_affine_transformation_from_matrix(matrix_source_coeffs: List):
-    from affine import Affine
+def load_affine_transformation_from_matrix(matrix_source_coeffs: List[float]) -> Affine:
+    """wrapper for rasterio Affine from_gdal method
+
+    Args:
+        matrix_source_coeffs: 6 floats ordered by GDAL.
+
+    Returns:
+        Affine: Affine transform
+    """
 
     if len(matrix_source_coeffs) != 6:
         raise ValueError(f"Expected 6 coefficients, found {len(matrix_source_coeffs)}; "
@@ -23,13 +31,29 @@ def load_affine_transformation_from_matrix(matrix_source_coeffs: List):
         raise e
 
 
-def get_affine_transform_from_gdal(matrix):
-    from rasterio import Affine
+def get_affine_transform_from_gdal(matrix_source_coeffs: List[float]) -> Affine:
+    """wrapper for rasterio Affine from_gdal method
+
+    Args:
+        matrix_source_coeffs: 6 floats ordered by GDAL.
+
+    Returns:
+        Affine: Affine transform
+    """
+    return Affine.from_gdal(*matrix_source_coeffs)
+
 
-    return Affine.from_gdal(*matrix)
+def get_vectorized_raster_as_geojson(mask: np.ndarray, matrix: Tuple[float]) -> Dict[str, int]:
+    """
+        Parse the input request lambda event.
 
+        Args:
+            mask: numpy mask
+            matrix: tuple of float to transform into an Affine transform
 
-def get_vectorized_raster_as_geojson(mask, matrix):
+        Returns:
+            Dict: dict containing the output geojson and the predictions number
+    """
     try:
         from rasterio.features import shapes
         from geopandas import GeoDataFrame

src/io/lambda_helpers.py

@@ -1,7 +1,8 @@
+"""lambda helper functions"""
 import json
 import logging
 import time
-from typing import Dict
+from typing import Dict, List
 from aws_lambda_powertools.event_handler import content_types
 
 from src import app_logger
@@ -41,6 +42,15 @@ def get_response(status: int, start_time: float, request_id: str, response_body:
 
 
 def get_parsed_bbox_points(request_input: RawRequestInput) -> Dict:
+    """
+    Format the bbox and prompt request input
+
+    Args:
+        request_input: input dict
+
+    Returns:
+        Dict:
+    """
     app_logger.info(f"try to parsing input request {request_input}...")
 
     bbox = request_input.bbox
@@ -78,7 +88,16 @@ def get_parsed_bbox_points(request_input: RawRequestInput) -> Dict:
     }
 
 
-def get_parsed_request_body(event):
+def get_parsed_request_body(event: Dict):
+    """
+    Parse the input request lambda event.
+
+    Args:
+        event: input dict
+
+    Returns:
+        RawRequestInput: parsed request input
+    """
     app_logger.info(f"event:{json.dumps(event)}...")
     try:
         raw_body = event["body"]

src/io/tms2geotiff.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""download geo-referenced raster tiles images"""
 
 import io
 import os

src/prediction_api/__init__.py

@@ -0,0 +1 @@
+"""functions useful to handle machine learning models"""

src/prediction_api/predictors.py

@@ -1,7 +1,6 @@
-# Press the green button in the gutter to run the script.
-import json
-import tempfile
-
+"""functions using the machine learning instance model"""
+from typing import Dict, Tuple
+from PIL.Image import Image
 import numpy as np
 
 from src import app_logger, MODEL_FOLDER
@@ -9,13 +8,29 @@ from src.io.geo_helpers import get_vectorized_raster_as_geojson, get_affine_tran
 from src.io.tms2geotiff import download_extent
 from src.prediction_api.sam_onnx import SegmentAnythingONNX
 from src.utilities.constants import MODEL_ENCODER_NAME, MODEL_DECODER_NAME, DEFAULT_TMS
-from src.utilities.serialize import serialize
-
+from src.utilities.type_hints import llist_float
 
 models_dict = {"fastsam": {"instance": None}}
 
 
-def samexporter_predict(bbox, prompt: list[dict], zoom: float, model_name: str = "fastsam") -> dict:
+def samexporter_predict(
+        bbox: llist_float, prompt: list[dict], zoom: float, model_name: str = "fastsam") -> Dict[str, int]:
+    """
+    Return predictions as a geojson from a geo-referenced image using the given input prompt.
+    1. if necessary instantiate a segment anything machine learning instance model
+    2. download a geo-referenced raster image delimited by the coordinates bounding box (bbox)
+    3. get a prediction image from the segment anything instance model using the input prompt
+    4. get a geo-referenced geojson from the prediction image
+
+    Args:
+        bbox: coordinates bounding box
+        prompt: machine learning input prompt
+        zoom: zoom value
+        model_name: machine learning model name
+
+    Returns:
+        dict: Affine transform
+    """
     try:
         if models_dict[model_name]["instance"] is None:
             app_logger.info(f"missing instance model {model_name}, instantiating it now!")
@@ -31,10 +46,7 @@ def samexporter_predict(bbox, prompt: list[dict], zoom: float, model_name: str =
         pt0, pt1 = bbox
         app_logger.info(f"downloading geo-referenced raster with bbox {bbox}, zoom {zoom}.")
         img, matrix = download_extent(DEFAULT_TMS, pt0[0], pt0[1], pt1[0], pt1[1], zoom)
-        app_logger.info(f"img type {type(img)} with shape/size:{img.size}, matrix:{matrix}.")
-
-        with tempfile.NamedTemporaryFile(mode='w', prefix=f"matrix_", delete=False) as temp_f1:
-            json.dump({"matrix": serialize(matrix)}, temp_f1)
+        app_logger.info(f"img type {type(img)} with shape/size:{img.size}, matrix:{type(matrix)}, matrix:{matrix}.")
 
         transform = get_affine_transform_from_gdal(matrix)
         app_logger.debug(f"transform to consume with rasterio.shapes: {type(transform)}, {transform}.")
@@ -49,7 +61,20 @@ def samexporter_predict(bbox, prompt: list[dict], zoom: float, model_name: str =
         app_logger.error(f"Error trying import module:{e_import_module}.")
 
 
-def get_raster_inference(img, prompt, models_instance, model_name):
+def get_raster_inference(
+        img: Image, prompt: list[dict], models_instance: SegmentAnythingONNX, model_name: str
+     ) -> Tuple[np.ndarray, int]:
+    """wrapper for rasterio Affine from_gdal method
+
+    Args:
+        img: input PIL Image
+        prompt: list of prompt dict
+        models_instance: SegmentAnythingONNX instance model
+        model_name: model name string
+
+    Returns:
+        Tuple[np.ndarray, int]: raster prediction mask, prediction number
+    """
     np_img = np.array(img)
     app_logger.info(f"img type {type(np_img)}, prompt:{prompt}.")
     app_logger.debug(f"onnxruntime input shape/size (shape if PIL) {np_img.size}.")
@@ -57,12 +82,6 @@ def get_raster_inference(img, prompt, models_instance, model_name):
         app_logger.debug(f"onnxruntime input shape (NUMPY) {np_img.shape}.")
     except Exception as e_shape:
         app_logger.error(f"e_shape:{e_shape}.")
-    try:
-        with tempfile.NamedTemporaryFile(mode='w', prefix=f"get_raster_inference__img_", delete=False) as temp_f0:
-            np.save(str(temp_f0.file.name), np_img)
-    except Exception as e_save:
-        app_logger.error(f"e_save:{e_save}.")
-        raise e_save
     app_logger.info(f"instantiated model {model_name}, ENCODER {MODEL_ENCODER_NAME}, "
                     f"DECODER {MODEL_DECODER_NAME} from {MODEL_FOLDER}: Creating embedding...")
     embedding = models_instance.encode(np_img)
@@ -76,12 +95,4 @@ def get_raster_inference(img, prompt, models_instance, model_name):
         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
-    try:
-        with tempfile.NamedTemporaryFile(mode='w', prefix=f"get_raster_inference__mask_", delete=False) as temp_f1:
-            np.save(temp_f1.file.name, mask)
-        with tempfile.NamedTemporaryFile(mode='w', prefix=f"get_raster_inference__inference_out_", delete=False) as temp_f2:
-            np.save(temp_f2.file.name, inference_out)
-    except Exception as e_save1:
-        app_logger.error(f"e_save1:{e_save1}.")
-        raise e_save1
     return mask, len_inference_out

src/prediction_api/sam_onnx.py

@@ -1,3 +1,4 @@
+"""machine learning segment anything class"""
 from copy import deepcopy
 
 import cv2

src/utilities/__init__.py

@@ -1 +1 @@
-"""various helpers utilities"""
+"""various helpers functions"""

src/utilities/type_hints.py

@@ -13,44 +13,37 @@ llist_float = list[list_float]
 
 
 class LatLngDict(BaseModel):
+    """A latitude-longitude type"""
     lat: float
     lng: float
 
 
 class PromptType(str, Enum):
+    """Segment Anyting enumeration prompt type"""
     point = "point"
     # rectangle = "rectangle"
 
 
-class ParsedPrompt(BaseModel):
-    type: PromptType
-    data: llist_float
-    label: int = 0
-
-
-class ParsedRequestInput(BaseModel):
-    bbox: llist_float
-    prompt: ParsedPrompt
-    zoom: int | float
-
-
-class PixelCoordinate(TypedDict):
+class ImagePixelCoordinates(TypedDict):
     x: int
     y: int
 
 
 class RawBBox(BaseModel):
+    """Input lambda bbox request - not parsed"""
     ne: LatLngDict
     sw: LatLngDict
 
 
 class RawPrompt(BaseModel):
+    """Input lambda prompt request - not parsed"""
     type: PromptType
     data: LatLngDict
     label: int = 0
 
 
 class RawRequestInput(BaseModel):
+    """Input lambda request - not parsed"""
     bbox: RawBBox
     prompt: list[RawPrompt]
     zoom: int | float

src/utilities/utilities.py

@@ -1,7 +1,7 @@
 """Various utilities (logger, time benchmark, args dump, numerical and stats info)"""
 
 
-def prepare_base64_input(sb):
+def _prepare_base64_input(sb):
     if isinstance(sb, str):
         # If there's any unicode here, an exception will be thrown and the function will return false
         return bytes(sb, 'ascii')
@@ -10,27 +10,45 @@ def prepare_base64_input(sb):
     raise ValueError("Argument must be string or bytes")
 
 
-def is_base64(sb: str or bytes):
+def _is_base64(sb: str or bytes):
     import base64
 
     try:
-        sb_bytes = prepare_base64_input(sb)
+        sb_bytes = _prepare_base64_input(sb)
         return base64.b64encode(base64.b64decode(sb_bytes, validate=True)) == sb_bytes
     except ValueError:
         return False
 
 
 def base64_decode(s):
+    """
+    Decode base64 strings
+
+    Args:
+        s: input string
+
+    Returns:
+        decoded string
+    """
     import base64
 
-    if isinstance(s, str) and is_base64(s):
+    if isinstance(s, str) and _is_base64(s):
         return base64.b64decode(s, validate=True).decode("utf-8")
 
     return s
 
 
-def base64_encode(sb: str or bytes):
+def base64_encode(sb: str or bytes) -> bytes:
+    """
+    Encode input strings or bytes as base64
+
+    Args:
+        sb: input string or bytes
+
+    Returns:
+        base64 encoded bytes
+    """
     import base64
 
-    sb_bytes = prepare_base64_input(sb)
+    sb_bytes = _prepare_base64_input(sb)
     return base64.b64encode(sb_bytes)

tests/io/test_coordinates_pixel_conversion.py

@@ -1,6 +1,6 @@
 import json
 
-from src.io.coordinates_pixel_conversion import get_latlng2pixel_projection, get_point_latlng_to_pixel_coordinates, \
+from src.io.coordinates_pixel_conversion import _get_latlng2pixel_projection, _get_point_latlng_to_pixel_coordinates, \
     get_latlng_to_pixel_coordinates
 from src.utilities.type_hints import LatLngDict
 from tests import TEST_EVENTS_FOLDER
@@ -15,7 +15,7 @@ def test_get_latlng2pixel_projection():
             print(f"k:{k}")
             current_input = input_output["input"]
             latlng_input = LatLngDict.model_validate(current_input["latlng"])
-            output = get_latlng2pixel_projection(latlng_input)
+            output = _get_latlng2pixel_projection(latlng_input)
             assert output == input_output["output"]
 
 
@@ -28,7 +28,7 @@ def test_get_point_latlng_to_pixel_coordinates():
             print(f"k:{k}")
             current_input = input_output["input"]
             latlng_input = LatLngDict.model_validate(current_input["latlng"])
-            output = get_point_latlng_to_pixel_coordinates(latlng=latlng_input, zoom=current_input["zoom"])
+            output = _get_point_latlng_to_pixel_coordinates(latlng=latlng_input, zoom=current_input["zoom"])
             assert output == input_output["output"]