Installation & Setup - Black-Lights/planetscope-py GitHub Wiki

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]