Installation & Setup

Installation Guide

This guide will help you install and configure planetscope-py for your development environment.

System Requirements

Minimum Requirements

• Python: 3.10 or higher
• Operating System: Windows, macOS, or Linux
• RAM: 4GB minimum, 8GB recommended for large datasets
• Internet Connection: Required for Planet API access
• Planet API Key: Valid credentials from Planet Labs

Recommended Development Environment

• Python: 3.11+ for best performance
• IDE: VS Code, PyCharm, or Jupyter Lab
• Virtual Environment: conda or venv for dependency isolation

Installation Methods

Method 1: Standard Installation (Recommended)

Basic Installation (v4.0.1+)

All core functionality works immediately:

# Install from PyPI with all core features
pip install planetscope-py  # NOTE: Create virtual environment.

This includes:

• Planet API integration
• Spatial density analysis (all 3 methods)
• Complete temporal analysis
• GeoPackage export capabilities
• Asset management with async downloads
• Visualization functions (matplotlib, contextily, folium, seaborn)

Enhanced Installation

For Jupyter notebook users and advanced features:

# Install with Jupyter support
pip install planetscope-py[jupyter]

# Install with all optional features
pip install planetscope-py[all]

Method 2: Development Installation

For developers who want to contribute or use the latest features:

# Clone the repository
git clone https://github.com/Black-Lights/planetscope-py.git
cd planetscope-py

# Creating a virtual environment
python -m venv planetscope_env

# Windows activation
planetscope_env\Scripts\activate

# Linux/macOS activation
source planetscope_env/bin/activate

# Upgrade pip and install build tools
pip install --upgrade pip wheel setuptools

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

Method 3: Conda Installation

# 1. Create and activate the conda environment
conda create -n planetscope python=3.11 -y
conda activate planetscope

# 2. Install core packages via conda-forge
conda install -c conda-forge requests shapely pyproj numpy pandas pip -y

# 3. Install planetscope-py from PyPI
pip install planetscope-py

# 4. For development installation
git clone https://github.com/Black-Lights/planetscope-py.git
cd planetscope-py
pip install -e .[dev]

# 5. Install Jupyter (from conda-forge for better compatibility)
conda install -c conda-forge jupyter -y

# 6. Install ipykernel so this env appears as a kernel in Jupyter
python -m ipykernel install --user --name=planetscope --display-name "Python (planetscope)"

# 7. Run Jupyter Lab
jupyter lab

Dependency Overview

Core Dependencies (v4.0.1+)

All included in basic installation:

Package	Version	Purpose
requests	>=2.32.4	HTTP client with session management
shapely	>=2.1.0	Geometric operations and validation
pyproj	>=3.7.1	Coordinate transformations and CRS handling
numpy	>=2.2.0	Numerical computations
pandas	>=2.2.3	Data manipulation and analysis
python-dateutil	>=2.9.0	Date parsing and operations
orjson	>=3.10.0	High-performance JSON processing
xarray	>=2024.02.0	Temporal analysis data cubes
aiohttp	>=3.8.0	Async asset downloads
geopandas	>=1.0.1	GeoPackage vector operations
fiona	>=1.9.0	GeoPackage I/O
rasterio	>=1.4.3	Raster processing and clipping
scipy	>=1.13.0	Statistical analysis for temporal patterns
matplotlib	>=3.10.0	Core plotting functionality
contextily	>=1.6.2	Basemaps in visualizations
folium	>=0.19.1	Interactive mapping capabilities
seaborn	>=0.12.2	Statistical data visualization

Optional Dependencies

Jupyter Enhancement

pip install planetscope-py[jupyter]

Adds: jupyter, ipywidgets, notebook

Development Tools

pip install planetscope-py[dev]

Includes:

• Testing framework (pytest, pytest-cov)
• Code quality tools (black, flake8, mypy)
• Documentation tools (sphinx)
• Build tools (twine, wheel)

Advanced Visualization

pip install planetscope-py[all]

Adds: plotly, bokeh, advanced interactive features

Verification

1. Test Installation

# Test basic import
import planetscope_py as psp
print(f"planetscope-py version: {psp.__version__}")

# Test core components
from planetscope_py import PlanetAuth, PlanetScopeConfig
print("Core components imported successfully")

# Test v4.0.1 fixes
from planetscope_py import quick_planet_analysis
print("Workflow functions imported successfully")

2. Check Module Status

# Check all available components
import planetscope_py
planetscope_py.check_module_status()

# Expected output: 12/14 components available (v4.0.1+)

3. Run Test Suite

# Run all tests
python -m pytest tests/ -v

# Run with coverage report
python -m pytest tests/ --cov=planetscope_py --cov-report=html

# Expected output: 349/349 tests passing

4. Verify Core Functionality

# Test that all major components work
from planetscope_py import (
    PlanetScopeQuery,           # Planet API integration
    SpatialDensityEngine,       # Spatial analysis
    TemporalAnalyzer,          # Temporal analysis
    GeoPackageManager,         # Data export
    AssetManager,              # Asset management
    quick_planet_analysis,     # One-line workflows
    plot_density_map_only      # Visualization
)

print("All core functionality available")

Configuration Setup

1. Planet API Key

You'll need a Planet API key to use the library. Get yours from Planet Account Settings.

2. Authentication Configuration

Method 1: Environment Variable (Recommended)

# Linux/macOS
export PL_API_KEY="your_planet_api_key_here"

# Windows Command Prompt
set PL_API_KEY=your_planet_api_key_here

