Skip to content

Home

Jump to bottom
Gjanosh61 edited this page Mar 12, 2026 · 1 revision

HeightmapExport

Heightmap Export is a QGIS plugin for exporting raster layers as 16-bit PNG heightmaps, designed primarily for physical terrain model workflows such as 3D printing, CNC machining, and relief carving.

It has been tested with QGIS 4.0 and updated for full Qt5 to Qt6 compatibility.

Overview

Heightmap Export was originally created to make it simple and practical to take a DEM or similar raster layer, calculate the required scaling for a terrain model, and export a high-resolution 16-bit grayscale PNG suitable for terrain relief workflows.

Although the plugin can also be used to generate a standalone PNG heightmap image, its internal logic is still strongly oriented toward physical model generation. For that reason, some model-dimension inputs are still required even when the final goal is only the image export.

In addition to PNG export, the plugin also includes PathTracer, a companion tool that maps SVG paths over a heightmap surface and generates G-code for engraving or laser workflows.

Features

  • Tested with QGIS 4.0
  • Full compatibility update from Qt5 to Qt6
  • Exports 16-bit PNG grayscale heightmaps
  • Metadata export in INI format
  • Automatic aspect ratio and resolution scaling
  • Embedded calculator for model dimensions and scale factors
  • Designed primarily for physical terrain model workflows
  • Includes PathTracer for SVG-to-G-code terrain engraving workflows

Requirements

  • QGIS 4.0 or later
  • Python 3.12
  • GDAL with PNG and raster support

Installation

  1. Clone or download the plugin folder.

  2. Make sure the package includes at least:

    • heightmapexport.py
    • heightmapexport_dialog.py
    • heightmapexport_dialog_base_3.py
    • resources_rc.py
    • PathTracer/ folder with its submodules

  3. Compress the plugin contents into a .zip file.

    • Zip the contents of the plugin folder, not the parent folder itself.

  4. In QGIS, go to:

    Plugins > Manage and Install Plugins > Install from ZIP

  5. Select the zip package and install it.

Usage

  1. Load a local raster layer into QGIS
    (for example a DEM .tif file).

  2. Optionally clip or refine the raster using QGIS tools before export.

  3. Open Heightmap Export from the QGIS Raster menu.

  4. Select the raster layer from the dropdown.

    • The plugin will display the dimensions of the selected layer.
    • Heightmap Export uses the ratio of the north/south and east/west distances across the center point to preserve the correct geographic aspect ratio of the output.

  5. Set the Model Dimensions.

  6. Set the Image Dimensions.

  7. Click Export Heightmap.

    • A 16-bit grayscale PNG will be saved.
    • An INI metadata file will be generated alongside it.

Note: The plugin is intended for local raster layers and automatically prevents export from unsupported sources such as online XYZ tiles.

Model Dimensions

This section should not be considered fully optional.

Even if your goal is only to export a PNG heightmap, you still need to enter at least some model dimension values so the plugin can calculate the export parameters correctly and enable PNG generation.

This behavior exists because Heightmap Export was originally developed primarily for physical terrain model production, including CNC carving, relief modeling, and 3D printing. The model-dimension fields therefore remain part of the core export logic.

Model Dimensions explained

Width (mm) and Height (mm) define the horizontal size of the model.

  • In most cases, you only need to enter one of them.
  • The other value is calculated automatically to preserve the correct geographic aspect ratio.

Depth (mm) defines the vertical relief of the model.

  • This is the physical height of the terrain relief on the model.
  • A value of 0 may still be valid in some workflows, but the required dimensional inputs must still be provided so the export can be computed correctly.

Vertical exaggeration

If you want to compress or exaggerate the terrain relief, you can use one of the following:

  • Scaled Depth (mm) → directly defines the final vertical relief
  • Scale Factor → multiplies the relief height

Use only one of these methods at a time.

Important note

Even when you do not intend to build a physical model, this section still acts as part of the export setup because the plugin uses these values internally to derive the final output configuration.

Image Dimensions

Set the size of the exported image in one of the following ways:

  • Enter Image Width
  • Enter Image Height
  • Or specify a physical resolution such as mm per pixel

