README

Laravel geophysics library for satellite-based mining activity detection and mineral identification. This package provides a comprehensive set of tools for analyzing satellite imagery to identify potential mineral deposits and mining activity.

Features

• STAC Client: Query and download satellite imagery from multiple providers (AWS Earth Search, Microsoft Planetary Computer, etc.)
• Anomaly Detection: Machine learning algorithms to identify spectral anomalies (Isolation Forest, RX Detector, Local Outlier Factor)
• Cloud Masking: Automatic cloud detection and removal for preprocessing
• Advanced Mineralogy: Crosta PCA, Spectral Angle Mapper (SAM), and Linear Spectral Unmixing
• Spectral Indices: Calculate common indices (NDVI, NDWI, Iron Oxide Ratio, Clay Ratio, etc.)
• Queue Support: Heavy processing jobs can be dispatched to queues for background execution
• Eloquent Integration: Store and track analysis results in the database

Requirements

• PHP 8.1 or higher
• Laravel 10 or 11
• Composer
• Extension: ext-json, ext-curl, ext-gd

Installation

1. Install via Composer:

composer require geomin/geomin-laravel

1. Publish the configuration:

php artisan vendor:publish --provider="GeoMin\Providers\GeoMinServiceProvider"

1. Run the migrations:

php artisan migrate

Configuration

Configure GeoMin by editing config/geomin.php:

return [
    // STAC Client Configuration
    'stac' => [
        'endpoint' => env('GEOMIN_STAC_ENDPOINT', 'aws'),
        'api_key' => env('GEOMIN_STAC_API_KEY'),
        'default_collection' => 'sentinel-2-l2a',
        'timeout' => 60,
        'max_results' => 100,
        'cache_enabled' => true,
        'cache_ttl' => 60,
    ],

    // Anomaly Detection
    'anomaly' => [
        'isolation_forest' => [
            'trees' => 100,
            'contamination' => 0.01,
        ],
        'rx' => [
            'threshold' => 0.99,
            'window_size' => null,
        ],
        'lof' => [
            'neighbors' => 20,
            'contamination' => 0.01,
        ],
    ],

    // Cloud Masking
    'cloud_masking' => [
        'default_algorithm' => 'sentinel2',
        'sentinel2' => [
            'blue_threshold' => 0.3,
            'nir_threshold' => 0.4,
            'swir_ratio_threshold' => 0.75,
        ],
    ],

    // Queue Configuration
    'queue' => [
        'connection' => 'redis',
        'queue' => 'geomin',
        'timeout' => 3600,
        'max_retries' => 3,
    ],
];

Usage

Using the Facade

use GeoMin\Facades\GeoMin;

// Search for satellite imagery
$results = GeoMin::stac()
    ->collection('sentinel-2-l2a')
    ->bbox([115.0, -32.0, 115.5, -31.5])
    ->date('2023-01-01', '2023-12-31')
    ->cloudCover(10)
    ->get();

// Calculate spectral index
$result = GeoMin::spectral()->calculateIndex($bands, 'ndvi');

// Detect anomalies
$result = GeoMin::detectAnomalies($imageData, 'isolation_forest', [
    'contamination' => 0.02,
]);

// Apply cloud masking
$result = GeoMin::cloudMasker()->mask($imageData, 'sentinel2');

// Perform Crosta PCA
$result = GeoMin::crostaPCA($imageData, 'hydroxyl');

CLI Commands

GeoMin provides several Artisan commands for command-line usage:

Fetch Satellite Data

# Search for imagery in a bounding box
php artisan geomin:fetch --bbox="[115.0,-32.0,115.5,-31.5]" --cloud-cover=10

# Search with date range
php artisan geomin:fetch --date="2023-01-01/2023-12-31" --collection="sentinel-2-l2a"

# Dry run (show results without downloading)
php artisan geomin:fetch --bbox="[115.0,-32.0,115.5,-31.5]" --dry-run

Calculate Spectral Index

# Calculate NDVI
php artisan geomin:index path/to/bands.json --index=NDVI

# Calculate multiple indices
php artisan geomin:index path/to/bands.json --index=iron_oxide,clay --output=/path/to/results

