Documentation

Complete guide to creating stunning 3D printable terrain models

πŸ—ΊοΈ Overview

3D Topo Generator is a powerful web application that allows you to generate 3D printable terrain models from digital elevation data. Select any area on Earth and create custom topographic STL or multi-part 3MF files ready for 3D printing with support for multi-material/multi-color printing.

πŸ’‘ Perfect for: Architects, educators, geologists, cartographers, and 3D printing enthusiasts who want to create accurate terrain models.

⚑ Browser-Based Processing & Limitations

100% Client-Side Processing: This application performs all computations directly in your web browser. No data is sent to external servers, ensuring complete privacy and instant processing.

Maximum Area Limit: Due to browser computational constraints, the maximum processable area is 100-200 kmΒ² (if the area size > 100 kmΒ² consider using higher value of resolution reduction factor). This limitation exists because:

  • All processing happens in your browser's JavaScript engine
  • Large datasets can exceed browser memory limits
  • Processing times increase significantly with larger areas

This tool is NOT a replacement for:

  • ArcGIS - Professional GIS analysis and mapping software and associated plugins
  • QGIS - Open-source desktop GIS with advanced processing capabilities and associated plugins
  • Blender - Advanced 3D modeling with unlimited area processing software and associated plugins
  • Others professional softwares/plugins

When to use professional software: If you need to process areas larger than 100 kmΒ², require advanced GIS analysis, or need production-level terrain modeling workflows, consider using desktop GIS software. Learn more about advanced terrain modeling workflows in this comprehensive guide.

Use 3D Topo Generator for: Quick terrain model generation, educational purposes, prototyping, small-scale projects, and when you need instant results without software installation.

✨ Features

πŸ—ΊοΈ

Interactive Mapping

Select locations with intuitive Leaflet.js map interface

πŸ“

Location Search

Find any place with integrated geocoding

🎨

Multiple DEM Sources

Access SRTM, NASADEM, Copernicus, and more

πŸ“

Customizable Models

Adjust dimensions and vertical exaggeration

πŸ”„

Real-time Preview

View 3D models with Three.js visualization

πŸ’Ύ

Multiple Export Formats

Download STL files or multi-part 3MF files ready for 3D printing.

πŸ’»

Responsive Design

Works on desktop, tablet, and mobile

πŸ“²

PWA Support

Install as native app with offline capability

πŸ‘€

Integrated User Menu

Seamlessly integrated collapsible menu in the workspace panel

⚑

Web Workers

Background processing keeps UI responsive

πŸš€

Processing Modes

Choose browser or cloud processing (coming soon)

πŸ’¨

Smart Cancellation

Cancel operations instantly at any time

⚑ Performance & Processing

Web Workers Technology

The application uses Web Workers for the most computationally intensive part of 3D model generation (mesh creation), significantly improving the user experience.

✨ How It Works:

  • Download Phase (5-70%) - Fetching elevation data; some UI responsiveness maintained
  • Generation Phase (70-90%) - Web Worker creates 3D mesh in background thread; UI stays responsive
  • Preview Phase (90-100%) - Creating 3D visualization; brief final processing
  • Instant cancellation - Cancel button works immediately at any stage

Processing Modes

Choose how your 3D models are generated with our flexible processing system:

πŸ–₯️ Browser Processing (Active)

  • FREE - No additional costs
  • Private - All data stays on your device
  • Offline capable - Works without internet after initial load
  • Web Workers enabled - Smooth, responsive performance
  • Recommended for areas up to 200 kmΒ²

☁️ Cloud Processing (Coming Soon)

  • Ultra-fast - Server-side processing power
  • Large areas - Handle terrain over 500 kmΒ²
  • Mobile friendly - Perfect for phones and tablets
  • Pay-per-use - Only pay for what you generate ($0.05-0.15 per model)
  • Coming in future update - Stay tuned!

To change processing mode: In the main application, access the integrated user menu in the bounding boxes panel (expand if collapsed), then click "πŸš€ Processing Mode" button. On mobile, tap your avatar and select Processing Mode from the dropdown.

