CoolFace
Apppublic

fmahezs/luma-lite

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
App README

Luma Geospatial Engine Frontend (lite version)

Streamlit-based frontend interface for the Luma land cover mapping platform, built with Streamlit and Land Use For All Geospatial Engine (Luma-GE).

Overview

This is the frontend interface for Luma GE, providing a user-friendly web interface for land cover/land use mapping workflows. The backend algorithms and Earth Engine processing are handled by the separate Luma-stack repository.

File Structure

  • —`Pages/`: Streamlit-based modules of Luma platform
  • —`Notebook/`: Jupyter notebooks used for development, experimentation, and demonstrating the functionality of the core modules
  • —`modules/`: Shared modules including navigation components
  • —`.streamlit/`: Streamlit configuration files (config.toml and custom CSS styling)
  • —`auth/`: Authentication configuration files
  • —`logos/`: Application logos and images
  • —`ui_helper.py`: UI utility functions for headers, footers, and banners
  • —`home.py`: Main Streamlit application entry point
  • —`pyproject.toml`: Python project configuration file defining metadata and dependencies
  • —`Dockerfile`: Docker build configuration
  • —`docker-compose.oauth.yml`: Docker Compose configuration with OAuth support

Modules/Pages

  • —Module 1: Generate Image Mosaic - Acquisition of near cloud-free satellite imagery
  • —Module 2: Classification Scheme - Define land use/land cover classification schemes
  • —Module 3: Generate ROI - Sample data generation
  • —Module 4: Analyze ROI - Sample quality analysis and spectral plotting
  • —Module 5: Predictor Generation - Adding predictor for improving classification model (Under development)
  • —Module 6: Classification and LULC Creation - Generate land cover maps
  • —Module 7: Thematic Accuracy Assessment - Validate map accuracy

State Management Architecture

LumaLite uses a hybrid session state management architecture to ensure data consistency and prevent state corruption across all modules. This architecture provides:

  • —Centralized state management for shared data (AOI, imagery, classification schemes, training data)
  • —Module-specific state managers for module-specific data and UI state
  • —Atomic updates with automatic rollback on errors to prevent partial state corruption
  • —Dependency validation to ensure modules are completed in the correct order
  • —State persistence across page navigation within a session

Key Features

  • —Atomic Operations: All state updates are all-or-nothing, with automatic rollback on errors
  • —Module Completion Tracking: Each module tracks completion status for workflow validation
  • —Dependency Validation: Modules validate that prerequisite modules are completed before allowing execution
  • —Organized State: State variables are grouped by functional area for clarity and maintainability

State Manager Files

  • —modules/session_state_manager.py - Core shared state (Module 1 + cross-module state)
  • —modules/module2_state_manager.py - Classification scheme state
  • —modules/module3_state_manager.py - Training data state
  • —modules/module4_state_manager.py - Separability analysis state
  • —modules/module5_state_manager.py - Predictors state
  • —modules/module6_state_manager.py - Classification state
  • —modules/module7_state_manager.py - Accuracy assessment state

Developer Guide

For detailed information on working with the state management system, see the Session State Developer Guide. This guide covers:

  • —How to add new state variables
  • —How to use atomic update functions
  • —Common patterns and best practices
  • —Backward compatibility considerations
  • —Testing and debugging state management

Prerequisites

Before you begin, ensure you have the following installed on your system:

  • —Git: A version control system for cloning the repository. Installation Guide.
  • —Python environment manager: If you do not yet have one installed, we recommend Miniforge; it is lightweight, no-frills compared to Anaconda, and works well for this project. If you already have another Conda-compatible manager, you can continue using it.

To confirm these tools are available in your shell, run:

powershell
git --version
conda --version

Warning for Windows Users: Do not add Python or Conda to your system PATH. This causes conflicts and prevents the luma_ge environment from working correctly. For details, see FAQ- Should I add Anaconda to the Windows PATH?.

  • —Luma-GE Backend: A Python package that serves as the geospatial engine for the Epistem Land Use Mapping for All (Luma) platform.

Install the backend package:

bash
pip install git+https://github.com/epistem-io/EpistemXBackend.git

This package provides the core functionality for Earth Engine operations, image processing, and land cover classification.

Installation

Option A: Install from Git

Recommended for most users - install directly from the repository.

Direct install (no cloning required):

bash
pip install git+https://github.com/epistem-io/LumaLite.git

Option B: Local Development Setup

For developers who want to modify the frontend.

  1. 1.Clone the repository:
bash
   git clone https://github.com/epistem-io/LumaLite.git
   cd LumaLite
  1. 1.Install the backend package:
bash
   pip install git+https://github.com/epistem-io/EpistemXBackend.git
  1. 1.Run the application:
