Spatial Density Analysis and Visualization - Black-Lights/planetscope-py GitHub Wiki

Spatial Density Analysis & Visualization

PlanetScope-py provides comprehensive spatial density analysis with enhanced visualization capabilities. This guide covers the complete workflow from scene density calculation to professional visualization output with coordinate system fixes and increased scene footprint limits.

Enhanced Features

Fixed coordinate system display - No more mirrored/flipped maps
Increased scene footprint limits - 150+ default (up to 1000+)
One-line functions - Individual plot access with single commands
Enhanced ROI clipping - Proper polygon-shaped outputs
Dynamic histogram bins - No more fixed 11-19 ranges
Robust GeoTIFF export - With coordinate fixes and PROJ error handling

Overview

Spatial density analysis answers the fundamental question: "How many satellite scenes cover each area of my region of interest?" This information is crucial for:

Acquisition Planning: Identify areas with insufficient coverage
Data Quality Assessment: Understand coverage density patterns
Research Applications: Analyze temporal and spatial coverage trends
Operational Monitoring: Plan data collection strategies

Quick Start

Ultra-Simple Analysis (1-line)

from planetscope_py import quick_planet_analysis
from shapely.geometry import box

# Milan area ROI
milan_roi = box(9.04, 45.40, 9.28, 45.52)

# Complete analysis in 1 line
result = quick_planet_analysis(milan_roi, "last_month", clip_to_roi = True)

print(f"Found {result['scenes_found']} scenes")
print(f"Mean density: {result['summary']['mean_density']:.1f}")

# With cloud cover filtering
result = quick_planet_analysis(
    milan_roi, "last_month", 
    cloud_cover_max=0.1,  # Only 10% cloud cover max
    resolution=30,
    clip_to_roi = True

)

Standard Workflow

from planetscope_py import SpatialDensityEngine, DensityConfig, DensityMethod, PlanetScopeQuery

# Search for scenes
query = PlanetScopeQuery()
scenes = query.search_scenes(
    geometry=milan_roi,
    start_date="2024-06-01",
    end_date="2024-06-20"
)

# Configure analysis
config = DensityConfig(
    resolution=30.0,
    method=DensityMethod.RASTERIZATION
)

# Calculate density
engine = SpatialDensityEngine(config)
result = engine.calculate_density(
    scene_footprints=scenes['features'],
    roi_geometry=milan_roi
)

print(f"Grid: {result.grid_info['width']}×{result.grid_info['height']} cells")

Quick Analysis with All Parameters

from planetscope_py import quick_planet_analysis

# Complete parameter example
result = quick_planet_analysis(
    roi=milan_roi,                          # ROI polygon (required)
    period="last_month",                    # Time period (default: "last_month")
    output_dir="./my_analysis",             # Output directory (default: "./output")
    max_scenes_footprint=300,               # Max scenes in footprint plot (default: 150)
    show_plots=True,                        # Show plots in notebooks (default: True)
    
    # Configuration overrides (all optional):
    resolution=30.0,                        # Grid resolution in meters (default: 30.0)
    cloud_cover_max=0.1,                    # Max cloud cover (default: 0.2)
    method="rasterization",                 # Density method (default: "rasterization")
    clip_to_roi=True,                       # Clip outputs to ROI (default: True)
    create_visualizations=True,             # Generate plots (default: True)
    export_geotiff=True,                    # Export GeoTIFF (default: True)
    coordinate_system_fixes=True,           # Enable coordinate fixes (default: True)
    force_single_chunk=False,               # Force single chunk processing (default: False)
    validate_geometries=True,               # Validate input geometries (default: True)
    chunk_size_km=200.0,                    # Processing chunk size (default: 200.0)
    max_memory_gb=16.0,                     # Memory limit (default: 16.0)
    parallel_workers=4,                     # Number of CPU cores (default: 4)
    no_data_value=-9999.0                   # NoData value (default: -9999.0)
)

Parameter Reference for Quick Analysis

