wildfire-analyser 0.1.10__tar.gz

wildfire_analyser-0.1.10/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marcelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wildfire_analyser-0.1.10/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: wildfire-analyser
+Version: 0.1.10
+Summary: Python library for post-fire assessment and wildfire analysis using Google Earth Engine.
+Author: Marcelo Camargo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/camargo-advanced/wildfire-analyser
+Project-URL: Source, https://github.com/camargo-advanced/wildfire-analyser
+Project-URL: Issues, https://github.com/camargo-advanced/wildfire-analyser/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geemap==0.36.6
+Requires-Dist: geopandas==1.1.1
+Requires-Dist: geedim==2.0.0
+Requires-Dist: python-dotenv==1.0.1
+Dynamic: license-file
+
+# wildfire-analyser
+
+Python project for analyzing wildfires in natural reserves.
+
+## Installation and Usage
+
+Follow the steps below to install and test `wildfire-analyser` inside an isolated environment:
+
+```bash
+mkdir /tmp/test
+cd /tmp/test
+
+python3 -m venv venv
+source venv/bin/activate
+
+pip install wildfire-analyser
+```
+
+### Required Files Before Running the Client
+
+Before running the client, you **must** prepare two items:
+
+---
+
+#### **1. Add a GeoJSON polygon**
+
+Create a folder named `polygons` in the project root and place your ROI polygon file inside it:
+
+```
+/tmp/test/
+├── polygons/
+│   └── your_polygon.geojson
+└── venv/
+```
+
+An example GeoJSON file is available in the repository.
+
+---
+
+#### **2. Create the `.env` file with GEE authentication data**
+
+In the project root, add a `.env` file containing your Google Earth Engine authentication variables.
+
+A `.env` template is also available in the GitHub repository.
+
+```
+/tmp/test/
+├── .env
+├── polygons/
+└── venv/
+```
+
+---
+
+### Running the Client
+
+After adding the `.env` file and your GeoJSON polygon:
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+This will start the analysis process, generate the configured deliverables, and save the output files in the current directory.
+
+
+
+## Setup Instructions for Developers
+
+1. **Clone the repository**
+
+```bash
+git clone git@github.com:camargo-advanced/wildfire-analyser.git
+cd wildfire-analyser
+```
+
+2. **Create a virtual environment**
+
+```bash
+python3 -m venv venv
+```
+
+3. **Activate the virtual environment**
+
+```bash
+source venv/bin/activate
+```
+
+4. **Install dependencies**
+   Make sure the virtual environment is activated, then run:
+
+```bash
+pip install -r requirements.txt
+```
+
+5. **Configure environment variables**
+   Copy your version of `.env` file to the root folder with your GEE authentication credentials. A template file `.env.template` is provided as an example.
+
+6. **Run the sample client application**
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+## Useful Commands
+
+* **Deactivate the virtual environment**:
+
+```bash
+deactivate
+```

wildfire_analyser-0.1.10/README.md

@@ -0,0 +1,110 @@
+# wildfire-analyser
+
+Python project for analyzing wildfires in natural reserves.
+
+## Installation and Usage
+
+Follow the steps below to install and test `wildfire-analyser` inside an isolated environment:
+
+```bash
+mkdir /tmp/test
+cd /tmp/test
+
+python3 -m venv venv
+source venv/bin/activate
+
+pip install wildfire-analyser
+```
+
+### Required Files Before Running the Client
+
+Before running the client, you **must** prepare two items:
+
+---
+
+#### **1. Add a GeoJSON polygon**
+
+Create a folder named `polygons` in the project root and place your ROI polygon file inside it:
+
+```
+/tmp/test/
+├── polygons/
+│   └── your_polygon.geojson
+└── venv/
+```
+
+An example GeoJSON file is available in the repository.
+
+---
+
+#### **2. Create the `.env` file with GEE authentication data**
+
+In the project root, add a `.env` file containing your Google Earth Engine authentication variables.
+
+A `.env` template is also available in the GitHub repository.
+
+```
+/tmp/test/
+├── .env
+├── polygons/
+└── venv/
+```
+
+---
+
+### Running the Client
+
+After adding the `.env` file and your GeoJSON polygon:
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+This will start the analysis process, generate the configured deliverables, and save the output files in the current directory.
+
+
+
+## Setup Instructions for Developers
+
+1. **Clone the repository**
+
+```bash
+git clone git@github.com:camargo-advanced/wildfire-analyser.git
+cd wildfire-analyser
+```
+
+2. **Create a virtual environment**
+
+```bash
+python3 -m venv venv
+```
+
+3. **Activate the virtual environment**
+
+```bash
+source venv/bin/activate
+```
+
+4. **Install dependencies**
+   Make sure the virtual environment is activated, then run:
+
+```bash
+pip install -r requirements.txt
+```
+
+5. **Configure environment variables**
+   Copy your version of `.env` file to the root folder with your GEE authentication credentials. A template file `.env.template` is provided as an example.
+
+6. **Run the sample client application**
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+## Useful Commands
+
+* **Deactivate the virtual environment**:
+
+```bash
+deactivate
+```

