Skip to main content
TerraLab is an astronomical visualization tool that generates real horizon profiles from digital elevation models (DEMs) and simulates realistic night sky conditions with light pollution modeling.

​
Launch TerraLab

There are three ways to launch TerraLab: 
python -m TerraLab
The application window will open at 1024×768 resolution and supports F11 for fullscreen mode.

​
Initial Configuration

1

Configure Terrain Data

On first launch, TerraLab will check for terrain configuration. If no DEM data is found, the Terrain Config Dialog will appear automatically.
Without DEM data, TerraLab will use procedurally generated terrain as a fallback.

​
Download DEM Data

The dialog provides download links for public DEM repositories:
  • ICGC (Catalonia): High-resolution elevation data for Catalonia
  • Copernicus (Europe): 25m resolution DEM covering all of Europe in 5×5 degree tiles
  • Other regions: Check your national mapping agency (USGS, IGN, OS, BKG, etc.)
Download at least 150km radius of coverage in tiled format (5×5° or similar) for best results.
Supported formats: .asc (ESRI ASCII Grid), .tif (GeoTIFF)
2

Select DEM Folder

Click “Seleccionar Carpeta DEM…” to choose the folder containing your elevation files. The system will validate that the folder contains supported formats.Configuration is stored in ~/.terralab/config.json
3

Choose Horizon Quality

Select your preferred horizon rendering quality preset:
PresetBandsUse Case
Low10Fast preview, low-end hardware
Normal20Default balanced quality
High40Detailed horizon profiles
Ultra60Professional accuracy
Extreme80Maximum detail (slow initial generation)
Quality affects the number of depth layers used for horizon calculation. Higher quality requires longer initial computation but provides better visual gradients.
The change applies on the next horizon regeneration (see terrain_config_dialog.py:16-23).
4

Configure Light Pollution (Optional)

TerraLab supports DVNL (Defense & Veterans Night Light) GeoTIFF data for realistic light pollution modeling.
  • Click the ”…” button next to the DVNL field
  • Select your .tif light pollution raster file
  • If not configured, TerraLab uses an internal fallback model
Light pollution intensity is automatically scaled based on Bortle class (see terrain_config_dialog.py:122-136).

​
Mouse Controls

Camera Rotation

Left-click + Drag: Rotate azimuth and elevation
  • Horizontal drag: Change azimuth (view direction)
  • Vertical drag: Change elevation (look up/down)
  • Sensitivity: 0.5 degrees per pixel (see sky_widget.py:5009)

Zoom

Mouse Wheel: Adjust field of view
  • Scroll up: Zoom in (narrow FOV)
  • Scroll down: Zoom out (wide FOV)
  • Zoom range: 0.1× to 5.0×
  • FOV calculation: 100° / zoom_level (see sky_widget.py:2441)

Telescope Mode Drag

Click + Drag (in Telescope Mode): Pan the target reticle
  • Movement inverts naturally (camera-like behavior)
  • Hold Ctrl + Drag to move global camera instead
  • See sky_widget.py:4943-4958

Measurement Tools

Click + Drag (in Measurement Mode): Create shapes
  • Click twice for ruler tool (distance measurement)
  • Click-drag for circle, square, or rectangle
  • Ctrl + Drag: Override to pan camera
  • Delete/Backspace: Remove selected measurement

​
Keyboard Controls

KeyAction
F11Toggle fullscreen
EscExit telescope/measurement mode
Arrow KeysNudge telescope reticle (fine control)
MToggle telescope movement speed (slow/fast)
Ctrl+LLog astronomical positions (debug)
Arrow keys in telescope mode use discrete steps: 0.05 arcmin (slow) or 0.05° (fast). See telescope_scope_mode.py:42-45.

​
Location and Time Configuration

TerraLab uses your system location and time by default, but you can override these settings in the main interface:
  • Latitude/Longitude: Set observer position (affects horizon calculation and celestial positions)
  • Date/Time: Adjust simulation time for planning observations
  • Time Speed: Control real-time simulation speed