Parameter	Type	Default	Description
Required Parameters
`roi`	Polygon/list	-	Region of interest geometry
Basic Parameters
`period`	str	"last_month"	Time period ("last_month", "last_3_months", "YYYY-MM-DD/YYYY-MM-DD")
`output_dir`	str	"./output"	Output directory for results
`max_scenes_footprint`	int	150	Maximum scenes in footprint visualizations
`show_plots`	bool	True	Whether to display plots in notebooks
Analysis Configuration
`resolution`	float	30.0	Grid cell size in meters (3.0-1000.0)
`cloud_cover_max`	float	0.2	Maximum cloud cover threshold (0.0-1.0)
`method`	str	"rasterization"	Density calculation method
`clip_to_roi`	bool	True	Clip outputs to ROI polygon shape
Visualization Control
`create_visualizations`	bool	True	Generate visualization plots
`export_geotiff`	bool	True	Export GeoTIFF files with QML styling
Advanced Configuration
`coordinate_system_fixes`	bool	True	Enable coordinate system corrections
`force_single_chunk`	bool	False	Force single chunk processing
`validate_geometries`	bool	True	Validate input geometries
`chunk_size_km`	float	200.0	Processing chunk size in kilometers
`max_memory_gb`	float	16.0	Maximum memory usage in GB
`parallel_workers`	int	4	Number of parallel processing workers
`no_data_value`	float	-9999.0	Value for areas outside ROI

Common Usage Patterns

# Basic analysis with cloud filtering
result = quick_planet_analysis(
    milan_roi, "last_month", 
    cloud_cover_max=0.1,
    clip_to_roi = True
)

# High-resolution analysis
result = quick_planet_analysis(
    milan_roi, "2025-01-01/2025-01-31",
    resolution=10.0,
    max_scenes_footprint=500,
    clip_to_roi = True
)

# Memory-optimized for large areas
result = quick_planet_analysis(
    large_roi, "last_3_months",
    resolution=100.0,
    method="adaptive_grid",
    max_memory_gb=8.0,
    chunk_size_km=50.0,
    clip_to_roi = True
)

# Custom output without visualizations
result = quick_planet_analysis(
    roi, "last_month",
    output_dir="./custom_analysis",
    create_visualizations=False,
    export_geotiff=True,
    show_plots=False,
    clip_to_roi = True
)

One-Line Functions

Individual Plot Functions

from planetscope_py import plot_density_map_only, plot_footprints_only, export_geotiff_only

# Just get density map (fixed coordinate system)
fig = plot_density_map_only(milan_roi, "last_month", "density.png")

# Just get footprints (300+ scenes default)
fig = plot_footprints_only(milan_roi, "last_month", max_scenes=500)

# Just export GeoTIFF + QML files
success = export_geotiff_only(milan_roi, "last_month", "output.tif")

Access from Results

# Use results from complete analysis
from planetscope_py.visualization import plot_density_only

result = quick_planet_analysis(milan_roi, "last_month")

# Individual plots from results
plot_density_only(result['density_result'], milan_roi, "density.png")

Function Type Comparison

Two Types of Plotting Functions

Type 1: Complete Workflow Functions (run full analysis)

# These run the ENTIRE analysis pipeline first, then extract plots
fig = plot_density_map_only(milan_roi, "last_month", "density.png")
# ↑ Runs: Planet API → Scene Discovery → Density Calculation → Plot

# Process: ROI + Time → Full Analysis → Extract Plot  
# Performance: Slower (includes API calls and computation)
# Use case: One-line convenience when starting from scratch

Type 2: Direct Visualization Functions (use existing results)

# These work with pre-computed analysis results
result = quick_planet_analysis(milan_roi, "last_month")  # Analysis once
fig = plot_density_only(result['density_result'], milan_roi, "density.png")
# ↑ Uses: Pre-computed DensityResult → Direct Plot

# Process: DensityResult → Direct Plotting
# Performance: Faster (no API calls, just visualization)  
# Use case: Multiple plots from same analysis results

Efficiency Comparison

# INEFFICIENT: Each function runs full analysis
fig1 = plot_density_map_only(roi, "last_month")      # API + Analysis #1
fig2 = plot_footprints_only(roi, "last_month")       # API + Analysis #2  
fig3 = plot_histogram_only(roi, "last_month")        # API + Analysis #3

# EFFICIENT: Analysis once, multiple visualizations
result = quick_planet_analysis(roi, "last_month")    # API + Analysis (once)
fig1 = plot_density_only(result['density_result'], roi)      # Plot only
fig2 = plot_footprints_only(result['scene_polygons'], roi)   # Plot only
fig3 = plot_histogram_only(result['density_result'], roi)    # Plot only

