🌍 Earth Image Downloader (eimg)

A secure, feature-rich command-line tool and web application to download stunning Earth images from NASA's EPIC API (Earth Polychromatic Imaging Camera).

🚀 Quick Start

Installation

# Python package
pip install eimg

# NPM package
npm i eimgd

# With web interface
pip install eimg[web]

# With video processing capabilities
pip install eimg[video]

# Full installation with all features
pip install eimg[all]

Get Started in 30 seconds

# 1. Get your free NASA API key at https://api.nasa.gov/
# 2. Setup eimg
eimg setup

# 3. Download your first Earth image
eimg download

# 4. Launch the web interface
eimg web

🔑 NASA API Key Setup

1. Get your API key:

   • Visit NASA API Portal
   • Click "Generate API Key"
   • Fill in your information
   • Copy your API key

2. Configure eimg:

   eimg setup
   # Enter your API key when prompted
   # Optional: Enable encryption for extra security

✨ Features

🖥️ Command Line Interface

• 📥 Smart Downloads: Latest images, batch downloads, date ranges
• 🎨 Image Processing: Brightness, contrast, saturation, sharpness adjustments
• 🔍 Advanced Filters: Blur, sharpen, edge enhance, emboss, and more
• 🏷️ Watermarks: Add custom text with flexible positioning
• 🎬 Timelapse Creation: Generate GIF and MP4 animations
• ⭐ Favorites System: Save and organize your favorite images
• 🔍 Smart Search: Find images by date, metadata, or keywords
• 📊 Usage Analytics: Track downloads, cache usage, and statistics

🌐 Web Interface

• 📱 Responsive Design: Works on desktop, tablet, and mobile
• 🎛️ Interactive Dashboard: Real-time stats and quick actions
• 🖼️ Image Gallery: Browse, preview, and manage your collection
• 📈 Progress Tracking: Live download progress indicators
• ⚙️ Settings Panel: Configure preferences through UI

🔒 Security & Privacy

• 🔐 API Key Encryption: Optional password-protected encryption
• 🗑️ Secure Deletion: Overwrite files when clearing cache
• ✅ Input Validation: Comprehensive security checks
• 🛡️ Safe URLs: Validate all external connections

💾 Smart Caching

• 🖼️ Thumbnails: Fast image previews
• 📦 Metadata Storage: Efficient data organization
• 🧹 Auto Cleanup: Configurable cache management
• 📊 Usage Tracking: Monitor cache size and performance

🤖 Automation

• 👻 Daemon Mode: Background auto-downloading
• ⏰ Scheduled Downloads: Configurable intervals
• 📤 Data Export: Backup your collection
• 📥 Data Import: Restore from backups

📖 Usage Examples

Basic Operations

# Download the latest Earth image
eimg download

# Download with image enhancements
eimg download --enhance --brightness 1.3 --contrast 1.2

# Download to specific directory
eimg download --directory ./earth-images --output earth-today.png

Batch Operations

# Download images for a date range
eimg batch --start-date 2025-01-01 --end-date 2025-01-07

# Create a timelapse video
eimg batch --start-date 2025-01-01 --end-date 2025-01-07 \
    --create-timelapse --format mp4 --fps 10

# Download with custom output directory
eimg batch --start-date 2025-01-01 --end-date 2025-01-07 \
    --output-dir ./january-2025

Image Processing

# Apply filters to existing images
eimg process image.png --filter sharpen --output sharp-image.png
eimg process image.png --filter blur --output blurred-image.png

# Add watermarks
eimg process image.png --watermark "Earth © NASA" \
    --watermark-position bottom-right

# Enhance images
eimg process image.png --brightness 1.5 --contrast 1.3 \
    --saturation 1.2 --sharpness 1.1

Management & Monitoring

# View system statistics
eimg stats

# Check system health
eimg doctor

# Manage favorites
eimg favorite ./earth-images/beautiful-earth.png
eimg favorites

# Search your collection
eimg search --query "2025-01"

# Cache management
eimg cache          # View cache statistics
eimg clear --type images    # Clear image cache

Automation & Advanced Features

# Run as background daemon
eimg daemon --auto-download --interval 3600 --max-downloads 24

# Export your collection
eimg export --include-images --output my-earth-collection.zip

# Import from backup
eimg import-data earth-backup.zip

# Web interface with custom settings
eimg web --port 8080 --host 0.0.0.0 --debug

🌐 Web Interface

Start the web interface:

eimg web

Then open your browser to http://localhost:5000

Web Features:

• 📊 Dashboard: Overview of your collection and quick actions
• 🖼️ Gallery: Browse and manage your Earth images
• ⭐ Favorites: Easy favorite management with visual interface
• 🎨 Processing: Apply filters and enhancements through web UI
• 📈 Analytics: Visual statistics and usage charts
• ⚙️ Settings: Configure all options through web interface

🔗 Links & Resources

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📚 Documentation: Project Wiki
• 🌍 NASA EPIC: Official EPIC Website
• 🔑 NASA API: NASA API Portal

📞 Support

• 📧 Email: [email protected]
• 💬 Discussions: GitHub Discussions
• 🐦 Twitter: @StasX_Official

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Run tests: python tests/test_basic.py
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NASA for providing the incredible EPIC API
• Earth Polychromatic Imaging Camera team for the amazing imagery
• Open Source Community for the excellent tools and libraries
• Contributors who help improve this project

Made with ❤️ by Kozosvyst Stas (STASX)

Download the beauty of Earth, one image at a time 🌍✨