Real-time astronomical calculations use Skyfield with high-precision ephemeris data.

​
Real Horizon Generation

Once DEM data is configured, TerraLab generates horizon profiles using raycasting with Earth curvature correction:
1

Trigger Generation

The horizon is computed automatically when:
  • DEM path is set for the first time
  • Observer location changes significantly
  • You manually click “Regenerar” (Regenerate)
2

Computation Process

TerraLab performs multi-band raycasting:
  • Loads DEM tiles from cache (.npy format for speed)
  • Computes 360° azimuth sweep at 0.5° intervals
  • Calculates horizon angles for each quality band
  • Applies Earth curvature correction using 6,371 km radius
  • Maximum raycast distance: 150 km
Band distribution uses logarithmic spacing:
  • 2/3 of bands cover 0-5 km (near detail)
  • 1/3 of bands cover 5-150 km (atmospheric haze)
See engine.py:23-118 for band generation logic.
3

Rendering

The computed profile is rendered as:
  • Multi-layer depth silhouettes with atmospheric perspective
  • Distance-based color gradation (near→far: dark→haze blue)
  • Blend with procedural terrain fallback for data gaps

​
Light Pollution Understanding

TerraLab models light pollution impact on sky visibility:

​
Bortle Scale Integration

The visual magnitude engine adjusts limiting magnitude based on the Bortle Dark Sky Scale (1-9):
  • Class 1: Pristine dark sky (mag ~7.8)
  • Class 5: Suburban sky (mag ~5.5)
  • Class 9: Inner city (mag ~4.0)

​
Horizon Extinction

When DVNL data is configured, TerraLab calculates local horizon extinction from light domes:
  • Intensity factor: (bortle - 1) / 8 scales dome contribution
  • Dynamic radius varies with distance to light source (up to 35 km influence)
  • Extinction penalty: up to 0.15 magnitude reduction per azimuth
  • See sky_widget.py:1004-1022 for the algorithm
Light pollution effects compound: a Bortle 7 location with nearby city domes may reduce limiting magnitude by 2-3 magnitudes near the horizon.

​
Measurement Tools

Access measurement tools from the toolbar or keyboard shortcuts:

​
Ruler Tool

Measures angular distance along a great circle arc:
  • Click two points to measure separation
  • Display: Distance in degrees (angular_distance formula)
  • Use case: Separation between stars, constellation size

​
Shape Tools

Circle

Measure circular field of view:
  • Drag from center to edge
  • Shows: Diameter (deg), Area (deg²)
  • Perfect for telescope eyepiece FOV

Square

Constrained rectangular FOV:
  • Automatically maintains aspect ratio 1:1
  • Shows: Width, Height, Area
  • Useful for square sensor frames

Rectangle

Free-form rectangular FOV:
  • Independent width/height control
  • Rotation handle for orientation
  • Shows: Width, Height, Area
  • Matches most camera sensors
All measurements use spherical geometry for accuracy. See measurement_tools.py for implementation details.

​
Telescope Mode Basics

Telescope mode simulates a reticle view for framing and planning observations:
1

Activate Telescope Mode

Click the telescope icon in the toolbar or use the menu. The screen will darken outside the simulated FOV.
2

Set Target Center

Click anywhere on the sky to position the reticle center. The HUD will show:
  • Current FOV (degrees and arcminutes)
  • Movement speed mode (SLOW/FAST)
  • Optional: RA/Dec coordinates if configured
3

Adjust FOV

Configure your optical setup:Sensor presets (SENSOR_PRESETS in telescope_scope_mode.py:27-32):
  • Tiny: 5.37×4.04 mm (~1/2.8” sensor)
  • APS-C: 23.6×15.7 mm
  • Full Frame: 36.0×24.0 mm
Focal length: Set your telescope/lens focal length (mm)FOV calculation: 2 × arctan(sensor_size / (2 × focal_length))
You can also set manual FOV override in degrees if you know your exact field width/height.
4