Recommendation: Use Type 2 (direct visualization) for better performance when creating multiple plots.

Key Concepts

Grid Resolution

The resolution parameter defines the size of each grid cell in meters:

3m: High resolution matching PlanetScope native resolution
30m: Standard resolution for most applications
100m: Fast analysis for large areas
1000m: Regional-scale analysis

Computational Methods

1. Rasterization Method

Best for: Most use cases, high-resolution analysis

Speed: Fastest (0.01-0.1 seconds)
Memory: Efficient for high-resolution grids
Accuracy: High for regular grids

2. Vector Overlay Method

Best for: Maximum precision, irregular geometries

Speed: Moderate (10-60 seconds)
Memory: Higher memory usage
Accuracy: Highest geometric precision

3. Adaptive Grid Method

Best for: Very large areas, memory-constrained systems

Speed: Variable (optimized for dataset)
Memory: Most efficient for large areas
Accuracy: Good with intelligent refinement

Configuration

Enhanced Configuration

from planetscope_py import DensityConfig, DensityMethod

# Standard configuration
config = DensityConfig(
    resolution=30.0,
    method=DensityMethod.RASTERIZATION,
    max_scenes_footprint=300  # Enhanced: increased from 50
)

# Advanced configuration
config = DensityConfig(
    resolution=30.0,
    method=DensityMethod.AUTO,
    max_memory_gb=8.0,
    parallel_workers=4,
    chunk_size_km=50.0,
    coordinate_system_fixes=True,  # Enhanced: fixed coordinate display
    clip_to_roi=True  # Enhanced: proper polygon clipping
)

Enhanced Visualization

Four-Panel Summary Plot with Fixes

The enhanced create_summary_plot() generates a comprehensive visualization with coordinate system fixes:

Density Map: Spatial distribution with corrected orientation
Density Distribution: Histogram with dynamic bins
Statistics Summary: Enhanced metrics table
Scene Footprints: Scene boundaries with increased limits (150+)

from planetscope_py.visualization import DensityVisualizer

result = quick_planet_analysis(milan_roi, "last_month")

visualizer = DensityVisualizer()
fig = visualizer.create_summary_plot(
    density_result=result['density_result'],
    roi_polygon=milan_roi,
    save_path="enhanced_summary.png",
    max_scenes_footprint=300,  # Enhanced: increased from 50
    show_plot=True  # Fixed: proper notebook display
)

Enhanced Customization

# Advanced options with coordinate fixes
fig = visualizer.create_summary_plot(
    density_result=result['density_result'],
    roi_polygon=roi,
    scene_polygons=result['scene_polygons'],
    save_path="custom_analysis.png",
    clip_to_roi=True,  # Enhanced: proper polygon clipping
    max_scenes_footprint=500,  # Enhanced: up to 1000+
    show_plot=True
)

Individual Plot Functions

Density Map Only

from planetscope_py import plot_density_map_only

# One-line density map with coordinate fixes
fig = plot_density_map_only(
    milan_roi, "last_month", 
    save_path="density.png",
    resolution=30,
    clip_to_roi=True
)

Scene Footprints Only

from planetscope_py import plot_footprints_only

# Enhanced footprint plot with increased limits
fig = plot_footprints_only(
    milan_roi, "last_month",
    save_path="footprints.png", 
    max_scenes=500  # Enhanced: up to 1000+
)

Histogram Only

from planetscope_py import plot_histogram_only

# Dynamic histogram with proper bins
fig = plot_histogram_only(
    milan_roi, "last_month",
    save_path="histogram.png",
    clip_to_roi=True
)

Enhanced GeoTIFF Export

One-Line Export with Fixes

from planetscope_py import export_geotiff_only

# Enhanced export with coordinate fixes
success = export_geotiff_only(
    milan_roi, "last_month", 
    output_path="density.tif",
    clip_to_roi=True
)

# Automatically creates:
# - density.tif (GeoTIFF with coordinate fixes)
# - density.qml (QGIS style file)

Enhanced File Properties

The exported GeoTIFF includes:

