A modern 3D terrain visualization web application using MapLibre GL JS

terrain2225 is the 2025 implementation of the terrain22 project, featuring advanced 3D terrain visualization based on the prestigious Terrain2021 dataset from the Geospatial Information Authority of Japan (GSI). This application provides an interactive web-based platform for exploring Japan's terrain classification data with stunning visual fidelity and modern web technologies.

Built upon the groundbreaking research by Iwahashi and Yamazaki (2022), this implementation transforms scientific terrain classification data into an accessible and visually compelling web mapping experience. The application leverages MapLibre GL JS for high-performance rendering and is deployed via GitHub Pages for seamless accessibility.

This 2025 implementation includes several significant enhancements over the original terrain22:

• 🗾 3D Terrain Visualization: Immersive 3D terrain rendering using official Terrain2021 data from GSI Japan
• 🚀 MapLibre GL JS: Modern, performant, open-source web mapping library with WebGL acceleration
• ⚡ Vite Build System: Lightning-fast development experience and optimized production builds
• 🎨 Rich Terrain Classification: 22 distinct terrain types with scientifically-based color coding
• 🌐 Globe Control: Interactive globe projection control for global context (when available)
• 📱 Responsive Design: Optimized for desktop and mobile viewing experiences
• 🔗 Clean URLs: Hash-free URLs for better SEO and sharing
• ☁️ GitHub Pages Deployment: Automatic CI/CD deployment with zero server maintenance
• 🎯 No Transparency Polygons: Terrain polygons rendered with full opacity for maximum visual impact

• 📊 Terrain Statistics: Interactive charts and analysis tools
• 🔍 Advanced Search: Location-based terrain type filtering
• 📥 Data Export: Export terrain data for research and analysis
• 🎮 Interactive Tours: Guided exploration of notable terrain features
• 📊 Elevation Profiles: Cross-sectional terrain analysis tools

This application is built upon the Terrain2021 dataset, a revolutionary global terrain classification system developed by the Geospatial Information Authority of Japan (GSI). Terrain2021 represents a significant advancement in terrain analysis, providing scientifically-rigorous classification of the Earth's surface into 22 distinct terrain types.

Key Dataset Information:

• Coverage: Global terrain classification with high-resolution focus on Japan
• Classes: 22 distinct terrain types based on slope and hydrological characteristics
• Resolution: Optimized for zoom levels 9-13 (detailed regional to local scale)
• Methodology: Based on uniform slope and basin analysis methodology

The application consumes terrain data through optimized tile services:

• https://tunnel.optgeo.org/martin/terrain22 - Vector terrain polygon data

  • Terrain classification polygons with 22-class system
  • Optimized for web mapping performance
  • Source layer: terrain22

• https://tunnel.optgeo.org/martin/mapterhorn - Elevation and hillshading data

  • High-resolution digital elevation model (DEM)
  • Real-time hillshading computation
  • Terrarium encoding for efficient data transfer

• 🏛️ Official GSI Terrain2021 Site - Primary data source and research documentation
• 📦 optgeo/terrain22 Repository - Original PMTiles implementation and data processing tools
• 🌐 Live terrain22 Demo - Previous generation implementation
• 📊 Observable Notebook - Interactive data exploration and analysis

🌐 Access the live application: https://optgeo.github.io/terrain2225/

The application loads with a default view of Tokyo, Japan, showcasing the diverse terrain types of the Kanto region. Use the navigation controls to explore different areas and zoom levels to see terrain classification at various scales.

• 🖱️ Pan: Click and drag to move around the map
• 🔍 Zoom: Use mouse wheel or +/- controls to zoom in/out
• 🌏 3D View: Drag with right mouse button to adjust pitch and bearing
• 🌐 Globe: Toggle globe projection using the globe control (top-right)
• 📍 Location: Click anywhere on the map to see coordinates in the console (developer mode)

The application visualizes 22 distinct terrain classification types, each represented by a unique color. These classifications are based on scientific analysis of slope characteristics and hydrological basins:

Key Terrain Categories:

• Mountain Terrain: High-elevation areas with steep slopes and varied topography
• Hill Terrain: Moderate elevation areas with rolling topography
• Basin Areas: Low-lying areas including valleys and depressions
• Coastal Plains: Flat areas near coastlines with minimal elevation change
• River Systems: Areas shaped by fluvial processes and water flow
• Plateau Regions: Elevated flat areas with distinct boundaries

Each terrain type reflects unique geomorphological processes and provides insights into the landscape formation history of Japan's diverse geography.

• Node.js 18+
• npm

npm install

npm run dev

The development server will start at http://localhost:5173/terrain2225/

npm run build

Built files are output to the dist/ directory.

npm run preview

The application is automatically deployed to GitHub Pages via GitHub Actions when changes are pushed to the main branch. The deployment workflow:

1. Installs dependencies
2. Builds the application
3. Deploys to GitHub Pages

The live application is available at: https://optgeo.github.io/terrain2225/