bash
   python -m streamlit run home.py

Repository Structure

├── home.py                      #streamlit home page (entry point)
├── Pages/                        #Individual module pages
│   ├── 1_Module_1_Generate_Image_Mosaic.py
│   ├── 2_Module_2_Classification_scheme.py
│   ├── 3_Module_3_Generate_ROI.py
│   ├── 4_Module_4_Analyze_ROI.py
│   ├── 5_Module_6_Classification_and_LULC_Creation.py
│   ├── 6_Module_7_Thematic_Accuracy.py
│   └── 7_About.py
├── modules/                  #Shared modules
│   ├── nav.py                #Navigation component
│   ├── session_state_manager.py      # Core shared state management
│   ├── module2_state_manager.py      # Module 2 state management
│   ├── module3_state_manager.py      # Module 3 state management
│   ├── module4_state_manager.py      # Module 4 state management
│   ├── module5_state_manager.py      # Module 5 state management
│   ├── module6_state_manager.py      # Module 6 state management
│   └── module7_state_manager.py      # Module 7 state management
├── docs/                   # Documentation
│   ├── SESSION_STATE_DEVELOPER_GUIDE.md  # State management guide
│   └── INTEGRATION_GUIDE.md              # Integration guide
├── .streamlit/                # Streamlit configuration
│   ├── config.toml            # Server and theme configuration
│   └── style.css              # Custom CSS styling
├── auth/                      # Authentication configuration
├── logos/                     # Application logos and images
├── ui_helper.py               # UI utility functions
├── pyproject.toml             # Python dependencies
├── Dockerfile                 # Docker build configuration
└── docker-compose.oauth.yml   # Docker Compose configuration

Running with Docker

The application can be deployed using Docker

Google Cloud OAuth2 Configuration Notes

Google cloud OAuth configuration is still under development. Currently it might not run according to expectation

Prerequisites for Docker Deployment

  1. 1.Docker and Docker Compose installed on your system
  2. 2.Google Cloud OAuth2 credentials (optional, for OAuth authentication)
  3. 3.Google Earth Engine service account (optional, for service account authentication)

Docker Setup

  1. 1.Prepare secrets (if using OAuth):

Create an secrets/ directory and add your base64-encoded credentials:

bash
   mkdir secrets
   echo "your_base64_encoded_service_account_json" > secrets/service_account_b64.txt
   echo "your_base64_encoded_oauth_client_config" > secrets/oauth_client_config_b64.txt
  1. 1.Build and run with Docker Compose:
bash
   docker-compose -f docker-compose.oauth.yml up --build
  1. 1.Access the application:

Open your browser and navigate to http://localhost:7860

Environment Variables

Copy .env.example to .env and configure as needed:

bash
cp .env.example .env

Key environment variables:

  • —STREAMLIT_SERVER_PORT: Port for the Streamlit server (default: 7860)
  • —GOOGLE_OAUTH_CLIENT_ID: OAuth2 client ID (if using OAuth)
  • —GOOGLE_OAUTH_CLIENT_SECRET: OAuth2 client secret (if using OAuth)

Configuration

Streamlit Configuration

The application uses custom configuration in .streamlit/config.toml:

  • —Server runs on port 7860
  • —Custom theme with EpistemX branding colors

Custom Styling

Custom CSS is defined in .streamlit/style.css with:

  • —EpistemX brand colors (pink: #ec1776, purple: #812fa8, blue: #3e4aff)
  • —Poppins font family
  • —Custom card designs and animations
  • —Responsive navigation buttons

Adding New Modules

  1. 1.Create a new page file in the Pages/ directory
  2. 2.Follow the naming convention: N_Module_N_Description.py
  3. 3.Update the navigation in modules/nav.py
  4. 4.Import required functions from the luma_ge backend package
  5. 5.Use show_header() and show_footer() from ui_helper.py for consistent styling

Troubleshooting

Common Issues

  1. 1.Import errors for `luma_ge` package: Ensure the backend package is installed correctly
  2. 2.Earth Engine authentication errors: Run earthengine authenticate and check service account setup
  3. 3.OAuth errors: Verify OAuth2 credentials and redirect URIs in Google Cloud Console
  4. 4.Docker build failures: Check that all required secrets files exist

Getting Help

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

  1. 1.Fork the repository
  2. 2.Create a feature branch
  3. 3.Make your changes
  4. 4.Add tests if applicable
  5. 5.Submit a pull request

Technology Stack

Acknowledgments

This project is developed as part of the Evolving Participatory Information System for Nature-based Climate Solutions (Epistem) initiative, supporting deforestation prevention and landscape restoration efforts in Indonesia.