Coordinate System: Fixed orientation and proper CRS handling
Spatial Reference: WGS84 (EPSG:4326) with PROJ error handling
Data Type: 32-bit floating point
NoData Value: -9999 for areas outside ROI
Compression: LZW compression for smaller files
Enhanced Metadata: Method, resolution, coordinate fixes applied

Understanding Results

Enhanced DensityResult Object

result = engine.calculate_density(...)

# Core results (coordinate-corrected)
result.density_array      # 2D numpy array with fixed orientation
result.transform         # Corrected geospatial transform
result.crs              # Coordinate reference system
result.bounds           # Bounding box (minx, miny, maxx, maxy)

# Enhanced statistics
result.stats['min']      # Minimum density value
result.stats['max']      # Maximum density value  
result.stats['mean']     # Mean density across grid
result.stats['median']   # Median density (enhanced)
result.stats['count']    # Number of valid cells

# Enhanced metadata
result.computation_time  # Analysis duration
result.method_used      # Actual method used
result.coordinate_fixes_applied  # Enhanced: coordinate system fixes

Interpreting Density Values

Density values represent the number of scenes covering each grid cell:

0: No scene coverage
1-5: Low coverage
6-15: Moderate coverage
16+: High coverage

Advanced Use Cases

1. Coverage Assessment with Enhanced Analytics

# Comprehensive coverage assessment
result = quick_planet_analysis(roi, "last_month", resolution=50.0)

# Enhanced coverage metrics
coverage_stats = {
    'total_area_km2': result['summary']['roi_area_km2'],
    'scenes_found': result['scenes_found'],
    'mean_density': result['summary']['mean_density'],
    'max_density': result['summary']['max_density'],
    'coverage_completeness': min(result['summary']['mean_density'] / 10.0, 1.0),
    'data_gaps': result['summary']['mean_density'] < 3.0
}

print(f"Coverage Assessment:")
print(f"  Area: {coverage_stats['total_area_km2']:.0f} km²")
print(f"  Scenes: {coverage_stats['scenes_found']}")
print(f"  Average density: {coverage_stats['mean_density']:.1f} scenes/pixel")
print(f"  Coverage completeness: {coverage_stats['coverage_completeness']*100:.0f}%")

if coverage_stats['data_gaps']:
    print("⚠️  Low coverage detected - consider expanding search criteria")

2. High-Resolution Analysis with Coordinate Fixes

# Ultra-high resolution analysis (3m native resolution)
result = quick_planet_analysis(
    small_roi, "last_month",
    resolution=3.0,                           # Native PlanetScope resolution
    max_scenes_footprint=500,                 # Enhanced: show more scenes
    coordinate_system_fixes=True,             # Essential for accuracy
    clip_to_roi=True                          # Precise polygon clipping
)

# Validate coordinate fixes applied
if result['summary'].get('coordinate_system_corrected', False):
    print("✓ Enhanced coordinate system fixes applied")
    print(f"✓ Resolution: {result['summary']['analysis_resolution_m']}m")
    print(f"✓ Grid size: {result['density_result'].grid_info['width']}×{result['density_result'].grid_info['height']}")

3. Large-Scale Analysis with Memory Optimization

# Regional analysis (country/state level)
large_roi = box(-125, 32, -114, 42)  # California-sized area

result = quick_planet_analysis(
    large_roi, "last_3_months",
    resolution=1000.0,                        # 1km cells for regional scale
    method=DensityMethod.ADAPTIVE_GRID,       # Memory-efficient method
    max_memory_gb=32.0,                       # Increased memory limit
    chunk_size_km=100.0,                      # Large chunks for efficiency
    max_scenes_footprint=1000                 # Enhanced: show many scenes
)

print(f"Large-scale analysis completed:")
print(f"  Method: {result['density_result'].method_used.value}")
print(f"  Computation time: {result['summary']['computation_time_s']:.1f}s")
print(f"  Scenes displayed: {result['summary']['max_scenes_displayed']}")

4. Quality Control and Validation

