pyguidos 2.3.0__py3-none-any.whl

pyguidos/__init__.py

@@ -0,0 +1,167 @@
+from pathlib import Path
+import os
+import sys
+import inspect
+import platform
+import warnings
+import tempfile
+from numba import config
+#import pyproj
+
+# Internal paths
+MODULE_ROOT = Path(__file__).resolve().parent
+PROJECT_ROOT = MODULE_ROOT.parent
+TEMPL_DIR = MODULE_ROOT / "templates"
+DATA_DIR = MODULE_ROOT / "data"
+
+
+# Package metadata
+__version__ = "2.3.0"
+__author__ = "Caudullo G. & Vogt P., European Commission, Joint Research Centre"
+
+# Global Numba Setup
+def _setup_numba():
+    curr_os = platform.system()
+
+    # --- 1. WINDOWS-SPECIFIC DLL FIX ---
+    if curr_os == "Windows" and sys.version_info >= (3, 8):
+        # 'Library\bin' folder relative to the running Python interpreter
+        venv_base = sys.prefix
+        paths_to_check = [
+            os.path.join(venv_base, "Library", "bin"),  # Conda style
+            os.path.join(venv_base, "Scripts"),         # Standard venv style
+            os.path.join(venv_base, "bin")              # Some local setups
+        ]
+
+        for path in paths_to_check:
+            if os.path.exists(path):
+                try:
+                    os.add_dll_directory(path)
+                except Exception:
+                    pass # Ignore errors if path is already added or inaccessible
+
+    # --- 2. THREADING LAYER CONFIG ---
+    if curr_os == "Linux":
+        os.environ['NUMBA_THREADING_LAYER'] = 'omp'
+    elif curr_os == "Darwin":
+        os.environ['NUMBA_THREADING_LAYER'] = 'workqueue'
+    else:
+        # On Windows, we prefer TBB if available
+        os.environ['NUMBA_THREADING_LAYER'] = 'tbb'
+
+    # --- 3. GLOBAL CONFIGS ---
+    warnings.filterwarnings("ignore", message=".*TBB threading layer.*")
+
+     # --- 4. CACHE TO TEMP CONFIGS ---
+    cache_path = os.path.join(tempfile.gettempdir(), "numba_spatcon_cache")
+    if not os.path.exists(cache_path):
+        try:
+            os.makedirs(cache_path)
+        except OSError:
+            cache_path = os.path.join(os.getcwd(), ".numba_cache")
+
+    config.CACHE_DIR = cache_path
+    config.RELEASE_GIL = 1
+
+# Execute setup upon import
+_setup_numba()
+
+
+# ================================================================================
+# Import Tools and Results
+from .fragmentation import frag, frag_stats
+from .fragmentation_change import frag_change
+from .land_mosaic import landmos, landmos_stats
+from .spa import spa, spa_stats
+from .accounting import acc, acc_stats
+from .rss import rss
+from .extract_by_polygon import extract_by_polygon
+from .utils import citation
+
+
+def info(tool: str = None):
+    """
+    Displays quick-help and JRC documentation links for pyguidos tools.
+
+    Usage:
+        pg.info()           # Lists all available tools
+        pg.info('acc')     # Shows details and documentation links for Accounting
+    """
+    registry = {
+        "spa": {
+            "title": "Simplified Pattern Analysis (SPA)",
+            "desc": "Classifies binary maps into mutually exclusive morphological classes "
+                    "(Core, Edge, Islet, Loop, Perforation, Linear).",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/mspa.html",
+            "sheet": "https://forest.jrc.ec.europa.eu/en/activities/lpa/mspa/"
+        },
+        "frag": {
+            "title": "Fragmentation",
+            "desc": "Calculates the Fragmentation with Fixed Observation Scale (FOS) approach.",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/fragmentation.html",
+            "sheet": "https://ies-ows.jrc.ec.europa.eu/gtb/GTB/psheets/GTB-Fragmentation-FADFOS.pdf"
+        },
+        "frag_change": {
+            "title": "Fragmentation change",
+            "desc": "Calculates the change of two Fragmentation output tiff files.",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/fragmentation_change.html",
+            "sheet": "https://ies-ows.jrc.ec.europa.eu/gtb/GTB/psheets/GTB-Fragmentation-FADFOS.pdf"
+        },        
+        "landmos": {
+            "title": "Landscape Mosaic",
+            "desc": "Tri-modal landscape classification (Agriculture, Natural, Developed).",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/landmos.html",
+            "sheet": "https://ies-ows.jrc.ec.europa.eu/gtb/GTB/psheets/GTB-Pattern-LM.pdf"
+        },
+        "acc": {
+            "title": "Accounting",
+            "desc": "Foreground patch size analysis.",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/accounting.html",
+            "sheet": "https://ies-ows.jrc.ec.europa.eu/gtb/GTB/psheets/GTB-Objects-Accounting.pdf"
+        },
+        "rss": {
+            "title": "Restoration Status Summary",
+            "desc": "Provide patch-based connectivity indices for a binary raster map.",
+            "guide": "https://jrc-forest.pages.code.europa.eu/guidos/pyguidos/usage/rss.html",
+            "sheet": "https://ies-ows.jrc.ec.europa.eu/gtb/GTB/psheets/GTB-RestorationPlanner.pdf"
+        }
+    }
+
+    if not tool:
+        print("\n" + "═"*60)
+        print(" pyguidos: Available Analytical Tools")
+        print("═"*60)
+        for name, data in registry.items():
+            print(f" • {name:8} : {data['title']}")
+        print("\nType pg.info('tool_name') for detailed links.")
+        print("═"*60 + "\n")
+        return
+
+    tool = tool.lower()
+    if tool in registry:
+        t = registry[tool]
+        # Dynamically get the function object from the module
+        func = globals().get(tool)
+
+        print(f"\n{'─'*10} {t['title'].upper()} {'─'*10}")
+        print(f"Description:  {t['desc']}")
+        print(f"User Guide:   {t['guide']}")
+        print(f"Method Sheet: {t['sheet']}")
+
+        if func:
+            # This shows the exact arguments: e.g., mspa(in_tiff, foreground=2, ...)
+            signature = inspect.signature(func)
+            print(f"Usage:        pg.{tool}{signature}")
+
+        print(f"\nFull usage: help(pg.{tool})\n")
+
+# Exported names
+__all__ = [
+           "spa", "spa_stats",
+           "frag", "frag_stats", "frag_change",
+           "landmos", "landmos_stats",
+           "acc", "acc_stats",
+           "rss",
+           "extract_by_polygon",
+           "citation", "info"
+           ]