The remaining values are calculated automatically so that the aspect ratio stays correct.

This makes it possible to control either:

  • the image size in pixels, or
  • the effective physical resolution of the final terrain model workflow

Output Files

When exporting, the plugin generates:

  • a 16-bit grayscale PNG heightmap
  • an accompanying INI metadata file

The PNG is intended for terrain and relief workflows where high bit depth is required to preserve elevation detail.

The INI metadata file is useful when the exported heightmap is later used in external modeling, CAM, CNC, or terrain-processing workflows.

PathTracer

PathTracer allows you to take a heightmap PNG and map the paths from an SVG file onto the terrain surface in order to generate G-code for engraving or carving.

This is especially useful for workflows such as:

  • laser-engraved hiking trails
  • engraved route overlays
  • CNC-carved terrain relief models with vector paths added on top

PathTracer features

  • Loads 16-bit PNG heightmaps
  • Loads SVG vector paths
  • Supports scaling and offsets
  • Can rescale a cropped heightmap to full range
  • Supports laser mode
  • Generates basic G-code suitable for CNC workflows

Quick workflow

  1. Export a heightmap PNG from Heightmap Export.
  2. Open the PathTracer dialog.
  3. Load the PNG heightmap.
  4. Load an SVG file containing the paths you want to engrave.
  5. Set:
    • model size
    • zero point
    • safe Z
    • plunge and carve feed rates
    • offsets if needed
  6. Optionally enable:
    • Laser mode
    • Offsets
    • Optimization
    • Rescale Heightmap to full range
  7. Export the generated G-code.

The generated G-code is intentionally simple and should always be tested carefully before use on a real machine.

PathTracer notes

The PathTracer dialog is mostly straightforward for users already familiar with CAM and relief-model workflows, but a few options deserve clarification.

Rescale Heightmap to full range

If you want to use only a section of a larger heightmap:

  1. Crop or edit the heightmap in image software, making sure the SVG paths still align correctly.
  2. Enter the new X width and new Y height in the CAM parameter fields.
  3. Enter the original Z depth.
  4. Enable Rescale Heightmap to full range and save new PNG.
  5. When exporting G-code, PathTracer will also create a new PNG with values rescaled to the full available range.

The generated filename may include the new Z depth and the offset from the original top surface.

Enable Laser Mode

When Enable Laser Mode is activated, PathTracer changes the motion logic to better fit laser workflows.

Typical behavior includes:

  1. Plunges are performed with rapid motion while the laser is off.
  2. Power is set using the configured spindle-speed logic, scaled according to the machine settings such as:
    • $30 → maximum spindle speed
    • $31 → minimum spindle speed

This allows the same interface to be adapted for laser-based engraving where spindle power values are reused as PWM control.

Enable Offsets

If Enable Offsets is checked, the generated G-code is shifted by the X/Y/Z offsets you provide.

Example:

  • if your spindle is at X0 Y0
  • but to place the laser correctly on the intended origin you must jog the machine to X-50 Y45

then you would typically enter:

  • -50 for X offset
  • 45 for Y offset

This is useful when the machine zero and the desired engraving origin do not coincide directly.

Optimize

Optimize is a simple path simplification option.

It removes some points from the generated G-code depending on how far they deviate from the line between neighboring points.

This can:

  • reduce G-code size
  • simplify toolpaths
  • improve practical usability in some workflows

It is intentionally basic and should be tested with your specific step size, machine behavior, and desired engraving quality.

Compatibility

The plugin has been updated for modern QGIS environments and tested with:

  • QGIS 4.0
  • Python 3.12
  • Qt6

The codebase was migrated for full Qt5 → Qt6 compatibility while preserving the original workflow and functionality of the plugin.

Credits

Originally developed by Nathaniel Klumb.

Updated and maintained for QGIS 4.x by Gjanosh61, with Qt5 → Qt6 migration support assisted by ChatGPT.

License

This plugin is released under a permissive license.

You are free to use, modify, and share it according to the project license terms. Attribution is appreciated.

Happy modeling!

Clone this wiki locally