# Enhanced quality control workflow
def validate_analysis_quality(result, roi_polygon):
    """Enhanced quality validation with coordinate system checks."""
    
    validation_report = {
        'coordinate_system_validated': False,
        'scene_limits_adequate': False,
        'roi_clipping_accurate': False,
        'density_range_reasonable': False,
        'performance_acceptable': False
    }
    
    # Check coordinate system fixes
    if result['summary'].get('coordinate_system_corrected', False):
        validation_report['coordinate_system_validated'] = True
        print("✓ Coordinate system fixes validated")
    
    # Check enhanced scene limits
    scenes_displayed = result['summary'].get('max_scenes_displayed', 0)
    if scenes_displayed >= 150:  # Enhanced minimum
        validation_report['scene_limits_adequate'] = True
        print(f"✓ Enhanced scene limits: {scenes_displayed} scenes displayed")
    
    # Check ROI clipping accuracy
    if result['summary'].get('roi_area_km2', 0) > 0:
        validation_report['roi_clipping_accurate'] = True
        print("✓ ROI clipping applied correctly")
    
    # Check density values are reasonable
    mean_density = result['summary']['mean_density']
    if 0 <= mean_density <= 50:  # Reasonable range
        validation_report['density_range_reasonable'] = True
        print(f"✓ Density range reasonable: {mean_density:.1f} scenes/pixel")
    
    # Check performance
    computation_time = result['summary']['computation_time_s']
    if computation_time < 300:  # Under 5 minutes
        validation_report['performance_acceptable'] = True
        print(f"✓ Performance acceptable: {computation_time:.1f}s")
    
    # Overall validation
    all_passed = all(validation_report.values())
    print(f"\nOverall validation: {'✓ PASSED' if all_passed else '⚠️ ISSUES DETECTED'}")
    
    return validation_report

# Run validation
validation = validate_analysis_quality(result, roi)

Batch Visualization

Enhanced Batch Processing

from planetscope_py.visualization import batch_plot_generation

# Enhanced batch visualization with increased limits
results_list = [result1, result2, result3]
roi_list = [roi1, roi2, roi3]

plot_paths = batch_plot_generation(
    results_list, roi_list,
    output_dir="./enhanced_batch_plots",
    max_scenes_per_plot=300,  # Enhanced: increased from 50
    clip_to_roi=True,
    coordinate_fixes=True
)

Performance Guidelines

Use Case	Recommended Method	Enhanced Features
Quick analysis	`quick_planet_analysis()`	One-line execution
Standard workflow	Rasterization	Fixed coordinates
High precision	Vector Overlay	Enhanced clipping
Large areas	Adaptive Grid	Memory optimization
High resolution (3-10m)	Rasterization	Coordinate fixes

Troubleshooting Guide

Common Issues and Enhanced Solutions

Issue: Coordinate System Display Problems

# Problem: Maps appear flipped or mirrored
# Solution: Enhanced coordinate fixes are automatic in v4.0+

result = quick_planet_analysis(roi, "last_month")
if result['summary'].get('coordinate_system_corrected', False):
    print("✓ Coordinate system fixes automatically applied")
else:
    # Manual fix if needed
    result = quick_planet_analysis(roi, "last_month", coordinate_system_fixes=True)

Issue: Too Many Scenes to Display

# Problem: Scene footprint plots show only 50 scenes
# Solution: Enhanced scene limits (up to 1000+)

from planetscope_py import plot_footprints_only

# Enhanced: Default is now 300, can go up to 1000+
fig = plot_footprints_only(roi, "last_month", max_scenes=1000)

# Or configure in main analysis
result = quick_planet_analysis(roi, "last_month", max_scenes_footprint=500)

Issue: Memory Errors with Large Areas

# Problem: MemoryError with large ROIs or high resolution
# Solution: Enhanced memory management

try:
    result = quick_planet_analysis(large_roi, "last_month", resolution=10.0)
except MemoryError:
    # Enhanced fallback strategy
    result = quick_planet_analysis(
        large_roi, "last_month",
        resolution=100.0,                     # Coarser resolution
        method=DensityMethod.ADAPTIVE_GRID,   # Memory-efficient method
        chunk_size_km=50.0,                   # Smaller chunks
        max_memory_gb=8.0                     # Conservative limit
    )

Issue: PROJ Database Errors

# Problem: CRS/projection errors during export
# Solution: Enhanced PROJ error handling (automatic)

from planetscope_py import export_geotiff_only

