# 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
Raw data
{
"_id": null,
"home_page": "https://github.com/Hbechri/SnowMapPy",
"name": "SnowMapPy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "modis, snow, remote sensing, earth engine, gis, hydrology",
"author": "Haytam Elyoussfi",
"author_email": "haytam.elyoussfi@um6p.ma",
"download_url": "https://files.pythonhosted.org/packages/f7/4b/2319b91d6dd38dafec23063f6c350e048864cb4eeadccc2705658adee33e/snowmappy-1.0.1.tar.gz",
"platform": null,
"description": "# SnowMapPy \ud83c\udf28\ufe0f\r\n\r\nA 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.\r\n\r\n## \ud83d\udccb Table of Contents\r\n\r\n- [Features](#features)\r\n- [Installation](#installation)\r\n- [Quick Start](#quick-start)\r\n- [Package Structure](#package-structure)\r\n- [Usage Examples](#usage-examples)\r\n- [Testing](#testing)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n## \u2728 Features\r\n\r\n- **\ud83c\udf10 Cloud Processing**: Download and process MODIS NDSI data directly from Google Earth Engine\r\n- **\ud83d\udcbe Local Processing**: Process locally stored MODIS NDSI files\r\n- **\ud83d\udd0d Quality Control**: Advanced masking using NDSI_Snow_Cover_Class for data validation\r\n- **\u23f0 Temporal Interpolation**: Fill missing data points using spatial and temporal interpolation\r\n- **\ud83d\uddfa\ufe0f Spatial Operations**: Clip data to regions of interest using shapefiles or bounding boxes\r\n- **\ud83d\udcca Data Export**: Save processed data in Zarr format for efficient storage and access\r\n- **\ud83e\uddea Comprehensive Testing**: Unit tests and real-world processing tests\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n### Option 1: Install from PyPI (Recommended)\r\n\r\n```bash\r\npip install SnowMapPy\r\n```\r\n\r\n### Option 2: Install from GitHub\r\n\r\n1. **Clone the repository:**\r\n ```bash\r\n git clone https://github.com/Hbechri/SnowMapPy.git\r\n cd SnowMapPy/package\r\n ```\r\n\r\n2. **Install the package:**\r\n ```bash\r\n pip install -e .\r\n ```\r\n\r\n### Prerequisites\r\n\r\n- Python 3.8+\r\n- Google Earth Engine account (for cloud processing)\r\n- Required Python packages (automatically installed with the package)\r\n\r\n### Google Earth Engine Setup (for cloud processing)\r\n\r\n1. **Sign up for Google Earth Engine:**\r\n - Visit [https://earthengine.google.com/](https://earthengine.google.com/)\r\n - Sign up for an account\r\n\r\n2. **Authenticate:**\r\n ```bash\r\n earthengine authenticate\r\n ```\r\n\r\n## \ud83c\udfaf Quick Start\r\n\r\n### Cloud Processing Example\r\n\r\n```python\r\nfrom SnowMapPy.cloud.processor import process_modis_ndsi_cloud\r\n\r\n# Process MODIS NDSI data from Google Earth Engine\r\nresult = process_modis_ndsi_cloud(\r\n project_name=\"your-gee-project\",\r\n shapefile_path=\"path/to/roi.shp\",\r\n start_date=\"2023-01-01\",\r\n end_date=\"2023-01-31\",\r\n output_path=\"output/\",\r\n file_name=\"snow_cover\"\r\n)\r\n```\r\n\r\n### Local Processing Example\r\n\r\n```python\r\nfrom SnowMapPy.local.processor import process_modis_ndsi_local\r\n\r\n# Process locally stored MODIS NDSI files\r\nresult = process_modis_ndsi_local(\r\n mod_dir=\"path/to/MOD/files/\",\r\n myd_dir=\"path/to/MYD/files/\",\r\n dem_file=\"path/to/dem.tif\",\r\n output_path=\"output/\",\r\n file_name=\"local_snow_cover\"\r\n)\r\n```\r\n\r\n## \ud83d\udcc1 Package Structure\r\n\r\n```\r\nSnowMapPy/\r\n\u251c\u2500\u2500 core/ # Shared functionality\r\n\u2502 \u251c\u2500\u2500 data_io.py # Data input/output operations\r\n\u2502 \u251c\u2500\u2500 quality.py # Quality control functions\r\n\u2502 \u251c\u2500\u2500 spatial.py # Spatial operations\r\n\u2502 \u251c\u2500\u2500 temporal.py # Temporal interpolation\r\n\u2502 \u2514\u2500\u2500 utils.py # Utility functions\r\n\u251c\u2500\u2500 cloud/ # Google Earth Engine processing\r\n\u2502 \u251c\u2500\u2500 auth.py # GEE authentication\r\n\u2502 \u251c\u2500\u2500 loader.py # Data loading from GEE\r\n\u2502 \u2514\u2500\u2500 processor.py # Cloud processing pipeline\r\n\u251c\u2500\u2500 local/ # Local file processing\r\n\u2502 \u251c\u2500\u2500 file_handler.py # File management\r\n\u2502 \u251c\u2500\u2500 preparator.py # Data preparation\r\n\u2502 \u2514\u2500\u2500 processor.py # Local processing pipeline\r\n\u2514\u2500\u2500 tests/ # Test suite\r\n \u251c\u2500\u2500 test_core/ # Core functionality tests\r\n \u251c\u2500\u2500 test_cloud/ # Cloud processing tests\r\n \u2514\u2500\u2500 test_local/ # Local processing tests\r\n```\r\n\r\n## \ud83d\udcd6 Usage Examples\r\n\r\n### Quality Control\r\n\r\n```python\r\nfrom SnowMapPy.core.quality import get_invalid_modis_classes, apply_modis_quality_mask\r\n\r\n# Get invalid MODIS class values\r\ninvalid_classes = get_invalid_modis_classes()\r\nprint(f\"Invalid classes: {invalid_classes}\")\r\n\r\n# Apply quality mask to data\r\nmasked_data = apply_modis_quality_mask(value_data, class_data)\r\n```\r\n\r\n### Spatial Operations\r\n\r\n```python\r\nfrom SnowMapPy.core.spatial import clip_dem_to_roi\r\n\r\n# Clip DEM to region of interest\r\nclipped_dem = clip_dem_to_roi(dem_data, shapefile_path)\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\nRun the test suite:\r\n\r\n```bash\r\n# Run all tests\r\npython -m pytest tests/\r\n\r\n# Run specific test categories\r\npython tests/test_core/test_quality.py\r\npython tests/test_cloud/test_basic_cloud.py\r\n```\r\n\r\nFor detailed testing instructions, see [TESTING.md](TESTING.md).\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Google Earth Engine team for providing the platform\r\n- NASA for MODIS data\r\n- The open-source geospatial community\r\n\r\n## \ud83d\udcde Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/Hbechri/SnowMapPy/issues)\r\n- **Documentation**: [GitHub README](https://github.com/Hbechri/SnowMapPy#readme)\r\n- **Email**: haytam.elyoussfi@um6p.ma\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python package for processing MODIS NDSI data from local files and Google Earth Engine",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/Hbechri/SnowMapPy/issues",
"Documentation": "https://github.com/Hbechri/SnowMapPy#readme",
"Homepage": "https://github.com/Hbechri/SnowMapPy",
"Source": "https://github.com/Hbechri/SnowMapPy"
},
"split_keywords": [
"modis",
" snow",
" remote sensing",
" earth engine",
" gis",
" hydrology"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fb4b82dfb12ec22f28b0a5f436e688ee60a662e41b057727fa0979d6e8482770",
"md5": "88902bc13b3cde30cdb23e4e2505d173",
"sha256": "94681ef691ed3fef55271a8f340ae57b7471fd9de14593623ea3cf3c1a9b32f7"
},
"downloads": -1,
"filename": "snowmappy-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88902bc13b3cde30cdb23e4e2505d173",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31742,
"upload_time": "2025-08-05T04:06:32",
"upload_time_iso_8601": "2025-08-05T04:06:32.981898Z",
"url": "https://files.pythonhosted.org/packages/fb/4b/82dfb12ec22f28b0a5f436e688ee60a662e41b057727fa0979d6e8482770/snowmappy-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f74b2319b91d6dd38dafec23063f6c350e048864cb4eeadccc2705658adee33e",
"md5": "4ab59aab5b23ffd2c9b91f5ebe866f0d",
"sha256": "321e90564944ecda7a2f4061d05d88208452a7d66b7d28fc998cc4faedea3d51"
},
"downloads": -1,
"filename": "snowmappy-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "4ab59aab5b23ffd2c9b91f5ebe866f0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 27524,
"upload_time": "2025-08-05T04:06:35",
"upload_time_iso_8601": "2025-08-05T04:06:35.589996Z",
"url": "https://files.pythonhosted.org/packages/f7/4b/2319b91d6dd38dafec23063f6c350e048864cb4eeadccc2705658adee33e/snowmappy-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 04:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hbechri",
"github_project": "SnowMapPy",
"github_not_found": true,
"lcname": "snowmappy"
}
JSON
