FilmDrop UI

A modern, browser-based interface for exploring and visualizing STAC API catalogs

FilmDrop UI is a powerful web application for searching, visualizing, and interacting with geospatial imagery catalogs through STAC (SpatioTemporal Asset Catalog) APIs. It provides multiple visualization modes including aggregated views, mosaics, and individual scenes with advanced filtering and export capabilities.

Check out FilmDrop-UI in action with Earth-Search.

📋 Table of Contents

• ✨ Key Features
• 🚀 Quick Start
• 📖 Documentation
• 🎯 Configuration Examples
• 📸 Screenshots
• 🏗️ Architecture
• 🤝 Contributing
• 📚 Related Projects
• 📄 License

✨ Key Features

• 🎨 Visualization
• Scene View - Individual imagery footprints and tile rendering with TiTiler
• Mosaic View - Seamless imagery mosaics using TiTiler
• Hex Aggregation - H3 geohex-based data density visualization
• Grid Aggregation - Grid code (MGRS, WRS2) based aggregation

• Customizable color formulas and band combinations

• 🔍 Search

• Date/time range filtering
• Cloud cover filtering
• Draw or upload GeoJSON search bounds
• Interactive map with Leaflet

• Light/dark theme support

• ⚙️ Auto-Configuration

• Automatic collection discovery from STAC API with include/exclude filters
• Automatic rendering configuration using STAC Render Extension (when TiTiler is available)
• Minimal configuration required - works out-of-the-box with most STAC catalogs

• Sensible defaults for common parameters

• 🔗 Direct Linking

• Share URLs to specific STAC items
• Browser back/forward navigation
• Bookmark scenes for later reference

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• A STAC API endpoint
• (Optional) TiTiler instance for imagery visualization

# Clone the repository
git clone https://github.com/Element84/filmdrop-ui.git
cd filmdrop-ui

# Install dependencies
npm install

# Create configuration file
cp config_helper/config-new-format-example.json public/config/config.json

# Edit configuration (at minimum, set STAC_API_URL)
nano public/config/config.json

# Start development server
npm start

# Application available at http://localhost:5173

For production deployment:

# Create production build
npm run build

# Build output in ./build directory
# Deploy contents to web server

📖 Documentation

• Configuration Guide - Complete configuration reference with migration guide
• Changelog - Version history and changes

Configuration Quick Reference

Create public/config/config.json (development) or build/config/config.json (production):

{
  "STAC_API_URL": "https://your-stac-api.com",
  "BASEMAP": {
    "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    "attribution": "© OpenStreetMap"
  },
  "COLLECTIONS_CONFIG": {
    "your-collection-id": {
      "sceneTilerParams": {
        "assets": ["red", "green", "blue"]
      },
      "sceneMinZoom": 7,
      "popupDisplayFields": ["datetime", "platform"]
    }
  }
}

STAC API Requirements

Some FilmDrop features require specific STAC API extensions:

• Aggregation Views - Aggregation Extension
• Hex view requires items with proj:centroid property
• Currently supported by stac-server and stac-fastapi-elasticsearch-opensearch

• The aggregation centroid_geohex_grid_frequency or grid_geohex_frequency (Deprecated) must be advertised by the /aggregations endpoint

• Grid Code Aggregation - Custom grid:code property

• Items must include grid identifier (e.g., MGRS, WRS2)

• Cloud Cover Filtering - EO Extension

• Automatic Rendering - Render Extension (Optional)

• When SCENE_TILER_URL is configured, FilmDrop will automatically configure visualization
• Collections with the renders extension will have TiTiler parameters auto-configured
• Eliminates need to manually configure sceneTilerParams for each collection

See CONFIGURATION.md for detailed feature configuration.

🎯 Configuration Examples

Basic Setup

Minimal configuration for viewing a single collection:

{
  "STAC_API_URL": "https://earth-search.aws.element84.com/v1",
  "BASEMAP": {
    "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    "attribution": "© OpenStreetMap"
  },
  "COLLECTIONS_CONFIG": {
    "sentinel-2-l2a": {
      "sceneMinZoom": 7
    }
  }
}

With Imagery Visualization

Add TiTiler for on-the-fly tile generation. Note that assets will be auto-configured based on the collection's STAC metadata if not specified:

{
  "STAC_API_URL": "https://earth-search.aws.element84.com/v1",
  "SCENE_TILER_URL": "https://titiler.xyz",
  "BASEMAP": {
    "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    "attribution": "© OpenStreetMap"
  },
  "COLLECTIONS_CONFIG": {
    "sentinel-2-l2a": {
      "sceneTilerParams": {
        "assets": ["red", "green", "blue"],
        "color_formula": "Gamma+RGB+3.2+Saturation+0.8"
      },
      "sceneMinZoom": 7
    }
  }
}

Multiple Collections

{
  "COLLECTIONS_CONFIG": {
    "sentinel-2-l2a": {
      "sceneTilerParams": { "assets": ["red", "green", "blue"] },
      "sceneMinZoom": 7,
      "popupDisplayFields": ["datetime", "platform", "eo:cloud_cover"]
    },
    "landsat-c2-l2": {
      "sceneTilerParams": { "assets": ["red", "green", "blue"] },
      "sceneMinZoom": 7,
      "popupDisplayFields": ["datetime", "platform", "instruments"]
    }
  }
}

📸 Screenshots

Landsat Hex Aggregation in light mode

Sentinel-1 Footprints

Landsat footprints with rendered scene

Sentinel-2 Grid Aggregation (on MGRS grids)

🏗️ Architecture

FilmDrop UI is built with:

• React - UI framework
• Redux - State management
• Leaflet - Interactive mapping
• Vite - Build tool and dev server

Key Design Principles

• Build-once, deploy-anywhere - Runtime configuration
• Responsive design - Works on desktop and mobile
• Extensible - Easy to add new collections and visualizations
• Performance - Optimized for large result sets

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Guidelines

• Follow existing code style
• Use meaningful variable and function names
• Add details of the changes/updates to the CHANGELOG's Unreleased section
• Add tests for new features
• Update documentation as needed

Available Scripts

npm start        # Start development server (localhost:5173)
npm test         # Run test suite
npm run build    # Create production build
npm run coverage # Generate test coverage report
npm run serve    # Serve production build locally

Running Tests

# Run tests
npm test

# Run tests with coverage
npm run coverage

# Run tests in watch mode
npm test -- --watch

📚 Related Projects

• STAC Specification - Core STAC specification
• stac-server - Serverless STAC API implementation
• TiTiler - Dynamic tile server
• NASA IMPACT TiTiler - Extended TiTiler with mosaicjson support

📄 License

Copyright 2020-2025 Element 84

Licensed under the Apache License, Version 2.0. See LICENSE for details.