# Enhanced: Automatic fallback CRS options
success = export_geotiff_only(roi, "last_month", "output.tif")
if success:
    print("✓ GeoTIFF exported with enhanced error handling")
    # Also creates output.qml automatically

Issue: Histogram Shows Fixed Ranges (11-19)

# Problem: Histogram bins stuck at 11-19 range
# Solution: Enhanced dynamic bin calculation (automatic)

from planetscope_py import plot_histogram_only

# Enhanced: Automatic dynamic bins based on data range
fig = plot_histogram_only(roi, "last_month", "histogram.png")
# No more fixed 11-19 ranges - bins adapt to actual data

Configuration Reference

DensityConfig Parameters

from planetscope_py import DensityConfig, DensityMethod

config = DensityConfig(
    resolution=30.0,                          # Grid cell size in meters (default: 30.0)
    method=DensityMethod.RASTERIZATION,       # Computational method (default: RASTERIZATION)
    chunk_size_km=200.0,                      # Processing chunk size in km (default: 200.0)
    max_memory_gb=16.0,                       # Memory limit in GB (default: 16.0)
    parallel_workers=4,                       # Number of CPU cores (default: 4)
    no_data_value=-9999.0,                    # NoData value (default: -9999.0)
    coordinate_system_fixes=True,             # Enable coordinate fixes (default: True)
    force_single_chunk=False,                 # Force single chunk processing (default: False)
    validate_geometries=True                  # Validate input geometries (default: True)
)

Configuration Options

Parameter	Type	Default	Description
`resolution`	float	30.0	Grid cell size in meters (3.0-1000.0)
`method`	DensityMethod	RASTERIZATION	Computational method
`chunk_size_km`	float	200.0	Processing chunk size in kilometers
`max_memory_gb`	float	16.0	Maximum memory usage in GB
`parallel_workers`	int	4	Number of parallel processing workers
`no_data_value`	float	-9999.0	Value for areas outside ROI
`coordinate_system_fixes`	bool	True	Enable coordinate system corrections
`force_single_chunk`	bool	False	Force single chunk processing
`validate_geometries`	bool	True	Validate input geometries

Method Options

Method	Value	Best For	Performance
`DensityMethod.AUTO`	"auto"	Automatic selection	Variable
`DensityMethod.RASTERIZATION`	"rasterization"	Most use cases	Fastest
`DensityMethod.VECTOR_OVERLAY`	"vector_overlay"	High precision	Moderate
`DensityMethod.ADAPTIVE_GRID`	"adaptive_grid"	Large areas	Memory efficient

Visualization Configuration

DensityVisualizer Parameters

from planetscope_py.visualization import DensityVisualizer

visualizer = DensityVisualizer(
    figsize=(12, 8)                           # Figure size in inches (default: (12, 8))
)

# Plot configuration options
plot_options = {
    'colormap': 'viridis',                    # Colormap (default: 'viridis')
    'title': 'Custom Title',                  # Plot title
    'save_path': 'output.png',               # Save path (optional)
    'show_stats': True,                       # Show statistics (default: True)
    'clip_to_roi': True,                      # Clip to ROI (default: True)
    'show_plot': True,                        # Display plot (default: True)
    'max_scenes': 300                         # Max scenes in footprint plots
}

Available Colormaps

Colormap	Best For	Style
`"turbo"`	Default - General use	Blue → cyan → green → yellow → red
`"viridis"`	Scientific publications	Purple to yellow
`"plasma"`	High contrast	Purple to pink
`"inferno"`	Dark backgrounds	Black to yellow
`"magma"`	Publications	Black to white
`"jet"`	Traditional (not recommended)	Blue to red

Performance Optimization

Enhanced Performance Guidelines

Use Case	Enhanced Method	Configuration	Expected Time
Quick analysis	`quick_planet_analysis()`	Default settings	<30 seconds
Standard workflow	Rasterization + fixes	`method="rasterization"`	1-60 seconds
High precision	Vector overlay	`method="vector_overlay"`	1-5 minutes
Large areas (>1000 km²)	Adaptive grid	`method="adaptive_grid"`	2-10 minutes
High resolution (3-10m)	Rasterization + fixes	`resolution=3.0, coordinate_system_fixes=True`	1-30 seconds
Memory constrained	Chunked processing	`chunk_size_km=25.0, max_memory_gb=4.0`	Variable

