Update README.md

README.md

@@ -1,132 +1,158 @@
----
-language: en
-license: mit
-library_name: pytorch
-tags:
-- biomass
-- remote-sensing
-- satellite-imagery
-- deep-learning
-- regression
----
+# Biomass Prediction Model
 
-# StableResNet Biomass Prediction Model
+[![Open In Spaces](https://img.shields.io/badge/🤗-Open%20In%20Spaces-blue.svg)](https://huggingface.co/spaces/vertify/biomass-prediction)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-This model predicts above-ground biomass (AGB) from multi-spectral satellite imagery on a per-pixel basis.
+## Overview
 
-## Model Description
+This model predicts above-ground biomass (AGB) in forest ecosystems using multi-spectral satellite imagery. Developed by vertify.earth for the GIZ Forest Forward initiative, this tool supports sustainable forest management and carbon monitoring efforts. Biomass estimation is a critical component for carbon stock assessment, ecosystem monitoring, and sustainable forest management.
 
-- **Developed by:** pokkiri
-- **Model type:** StableResNet
-- **Date:** 2025-05-17
-- **License:** MIT
+## Model Details
 
-### Input
+- **Model Type**: StableResNet (Custom PyTorch architecture)
+- **Task**: Regression (Biomass prediction in Mg/ha)
+- **Input**: Multi-spectral satellite imagery (GeoTIFF format)
+- **Output**: Biomass heatmap and statistics
+- **Creator**: vertify.earth
+- **Partner**: GIZ Forest Forward initiative
+- **Date**: May 16, 2025
 
-The model takes multi-spectral satellite data as input, processing features extracted from each pixel.
+## Key Features
 
-### Output
+- **Multi-source Fusion**: Combines data from multiple satellite sensors (Sentinel-1, Sentinel-2, Landsat-8, PALSAR)
+- **Advanced Feature Engineering**: Calculates spectral indices, texture features, and spatial context features
+- **Stable Architecture**: Uses ResNet-inspired architecture with numerical stability improvements
+- **Interactive Visualization**: Provides heatmaps and RGB overlays of biomass predictions
+- **Comprehensive Statistics**: Calculates mean, median, min, max, and total biomass for the analyzed area
 
-The model outputs biomass predictions in Mg/ha (megagrams per hectare).
+## Performance
 
-## Training Data
+| Metric | Log Scale | Original Scale |
+|--------|-----------|----------------|
+| R² | 0.87 | 0.83 |
+| RMSE | 0.32 log(Mg/ha) | 28.7 Mg/ha |
+| MAE | 0.25 log(Mg/ha) | 19.5 Mg/ha |
 
-The model was trained on multi-spectral satellite imagery from various forest regions, including:
-- Sentinel-1 (SAR)
-- Sentinel-2 (optical)
-- Landsat-8 (optical)
-- PALSAR (SAR)
+## Use Cases
 
-Ground truth biomass measurements were derived from field measurements.
+- **Carbon Stock Assessment**: Estimate carbon sequestration in forests
+- **Biodiversity Monitoring**: Monitor forest structure as a proxy for habitat quality
+- **Sustainable Forestry**: Plan and monitor sustainable timber harvesting
+- **Land Use Change**: Detect and quantify forest degradation and regrowth
+- **Climate Change Research**: Monitor changes in biomass over time
 
-## Performance
+## Usage
 
-The model achieves strong performance in predicting biomass across diverse landscapes:
-- RMSE: ~25 Mg/ha
-- R²: ~0.90
-- MAE: ~18 Mg/ha
+### Gradio App
 
-## Training Procedure
+The easiest way to use this model is through the provided Gradio interface:
 
-The model was trained with:
-- MSE loss function
-- Adam optimizer with learning rate 0.001
-- Early stopping based on validation performance
-- Log transformation for target values to stabilize training
+1. Upload a multi-band satellite image in GeoTIFF format
+2. Select visualization type (heatmap or RGB overlay)
+3. Click "Generate Biomass Prediction"
+4. View the biomass map and statistics
 
-## How to Use
+### API Usage
 
 ```python
-from huggingface_hub import hf_hub_download
-import torch
-import joblib
-import numpy as np
-from model import StableResNet
-
-# Download model files
-model_path = hf_hub_download(repo_id="pokkiri/biomass-model", filename="model.pt")
-package_path = hf_hub_download(repo_id="pokkiri/biomass-model", filename="model_package.pkl")
-
-# Load model and package
-package = joblib.load(package_path)
-model = StableResNet(n_features=package['n_features'])
-model.load_state_dict(torch.load(model_path, map_location="cpu"))
-model.eval()
-
-# Example inference function
-def predict_biomass(features):
-    # Scale features
-    features_scaled = package['scaler'].transform(features)
-    
-    # Convert to tensor
-    tensor = torch.tensor(features_scaled, dtype=torch.float32)
-    
-    # Make prediction
-    with torch.no_grad():
-        output = model(tensor).numpy()
-    
-    # Convert from log scale if needed
-    if package.get('use_log_transform', True):
-        output = np.exp(output) - package.get('epsilon', 1.0)
-        output = np.maximum(output, 0)  # Ensure non-negative
-    
-    return output
-
-# Example: predict for a single pixel with features
-example_features = np.random.rand(1, package['n_features'])  # Replace with actual features
-biomass = predict_biomass(example_features)
-print(f"Predicted biomass: {biomass[0]:.2f} Mg/ha")
-
-
-
-For GeoTIFF processing, use the included inference.py:
-
-``` Python
-from inference import predict_from_geotiff
-
-# Process a multi-band satellite image
-biomass_map = predict_from_geotiff(
-    "satellite_image.tif",
-    "output_biomass.tif",
-    repo_id="pokkiri/biomass-model"
-)
+import requests
+import io
+from PIL import Image
+
+# API endpoint
+API_URL = "https://api-inference.huggingface.co/models/vertify/biomass-prediction"
+headers = {"Authorization": f"Bearer {API_TOKEN}"}
+
+def predict_biomass(filename):
+    with open(filename, "rb") as f:
+        data = f.read()
+    response = requests.post(API_URL, headers=headers, data=data)
+    return response.json()
+
+# Example usage
+result = predict_biomass("path/to/your/satellite_image.tif")
+```
+
+### Local Installation
 
+```bash
+# Clone the repository
+git clone https://huggingface.co/vertify/biomass-prediction
+cd biomass-prediction
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the Gradio app
+python app.py
 ```
 
+### Inference Script
+
+This repository includes a full inference script (`predict_biomass.py`) that allows you to process satellite imagery in batch mode and generate biomass maps:
+
+```bash
+# Example usage
+python predict_biomass.py --input_dir /path/to/satellite_images --output_dir /path/to/output --visualization_type heatmap
+```
+
+For full documentation on the inference script options, see the script header or run:
+```bash
+python predict_biomass.py --help
+```
+
+## Full Training Pipeline
+
+The complete training pipeline, including data preprocessing, feature engineering, model training, and evaluation is available in our [GitHub repository](https://github.com/vertify/biomass-prediction-training). Please refer to the GitHub repository for detailed documentation on training your own biomass prediction models.
+
+## Input Data Requirements
+
+For optimal results, your satellite imagery should include:
+
+- **Optical bands**: Blue, Green, Red, Near Infrared (NIR), SWIR1, SWIR2
+- **Radar bands**: Sentinel-1 VV, VH polarizations (if available)
+- **DEM**: Digital Elevation Model (if available)
+- **Format**: GeoTIFF with proper georeferencing
+
+The model has been trained on data from various forest types including tropical, temperate, and boreal forests, making it adaptable to different ecosystems.
+
 ## Limitations
 
-- The model performs best on forest types similar to those in the training data
-- Very high biomass values (>500 Mg/ha) may be underestimated
-- Requires calibrated multi-spectral satellite imagery as input
+- Performance may vary in extremely dense forests (>500 Mg/ha) due to saturation effects
+- Model accuracy depends on the quality and consistency of input satellite data
+- Cloud cover in optical imagery can reduce prediction quality
+- Limited validation in certain ecosystem types (e.g., mangroves, wetlands)
+
+## Citation
 
-@## Citation
+If you use this model in your research, please cite:
 
 ```
-@misc{biomass_model,
-  author = {pokkiri},
-  title = {StableResNet Biomass Prediction Model},
+@misc{vertify2025biomass,
+  author = {vertify.earth},
+  title = {Biomass Prediction Model Using Multi-spectral Satellite Imagery},
   year = {2025},
   publisher = {HuggingFace},
-  howpublished = {https://huggingface.co/pokkiri/biomass-model}
+  note = {Developed for GIZ Forest Forward initiative},
+  howpublished = {\url{https://huggingface.co/spaces/vertify/biomass-prediction}}
 }
-```
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgements
+
+- Project developed by vertify.earth for the GIZ Forest Forward initiative
+- Training data sources include field measurements from various research institutions
+- Satellite imagery from ESA Copernicus Programme (Sentinel-1, Sentinel-2) and NASA/USGS (Landsat-8)
+- Special thanks to the open-source community for tools and libraries used in this project
+
+## Contact
+
+For questions, feedback, or collaboration opportunities, please reach out via:
+- HuggingFace: [@vertify](https://huggingface.co/vertify)
+- GitHub: [vertify](https://github.com/vertify)
+- Email: info@vertify.earth