# Windows PowerShell
$env:PL_API_KEY="your_planet_api_key_here"

Method 2: Configuration File

Create ~/.planet.json in your home directory:

{
    "api_key": "your_planet_api_key_here"
}

Method 3: Direct Parameter

from planetscope_py import PlanetAuth
auth = PlanetAuth(api_key="your_planet_api_key_here")

Development Environment Setup

1. IDE Configuration

VS Code Settings (.vscode/settings.json):

{
    "python.defaultInterpreterPath": "./planetscope_env/bin/python",
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": ["tests/"],
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black"
}

2. Pre-commit Hooks

# Install pre-commit hooks for code quality
pip install pre-commit
pre-commit install

# Run hooks manually
pre-commit run --all-files

3. Environment Variables

Create a .env file for development:

# Planet API Configuration
PL_API_KEY=your_planet_api_key_here

# Development Settings
PLANETSCOPE_LOG_LEVEL=DEBUG
PLANETSCOPE_MAX_RETRIES=3

Troubleshooting

Common Installation Issues

Issue: Import errors after v4.0.0

Solution: Upgrade to v4.0.1 which fixes import issues:

pip install --upgrade planetscope-py

Issue: ImportError for shapely

Solution: Install GEOS library

# Ubuntu/Debian:
sudo apt-get install libgeos-dev

# macOS:
brew install geos

# Windows:
conda install -c conda-forge shapely

Issue: PyProj installation fails

Solution: Install PROJ library

# Ubuntu/Debian:
sudo apt-get install libproj-dev

# macOS:
brew install proj

# Windows:
conda install -c conda-forge pyproj

Issue: contextily import errors

Solution: This is fixed in v4.0.1 (contextily now included in core dependencies)

pip install --upgrade planetscope-py

Issue: NumPy compatibility warnings

Solution: Ensure NumPy 2.x compatibility

pip install "numpy>=2.2.0"
pip install "pandas>=2.2.3"

Issue: Workflow functions not available

Solution: Check module status and upgrade if needed

import planetscope_py
planetscope_py.check_module_status()

# If workflow functions show "Not Available", upgrade:
pip install --upgrade planetscope-py

Verification Commands

# Check Python version
python --version  # Should be 3.10+

# Check pip version
pip --version

# Verify virtual environment
which python  # Should point to your venv

# Test core functionality
python -c "from planetscope_py import quick_planet_analysis; print('Installation successful')"

# Check for v4.0.1 fixes
python -c "
import planetscope_py
result = planetscope_py._version.test_import_fixes()
print('Import fixes working:', result.get('fix_successful', False))
"

Performance Optimization

For Large Datasets

# Install optional performance packages
pip install numba  # JIT compilation
pip install dask   # Parallel processing

Memory Management

# Configure for large ROI processing
import os
os.environ['PLANETSCOPE_MAX_ROI_AREA'] = '50000'  # 50,000 km²

What's New in v4.0.1

Critical Bug Fixes

• Fixed workflow module availability detection
• Fixed silent import failures in init.py
• Fixed quick_planet_analysis function not working
• Fixed visualization module import issues

Enhanced Installation Experience

• Core visualization dependencies now included in basic installation
• Better error messages for missing dependencies
• Improved module status reporting
• Success confirmations for module loading

Migration from v4.0.0

If upgrading from v4.0.0:

# Simply upgrade - no code changes needed
pip install --upgrade planetscope-py

# Verify the fix
python -c "
from planetscope_py import quick_planet_analysis
from shapely.geometry import box
roi = box(9.04, 45.40, 9.28, 45.52)
print('quick_planet_analysis is working!')
"

Installation Validation Checklist

After installation, verify these components work:

# Core functionality checklist
checks = {
    "Planet API": "from planetscope_py import PlanetScopeQuery",
    "Spatial Analysis": "from planetscope_py import SpatialDensityEngine", 
    "Temporal Analysis": "from planetscope_py import TemporalAnalyzer",
    "Asset Management": "from planetscope_py import AssetManager",
    "GeoPackage Export": "from planetscope_py import GeoPackageManager",
    "Workflow Functions": "from planetscope_py import quick_planet_analysis",
    "Visualization": "from planetscope_py import plot_density_map_only"
}

for name, import_statement in checks.items():
    try:
        exec(import_statement)
        print(f"✓ {name}: Working")
    except ImportError as e:
        print(f"✗ {name}: Failed - {e}")

Next Steps

1. Configure Authentication: Set up your Planet API key
2. Explore Core Features: Try basic scene search and analysis
3. Try Examples: Check out the tutorials and examples
4. Core API Reference: Browse the API documentation
5. Planet API Reference: Learn about Planet API integration

Support

If you encounter issues during installation:

1. Check Requirements: Ensure Python 3.10+ and virtual environment
2. Review Error Messages: Look for specific dependency issues
3. Try Clean Installation: Create fresh virtual environment
4. Check Version: Ensure you have v4.0.1+ for import fixes
5. GitHub Issues: Report installation problems
6. Community: Join discussions in GitHub Discussions

Common Installation Patterns

Data Scientists

# Full installation with Jupyter support
pip install planetscope-py[jupyter]
jupyter lab

GIS Professionals

# Basic installation covers all GIS needs
pip install planetscope-py

Software Developers

# Development installation
git clone https://github.com/Black-Lights/planetscope-py.git
cd planetscope-py
pip install -e .[dev]

Research Scientists

# Full installation with all features
pip install planetscope-py[all]