wildfire_analyser-0.1.10/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "wildfire-analyser"
+version = "0.1.10"
+description = "Python library for post-fire assessment and wildfire analysis using Google Earth Engine."
+authors = [
+    { name = "Marcelo Camargo" }
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+
+dependencies = [
+    "geemap==0.36.6",
+    "geopandas==1.1.1",
+    "geedim==2.0.0",
+    "python-dotenv==1.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/camargo-advanced/wildfire-analyser"
+Source = "https://github.com/camargo-advanced/wildfire-analyser"
+Issues = "https://github.com/camargo-advanced/wildfire-analyser/issues"
+
+[tool.setuptools.packages.find]
+include = ["wildfire_analyser*"]
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

wildfire_analyser-0.1.10/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wildfire_analyser-0.1.10/wildfire_analyser/__init__.py

@@ -0,0 +1,4 @@
+from .fire_assessment.post_fire_assessment import PostFireAssessment
+from .fire_assessment.deliverable import Deliverable
+from .fire_assessment.fire_severity import FireSeverity
+__all__ = ["PostFireAssessment", "Deliverable", "FireSeverity"]

wildfire_analyser-0.1.10/wildfire_analyser/client.py

@@ -0,0 +1,72 @@
+# client.py
+import logging
+import os
+from dotenv import load_dotenv 
+
+from wildfire_analyser import PostFireAssessment, Deliverable, FireSeverity
+
+logger = logging.getLogger(__name__)
+
+
+def main():
+    # Configure global logging format and level
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(message)s"
+    )
+    logger.info("Client starts")
+
+    try:
+        # Load the local .env file
+        load_dotenv()
+
+        # Read the environment variable from .env
+        gee_key_json = os.getenv("GEE_PRIVATE_KEY_JSON")
+        if gee_key_json is None:
+            raise ValueError("GEE_PRIVATE_KEY_JSON environment variable is not set in .env")
+
+        # Path to the GeoJSON polygon used as the Region of Interest (ROI)
+        geojson_path = os.path.join("polygons", "APAPiracicabaJuqueriMirimAreaII.geojson")
+        #geojson_path = os.path.join("polygons", "eejatai.geojson")
+
+        # Initialize the wildfire assessment processor with date range
+        runner = PostFireAssessment(gee_key_json,
+                                    geojson_path, "2024-09-01", "2024-11-08", 
+                                    deliverables=[
+                                        Deliverable.RGB_PRE_FIRE,
+                                        Deliverable.RGB_POST_FIRE,
+                                        #Deliverable.NDVI_PRE_FIRE,
+                                        #Deliverable.NDVI_POST_FIRE,
+                                        #Deliverable.RBR,
+                                    ], 
+                                    track_timings=True)
+
+        # Run the analysis
+        result = runner.run_analysis()
+
+        # Print fire severity
+        for row in result["area_by_severity"]:
+            logger.info(
+                f"{row['severity_name']}({row['severity']}): {row['ha']:.2f} ha ({row['percent']:.2f}%) -> {row['color']}"
+            )
+
+        # Save each deliverable to local files
+        for key, item in result["images"].items():
+            with open(item["filename"], "wb") as f:
+                f.write(item["data"])
+            logger.info(f"Saved file: {item['filename']}")
+
+        # Print processing time metrics
+        timings = result.get("timings", {})
+        logger.info("Stats:")
+        for key, value in timings.items():
+            logger.info(f" → {key}: {value:.2f} sec")
+
+        logger.info("Client ends")
+
+    except Exception as e:
+        logger.exception("Unexpected error during processing")
+
+# Entry point
+if __name__ == "__main__":
+    main()

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/date_utils.py

@@ -0,0 +1,14 @@
+# date_utils.py
+import logging
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+
+def expand_dates(start_date: str, end_date: str, days_before_after: int):
+    sd = datetime.strptime(start_date, "%Y-%m-%d")
+    ed = datetime.strptime(end_date, "%Y-%m-%d")
+    before_start = (sd - timedelta(days=days_before_after)).strftime("%Y-%m-%d")
+    after_end = (ed + timedelta(days=days_before_after)).strftime("%Y-%m-%d")
+    return before_start, start_date, end_date, after_end
+

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/deliverable.py

@@ -0,0 +1,12 @@
+# deliverable.py
+from enum import Enum
+
+class Deliverable(Enum):
+    RGB_PRE_FIRE = "rgb_pre_fire"
+    RGB_POST_FIRE = "rgb_post_fire"
+    NDVI_PRE_FIRE = "ndvi_pre_fire"
+    NDVI_POST_FIRE = "ndvi_post_fire"
+    RBR = "rbr"
+
+    def __str__(self):
+        return self.value

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/downloaders.py

@@ -0,0 +1,106 @@
+# downloaders.py
+import logging
+import ee
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Local cache:  { (bbox_key) → best_scale }
+scale_cache = {}
+
+
+def bbox_key(region: ee.Geometry):
+    """
+    Compute a stable and compact key for a geometry.
+
+    - Uses the bounding box
+    - Rounds coordinates to 3 decimal places
+    - Output: tuple usable as dict key
+    """
+    coords = region.bounds().coordinates().getInfo()
+    flat = [round(c, 3) for pair in coords[0] for c in pair]
+    return tuple(flat)
+
+def download_image(
+    image: ee.Image,
+    region: ee.Geometry,
+    scale: int = 10,
+    format: str = "GEO_TIFF",
+    bands: list | None = None,
+) -> bytes:
+    """
+    Generic and robust Earth Engine image downloader with caching.
+
+    - If a successful scale was already found for this region, reuses it directly.
+    - Otherwise tries scales: scale → scale+15 → ... → 150.
+    - Caches the first scale that works for future downloads.
+    - Works for both single-band (TIFF) and multi-band images.
+    """
+
+    region_id = bbox_key(region)
+
+    # Select band(s) if needed
+    img = image.select(bands) if bands else image
+
+    # Try using cached scale first (fast path)
+    if region_id in scale_cache:
+        cached_scale = scale_cache[region_id]
+
+        try:
+            logger.info(f"Using cached scale {cached_scale} m for region {region_id}")
+            url = img.getDownloadURL({
+                "scale": cached_scale,
+                "region": region,
+                "format": format
+            })
+
+            resp = requests.get(url, stream=True)
+            resp.raise_for_status()
+
+            logger.info(f"Downloaded successfully with cached scale {cached_scale} m")
+            return resp.content
+
+        except Exception as e:
+            logger.warning(
+                f"Cached scale {cached_scale} m failed ({e}). Will try fallback loop."
+            )
+            # continue to fallback progressive search
+
+    # Progressive search for a working scale (slow path)
+    for attempt_scale in range(scale, 151, 15):
+
+        try:
+            url = img.getDownloadURL({
+                "scale": attempt_scale,
+                "region": region,
+                "format": format
+            })
+
+            resp = requests.get(url, stream=True)
+            resp.raise_for_status()
+
+            logger.info(f"Downloaded successfully at {attempt_scale} m")
+
+            # SAVE the working scale in cache for future images
+            scale_cache[region_id] = attempt_scale
+            logger.info(
+                f"Caching scale {attempt_scale} m for region {region_id}"
+            )
+
+            return resp.content
+
+        except Exception as e:
+            # classic GEE “too large” error
+            if "Total request size" in str(e):
+                logger.info(
+                    f"Scale {attempt_scale} m rejected (too large). Trying next..."
+                )
+                continue
+
+            # other error → raise immediately
+            raise
+
+    # No scale worked up to 150 m
+    raise RuntimeError(
+        "Unable to download image even at 150 m — region too large."
+    )

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/fire_severity.py

@@ -0,0 +1,15 @@
+# fire_severity.py
+from enum import IntEnum
+
+class FireSeverity(IntEnum):
+    UNBURNED = (0, "Unburned")
+    LOW = (1, "Low")
+    MODERATE = (2, "Moderate")
+    HIGH = (3, "High")
+    VERY_HIGH = (4, "Very High")
+
+    def __new__(cls, value, label):
+        obj = int.__new__(cls, value)
+        obj._value_ = value
+        obj.label = label
+        return obj

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/post_fire_assessment.py

@@ -0,0 +1,454 @@
+# post_fire_assessment.py
+import logging
+import json
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+import time
+
+import ee
+from rasterio.io import MemoryFile
+
+from wildfire_analyser.fire_assessment.date_utils import expand_dates
+from wildfire_analyser.fire_assessment.deliverable import Deliverable
+from wildfire_analyser.fire_assessment.validators import (
+    validate_date,
+    validate_geojson_path,
+    validate_deliverables,
+    ensure_not_empty
+)
+from wildfire_analyser.fire_assessment.downloaders import download_image
+
+CLOUD_THRESHOLD = 70
+COLLECTION_ID = "COPERNICUS/S2_SR_HARMONIZED"
+DAYS_BEFORE_AFTER = 30
+IMAGE_SCALE = 10
+
+logger = logging.getLogger(__name__)
+
+
+class PostFireAssessment:
+    def __init__(self, gee_key_json: str, geojson_path: str, start_date: str, end_date: str, 
+                 deliverables=None, track_timings: bool = False):
+        # Validate input parameters
+        validate_geojson_path(geojson_path)
+        validate_date(start_date, "start_date")
+        validate_date(end_date, "end_date")
+        validate_deliverables(deliverables)
+
+        # Check chronological order
+        if start_date > end_date:
+            raise ValueError(f"'start_date' must be earlier than 'end_date'. Received: {start_date} > {end_date}")
+      
+        # Store parameters
+        self.gee = self.gee_authenticate(gee_key_json)
+        self.roi = self.load_geojson(geojson_path)
+        self.start_date = start_date
+        self.end_date = end_date
+        self.deliverables = deliverables or []
+        self.track_timings = track_timings
+
+    def gee_authenticate(self, gee_key_json: str) -> ee:
+        """
+        Authenticate to Google Earth Engine using a service account key JSON.
+        """
+        # Converte a string JSON para dicionário
+        try:
+            key_dict = json.loads(gee_key_json)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Error decoding GEE_PRIVATE_KEY_JSON: {e}") from e
+
+        # Inicializa GEE usando arquivo temporário
+        try:
+            with NamedTemporaryFile(mode="w+", suffix=".json") as f:
+                json.dump(key_dict, f)
+                f.flush()
+                credentials = ee.ServiceAccountCredentials(key_dict["client_email"], f.name)
+                ee.Initialize(credentials)
+        except Exception as e:
+            raise RuntimeError(f"Failed to authenticate with Google Earth Engine: {e}") from e
+
+        return ee
+
+    def load_geojson(self, path: str) -> ee.Geometry:
+        """Load a GeoJSON file and return an Earth Engine Geometry."""
+        file_path = Path(path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"GeoJSON not found: {path}")
+
+        with open(file_path, 'r') as f:
+            geojson = json.load(f)
+
+        # Converts GeoJSON to EE geometry
+        try:
+            geometry = ee.Geometry(geojson['features'][0]['geometry'])
+        except Exception as e:
+            raise ValueError(f"Invalid GeoJSON geometry: {e}") from e
+        
+        return geometry
+    
+    def _load_full_collection(self):
+        """Load all images intersecting ROI under cloud threshold, mask clouds, select bands, add reflectance."""
+        bands_to_select = ['B2', 'B3', 'B4', 'B8', 'B12', 'QA60']
+        
+        def mask_s2_clouds(img):
+            qa = img.select('QA60')
+            cloud = qa.bitwiseAnd(1 << 10).neq(0)
+            cirrus = qa.bitwiseAnd(1 << 11).neq(0)
+            mask = cloud.Or(cirrus).Not()
+            return img.updateMask(mask)
+
+        collection = (
+            self.gee.ImageCollection(COLLECTION_ID)
+            .filterBounds(self.roi)
+            .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', CLOUD_THRESHOLD))
+            .map(mask_s2_clouds)
+            .sort('CLOUDY_PIXEL_PERCENTAGE', False)
+        )
+        
+        # Function to add reflectance (_refl).
+        def preprocess(img):
+            refl_bands = img.select(bands_to_select).multiply(0.0001)
+            refl_names = refl_bands.bandNames().map(lambda b: ee.String(b).cat('_refl'))
+            img = img.addBands(refl_bands.rename(refl_names))
+            return img
+        
+        collection = collection.map(preprocess)
+
+        return collection
+
+    def merge_bands(self, band_tiffs: dict[str, bytes]) -> bytes:
+        """
+        Merge multiple single-band GeoTIFFs (raw bytes) into a single multi-band GeoTIFF.
+        """
+        memfiles = {b: MemoryFile(tiff_bytes) for b, tiff_bytes in band_tiffs.items()}
+        datasets = {b: memfiles[b].open() for b in memfiles}
+
+        # Reference band to copy metadata
+        first = next(iter(datasets.values()))
+        profile = first.profile.copy()
+        profile.update(count=len(datasets))
+
+        # Merge bands
+        with MemoryFile() as merged_mem:
+            with merged_mem.open(**profile) as dst:
+                for idx, (band, ds) in enumerate(datasets.items(), start=1):
+                    dst.write(ds.read(1), idx)
+
+            return merged_mem.read()
+        
+    def _generate_rgb_pre_fire(self, mosaic: ee.Image) -> dict:
+        """
+        Generates two GeoTIFF and JPEG images.
+        """
+        # Generate the technical multi-band RGB GeoTIFF
+        tiff = self._generate_rgb(mosaic, Deliverable.RGB_PRE_FIRE.value)
+        
+        # Generate the visual RGB JPEG (with overlay)
+        rgb_img = mosaic.select(['B4_refl', 'B3_refl', 'B2_refl'])
+        vis_params = {"min": 0.0, "max": 0.3}
+        jpeg = self._generate_visual_image(rgb_img, "rgb_pre_fire_visual", vis_params)
+    
+        return tiff, jpeg
+
+    def _generate_rgb_post_fire(self, mosaic: ee.Image) -> dict:
+        """
+        Generates two GeoTIFF and JPEG images.
+        """
+        # Generate the technical multi-band RGB GeoTIFF
+        tiff = self._generate_rgb(mosaic, Deliverable.RGB_POST_FIRE.value)
+
+        # Generate the visual RGB JPEG (with overlay)
+        rgb_img = mosaic.select(['B4_refl', 'B3_refl', 'B2_refl'])
+        vis_params = {"min": 0.0, "max": 0.3}
+        jpeg = self._generate_visual_image(rgb_img, "rgb_post_fire_visual", vis_params)
+
+        return tiff, jpeg
+
+    def _generate_rgb(self, mosaic, filename_prefix):
+        """
+        Generates an RGB (B4, B3, B2) as a single multiband GeoTIFF.
+        """
+        # Merges into a single multiband TIFF.
+        image_bytes = self.merge_bands({
+            "B4_refl": download_image(image=mosaic, bands=['B4_refl'], region=self.roi, scale=IMAGE_SCALE, format="GEO_TIFF"),
+            "B3_refl": download_image(image=mosaic, bands=['B3_refl'], region=self.roi, scale=IMAGE_SCALE, format="GEO_TIFF"),
+            "B2_refl": download_image(image=mosaic, bands=['B2_refl'], region=self.roi, scale=IMAGE_SCALE, format="GEO_TIFF"),
+        })
+
+        return {
+            "filename": f"{filename_prefix}.tif", 
+            "content_type": "image/tiff",
+            "data": image_bytes
+        }
+
+    def _generate_visual_image(self, img: ee.Image, filename: str, vis_params: dict) -> dict:
+        """
+        Generates a JPEG of an Earth Engine image with styled ROI overlay.
+        """
+        vis = img.visualize(**vis_params)
+        overlay = self._styled_roi_overlay().visualize()
+        final = vis.blend(overlay)
+
+        jpeg_bytes = download_image(
+            image=final,
+            region=self.roi,
+            scale=IMAGE_SCALE,
+            format="JPEG"
+        )
+
+        # Return dict just like before
+        return {
+            "filename": f"{filename}.jpg",
+            "content_type": "image/jpeg",
+            "data": jpeg_bytes
+        }
+    
+    def _generate_ndvi(self, mosaic: ee.Image, filename: str) -> dict:
+        """
+        Computes NDVI from a mosaic using reflectance bands (B8_refl and B4_refl).
+        Downloads the resulting index as a single-band GeoTIFF and returns it as a
+        deliverable object. 
+        """
+        data = download_image(image=mosaic, bands=['ndvi'], region=self.roi, scale=IMAGE_SCALE, format="GEO_TIFF")
+        return {
+            "filename": f"{filename}.tif",
+            "content_type": "image/tiff",
+            "data": data
+        }
+
+    def _generate_rbr(self, rbr_img: ee.Image, severity_img: ee.Image) -> tuple[dict, dict, dict]:
+        """
+        Computes RBR and generates deliverables:
+            - rbr.tif (GeoTIFF)
+            - rbr_severity_visual.jpg (RBR class color)
+            - rbr_visual.jpg (RBR color JPEG with rbrVis palette)
+        """
+        # GeoTIFF
+        image_bytes = download_image(image=rbr_img, bands=['rbr'], region=self.roi, scale=IMAGE_SCALE, format="GEO_TIFF")
+        tiff_deliverable = {
+            "filename": "rbr.tif",
+            "content_type": "image/tiff",
+            "data": image_bytes
+        }
+
+        # Visual JPEG
+        vis_params = {"min": -0.5, "max": 0.6, "palette": ["black", "yellow", "red"]}
+        visual_deliverable = self._generate_visual_image(rbr_img, "rbr_visual", vis_params)
+
+        # Severity visual JPEG
+        severity_vis_params = {
+            "min": 0,
+            "max": 4,
+            "palette": ["00FF00","FFFF00","FFA500","FF0000","8B4513"]
+        }
+        severity_visual_deliverable = self._generate_visual_image(severity_img, "rbr_severity_visual", severity_vis_params)
+
+        return tiff_deliverable, severity_visual_deliverable, visual_deliverable
+
+    def _styled_roi_overlay(self):
+        """Creates a styled overlay of the ROI polygon (purple outline, no fill)."""
+        fc = ee.FeatureCollection([ee.Feature(self.roi)])
+        styled = fc.style(
+            color='#800080',     # purple border
+            fillColor='00000000',  # transparent fill
+            width=3
+        )
+        return styled
+
+    def _build_mosaic_with_indexes(self, collection: ee.ImageCollection) -> ee.Image:
+        """
+        Takes a filtered collection → builds a mosaic → computes NDVI and 
+        NBR → returns a mosaic with the additional bands.
+        """
+        mosaic = collection.mosaic()
+        ndvi = mosaic.normalizedDifference(["B8_refl", "B4_refl"]).rename("ndvi")
+        nbr  = mosaic.normalizedDifference(["B8_refl", "B12_refl"]).rename("nbr")
+        return mosaic.addBands([ndvi, nbr])
+
+    def _compute_rbr(self, before_mosaic: ee.Image, after_mosaic: ee.Image) -> ee.Image:
+        """
+        Computes RBR (Relative Burn Ratio) from BEFORE and AFTER mosaics.
+        Assumes both mosaics already include band 'nbr'.
+        """
+        delta_nbr = before_mosaic.select('nbr').subtract(after_mosaic.select('nbr')).rename('dnbr')
+        rbr = delta_nbr.divide(before_mosaic.select('nbr').add(1.001)).rename('rbr')
+        return rbr
+
+    def _compute_area_by_severity(self, severity_img: ee.Image) -> dict[int, float]:
+        """
+        Calculates the area per class (in hectares) within the ROI in an optimized way.
+        """
+        # 1 Sentinel-2 pixel = 10 m → pixel area = 100 m² = 0.01 ha
+        pixel_area_ha = ee.Image.pixelArea().divide(10000)
+
+        # Creates an image using 'severity' as a mask for each class
+        def area_per_class(c):
+            mask = severity_img.eq(c)
+            return pixel_area_ha.updateMask(mask).rename('area_' + str(c))
+        
+        class_images = [area_per_class(c) for c in range(5)]
+        stacked = ee.Image.cat(class_images)
+
+        # Reduces all bands simultaneously
+        areas = stacked.reduceRegion(
+            reducer=ee.Reducer.sum(),
+            geometry=self.roi,
+            scale=IMAGE_SCALE,
+            maxPixels=1e12
+        ).getInfo()
+
+        return { c: float(areas.get(f'area_{c}', 0) or 0) for c in range(5) }
+
+    def _classify_rbr_severity(self, rbr_img: ee.Image) -> ee.Image:
+        """
+        Classify RBR by severity:
+            0 = Unburned        (RBR < 0.1)
+            1 = Low             (0.1 ≤ RBR < 0.27)
+            2 = Moderate        (0.27 ≤ RBR < 0.44)
+            3 = High            (0.44 ≤ RBR < 0.66)
+            4 = Very High       (RBR ≥ 0.66)
+        """
+
+        severity = rbr_img.expression(
+            """
+            (b('rbr') < 0.10) ? 0 :
+            (b('rbr') < 0.27) ? 1 :
+            (b('rbr') < 0.44) ? 2 :
+            (b('rbr') < 0.66) ? 3 :
+                                4
+            """
+        ).rename("severity")
+
+        return severity
+
+    def format_severity_table(self, area_dict: dict[int, float]) -> list[dict]:
+        """
+        Converts the raw {severity: hectares} dict into a structured JSON
+        with severity, severity_name, ha, percent, and color.
+        """
+
+        severity_names = {
+            0: "Unburned",
+            1: "Low",
+            2: "Moderate",
+            3: "High",
+            4: "Very High",
+        }
+
+        severity_colors = {
+            0: "Green",
+            1: "Yellow",
+            2: "Orange",
+            3: "Red",
+            4: "Maroon",
+        }
+
+        total_ha = sum(area_dict.values()) or 1  # avoid division by zero
+
+        table = []
+        for s in range(5):
+            ha = float(area_dict.get(s, 0))
+            pct = (ha / total_ha) * 100
+
+            table.append({
+                "severity": s,
+                "severity_name": severity_names[s],
+                "ha": round(ha, 2),
+                "percent": round(pct, 2),
+                "color": severity_colors[s]
+            })
+
+        return table
+
+    def force_execution(self, obj):
+        """
+        Forces GEE to execute pending computations while retrieving the smallest possible data.
+        """
+        try:
+            # Collections → safest, smallest fetch possible
+            if isinstance(obj, ee.ImageCollection) or isinstance(obj, ee.FeatureCollection):
+                return obj.size().getInfo()
+
+            # Images → never call getInfo() directly (too heavy)
+            if isinstance(obj, ee.Image):
+                # Use a tiny region and simple stats to force execution
+                # without downloading the full image
+                test = obj.reduceRegion(
+                    reducer=ee.Reducer.mean(),
+                    geometry=self.roi.centroid(),
+                    scale=100,
+                    maxPixels=1e9
+                )
+                return test.getInfo()
+
+            # Numbers / Dictionaries / anything else
+            return obj.getInfo()
+
+        except Exception:
+            return None
+
+    def run_analysis(self):
+        timings = {}
+
+        # Load satellite collection
+        if self.track_timings: t0 = time.time()
+        full_collection = self._load_full_collection()
+        if self.track_timings: 
+            self.force_execution(full_collection)
+            timings["Sat collection loaded"] = time.time() - t0
+
+        # Expand dates to maximize satellite image coverage
+        before_start, before_end, after_start, after_end = expand_dates(
+            self.start_date, self.end_date, DAYS_BEFORE_AFTER 
+        )
+
+        # Build pre fire mosaic
+        if self.track_timings: t1 = time.time()
+        before_collection = full_collection.filterDate(before_start, before_end)
+        ensure_not_empty(before_collection, before_start, before_end)
+        before_mosaic = self._build_mosaic_with_indexes(before_collection)
+
+        # Build post fire mosaic
+        after_collection = full_collection.filterDate(after_start, after_end)
+        ensure_not_empty(after_collection, after_start, after_end)
+        after_mosaic = self._build_mosaic_with_indexes(after_collection)
+
+        # Compute RBR
+        rbr = self._compute_rbr(before_mosaic, after_mosaic)
+        
+        # Classification and severity extension calculation
+        severity = self._classify_rbr_severity(rbr)
+        area_stats = self._compute_area_by_severity(severity)
+        if self.track_timings: 
+            self.force_execution(area_stats)
+            timings["Indexes calculated"] = time.time() - t1
+
+        deliverable_registry = {
+            Deliverable.RGB_PRE_FIRE: lambda ctx: self._generate_rgb_pre_fire(before_mosaic),
+            Deliverable.RGB_POST_FIRE: lambda ctx: self._generate_rgb_post_fire(after_mosaic),
+            Deliverable.NDVI_PRE_FIRE: lambda ctx: [self._generate_ndvi(before_mosaic, Deliverable.NDVI_PRE_FIRE.value)],
+            Deliverable.NDVI_POST_FIRE: lambda ctx: [self._generate_ndvi(after_mosaic, Deliverable.NDVI_POST_FIRE.value)],
+            Deliverable.RBR: lambda ctx: self._generate_rbr(rbr, severity),
+        }
+
+        # Download binaries
+        if self.track_timings: t2 = time.time()
+        images = {} 
+
+        for d in self.deliverables:
+            gen_fn = deliverable_registry.get(d)
+            outputs = gen_fn({})
+            if isinstance(outputs, tuple) or isinstance(outputs, list):
+                for out in outputs:
+                    images[out["filename"]] = out
+            else:
+                images[outputs["filename"]] = outputs
+
+        if self.track_timings: timings["Images downloaded"] = time.time() - t2
+
+        return {
+            "images": images,
+            "timings": timings,
+            "area_by_severity": self.format_severity_table(area_stats)
+        }

wildfire_analyser-0.1.10/wildfire_analyser/fire_assessment/validators.py

@@ -0,0 +1,60 @@
+# validators.py
+import os
+import re
+import ee
+from datetime import datetime
+from wildfire_analyser.fire_assessment.deliverable import Deliverable
+
+DATE_PATTERN = r"^\d{4}-\d{2}-\d{2}$"
+
+
+def validate_date(value: str, field_name: str) -> None:
+    """Validate date format YYYY-MM-DD."""
+    if not isinstance(value, str):
+        raise ValueError(f"{field_name} must be a string in format YYYY-MM-DD.")
+
+    if not re.match(DATE_PATTERN, value):
+        raise ValueError(f"{field_name} must follow format YYYY-MM-DD.")
+
+    try:
+        datetime.strptime(value, "%Y-%m-%d")
+    except Exception:
+        raise ValueError(f"{field_name} is not a valid calendar date.")
+
+
+def validate_geojson_path(path: str) -> None:
+    """Validate that path exists, is a file, and ends with .geojson."""
+    if not isinstance(path, str):
+        raise ValueError("geojson_path must be a string.")
+
+    if not path.endswith(".geojson"):
+        raise ValueError("geojson_path must end with .geojson")
+
+    if not os.path.isfile(path):
+        raise ValueError(f"geojson_path does not exist: {path}")
+
+
+def validate_deliverables(deliverables: list | None) -> None:
+    """
+    Validate deliverables list.
+    If None → allowed (client wants all deliverables).
+    If list → ensure each item is Deliverable.
+    """
+    if deliverables is None:
+        return  # valid, user wants default behavior
+
+    if not isinstance(deliverables, list):
+        raise ValueError("deliverables must be a list of Deliverable values.")
+
+    invalid = [d for d in deliverables if not isinstance(d, Deliverable)]
+    if invalid:
+        raise ValueError(f"Invalid deliverables: {invalid}")
+
+def ensure_not_empty(collection: ee.ImageCollection, start: str, end: str) -> None:
+    try:
+        size_val = collection.size().getInfo()
+    except Exception:
+        size_val = 0
+
+    if size_val == 0:
+        raise ValueError(f"No images found in date range {start} → {end}")

wildfire_analyser-0.1.10/wildfire_analyser.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: wildfire-analyser
+Version: 0.1.10
+Summary: Python library for post-fire assessment and wildfire analysis using Google Earth Engine.
+Author: Marcelo Camargo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/camargo-advanced/wildfire-analyser
+Project-URL: Source, https://github.com/camargo-advanced/wildfire-analyser
+Project-URL: Issues, https://github.com/camargo-advanced/wildfire-analyser/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geemap==0.36.6
+Requires-Dist: geopandas==1.1.1
+Requires-Dist: geedim==2.0.0
+Requires-Dist: python-dotenv==1.0.1
+Dynamic: license-file
+
+# wildfire-analyser
+
+Python project for analyzing wildfires in natural reserves.
+
+## Installation and Usage
+
+Follow the steps below to install and test `wildfire-analyser` inside an isolated environment:
+
+```bash
+mkdir /tmp/test
+cd /tmp/test
+
+python3 -m venv venv
+source venv/bin/activate
+
+pip install wildfire-analyser
+```
+
+### Required Files Before Running the Client
+
+Before running the client, you **must** prepare two items:
+
+---
+
+#### **1. Add a GeoJSON polygon**
+
+Create a folder named `polygons` in the project root and place your ROI polygon file inside it:
+
+```
+/tmp/test/
+├── polygons/
+│   └── your_polygon.geojson
+└── venv/
+```
+
+An example GeoJSON file is available in the repository.
+
+---
+
+#### **2. Create the `.env` file with GEE authentication data**
+
+In the project root, add a `.env` file containing your Google Earth Engine authentication variables.
+
+A `.env` template is also available in the GitHub repository.
+
+```
+/tmp/test/
+├── .env
+├── polygons/
+└── venv/
+```
+
+---
+
+### Running the Client
+
+After adding the `.env` file and your GeoJSON polygon:
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+This will start the analysis process, generate the configured deliverables, and save the output files in the current directory.
+
+
+
+## Setup Instructions for Developers
+
+1. **Clone the repository**
+
+```bash
+git clone git@github.com:camargo-advanced/wildfire-analyser.git
+cd wildfire-analyser
+```
+
+2. **Create a virtual environment**
+
+```bash
+python3 -m venv venv
+```
+
+3. **Activate the virtual environment**
+
+```bash
+source venv/bin/activate
+```
+
+4. **Install dependencies**
+   Make sure the virtual environment is activated, then run:
+
+```bash
+pip install -r requirements.txt
+```
+
+5. **Configure environment variables**
+   Copy your version of `.env` file to the root folder with your GEE authentication credentials. A template file `.env.template` is provided as an example.
+
+6. **Run the sample client application**
+
+```bash
+python3 -m wildfire_analyser.client
+```
+
+## Useful Commands
+
+* **Deactivate the virtual environment**:
+
+```bash
+deactivate
+```

wildfire_analyser-0.1.10/wildfire_analyser.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+wildfire_analyser/__init__.py
+wildfire_analyser/client.py
+wildfire_analyser.egg-info/PKG-INFO
+wildfire_analyser.egg-info/SOURCES.txt
+wildfire_analyser.egg-info/dependency_links.txt
+wildfire_analyser.egg-info/requires.txt
+wildfire_analyser.egg-info/top_level.txt
+wildfire_analyser/fire_assessment/__init__.py
+wildfire_analyser/fire_assessment/date_utils.py
+wildfire_analyser/fire_assessment/deliverable.py
+wildfire_analyser/fire_assessment/downloaders.py
+wildfire_analyser/fire_assessment/fire_severity.py
+wildfire_analyser/fire_assessment/post_fire_assessment.py
+wildfire_analyser/fire_assessment/validators.py

wildfire_analyser-0.1.10/wildfire_analyser.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wildfire_analyser-0.1.10/wildfire_analyser.egg-info/requires.txt

@@ -0,0 +1,4 @@
+geemap==0.36.6
+geopandas==1.1.1
+geedim==2.0.0
+python-dotenv==1.0.1

wildfire_analyser-0.1.10/wildfire_analyser.egg-info/top_level.txt

@@ -0,0 +1 @@
+wildfire_analyser