# 🌱 NDVI Pro Python SDK (`ndvipy`)
[](https://badge.fury.io/py/ndvipy)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
Professional Python SDK for generating NDVI (Normalized Difference Vegetation Index) visualizations from satellite imagery using the NDVI Pro cloud service.
## 🚀 Quick Start
### Installation
```bash
pip install ndvipy
```
### Basic Usage
```python
from ndvipy import NDVIClient
# Initialize client with your API key
client = NDVIClient(api_key="your_64_character_api_key_here")
# Process an image and save the result
client.save_processed_image("satellite_image.jpg", "ndvi_result.png")
# Or get the result as bytes for further processing
result_bytes = client.process_image("satellite_image.jpg")
with open("ndvi_output.png", "wb") as f:
f.write(result_bytes)
```
## 🔑 Getting an API Key
1. Sign up at [NDVI Pro Dashboard](https://ndvipro.com/dashboard)
2. Generate your API key in the dashboard
3. All API calls are logged and tracked in your dashboard
## 📖 Documentation
### NDVIClient
The main client class for interacting with the NDVI Pro service.
```python
NDVIClient(
api_key: str,
backend_url: str = "https://b563bb24a1b2.ngrok-free.app",
timeout: int = 120,
max_retries: int = 3,
validate_images: bool = True
)
```
**Parameters:**
- `api_key`: Your 64-character API key from the NDVI Pro dashboard
- `backend_url`: Backend service URL (optional, uses default cloud service)
- `timeout`: Request timeout in seconds (default: 120)
- `max_retries`: Maximum retry attempts for failed requests (default: 3)
- `validate_images`: Whether to validate image files before upload (default: True)
### Methods
#### `process_image(image, user_id=None)`
Process an image and return NDVI visualization as PNG bytes.
**Parameters:**
- `image`: Input image. Supports:
- File path (string or Path object)
- Raw image bytes
- Binary file-like object
- `user_id`: Optional user ID for request tracking
**Returns:** PNG image bytes containing the NDVI visualization
**Example:**
```python
# From file path
result = client.process_image("satellite.jpg")
# From bytes
with open("image.jpg", "rb") as f:
result = client.process_image(f.read())
# From file object
with open("image.jpg", "rb") as f:
result = client.process_image(f)
```
#### `save_processed_image(image, output_path, user_id=None)`
Process an image and save the result directly to a file.
**Parameters:**
- `image`: Input image (same formats as `process_image`)
- `output_path`: Path where to save the NDVI result
- `user_id`: Optional user ID for request tracking
**Returns:** Path object pointing to the saved file
**Example:**
```python
saved_path = client.save_processed_image("input.jpg", "output.png")
print(f"NDVI result saved to: {saved_path}")
```
#### `validate_api_key()`
Validate that the API key is working correctly.
**Returns:** `True` if API key is valid, `False` otherwise
**Example:**
```python
if client.validate_api_key():
print("API key is valid!")
else:
print("Invalid API key")
```
#### `get_health_status()`
Get the health status of the NDVI service.
**Returns:** Dictionary with service health information
**Example:**
```python
health = client.get_health_status()
print(f"Service status: {health['status']}")
```
## 📊 Advanced Examples
### Batch Processing
```python
from ndvipy import NDVIClient
from pathlib import Path
client = NDVIClient(api_key="your_api_key")
# Process all images in a directory
input_dir = Path("satellite_images/")
output_dir = Path("ndvi_results/")
output_dir.mkdir(exist_ok=True)
for image_file in input_dir.glob("*.jpg"):
try:
output_file = output_dir / f"ndvi_{image_file.stem}.png"
client.save_processed_image(image_file, output_file)
print(f"✅ Processed: {image_file.name}")
except Exception as e:
print(f"❌ Failed {image_file.name}: {e}")
```
### Error Handling
```python
from ndvipy import NDVIClient, NDVIError, NDVIAuthError, NDVIValidationError
client = NDVIClient(api_key="your_api_key")
try:
result = client.process_image("satellite.jpg")
print("✅ Processing successful!")
except NDVIAuthError:
print("❌ Invalid API key - check your dashboard")
except NDVIValidationError as e:
print(f"❌ Invalid input: {e}")
except NDVIError as e:
print(f"❌ NDVI service error: {e}")
except Exception as e:
print(f"💥 Unexpected error: {e}")
```
### Environment Variable Configuration
```python
import os
from ndvipy import NDVIClient
# Set API key via environment variable
os.environ["NDVI_API_KEY"] = "your_api_key_here"
# Initialize client
api_key = os.getenv("NDVI_API_KEY")
client = NDVIClient(api_key=api_key)
```
### Custom Configuration
```python
from ndvipy import NDVIClient
# Custom configuration for production use
client = NDVIClient(
api_key="your_api_key",
timeout=180, # 3 minute timeout for large images
max_retries=5, # More retries for reliability
validate_images=False # Skip validation for speed
)
```
## 🔧 Supported Image Formats
- **JPEG** (`.jpg`, `.jpeg`)
- **PNG** (`.png`)
- **TIFF** (`.tiff`, `.tif`)
- **BMP** (`.bmp`)
- **WebP** (`.webp`)
**File Size Limit:** 50MB per image
## ⚡ Performance Tips
1. **Use appropriate timeouts** for your use case
2. **Enable retry logic** for production deployments
3. **Validate images locally** before uploading when possible
4. **Process images in parallel** for batch processing
```python
import concurrent.futures
from ndvipy import NDVIClient
client = NDVIClient(api_key="your_api_key")
def process_single_image(image_path):
return client.save_processed_image(
image_path,
f"ndvi_{image_path.stem}.png"
)
# Parallel processing
image_files = ["image1.jpg", "image2.jpg", "image3.jpg"]
with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
results = list(executor.map(process_single_image, image_files))
```
## 🛠️ Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
python -m pytest tests/
# Run with coverage
python -m pytest tests/ --cov=ndvipy
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## 📝 Error Reference
- **NDVIError**: Base exception for all SDK errors
- **NDVIAuthError**: Invalid API key or authentication failure
- **NDVIValidationError**: Invalid input data or parameters
- **NDVIServerError**: Server-side processing error
- **NDVINetworkError**: Network connection issues
- **NDVITimeoutError**: Request timeout
## 🔗 Links
- [NDVI Pro Dashboard](https://ndvipro.com/dashboard)
- [API Documentation](https://ndvipro.com/docs)
- [GitHub Repository](https://github.com/ndvipro/ndvipy)
- [PyPI Package](https://pypi.org/project/ndvipy/)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Support
- 📧 Email: support@ndvipro.com
- 💬 GitHub Issues: [Report a Bug](https://github.com/ndvipro/ndvipy/issues)
- 📖 Documentation: [Full API Docs](https://ndvipro.com/docs)
---
**Built with ❤️ for the remote sensing and agriculture communities**
Raw data
{
"_id": null,
"home_page": null,
"name": "ndvipy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "NDVI Pro Team <support@ndvipro.com>",
"keywords": "ndvi, satellite, vegetation, remote-sensing, geospatial, agriculture",
"author": null,
"author_email": "NDVI Pro Team <support@ndvipro.com>",
"download_url": "https://files.pythonhosted.org/packages/bb/43/a30af2b175feea9a8732c23b302a3903147057b1da9bf2b3a3b8bc4ca871/ndvipy-0.1.2.tar.gz",
"platform": null,
"description": "# \ud83c\udf31 NDVI Pro Python SDK (`ndvipy`)\r\n\r\n[](https://badge.fury.io/py/ndvipy)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nProfessional Python SDK for generating NDVI (Normalized Difference Vegetation Index) visualizations from satellite imagery using the NDVI Pro cloud service.\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install ndvipy\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom ndvipy import NDVIClient\r\n\r\n# Initialize client with your API key\r\nclient = NDVIClient(api_key=\"your_64_character_api_key_here\")\r\n\r\n# Process an image and save the result\r\nclient.save_processed_image(\"satellite_image.jpg\", \"ndvi_result.png\")\r\n\r\n# Or get the result as bytes for further processing\r\nresult_bytes = client.process_image(\"satellite_image.jpg\")\r\nwith open(\"ndvi_output.png\", \"wb\") as f:\r\n f.write(result_bytes)\r\n```\r\n\r\n## \ud83d\udd11 Getting an API Key\r\n\r\n1. Sign up at [NDVI Pro Dashboard](https://ndvipro.com/dashboard)\r\n2. Generate your API key in the dashboard\r\n3. All API calls are logged and tracked in your dashboard\r\n\r\n## \ud83d\udcd6 Documentation\r\n\r\n### NDVIClient\r\n\r\nThe main client class for interacting with the NDVI Pro service.\r\n\r\n```python\r\nNDVIClient(\r\n api_key: str,\r\n backend_url: str = \"https://b563bb24a1b2.ngrok-free.app\",\r\n timeout: int = 120,\r\n max_retries: int = 3,\r\n validate_images: bool = True\r\n)\r\n```\r\n\r\n**Parameters:**\r\n- `api_key`: Your 64-character API key from the NDVI Pro dashboard\r\n- `backend_url`: Backend service URL (optional, uses default cloud service)\r\n- `timeout`: Request timeout in seconds (default: 120)\r\n- `max_retries`: Maximum retry attempts for failed requests (default: 3)\r\n- `validate_images`: Whether to validate image files before upload (default: True)\r\n\r\n### Methods\r\n\r\n#### `process_image(image, user_id=None)`\r\n\r\nProcess an image and return NDVI visualization as PNG bytes.\r\n\r\n**Parameters:**\r\n- `image`: Input image. Supports:\r\n - File path (string or Path object)\r\n - Raw image bytes\r\n - Binary file-like object\r\n- `user_id`: Optional user ID for request tracking\r\n\r\n**Returns:** PNG image bytes containing the NDVI visualization\r\n\r\n**Example:**\r\n```python\r\n# From file path\r\nresult = client.process_image(\"satellite.jpg\")\r\n\r\n# From bytes\r\nwith open(\"image.jpg\", \"rb\") as f:\r\n result = client.process_image(f.read())\r\n\r\n# From file object\r\nwith open(\"image.jpg\", \"rb\") as f:\r\n result = client.process_image(f)\r\n```\r\n\r\n#### `save_processed_image(image, output_path, user_id=None)`\r\n\r\nProcess an image and save the result directly to a file.\r\n\r\n**Parameters:**\r\n- `image`: Input image (same formats as `process_image`)\r\n- `output_path`: Path where to save the NDVI result\r\n- `user_id`: Optional user ID for request tracking\r\n\r\n**Returns:** Path object pointing to the saved file\r\n\r\n**Example:**\r\n```python\r\nsaved_path = client.save_processed_image(\"input.jpg\", \"output.png\")\r\nprint(f\"NDVI result saved to: {saved_path}\")\r\n```\r\n\r\n#### `validate_api_key()`\r\n\r\nValidate that the API key is working correctly.\r\n\r\n**Returns:** `True` if API key is valid, `False` otherwise\r\n\r\n**Example:**\r\n```python\r\nif client.validate_api_key():\r\n print(\"API key is valid!\")\r\nelse:\r\n print(\"Invalid API key\")\r\n```\r\n\r\n#### `get_health_status()`\r\n\r\nGet the health status of the NDVI service.\r\n\r\n**Returns:** Dictionary with service health information\r\n\r\n**Example:**\r\n```python\r\nhealth = client.get_health_status()\r\nprint(f\"Service status: {health['status']}\")\r\n```\r\n\r\n## \ud83d\udcca Advanced Examples\r\n\r\n### Batch Processing\r\n\r\n```python\r\nfrom ndvipy import NDVIClient\r\nfrom pathlib import Path\r\n\r\nclient = NDVIClient(api_key=\"your_api_key\")\r\n\r\n# Process all images in a directory\r\ninput_dir = Path(\"satellite_images/\")\r\noutput_dir = Path(\"ndvi_results/\")\r\noutput_dir.mkdir(exist_ok=True)\r\n\r\nfor image_file in input_dir.glob(\"*.jpg\"):\r\n try:\r\n output_file = output_dir / f\"ndvi_{image_file.stem}.png\"\r\n client.save_processed_image(image_file, output_file)\r\n print(f\"\u2705 Processed: {image_file.name}\")\r\n except Exception as e:\r\n print(f\"\u274c Failed {image_file.name}: {e}\")\r\n```\r\n\r\n### Error Handling\r\n\r\n```python\r\nfrom ndvipy import NDVIClient, NDVIError, NDVIAuthError, NDVIValidationError\r\n\r\nclient = NDVIClient(api_key=\"your_api_key\")\r\n\r\ntry:\r\n result = client.process_image(\"satellite.jpg\")\r\n print(\"\u2705 Processing successful!\")\r\n \r\nexcept NDVIAuthError:\r\n print(\"\u274c Invalid API key - check your dashboard\")\r\n \r\nexcept NDVIValidationError as e:\r\n print(f\"\u274c Invalid input: {e}\")\r\n \r\nexcept NDVIError as e:\r\n print(f\"\u274c NDVI service error: {e}\")\r\n \r\nexcept Exception as e:\r\n print(f\"\ud83d\udca5 Unexpected error: {e}\")\r\n```\r\n\r\n### Environment Variable Configuration\r\n\r\n```python\r\nimport os\r\nfrom ndvipy import NDVIClient\r\n\r\n# Set API key via environment variable\r\nos.environ[\"NDVI_API_KEY\"] = \"your_api_key_here\"\r\n\r\n# Initialize client\r\napi_key = os.getenv(\"NDVI_API_KEY\")\r\nclient = NDVIClient(api_key=api_key)\r\n```\r\n\r\n### Custom Configuration\r\n\r\n```python\r\nfrom ndvipy import NDVIClient\r\n\r\n# Custom configuration for production use\r\nclient = NDVIClient(\r\n api_key=\"your_api_key\",\r\n timeout=180, # 3 minute timeout for large images\r\n max_retries=5, # More retries for reliability\r\n validate_images=False # Skip validation for speed\r\n)\r\n```\r\n\r\n## \ud83d\udd27 Supported Image Formats\r\n\r\n- **JPEG** (`.jpg`, `.jpeg`)\r\n- **PNG** (`.png`)\r\n- **TIFF** (`.tiff`, `.tif`)\r\n- **BMP** (`.bmp`)\r\n- **WebP** (`.webp`)\r\n\r\n**File Size Limit:** 50MB per image\r\n\r\n## \u26a1 Performance Tips\r\n\r\n1. **Use appropriate timeouts** for your use case\r\n2. **Enable retry logic** for production deployments\r\n3. **Validate images locally** before uploading when possible\r\n4. **Process images in parallel** for batch processing\r\n\r\n```python\r\nimport concurrent.futures\r\nfrom ndvipy import NDVIClient\r\n\r\nclient = NDVIClient(api_key=\"your_api_key\")\r\n\r\ndef process_single_image(image_path):\r\n return client.save_processed_image(\r\n image_path, \r\n f\"ndvi_{image_path.stem}.png\"\r\n )\r\n\r\n# Parallel processing\r\nimage_files = [\"image1.jpg\", \"image2.jpg\", \"image3.jpg\"]\r\n\r\nwith concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:\r\n results = list(executor.map(process_single_image, image_files))\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Development\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npython -m pytest tests/\r\n\r\n# Run with coverage\r\npython -m pytest tests/ --cov=ndvipy\r\n```\r\n\r\n### Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests for new functionality\r\n5. Run the test suite\r\n6. Submit a pull request\r\n\r\n## \ud83d\udcdd Error Reference\r\n\r\n- **NDVIError**: Base exception for all SDK errors\r\n- **NDVIAuthError**: Invalid API key or authentication failure\r\n- **NDVIValidationError**: Invalid input data or parameters\r\n- **NDVIServerError**: Server-side processing error\r\n- **NDVINetworkError**: Network connection issues\r\n- **NDVITimeoutError**: Request timeout\r\n\r\n## \ud83d\udd17 Links\r\n\r\n- [NDVI Pro Dashboard](https://ndvipro.com/dashboard)\r\n- [API Documentation](https://ndvipro.com/docs)\r\n- [GitHub Repository](https://github.com/ndvipro/ndvipy)\r\n- [PyPI Package](https://pypi.org/project/ndvipy/)\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## \ud83e\udd1d Support\r\n\r\n- \ud83d\udce7 Email: support@ndvipro.com\r\n- \ud83d\udcac GitHub Issues: [Report a Bug](https://github.com/ndvipro/ndvipy/issues)\r\n- \ud83d\udcd6 Documentation: [Full API Docs](https://ndvipro.com/docs)\r\n\r\n---\r\n\r\n**Built with \u2764\ufe0f for the remote sensing and agriculture communities** \r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for NDVI Pro cloud service - Generate vegetation analysis from satellite imagery",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/ndvipro/ndvipy#readme",
"Homepage": "https://github.com/ndvipro/ndvipy",
"Issues": "https://github.com/ndvipro/ndvipy/issues",
"Repository": "https://github.com/ndvipro/ndvipy.git"
},
"split_keywords": [
"ndvi",
" satellite",
" vegetation",
" remote-sensing",
" geospatial",
" agriculture"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85a5cc90a3a581bb738e2502f6d68aa964f7da87a98a197aa55d0b435067557c",
"md5": "ebb0acf3e7d5191c85ccdce2e33b6dd9",
"sha256": "47ac27037d61d8a651d1ab3e79b53464d05df8306b6e6c45d7ef4bf609cfc6ab"
},
"downloads": -1,
"filename": "ndvipy-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ebb0acf3e7d5191c85ccdce2e33b6dd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9990,
"upload_time": "2025-07-12T03:38:50",
"upload_time_iso_8601": "2025-07-12T03:38:50.472705Z",
"url": "https://files.pythonhosted.org/packages/85/a5/cc90a3a581bb738e2502f6d68aa964f7da87a98a197aa55d0b435067557c/ndvipy-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bb43a30af2b175feea9a8732c23b302a3903147057b1da9bf2b3a3b8bc4ca871",
"md5": "47e3272ae05a67ebfe09062734f8ea43",
"sha256": "9a021f0d4fa6f7f0c43ef2bebf4cf78a084bc3644d618959873c5b6e44fa3854"
},
"downloads": -1,
"filename": "ndvipy-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "47e3272ae05a67ebfe09062734f8ea43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11506,
"upload_time": "2025-07-12T03:38:51",
"upload_time_iso_8601": "2025-07-12T03:38:51.577778Z",
"url": "https://files.pythonhosted.org/packages/bb/43/a30af2b175feea9a8732c23b302a3903147057b1da9bf2b3a3b8bc4ca871/ndvipy-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 03:38:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ndvipro",
"github_project": "ndvipy#readme",
"github_not_found": true,
"lcname": "ndvipy"
}
JSON