🐳 Running Locally with Docker

You can run the full application locally using Docker. This is perfect for developers or users who prefer a containerized environment.

# Option 1: Run directly from Docker Hub (No installation needed)
docker run -p 8080:80 sicilian4ever/3d-topo-generator:latest

# Option 2: Run in background (detached mode)
docker run -d -p 8080:80 --name 3d-topo sicilian4ever/3d-topo-generator:latest

# Option 3: Run on a different port (e.g., 3000)
docker run -p 3000:80 sicilian4ever/3d-topo-generator:latest

# Access the application
# Open your browser and visit: http://localhost:8080 (or your custom port)

πŸ’‘ Docker Benefits: Running with Docker ensures you have the exact same environment as the production server, with no need to install Node.js or other dependencies on your machine.

Area Size Guidelines

Area Size Processing Time Recommendation
< 25 kmΒ² 2-5 seconds βœ… Excellent - Browser mode
25-100 kmΒ² 5-30 seconds βœ… Good - Browser mode
100-200 km² 30-90 seconds ⚠️ Large - Consider resolution reduction
> 200 km² 90+ seconds ⚠️ Very Large - Wait for cloud processing

⚠️ Large Area Warning

When creating a bounding box larger than 100 kmΒ², you'll see a warning. For best results with large areas, increase the resolution reduction factor or wait for cloud processing feature.

πŸ“– Usage Guide

Step 0: Create Your Account (First Time Only)

Before you can start generating 3D terrain models, you need to create a free account:

  1. Click the "Launch App" button from the landing page or navigation bar
  2. If you're not logged in, you'll be redirected to the authentication page
  3. Enter your name, email, and password, then click "Register"
  4. After successful registration, you'll be automatically logged in
  5. Your user menu will appear in the top navigation bar with your initials/avatar

πŸŽ‰ 100% Free: After registration, you can immediately access all features at no cost. No credit card required!

Accessing Your Account

Once logged in, you'll have access to your personalized user menu:

  • On the Landing Page: Your user avatar/name appears in the top navigation bar with a dropdown menu
  • In the Main Application (Desktop): The user menu is elegantly integrated at the top of the bounding boxes panel on the right side, featuring a collapsible design (click "Open/Close Menu" to toggle)
  • In the Main Application (Mobile): Your user avatar appears in the top mobile header with a tap-to-open menu

The integrated user menu displays:

  • Your full name, email address, and profile avatar
  • Your status badge showing "Free"
  • Quick navigation links to Home and Print-Calculator
  • Action buttons for OT API Key, Processing Mode, and Log Out
  • Collapsible interface to save space when working with bounding boxes (Desktop only)

Step 1: Get Your OpenTopography API Key (First Time Only)

