Skip to content

PROJECT_SUMMARY.md

Latest commit

 

History

History
240 lines (191 loc) · 6.45 KB

PROJECT_SUMMARY.md

File metadata and controls

240 lines (191 loc) · 6.45 KB
Raw

GDAL GUI - Project Summary

Project Overview

GDAL GUI is a professional, open-source geospatial data processing application developed at the University of Miami. The project provides a modern web-based interface to GDAL (Geospatial Data Abstraction Library) operations, enabling users to analyze and transform raster and vector geospatial data.

Technical Architecture

Backend (FastAPI)

  • Framework: FastAPI 0.104.1
  • Server: Uvicorn 0.24.0
  • Language: Python 3.11+
  • Dependencies:
    • GDAL 3.12.0 (core geospatial library)
    • NumPy (numerical operations)
    • Python-Multipart (file upload handling)

Frontend (React)

  • Framework: React 18.2.0
  • Build Tool: Vite 5.0.7
  • Language: TypeScript
  • Package Manager: npm
  • Styling: CSS3 with IBM Carbon Design System principles

Project Structure

GDAL-GUI/
├── backend/
│   ├── __init__.py
│   ├── main.py              # Application entry point
│   ├── config.py            # Configuration and setup
│   ├── routes.py            # API endpoints
│   └── gdal_operations.py   # GDAL operation wrappers
├── frontend/
│   ├── src/
│   │   ├── App.tsx          # Main React component
│   │   ├── main.tsx         # Entry point
│   │   ├── components/      # React components
│   │   ├── services/        # API client
│   │   └── styles/          # Global styles
│   ├── index.html
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── package.json
├── docs/
│   ├── DEVELOPMENT.md       # Development guide
│   └── GDAL_INSTALLATION.md # GDAL setup instructions
├── tests/                   # Test suite (expandable)
├── requirements.txt         # Python dependencies
├── setup.sh                # Installation script
├── start-dev.sh            # Development server launcher
├── README.md               # Project documentation
├── LICENSE                 # MIT License
└── CONTRIBUTING.md         # Contribution guidelines

Development Standards

Code Quality

  • Type hints for all function signatures
  • Comprehensive docstrings (Google format)
  • Error handling with proper logging
  • Modular code organization
  • PEP 8 compliance for Python

Documentation

  • MIT-style project documentation
  • Comprehensive API documentation
  • Development setup guides
  • Contribution guidelines
  • GDAL installation instructions

Version Control

  • Git repository initialized
  • .gitignore configured for Python and Node
  • Professional commit messages
  • MIT License included

API Endpoints

Health Check

GET /api/v1/health

Returns API status and GDAL version information.

Raster Operations

POST /api/v1/raster/info          # Get raster metadata
POST /api/v1/raster/statistics    # Calculate raster statistics
POST /api/v1/raster/hillshade     # Generate hillshade from DEM
POST /api/v1/raster/colormap      # Apply color relief to elevation data
POST /api/v1/raster/slope         # Calculate slope from DEM
POST /api/v1/raster/aspect        # Calculate aspect from DEM
POST /api/v1/raster/translate     # Convert raster format
POST /api/v1/raster/reproject     # Reproject to different CRS
POST /api/v1/raster/clip          # Clip raster by bounding box
POST /api/v1/raster/polygonize    # Convert raster to vector polygons
POST /api/v1/raster/contours      # Generate contour lines from DEM

Vector Operations

POST /api/v1/vector/info          # Get vector metadata
POST /api/v1/vector/buffer        # Create buffer zones around features
POST /api/v1/vector/rasterize     # Convert vector to raster

Getting Started

Installation

  1. Clone the repository
  2. Run setup script: 
    bash setup.sh
  3. Activate virtual environment: 
    source venv/bin/activate

Development

Start development servers:

bash start-dev.sh

Alternatively, start services separately:

# Terminal 1 - Backend
source venv/bin/activate
python -m uvicorn backend.main:app --reload

# Terminal 2 - Frontend
cd frontend
npm run dev

Access application at: http://127.0.0.1:5173

Building for Distribution

Frontend Build

cd frontend
npm run build

Output: frontend/dist/

Backend Distribution

Package using standard Python tools:

pip install build
python -m build

Key Features

  1. Raster Inspection

    • Comprehensive metadata extraction
    • Band-level statistics calculation
    • Projection and transformation information

  2. Terrain Analysis

    • Hillshade generation with customizable parameters
    • Slope calculation (degrees or percent)
    • Aspect (direction of slope) computation
    • Color relief mapping with multiple color schemes

  3. Raster Processing

    • Format conversion (GeoTIFF, PNG, JPEG, and more)
    • Coordinate system reprojection
    • Spatial clipping by bounding box
    • Raster-to-vector conversion (polygonize)
    • Contour line generation

  4. Vector Processing

    • Vector metadata extraction
    • Buffer zone creation
    • Vector-to-raster conversion (rasterize)

  5. Professional Interface

    • IBM Carbon Design System implementation
    • Real-time operation feedback
    • Responsive layout
    • Intuitive parameter controls

  6. RESTful API

    • Standard HTTP methods
    • JSON request/response
    • Comprehensive error handling
    • File upload/download support

Authors

  • Erika Barker, University of Miami

License

MIT License - See LICENSE file for details

Citation

Barker, E. (2025). GDAL GUI: Professional Geospatial Data Processing Interface.
University of Miami.

Project Status

  • Version: 1.0.0
  • Status: Active Development
  • Release Date: December 2025
  • Last Updated: December 14, 2025

Future Enhancements

  • Additional GDAL operations (mosaic, warp, advanced filtering)
  • Advanced visualization with interactive map previews
  • Multi-file batch processing
  • User authentication and project management
  • Cloud storage integration (S3, Azure Blob Storage)
  • Desktop application packaging (Electron or Tauri)
  • WebAssembly GDAL integration for client-side processing

Support

For issues, questions, or contributions, please refer to CONTRIBUTING.md.

Resources