# Save as CSV
php artisan geomin:index path/to/bands.json --index=NDVI --format=csv

Detect Anomalies

# Using RX Detector
php artisan geomin:detect path/to/image.json --algorithm=rx

# Using Isolation Forest
php artisan geomin:detect path/to/image.json --algorithm=isolation_forest --contamination=0.02

# Dispatch to queue
php artisan geomin:detect path/to/image.json --algorithm=rx --queue

Mineral Mapping

# Crosta PCA for hydroxyl alteration
php artisan geomin:mineral path/to/image.json --method=crosta --target=hydroxyl

# Spectral Angle Mapper
php artisan geomin:mineral path/to/image.json --method=sam --mineral=kaolinite

# Spectral Unmixing
php artisan geomin:mineral path/to/image.json --method=unmixing --endmembers=kaolinite,hematite

Cloud Masking

# Apply cloud masking
php artisan geomin:mask path/to/image.json --algorithm=sentinel2

# Generate cloud probability visualization
php artisan geomin:mask path/to/image.json --visualize --output=/path/to/results

Working with Results

use GeoMin\Models\SpatialAnalysis;

// Get analysis by ID
$analysis = SpatialAnalysis::find(1);

// Check status
if ($analysis->isCompleted()) {
    $result = $analysis->getResult();
    
    // Access statistics
    $stats = $result['statistics'] ?? [];
    
    // Access anomaly locations
    $locations = $result['top_locations'] ?? [];
}

// Get user's analyses
$analyses = SpatialAnalysis::forUser(auth()->id())
    ->recent(7)
    ->get();

Queue Processing

For large datasets, dispatch jobs to the queue:

use GeoMin\Facades\GeoMin;

// Dispatch anomaly detection to queue
$analysis = GeoMin::dispatchProcessingJob($path, 'anomaly_detection', [
    'algorithm' => 'isolation_forest',
    'contamination' => 0.01,
]);

// Check status later
$status = $analysis->status;

Available Spectral Indices

Available Reference Minerals

• Kaolinite, Alunite, Jarosite (Clay/Sulfate)
• Hematite, Goethite (Iron Oxide)
• Sericite, Chlorite (Phyllosilicate)
• Calcite, Dolomite (Carbonate)
• Muscovite, Biotite (Mica)
• Quartz, Feldspar

STAC Endpoints

The package supports multiple STAC providers:

Events

GeoMin dispatches events during analysis lifecycle:

use GeoMin\Events\AnalysisCompleted;
use GeoMin\Events\AnalysisFailed;
use GeoMin\Events\AnalysisStarted;

// Listen for events
Event::listen(function (AnalysisStarted $event) {
    Log::info("Analysis {$event->getAnalysisId()} started");
});

Event::listen(function (AnalysisCompleted $event) {
    Log::info("Analysis {$event->getAnalysisId()} completed");
});

Event::listen(function (AnalysisFailed $event) {
    Log::error("Analysis {$event->getAnalysisId()} failed: {$event->error}");
});

Exception Handling

use GeoMin\Exceptions\STACException;
use GeoMin\Exceptions\AnalysisException;

try {
    $results = GeoMin::stac()->search($options);
} catch (STACException $e) {
    Log::error('STAC error', ['message' => $e->getFullMessage()]);
}

try {
    $result = GeoMin::detectAnomalies($data, $algorithm);
} catch (AnalysisException $e) {
    Log::error('Analysis error', ['context' => $e->getContext()]);
}

Testing

# Run tests
./vendor/bin/phpunit

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage

Performance Considerations

1. Memory Usage: Large images can consume significant memory. Consider:

   • Increasing memory_limit in php.ini
   • Using chunked processing for very large images
   • Dispatching to queue for background processing

2. Queue Configuration: For production:

   'queue' => [
       'connection' => 'redis',
       'queue' => 'geomin',
       'timeout' => 3600,
       'max_retries' => 3,
   ],

3. Caching: STAC search results are cached by default. Adjust cache TTL based on your needs.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email security@example.com instead of using the issue tracker.

License

The MIT License (MIT). Please see LICENSE file for more information.

Author

Kazashim Kuzasuwat

• GitHub
• Email

Links

• Package Repository
• Issue Tracker
• Python Version