• 🖥️ Frontend Framework: Vanilla JavaScript with ES6+ modules
• 🗺️ Mapping Library: MapLibre GL JS v4.7.1 - Open-source WebGL-powered mapping
• 🔧 Build Tool: Vite v5.4.0 - Next-generation frontend tooling
• ☁️ Deployment: GitHub Pages with automated CI/CD via GitHub Actions
• 📦 Module System: ES6 modules with tree-shaking optimization
• 🎨 Styling: CSS3 with responsive design principles

• 🌍 Base Path: /terrain2225/ (configured for GitHub Pages)
• 🎮 Map Controls: Navigation controls, Attribution, Globe projection (when available)
• 📍 Initial Location: Tokyo, Japan (139.7°E, 35.68°N)
• 👁️ Initial View: Zoom level 10, Pitch 60° for optimal 3D terrain visualization
• 🎯 Zoom Range: Levels 9-13 (optimized for terrain data resolution)

• ⚡ Vector Tiles: Efficient terrain polygon data delivery
• 🗻 Terrarium Encoding: Optimized elevation data encoding (16-bit precision)
• 🔄 Retry Logic: Robust TileJSON loading with automatic retry mechanisms
• 📱 Responsive: Optimized for both desktop and mobile devices
• 🚀 CDN Delivery: Fast global content delivery via GitHub Pages CDN

The terrain data follows this processing pipeline:

1. Source Data: Terrain2021 global polygon dataset from GSI Japan
2. Tile Generation: Converted to vector tiles via Martin tile server
3. Classification: 22-class terrain type system with scientific color mapping
4. Elevation Integration: Combined with mapterhorn DEM for 3D visualization
5. Web Optimization: Optimized for web delivery with appropriate zoom level ranges

This project is built upon the exceptional Terrain2021 dataset provided by the Geospatial Information Authority of Japan (GSI). We extend our deepest gratitude to GSI for making this valuable scientific dataset publicly available and accessible to the global research and development community.

Official Source: GSI Terrain2021 Portal

The terrain classification system implemented in this application is based on the pioneering research methodology developed by:

Iwahashi, J., Yamazaki, D. (2022) Global polygons for terrain classification divided into uniform slopes and basins. Progress in Earth and Planetary Science 9, 33. https://doi.org/10.1186/s40645-022-00487-2

This research represents a significant advancement in automated terrain classification and provides the scientific foundation for the 22-class terrain type system visualized in this application.

The original research was supported by JSPS KAKENHI Grant Number JP18H00769. Following the open access principles encouraged by JSPS KAKENHI, this valuable dataset has been made available to benefit the broader scientific and development communities.

• Original terrain22 Implementation: optgeo/terrain22 project team
• PMTiles Technology: Protomaps community and contributors
• MapLibre GL JS: MapLibre Organization and open-source contributors
• Data Processing: Martin tile server and associated toolchain

This project demonstrates the power of open science and data sharing. By making Terrain2021 data accessible through modern web technologies, we hope to:

• Enable new research applications in geomorphology and terrain analysis
• Support educational initiatives in earth sciences and geography
• Facilitate development of location-aware applications and services
• Promote understanding of Japan's diverse and complex terrain characteristics

We are deeply grateful to all contributors who have made this visualization possible, from the original researchers to the open-source software maintainers who provide the technological foundation for this work.

When using terrain classification data from this application, please cite the foundational research:

Iwahashi, J., Yamazaki, D. (2022) Global polygons for terrain classification 
divided into uniform slopes and basins. Prog. Earth Planet. Sci. 9, 33. 
https://doi.org/10.1186/s40645-022-00487-2

When specifically referencing the Terrain2021/Terrain22 dataset, please include:

We used Terrain22, which is publicly available from https://gisstar.gsi.go.jp/terrain2021/ 
as a derivative of the data by Iwahashi and Yamazaki (2022).

When referencing this specific web application or implementation:

terrain2225: A web-based 3D terrain visualization application based on Terrain2021 data. 
Available at: https://optgeo.github.io/terrain2225/

This terrain2225 web application is released under CC0 1.0 Universal - dedicated to the public domain.

You are free to:

• ✅ Use the code for any purpose, including commercial applications
• ✅ Modify and distribute the code without restrictions
• ✅ Create derivative works and adaptations
• ✅ Use without attribution (though attribution is appreciated)

The underlying Terrain2021 data is made available by GSI Japan under Creative Commons CC-BY 4.0 license, consistent with JSPS KAKENHI open access principles.

Requirements for data usage:

• ✅ Attribution Required: Must cite the original research (Iwahashi & Yamazaki, 2022)
• ✅ Source Acknowledgment: Must reference GSI Terrain2021 portal
• ✅ Academic Integrity: Follow proper scientific citation practices

• MapLibre GL JS: BSD-3-Clause License
• Vite: MIT License
• Node.js Dependencies: Various open-source licenses (see package.json)

For questions, contributions, or collaboration opportunities, please visit the GitHub repository or explore the broader optgeo project ecosystem.