Before you can generate 3D models, you need a free API key from OpenTopography:

  1. Visit OpenTopography API Registration
  2. Create a free account or log in to your existing account
  3. Request an API key (you'll receive a 32-character hexadecimal string)
  4. Copy your API key for the next step

Note: OpenTopography provides free API access with reasonable usage limits. Keep your API key secure as it's tied to your account.

Step 2: Configure Your API Key

After logging in or registering, you can access your API key settings from anywhere in the application:

Option A: From the Landing Page

  1. After logging in, you'll see your user menu (avatar with your initials) in the top navigation bar, next to the "Launch App" button
  2. Click on your user avatar/name to open the dropdown menu
  3. Select "OT API Key" from the menu
  4. You'll be redirected to the application with the settings modal automatically opened

Option B: From the Main Application

  1. Launch the application from the landing page
  2. Desktop: In the bounding boxes panel (right side), locate the integrated user menu at the top
    • If the menu is collapsed, click "Open Menu" to expand it
    • Click the "OT API Key" button to open the settings modal
  3. Mobile: Tap your user avatar in the top mobile header, then select "OT API Key" from the dropdown menu

Configuring Your Key

  1. In the "OT API Key" window, paste your OpenTopography API key into the input field
  2. Click "Save API Key" or press Enter
  3. You'll see a confirmation: "βœ… API Key configured"
  4. Click the Γ— button or click outside the modal to close it

πŸ’‘ Integrated User Menu Features: The user menu in the main application (desktop) is seamlessly integrated into the bounding boxes panel for easy access while working. It features:

  • Collapsible Design: Click "Open Menu" or "Close Menu" to expand/collapse and optimize your workspace
  • User Profile: View your name, email, avatar, and "Free" badge at a glance
  • Quick Links: Navigate to Home or access the Print-Calculator tool
  • Settings & Actions: OT API Key configuration, Processing Mode selection, and Log Out
  • Persistent State: Your menu preference (collapsed/expanded) is remembered for your next session

Security Note: Your API key is stored only in your browser's session storage and will be cleared when you close your browser. The key is never sent to any server except OpenTopography when generating models.

Welcome Guide

When you first access the main application, a welcome modal will appear showing you a quick overview of the 4 steps to get started:

  1. Get Your API Key: Configure your OpenTopography API key via the user menu
  2. Select Your Area: Navigate the map to find your desired terrain
  3. Draw Bounding Box: Define your terrain area by selecting 4 points
  4. Generate & Download: Customize settings and create your 3D model

You can close this welcome modal anytime and optionally choose not to see it again during your session. The modal provides a helpful starting point for new users.

⚠️ Important: You must be logged in to save and use an API key. If you're not logged in, you'll be redirected to the authentication page first.

Understanding the Workspace Layout

The main application workspace is organized for optimal workflow:

Desktop Layout

  • Left Side (65%): Interactive map where you draw bounding boxes and select terrain areas
  • Right Side (35%): Bounding Boxes panel with three sections:
    • Top: Integrated user menu (collapsible) with your profile, navigation links, and action buttons
    • Middle: List of your bounding boxes with settings and controls
    • Bottom: Creator information card ("Created by Carmelo Sammarco") in an elegant purple gradient design

Mobile Layout

  • Top: Fixed header with panel toggle button and user avatar menu
  • Main Area: Full-screen map for terrain selection
  • Collapsible Panel: Tap "☰ Panel" to access bounding boxes list and controls
  • Creator Card: Appears at the bottom of the bounding boxes panel

Step 3: Select Your Area

There are two ways to select your terrain area:

  1. Manual Selection: Click the "Draw Bounding Box" button (desktop: floating on map, mobile: inside panel) and click 4 points on the map to define your area
  2. Search: Use the search bar (magnifying glass icon on the map) to find a specific location, then draw your bounding box around it

Managing Your Bounding Boxes

Once you've created bounding boxes, you can efficiently manage them in the panel:

Bounding Box Organization

  • New boxes appear at the top - Most recent selections are listed first for easy access
  • Collapsible boxes - Click the β–Ό/β–Ά arrow button next to the box name to collapse/expand individual boxes and save space
  • Box naming - Click the "Rename" button (green) in the title bar to give boxes meaningful names

Quick Actions (Title Bar Buttons)

Each bounding box has three convenient action buttons in the title bar:

  • Rename (Green): Change the box name for better organization
  • Hide (Yellow): Toggle box visibility on the map without deleting it
  • Delete (Red): Permanently remove the bounding box

πŸ’‘ Pro Tip: You can hide/delete boxes even when they're collapsed, making it easy to manage large lists of bounding boxes efficiently. Collapsed state is saved in your browser's local storage.

Step 4: Configure Your Model

For each bounding box, customize your terrain model with these settings:

  • Width & Length: Set the physical dimensions of your model in millimeters
  • Vertical Exaggeration: Enhance terrain features by increasing the vertical scale (1x = true scale, 2x = double height)
  • DEM Source: Choose from multiple elevation datasets based on your needs
  • Smoothness: Adjust the level of terrain smoothing for better printing results
  • Resolution Reduction Factor: Higher values reduce detail but speed up processing (default: 2)
  • Color Mode: Choose between solid color or topographic coloring
    • Solid Color: Single color model for traditional 3D printing
    • Topographic: 4-color elevation bands optimized for multicolor 3D printing with automatic filament changes
  • Color Schemes: Select from 5 topographic color schemes (Terrain, Rainbow, Atlas, Ocean, Viridis), each using exactly 4 discrete color bands. Colors are assigned based on actual Z-height in your 3D model (measured from the build plate), making it easy to know exactly when to change filament during printing

Step 5: Generate & Download

  1. Click the "Generate 3D Model" button
  2. Wait for the DEM data to be fetched and processed
  3. Preview your 3D model in the interactive viewer
  4. Rotate and zoom to inspect the model
  5. Download Your Model: You'll see two download options side-by-side:
    • Left: STL File Group
      • Download STL File: Standard format for 3D printing (universal compatibility)
      • Printing Guide for STL: Smaller button below - detailed TXT instructions for manual filament changes at specific Z-heights
    • Right: 3MF Multi-Part (Recommended)
      • Download 3MF Multi-Part: Single file containing separate objects for each terrain layer - perfect for multi-material/multi-color printing with Bambu Studio, PrusaSlicer, etc.
      • Shows part count (6 parts for Topographic, 2 parts for Solid mode) and benefits

🎨 Multi-Part 3MF (Recommended): The 3MF Multi-Part format is the best option for multi-material/multi-color printing! Each terrain layer is a separate object that you can assign to different filaments/colors in your slicer. Works perfectly with Bambu Studio AMS, Prusa MMU3, and other multi-material systems.

Step 6: Get 3D Printing Cost Estimates (Optional)

After downloading your STL file, you may want to know how much it will cost to 3D print your terrain model. We offer a free Print-Calculator tool to help you estimate printing costs:

Free Print-Calculator Tool: Access the Print-Calculator from the navigation bar at any time - no registration required!

Works with ANY 3D model: The Print-Calculator is not limited to terrain models from this application (for best result it is mandatory to load and export as new 3D-file by the use of 3D-printing softwares and other alternavives). In fact, can be used with any STL, OBJ, or 3DS file from any source - terrain models, figurines, mechanical parts, architectural models, or any other 3D printable design.

  1. Click on the Print-Calculator link in the navigation bar
  2. Input your model specifications (dimensions, material preferences, infill density, etc.)
  3. Get an instant cost estimate based on standard pricing
  4. For a personalized quote tailored to your specific needs, contact me directly through the calculator

Why use the Print-Calculator?

  • Free to use: No registration or login required
  • Instant estimates: Get approximate costs immediately
  • Custom quotes: Request case-by-case pricing for your exact requirements
  • Professional service: Direct communication with the developer for personalized 3D printing services
  • Universal compatibility: Works with STL, OBJ, and 3DS files from any source or application

🌍 DEM Data Sources

The application supports multiple Digital Elevation Model sources, each with different coverage and resolution. Below you'll find detailed information about each DEM family:

SRTM Family (Shuttle Radar Topography Mission)

An SRTM DEM is a Digital Elevation Model created from data collected by NASA's Shuttle Radar Topography Mission (SRTM) in 2000. It provides near-global elevation data for most of the world at resolutions of 3 arc-seconds (~90m) and 1 arc-second (~30m), filling gaps in elevation data to provide a continuous topographic surface. To be noted that SRTM15PLUS integrates the original Shuttle Radar Topography Mission (SRTM) land data with improved ocean bathymetry, which is derived from a combination of direct shipboard measurements and predicted depths using satellite altimetry.

  • SRTMGL3: SRTM GL3 90m resolution
  • SRTMGL1: SRTM GL1 30m resolution
  • SRTMGL1_E: SRTM GL1 Ellipsoidal 30m resolution
  • SRTM15Plus: Global Bathymetry SRTM15+ V2.1 500m resolution

ALOS World 3D (AW3D30)

AW3D30 is a global digital surface model (DSM) with a 30-meter (1 arcsec) horizontal resolution, generated from satellite stereo images by JAXA (Japan Aerospace Exploration Agency).

  • AW3D30: ALOS World 3D 30m resolution
  • AW3D30_E: ALOS World 3D Ellipsoidal 30m resolution

NASADEM

NASADEM (NASA Making Earth System Data Records for Use in Research Environments) is a digital elevation model (DEM) that provides global, near-global land elevation data at a resolution of 1 arc second (approximately 30 meters). It is a modernization of the original Shuttle Radar Topography Mission (SRTM) DEM, using improved processing techniques.

  • NASADEM: NASADEM Global DEM 500m resolution

Copernicus DEM

The Copernicus DEM is a Digital Surface Model (DSM) that represents the Earth's surface, including buildings, vegetation, and other infrastructure, in a 30-meter or 90-meter resolution format.

  • COP30: Copernicus Global DSM 30m resolution
  • COP90: Copernicus Global DSM 90m resolution

European Digital Terrain Model (EU_DTM)

The European Digital Terrain Model (EU_DTM) is a 30-meter resolution model representing the bare-earth surface of Continental Europe, developed by Dr. Tom Hengl and the OpenGeoHub Foundation, using an Ensemble Machine Learning (EML) algorithm trained on various Digital Elevation Models (DEMs) and elevation data from GEDI and ICESat-2. Unlike the older EU-DEM, which was a Digital Surface Model and is no longer maintained, the EU_DTM specifically models the ground's terrain by removing vegetation and buildings, making it suitable for analyses requiring the underlying topography of the landscape.

  • EU_DTM: DTM 30m resolution (Continental Europe only)

GEDI (Global Ecosystem Dynamics Investigation)

The Global Ecosystem Dynamics Investigation (GEDI) produces high resolution laser ranging observations of the 3D structure of the Earth. GEDI's precise measurements of forest canopy height, canopy vertical structure, and surface elevation greatly advance the ability to characterize important carbon and water cycling processes, biodiversity, and habitat. GEDI was funded as a NASA Earth Ventures Instrument (EVI) mission. It was launched to the International Space Station in December 2018 and completed initial orbit checkout in April 2019.

  • GEDI_L3: DTM 1000m resolution

GEBCO (General Bathymetric Chart of the Oceans)

The GEBCO DEM is a 15 arc-second resolution global elevation model that provides continuous coverage of both ocean depths (bathymetry) and land/ice surface heights (topography), with negative values representing water depths and positive values representing land/ice heights. Developed by the General Bathymetric Chart of the Oceans (GEBCO), it's a composite of diverse data sources, including satellite-derived gravity and ship-track soundings.

  • GEBCOIceTopo: Global Bathymetry 500m resolution (includes ice topography)
  • GEBCOSubIceTopo: Global Bathymetry 500m resolution (sub-ice topography)

Choosing the Right Source

  • For detailed terrain: Use SRTMGL1, NASADEM, COP30, or AW3D30 (30m resolution)
  • For larger areas: Use SRTMGL3 or COP90 (90m resolution)
  • For coastal areas and bathymetry: SRTM15Plus or GEBCO sources include ocean depth data
  • For mountains: NASADEM or COP30 provide excellent detail
  • For European terrain: EU_DTM provides bare-earth surface modeling
  • For polar regions: GEBCO sources include ice topography data
  • For vegetation analysis: GEDI_L3 includes canopy height information

πŸ’‘ Tip: Data quality and availability may vary by location. If one source doesn't work well, try another for better results. Each DEM source has its strengths depending on your specific use case and geographic area of interest.

🌐 Browser Support

The application is compatible with all modern browsers:

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+
  • Mobile browsers (iOS Safari 14+, Chrome Mobile)

⚠️ Note: Internet Explorer is not supported. Please use a modern browser for the best experience.

πŸ‘¨β€πŸ’» Credits

Created by Carmelo Sammarco (Sicilian4Ever)

This application represents the intersection of geospatial science and modern web technology. Built with passion for cartography, 3D printing, and open-source software.

πŸ“§ Support: For issues and questions contact the developer.

Contact Developer

Ready to Get Started?

Create your first 3D terrain model in minutes

Launch Application