pyguidos/accounting.py

@@ -0,0 +1,410 @@
+import sys
+import time
+from pathlib import Path
+import collections
+
+import rasterio
+import numpy as np
+
+from . import utils
+from . import engine
+from . import checks
+from . import TEMPL_DIR
+
+
+ACC_VALUES = [103, 33, 65, 1, 9, 17]
+
+
+def acc(
+    in_tiff,
+    thresholds,
+    outdir=None,
+    statists=True,
+    stat_files=True,
+    verb=False
+    ):
+    """
+    Performs Foreground Patch Size Accounting (ACC) on a binary or
+    multi-class raster. Each foreground patch is classified into size
+    categories defined by the user-provided thresholds, allowing
+    analysis of patch size distribution across the landscape.
+
+    Parameters
+    ----------
+    in_tiff : str or Path
+        Path to the input GeoTIFF. Must be uint8 with values:
+        0 = NoData, 1 = Background, 2 = Foreground.
+        Optional: 3 = Background class 2, 4 = Background class 3.
+    thresholds : list, tuple or np.ndarray
+        Sequence of 1 to 5 unique positive integers defining the patch
+        size class boundaries in pixels. For example, [10, 100, 1000]
+        creates 4 classes: [1-10], [11-100], [101-1000], [>1000].
+    outdir : str or Path, optional
+        Directory for output files. Defaults to the input file's directory.
+    statists : bool, optional
+        If True (default), computes and returns statistics.
+    stat_files : bool, optional
+        If True (default), writes statistics to a .txt report file.
+    verb : bool, optional
+        If True, prints progress messages. Default False.
+
+    Returns
+    -------
+    dict
+        Nested dictionary with three keys:
+        - 'output paths' (dict or None): paths to generated output files
+          ('path tif', 'path txt'), or None if outfile=False.
+        - 'input stats' (dict): pixel counts for foreground, background,
+          missing and special class pixels.
+        - 'output stats' (dict): per-class pixel counts and patch counts
+          for each accounting size class.
+
+    Output Files
+    ------------
+    - <in_name>_acc.tif : accounting result
+    - <in_name>_acc.txt : statistics report
+    """
+    start_time = time.time()
+
+    # Log
+    utils.log_msg(verb, "[   START   ]  Verifying input raster...")
+
+    # Validate parametres
+    thresholds = checks.validate_acc_params(thresholds)
+
+    # Initialize Paths and Metadata
+    in_tiff = Path(in_tiff)
+    outdir = Path(outdir) if outdir else in_tiff.parent
+    in_name = in_tiff.stem
+    out_name = f"{in_name}_acc"
+    info = utils.get_raster_info(in_tiff)
+
+    # Read the input Geotiff
+    with rasterio.open(in_tiff) as src:
+        input_data = src.read(1).astype(np.int16)
+
+    # Get the pixel counting
+    input_pxl_freq = utils.get_pxl_freq(input_data)
+
+    # Input Geotiff validations
+    checks.validate_fmap_input(list(input_pxl_freq.keys()), info["bands"], info['dtype'], allow_34=True)
+
+    # Log
+    utils.log_msg(verb, "[    OK     ]  Input raster verified.")
+
+    try:
+        # Log
+        utils.log_msg(verb, "[   START   ]  Computing Accounting...")
+
+        # Get patch size frequencies
+        labeled_array, lab_pxl_freq = engine.labelling_array(input_data, 2)
+
+        # Create a lookup array for high-speed mapping
+        max_id = max(lab_pxl_freq.keys())
+        lookup = np.zeros(int(max_id) + 1, dtype=np.uint32)
+
+        # Fill the lookup table
+        for patch_id, pixel_count in lab_pxl_freq.items():
+            # Skip the Background (0)
+            if patch_id == 0:
+                lookup[patch_id] = 0   # Keep Background as 0
+                continue
+            lookup[patch_id] = get_class(pixel_count, thresholds)
+
+        # Reclassification
+        reclass_array = lookup[labeled_array.astype(np.int32)]
+        reclass_array = reclass_array.astype(np.uint8, casting='unsafe')
+
+        # Mapping logic (NoData, Special codes)
+        choices = np.array([129, 105, 176], dtype=np.uint8)
+        out_array = np.select(
+            [input_data == 0, input_data == 3, input_data == 4],
+            choices,
+            default=reclass_array
+        ).astype(np.uint8, casting='unsafe')
+
+        # Save Final Geotiff with Palette and Tags
+        thresh_list = ",".join([str(x) for x in thresholds])
+        weblink = "https://forest.jrc.ec.europa.eu/en/activities/lpa/"
+        tag_descr = f"GTB_ACC, <{thresh_list}>, {weblink}"
+        cmap_path = TEMPL_DIR / "acc_colormap.txt"
+        out_tiff = outdir / f"{out_name}.tif"
+        utils.save_output_geotiff(out_tiff, out_array, info['profile'], cmap_path, tag_descr)
+
+        # Log
+        utils.log_msg(verb, "[    OK     ]  Accounting computed.")
+
+        # Statistics and Reporting
+        stats_dict = None
+        if statists:
+            # Log
+            utils.log_msg(verb, "[   START   ]  Generating statistics...")
+
+            minfo = utils.get_raster_info(out_tiff)
+            acc_pxl_freq = utils.get_pxl_freq(out_array)
+            stats_dict = _get_acc_stats(acc_freq = acc_pxl_freq,
+                                        lab_freq = lab_pxl_freq,
+                                        tiff_info = minfo,
+                                        outfile=stat_files,
+                                        out_name=out_name,
+                                        out_dir=outdir,
+                                        source_tiff=in_tiff)
+
+        # Computational time
+        time_str = utils.running_time(start_time, time.time())
+        if statists:
+            txt_file = outdir / f'{out_name}.txt'
+            utils.update_time_line(txt_file, time_str)
+            utils.log_msg(verb, "[    OK     ]  Statistics complete and files saved.")
+
+        # Log
+        utils.log_msg(verb, f"\n>>> Accounting task finished in {time_str}")
+
+        return stats_dict
+
+    except Exception as e:
+        print(f"Error during run: {e}")
+        raise # Still show the error
+
+
+
+def acc_stats(acc_tiff, stat_files=True, outdir=None, source_tiff=None):
+    """
+    Computes statistics for an existing Accounting GeoTIFF. Can be
+    called independently on a previously generated accounting output.
+
+    Parameters
+    ----------
+    acc_tiff : str or Path
+        Path to the accounting result GeoTIFF. Must contain a valid GTB_ACC
+        metadata tag in the TIFFTAG_IMAGEDESCRIPTION field.
+    stat_files : bool, optional
+        If True (default), writes statistics to a .txt report file.
+    outdir : str or Path, optional
+        Directory for output files. Defaults to the input file's directory.
+    source_tiff : str or Path, optional
+        Path to the original input GeoTIFF used to generate the accounting
+        result. Used only to report the source filename in the statistics
+        report. Default None.
+
+    Returns
+    -------
+    dict
+        Nested dictionary with three keys:
+        - 'output paths' (dict or None): paths to generated output files
+          ('path tif', 'path txt'), or None if outfile=False.
+        - 'input stats' (dict): pixel counts for foreground, background,
+          missing and special class pixels.
+        - 'output stats' (dict): per-class pixel counts and patch counts
+          for each accounting size class.
+
+        Note: 'output paths' is None when outfile=False. All other keys
+        are always populated regardless of outfile.
+
+    Output Files
+    ------------
+    - <acc_tiff_stem>.txt : statistics report
+    """
+    start_time_stat = time.time()
+
+    # Read metadata
+    acc_tiff = Path(acc_tiff)
+    minfo = utils.get_raster_info(acc_tiff)
+    if minfo["tag"] is None:
+        sys.exit("ERROR: No valid GuidosToolbox metadata found in the input Geotiff")
+
+    # Check input tag with used tool and parametres
+    tool_params = utils.get_tool_parameters(minfo["tag"])
+    if tool_params.get("tool_id") != "GTB_ACC":
+        sys.exit(f"ERROR: Input Geotiff is labeled as '{tool_params.get('tool_id')}', "
+                 "acc_stats requires a 'GTB_ACC' result file."
+        )
+
+    # Define input and output file names
+    out_name = Path(acc_tiff).stem
+    outdir = Path(outdir) if outdir else acc_tiff.parent
+    source_tiff = Path(source_tiff) if source_tiff else None
+
+    # Accounting pixel and patch counting
+    with rasterio.open(acc_tiff) as src:
+        acc_data = src.read(1)
+    acc_pxl_freq = utils.get_pxl_freq(acc_data)
+
+    # Get statistics
+    stats_dict = _get_acc_stats(acc_freq = acc_pxl_freq,
+                                lab_freq = None,
+                                tiff_info = minfo,
+                                outfile = stat_files,
+                                out_name = out_name,
+                                out_dir = outdir,
+                                source_tiff = source_tiff)
+
+    # Computational time
+    time_str = utils.running_time(start_time_stat, time.time())
+    if stat_files:
+        txt_file = outdir / f'{out_name}.txt'
+        utils.update_time_line(txt_file, time_str)
+
+    return stats_dict
+
+
+#############
+
+def _get_acc_stats(acc_freq,
+                   tiff_info,
+                   lab_freq=None,
+                   outfile=True,
+                   out_name=None,
+                   out_dir=None,
+                   source_tiff=None):
+    """
+    Get the Accounting statistics.
+    """
+    # Get ACC parameters
+    tag = tiff_info["tag"]
+    tool_params = utils.get_tool_parameters(tag)
+    thre_str = tool_params["thresholds"]
+    thresholds = [int(t) for t in thre_str]
+
+    # Define input and output file names
+    source_tiff = Path(source_tiff) if source_tiff else None
+
+    # Counting pixel per ACC class
+    bgrnd = acc_freq[0]
+    bgr3 = acc_freq[105]
+    bgr4 = acc_freq[176]
+    ndata =  acc_freq[129]
+    fgrnd = (tiff_info["rows"] * tiff_info["cols"]) - bgrnd - bgr3 - bgr4 - ndata
+
+    # Counting patches and pixels per class
+    tot_pch = "-"
+    avg_size_txt = "-"
+    median_size = "-"
+    largest_size = "-"
+    class_pch = None
+    if lab_freq:
+        class_pch = collections.Counter()
+        patch_sizes = []
+        for patch_id, pixel_count in lab_freq.items():
+            if patch_id > 0:
+                patch_class = get_class(pixel_count, thresholds)
+                class_pch[patch_class] += 1
+                patch_sizes.append(pixel_count)
+
+        tot_pch = len(patch_sizes)
+        avg_size = np.mean(patch_sizes)
+        avg_size_txt = f"{avg_size:.1f}"
+        median_size = np.median(patch_sizes)
+        largest_size = np.max(patch_sizes)
+
+    if outfile:
+        ### TXT Template Reporting ###
+
+        color_seq = ["black", "red", "yellow", "orange", "brown", "green"]
+        rows_list = []
+        num_thr = len(thresholds)
+
+        class_pxl_out = {}
+        class_pth_out = {}
+        for i in range(num_thr + 1):
+            # Determine Class Value and Color from the sequences
+            val = ACC_VALUES[i]
+            color = color_seq[i]
+
+            # Determine the Size String
+            if i == 0:
+                size_raw = f"[1-{thresholds[i]}]"
+            elif i < num_thr:
+                size_raw = f"[{thresholds[i-1]+1}-{thresholds[i]}]"
+            else:
+                size_raw = f"[>{thresholds[-1]}]"
+
+            size_col = f"{size_raw:<16}"
+
+            # Pixel class count and freq
+            p_count = acc_freq[val]
+            p_pct = (p_count / fgrnd * 100) if fgrnd > 0 else 0
+            class_pxl_out[f'{i+1} {size_raw}'] = p_count
+
+            # Patch class count and freq
+            o_count_txt = "        -"
+            o_pct_txt = "       -"
+            if lab_freq:
+                o_count = class_pch.get(val, 0)
+                o_pct = (o_count / tot_pch * 100) if tot_pch > 0 else 0
+                o_count_txt = f"{o_count:>9}"
+                o_pct_txt = f"{o_pct:>8.2f}"
+                class_pth_out[f'{i+1} {size_raw}']=o_count
+
+            # Format the row string
+            row = (f"{i+1:<6} {val:<8} {color:<7} {size_col} "
+                   f"{p_count:>10} {p_pct:>8.2f} {o_count_txt} {o_pct_txt}")
+            rows_list.append(row)
+
+        # Combine rows into a single string
+        table_body = "\n".join(rows_list)
+
+        content = {
+            "input_file": source_tiff.name if source_tiff else "n/a",
+            "epsg_code": tiff_info["epsg"],
+            "unit_type": 'metres' if tiff_info["is_projected"] else 'degrees',
+            "resolx": tiff_info["resX"],
+            "resoly": tiff_info["resY"],
+            "rows_val": tiff_info["rows"],
+            "cols_val": tiff_info["cols"],
+            "tot_pxl": tiff_info["rows"] * tiff_info["cols"],
+            "foreg_pxl": fgrnd,
+            "backg_pxl": bgrnd,
+            "miss_pxl": ndata,
+            "spec3_pxl": bgr3,
+            "spec4_pxl": bgr4,
+
+            "threshold_list": " ".join(thre_str),
+
+            "output_file": f"{out_name}.tif",
+            "table_rows": table_body,
+            "tot_pch": tot_pch,
+            "avg_pch": avg_size_txt,
+            "med_pch": median_size,
+            "lar_pch": largest_size,
+        }
+
+        txt_file = out_dir / f'{out_name}.txt'
+        utils.generate_text_report(TEMPL_DIR / 'acc_templ.txt', txt_file, content)
+
+    # Statistic dictionaries
+    path_stats_dict = None
+    if outfile:
+        path_stats_dict = {
+            "path tif" : str(out_dir / f"{out_name}.tif"),
+            "path txt" : str(txt_file)
+            }
+    input_stats_dict = {
+        "foreground pxl" : fgrnd,
+        "background pxl" : bgrnd,
+        "missing pxl" : ndata,
+        "backgr3 pxl" : bgr3,
+        "backgr4 pxl" : bgr4
+        }
+    output_stats_dict = {
+        "class pxl": class_pxl_out,
+        "class patch": class_pth_out
+        }
+    stats_dict = {
+        "output paths" : path_stats_dict,
+        "input stats" : input_stats_dict,
+        "output stats" : output_stats_dict
+        }
+
+    return stats_dict
+
+
+def get_class(count, thresholds):
+    """
+    Checks count against thresholds.
+    """
+    for i, t in enumerate(thresholds):
+        if count <= t:
+            return ACC_VALUES[i]
+    # Return the last class
+    return ACC_VALUES[len(thresholds)]