atash 0.1.7

A library for satellite image processing and fire analysis.

Atash: Fire Detection and Severity Classification using Remote Sensing Data

Atash is an open-source Python library designed for fire detection and burn severity classification using remote sensing data. It integrates with OpenEO to process Sentinel-2 imagery and generates detailed NDVI, NBR, and NDWI maps for analysis.

Table of Contents

1. Authentication Details
2. Features
3. File Structure
4. Installation
5. Configuration
6. Usage
7. Input/Output Specifications
8. Function Documentation
9. Error Handling
10. Performance Considerations
11. Contributors and Support
12. License
13. Data Privacy Note

---

1. Authentication Details

To authenticate with OpenEO, you need OIDC credentials.

1. Register at Copernicus Data Space to obtain login credentials.
2. Create a secrets.yaml file with the following contents:

   openeo:
     url: "https://openeo.dataspace.copernicus.eu"
     authentication: "OIDC"
   

3. Ensure secrets.yaml is excluded from version control using .gitignore.

---

2. Features

• OpenEO Integration: Easily connect and authenticate using OIDC.
• NDVI, NBR, and NDWI Calculations: Compute vegetation health, burn severity, and water indices.
• Fire Detection: Detect fire-affected areas using NDVI and NBR differences.
• Severity Classification: Classify burn severity using thresholds and KMeans clustering.
  • KMeans Clustering: Groups pixels into clusters based on NDVI, NBR, and NDWI values to classify fire severity levels.
• Interactive ROI Selection: Use an interactive map to define spatial extents.
• Water Masking: Improve accuracy by excluding water bodies using NDWI.

---

3. File Structure

atash/
├── data/
│   └── README.md (instructions for adding `.tiff` files)
├── src/
│   └── atash.py (library source code)
├── requirements.txt (library dependencies)
├── secrets.yaml (authentication credentials, ignored in `.gitignore`)
└── README.md (project documentation)

---

4. Installation

Prerequisites

• Python 3.8+
• Pip and Git

Steps

1. Clone the repository:

   git clone https://github.com/username/Atash.git
   cd Atash
   

2. Create a virtual environment:

   python -m venv env
   source env/bin/activate  # For Windows: env\\Scripts\\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

---

5. Configuration

secrets.yaml Setup

Ensure your secrets.yaml contains the required URL and authentication mode.

---

6. Usage

Complete Workflow Example

from atash import connect_to_openeo, load_map, get_start_and_end_dates, load_pre_ndvi, load_post_ndvi, fire_detector_ndvi, severity_ndvi

# Step 1: Connect to OpenEO
connection = connect_to_openeo()

# Step 2: Define area of interest
map_interface = load_map()

# Step 3: Set temporal extent
start_date, end_date = get_start_and_end_dates()

# Step 4: Process pre/post-event data
load_pre_ndvi(connection, extent, start_date, end_date)
load_post_ndvi(connection, extent, start_date, end_date)

# Step 5: Analyze fire impact
fire_detector_ndvi()
severity_ndvi()

---

7. Input/Output Specifications

Input Data:

• Format: .tiff files for raster data.
• Required Bands:
  • B03 (Green), B04 (Red), B08 (NIR), B12 (SWIR).
• Coordinate Reference System (CRS): Input rasters must have the same CRS (e.g., EPSG:4326).
• Raster Resolution: Assumed to be 10m x 10m.

File Naming Conventions:

• Ensure consistent file naming:
  • NDVI_PRE.tiff for pre-event NDVI.
  • NBR_PRE.tiff for pre-event NBR.
  • NDWI.tiff for water mask rasters.
  • NDVI_Post.tiff for post-event NDVI.
  • NBR_Post.tiff for post-event NBR.

Output Files:

• ``: Pre-event NDVI raster.
• ``: Post-event NDVI raster.
• ``: Pre-event NBR raster.
• ``: Post-event NBR raster.
• ``: Water mask raster.

---

8. Function Documentation

API Reference Table

Function	Purpose	Parameters
connect_to_openeo()	Establishes OpenEO connection	-
load_map()	Displays an interactive map for ROI	-
get_start_and_end_dates()	Captures start and end dates	-
load_pre_ndvi()	Loads pre-event NDVI data	connection, extent, start_date, end_date
load_post_ndvi()	Loads post-event NDVI data	connection, extent, start_date, end_date
fire_detector_ndvi()	Detects fire-affected areas via NDVI	-
severity_ndvi()	Classifies fire severity (NDVI)	-
severity_kmeans()	Uses KMeans clustering for classification	-

---

9. Error Handling

Common Issues and Solutions

1. OpenEO Connection Error:

   • Message: "Failed to connect to OpenEO: [specific error]"
   • Solution: Check OpenEO URL, credentials, and internet connection.

2. FileNotFoundError:

   • Message: "File not found: NDVI_PRE.tiff"
   • Solution: Ensure the required .tiff files are present in the data/ folder.

3. MemoryError:

   • Message: "Unable to allocate array"
   • Solution: Reduce raster size or increase system memory.

4. Data Format Issue:

   • Message: "Invalid raster dimensions"
   • Solution: Ensure input .tiff files have matching resolutions and CRS.

5. Median Filter Missing Dependency:

   • Message: "ModuleNotFoundError: No module named 'scipy'"
   • Solution: Install scipy using pip install scipy.

---

10. Performance Considerations

• Processing Time:
  • Small ROI (<50 km²): ~5 minutes.
  • Large ROI (>500 km²): ~30 minutes.
• System Requirements:
  • 8GB RAM (minimum).
  • Multi-core CPU recommended.

---

11. Contributors and Support

We extend our gratitude to the contributors of the "Atash" project. You can explore their profiles for more projects and collaborations:

• Bahman Amirsardary – [e-mail].
• Hadi Kheiri Gharajeh – [e-mail].
• Milad Ramezani Ziarani – [e-mail].

For support or contributions, feel free to contact us.

12. License

This project is released under the MIT License.

---

13. Data Privacy Note

Atash does not store or log user data. Any authentication or API usage is handled securely via OpenEO's OIDC protocol. Ensure you review OpenEO's privacy policy for their data handling practices.

---

Contributions are welcome! Feel free to open issues or submit pull requests.