Metadata-Version: 2.4
Name: snowmappy
Version: 1.0.0
Summary: A comprehensive Python package for processing MODIS NDSI data from local files and Google Earth Engine
Home-page: https://github.com/Hbechri/SnowMapPy
Author: Haytam Elyoussfi
Author-email: haytam.elyoussfi@um6p.ma
Project-URL: Bug Reports, https://github.com/Hbechri/SnowMapPy/issues
Project-URL: Source, https://github.com/Hbechri/SnowMapPy
Project-URL: Documentation, https://github.com/Hbechri/SnowMapPy#readme
Keywords: modis,snow,remote sensing,earth engine,gis,hydrology
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy==2.1.0
Requires-Dist: scipy==1.15.2
Requires-Dist: pandas==2.2.3
Requires-Dist: rasterio==1.4.3
Requires-Dist: geopandas==1.0.1
Requires-Dist: pyproj==3.7.1
Requires-Dist: shapely==2.1.0
Requires-Dist: affine==2.4.0
Requires-Dist: xarray==2025.3.1
Requires-Dist: zarr==3.0.6
Requires-Dist: numcodecs==0.16.0
Requires-Dist: h5py==3.13.0
Requires-Dist: netCDF4==1.7.2
Requires-Dist: earthengine-api==1.5.9
Requires-Dist: geemap==0.35.3
Requires-Dist: tqdm==4.66.4
Requires-Dist: joblib==1.4.2
Requires-Dist: python-dateutil==2.9.0
Requires-Dist: matplotlib==3.10.1
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SnowMapPy 🌨️

A comprehensive Python package for processing MODIS NDSI (Normalized Difference Snow Index) data from both local files and Google Earth Engine, with advanced quality control and temporal interpolation capabilities.

## 📋 Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Package Structure](#package-structure)
- [Usage Examples](#usage-examples)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

## ✨ Features

- **🌐 Cloud Processing**: Download and process MODIS NDSI data directly from Google Earth Engine
- **💾 Local Processing**: Process locally stored MODIS NDSI files
- **🔍 Quality Control**: Advanced masking using NDSI_Snow_Cover_Class for data validation
- **⏰ Temporal Interpolation**: Fill missing data points using spatial and temporal interpolation
- **🗺️ Spatial Operations**: Clip data to regions of interest using shapefiles or bounding boxes
- **📊 Data Export**: Save processed data in Zarr format for efficient storage and access
- **🧪 Comprehensive Testing**: Unit tests and real-world processing tests

## 🚀 Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install snowmappy
```

### Option 2: Install from GitHub

1. **Clone the repository:**
   ```bash
   git clone https://github.com/Hbechri/SnowMapPy.git
   cd SnowMapPy/package
   ```

2. **Install the package:**
   ```bash
   pip install -e .
   ```

### Prerequisites

- Python 3.8+
- Google Earth Engine account (for cloud processing)
- Required Python packages (automatically installed with the package)

### Google Earth Engine Setup (for cloud processing)

1. **Sign up for Google Earth Engine:**
   - Visit [https://earthengine.google.com/](https://earthengine.google.com/)
   - Sign up for an account

2. **Authenticate:**
   ```bash
   earthengine authenticate
   ```

## 🎯 Quick Start

### Cloud Processing Example

```python
from snowmappy.cloud.processor import process_modis_ndsi_cloud

# Process MODIS NDSI data from Google Earth Engine
result = process_modis_ndsi_cloud(
    project_name="your-gee-project",
    shapefile_path="path/to/roi.shp",
    start_date="2023-01-01",
    end_date="2023-01-31",
    output_path="output/",
    file_name="snow_cover"
)
```

### Local Processing Example

```python
from snowmappy.local.processor import process_modis_ndsi_local

# Process locally stored MODIS NDSI files
result = process_modis_ndsi_local(
    mod_dir="path/to/MOD/files/",
    myd_dir="path/to/MYD/files/",
    dem_file="path/to/dem.tif",
    output_path="output/",
    file_name="local_snow_cover"
)
```

## 📁 Package Structure

```
SnowMapPy/
├── core/                    # Shared functionality
│   ├── data_io.py          # Data input/output operations
│   ├── quality.py           # Quality control functions
│   ├── spatial.py           # Spatial operations
│   ├── temporal.py          # Temporal interpolation
│   └── utils.py             # Utility functions
├── cloud/                   # Google Earth Engine processing
│   ├── auth.py              # GEE authentication
│   ├── loader.py            # Data loading from GEE
│   └── processor.py         # Cloud processing pipeline
├── local/                   # Local file processing
│   ├── file_handler.py      # File management
│   ├── preparator.py        # Data preparation
│   └── processor.py         # Local processing pipeline
└── tests/                   # Test suite
    ├── test_core/           # Core functionality tests
    ├── test_cloud/          # Cloud processing tests
    └── test_local/          # Local processing tests
```

## 📖 Usage Examples

### Quality Control

```python
from snowmappy.core.quality import get_invalid_modis_classes, apply_modis_quality_mask

# Get invalid MODIS class values
invalid_classes = get_invalid_modis_classes()
print(f"Invalid classes: {invalid_classes}")

# Apply quality mask to data
masked_data = apply_modis_quality_mask(value_data, class_data)
```

### Spatial Operations

```python
from snowmappy.core.spatial import clip_dem_to_roi

# Clip DEM to region of interest
clipped_dem = clip_dem_to_roi(dem_data, shapefile_path)
```

## 🧪 Testing

Run the test suite:

```bash
# Run all tests
python -m pytest tests/

# Run specific test categories
python tests/test_core/test_quality.py
python tests/test_cloud/test_basic_cloud.py
```

For detailed testing instructions, see [TESTING.md](TESTING.md).

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Google Earth Engine team for providing the platform
- NASA for MODIS data
- The open-source geospatial community

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/Hbechri/SnowMapPy/issues)
- **Documentation**: [GitHub README](https://github.com/Hbechri/SnowMapPy#readme)
- **Email**: haytam.elyoussfi@um6p.ma