Memory Optimization

# Memory-efficient configuration for large areas
large_area_config = {
    'resolution': 100.0,                      # Coarser resolution
    'method': DensityMethod.ADAPTIVE_GRID,    # Memory-efficient method
    'chunk_size_km': 50.0,                    # Smaller chunks
    'max_memory_gb': 8.0,                     # Conservative limit
    'parallel_workers': 2                     # Fewer workers
}

# High-resolution configuration for detailed analysis
high_res_config = {
    'resolution': 3.0,                        # Native PlanetScope resolution
    'method': DensityMethod.RASTERIZATION,    # Fastest method
    'chunk_size_km': 25.0,                    # Smaller chunks for memory
    'max_memory_gb': 16.0,                    # Higher limit
    'coordinate_system_fixes': True           # Essential for accuracy
}

# Balanced configuration for most use cases
balanced_config = {
    'resolution': 30.0,                       # Standard resolution
    'method': DensityMethod.AUTO,             # Automatic selection
    'chunk_size_km': 200.0,                   # Optimal chunk size
    'max_memory_gb': 16.0,                    # Standard limit
    'coordinate_system_fixes': True,          # Enhanced accuracy
    'validate_geometries': True               # Input validation
}

Enhanced Error Recovery

Error Type	Enhanced Solution	Configuration
MemoryError	Automatic chunking + reduced resolution	`chunk_size_km=50.0, resolution=100.0`
PROJ errors	Multiple CRS fallbacks	`coordinate_system_fixes=True`
Large datasets	Adaptive grid method	`method=DensityMethod.ADAPTIVE_GRID`
Coordinate issues	Built-in fixes	`coordinate_system_fixes=True`
Geometry errors	Automatic validation	`validate_geometries=True`

Summary

The enhanced spatial density analysis and visualization system provides:

Fixed coordinate system display ensuring proper geographic alignment
Increased scene footprint limits with defaults of 150-300 and support up to 1000+
One-line functions for rapid individual plot generation
Enhanced ROI clipping with proper polygon-shaped outputs
Robust error handling for PROJ database and memory issues
Professional GeoTIFF export with automatic QGIS styling

All coordinate system issues have been resolved, scene display limits increased, and simplified interfaces added for efficient analysis workflows.

Spatial Density Analysis and Visualization - Black-Lights/planetscope-py GitHub Wiki

Spatial Density Analysis & Visualization

Enhanced Features

Overview

Quick Start

Ultra-Simple Analysis (1-line)

Standard Workflow

Quick Analysis with All Parameters

Parameter Reference for Quick Analysis

Common Usage Patterns

One-Line Functions

Individual Plot Functions

Access from Results

Function Type Comparison

Two Types of Plotting Functions

Efficiency Comparison

Key Concepts

Grid Resolution

Computational Methods

1. Rasterization Method

2. Vector Overlay Method

3. Adaptive Grid Method

Configuration

Enhanced Configuration

Enhanced Visualization

Four-Panel Summary Plot with Fixes

Enhanced Customization

Individual Plot Functions

Density Map Only

Scene Footprints Only

Histogram Only

Enhanced GeoTIFF Export

One-Line Export with Fixes

Enhanced File Properties

Understanding Results

Enhanced DensityResult Object

Interpreting Density Values

Advanced Use Cases

1. Coverage Assessment with Enhanced Analytics

2. High-Resolution Analysis with Coordinate Fixes

3. Large-Scale Analysis with Memory Optimization

4. Quality Control and Validation

Batch Visualization

Enhanced Batch Processing

Performance Guidelines

Troubleshooting Guide

Common Issues and Enhanced Solutions

Issue: Coordinate System Display Problems

Issue: Too Many Scenes to Display

Issue: Memory Errors with Large Areas

Issue: PROJ Database Errors

Issue: Histogram Shows Fixed Ranges (11-19)

Configuration Reference

DensityConfig Parameters

Configuration Options

Method Options

Visualization Configuration

DensityVisualizer Parameters

Available Colormaps

Performance Optimization

Enhanced Performance Guidelines

Memory Optimization

Enhanced Error Recovery

Summary

Related Documentation

Core Features

Advanced Analysis

Integration & Workflows

Examples & Tutorials

API Reference

Getting Started

Support