Frame Your Target

Use these controls for precise positioning:
  • Arrow keys: Tap for discrete steps
    • Slow mode: 0.05 arcmin steps
    • Fast mode: 0.05° steps
  • Click + Drag: Pan the reticle smoothly
  • Ctrl + Wheel: Adjust scope FOV (change focal length)
  • Wheel: Zoom global view without changing scope FOV
  • M key: Toggle slow/fast movement speed
5

Choose Reticle Shape

Switch between:
  • Circle: Round eyepiece or uniform FOV
  • Rectangle: Camera sensor with aspect ratio
The exterior is darkened with alpha overlay (190/255) to emphasize the frame (see telescope_scope_mode.py:226).

​
Troubleshooting

​
Horizon not appearing

Symptoms: Procedural terrain only, no real horizonSolutions:
  • Verify DEM files are in supported format (.asc, .tif)
  • Check file extensions match exactly (case-sensitive on Linux)
  • Ensure folder contains files directly (not in nested subdirectories)
  • Reopen terrain config dialog and reselect folder
Symptoms: Flat horizon or gaps in profileSolutions:
  • Verify your latitude/longitude is within downloaded tile coverage
  • Download additional tiles for your observation area (±150 km)
  • Check console for “No valid tiles found” warnings
Symptoms: Initial generation takes >5 minutesSolutions:
  • First-time generation builds .npy cache files (one-time cost)
  • Reduce horizon quality preset temporarily (use Normal or Low)
  • Check disk I/O if files are on network storage
  • Monitor console for progress messages

​
Performance issues

Solutions:
  • Reduce horizon quality preset (Low = 10 bands)
  • Disable light pollution DVNL if not needed
  • Close other GPU-intensive applications
  • Check that PyQt5 is using hardware acceleration
Solutions:
  • DEM tiles are cached in RAM for speed
  • Limit coverage area to necessary radius only
  • Restart TerraLab to clear cache
  • Consider using lower-resolution source DEMs (25m vs 5m)

​
Light pollution not visible

Symptoms: Light domes not appearing on horizonSolutions:
  • Verify DVNL file is valid GeoTIFF (.tif)
  • Check file projection matches WGS84 if possible
  • Ensure file covers your observation location
  • Review console for DVNL loading errors
Symptoms: Light pollution seems to have no impactSolutions:
  • Increase Bortle class in settings (effect scales with Bortle)
  • Point view toward known light pollution source (city direction)
  • Effect is strongest at low altitudes (0-15°)
  • Verify DVNL path is set in terrain config dialog

​
Telescope mode issues

Solutions:
  • Click on sky to reposition reticle center
  • Ensure FOV is reasonable (0.1° - 90°)
  • Check that sensor + focal length combination is valid
  • Press Esc and re-enter telescope mode to reset
Solutions:
  • Press M to toggle speed mode (SLOW/FAST)
  • Slow: 0.5 arcmin/s hold, 0.05 arcmin tap
  • Fast: 0.5 deg/s hold, 0.05 deg tap
  • Use Ctrl+Drag for camera pan if reticle movement feels wrong

​
Application crashes or freezes

Solutions:
  • Check terralab_crash.log in working directory for fault handler output
  • Verify all dependencies installed: pip install PyQt5 numpy skyfield
  • Update graphics drivers (OpenGL issues common on Linux)
  • Try running with python -m TerraLab for detailed traceback
Symptoms: WARNING: Skyfield not availableSolutions:
  • Install missing dependency: pip install skyfield
  • Verify numpy is also installed (Skyfield dependency)
  • Use virtual environment to avoid version conflicts

​
Next Steps

Core Concepts

Learn how the multi-band horizon raycasting engine works

Light Pollution Model

Deep dive into DVNL integration and Bortle scaling

API Reference

Programmatic access to ConfigManager and horizon profiles

CLI Tools

Batch processing and calibration utilities

Build docs developers (and LLMs) love

Get started for freeTalk to us