r.out.3mf
Exports a raster DEM to 3MF or STL format for 3D printing, with optional hollow mold and multi-color output.
r.out.3mf [-nmr] input=name output=name [zscale=float] [base_height=float] [wall_thickness=float] [resolution=integer] [size=float] [units=string] [colors=string] [format=string] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.out.3mf input=name output=output.3mf
grass.tools.Tools.r_out_3mf(input, output="output.3mf", zscale=1.0, base_height=3.0, wall_thickness=3.0, resolution=1, size=100.0, units="millimeter", colors="elevation", format="3mf", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_out_3mf(input="name", output="output.3mf")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.run_command("r.out.3mf", input, output="output.3mf", zscale=1.0, base_height=3.0, wall_thickness=3.0, resolution=1, size=100.0, units="millimeter", colors="elevation", format="3mf", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.run_command("r.out.3mf", input="name", output="output.3mf")
Parameters
input=name [required]
Name of input raster DEM
output=name [required]
Name of output file (extension follows the format option)
Default: output.3mf
zscale=float
Vertical exaggeration factor; with -n flag, interpreted as mm of relief
Allowed values: 0.01-100.0
Default: 1.0
base_height=float
Base thickness in mm (solid) or wall height below terrain (mold)
Default: 3.0
wall_thickness=float
Shell wall thickness in mm (mold mode only, -m flag)
Allowed values: 1.0-20.0
Default: 3.0
resolution=integer
Resampling factor (1 = native, 2 = half resolution, etc.)
Allowed values: 1-16
Default: 1
size=float
Longest model axis in mm
Default: 100.0
units=string
Units declaration embedded in the 3MF file
Allowed values: millimeter, centimeter, inch, foot, meter
Default: millimeter
colors=string
Color scheme for multi-color 3MF (requires multi-material slicer)
Allowed values: none, elevation
Default: elevation
format=string
Output file format (3mf includes color metadata; stl is geometry-only but universally supported)
Allowed values: 3mf, stl
Default: 3mf
-n
Normalize Z to 0-1 before applying zscale (useful for non-metric DEMs)
-m
Hollow mold mode (open-bottom shell for kinetic sand or casting molds)
-r
Export the full input raster extent instead of the current region
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
input : str | np.ndarray, required
Name of input raster DEM
Used as: input, raster, name
output : str, required
Name of output file (extension follows the format option)
Used as: output, file, name
Default: output.3mf
zscale : float, optional
Vertical exaggeration factor; with -n flag, interpreted as mm of relief
Allowed values: 0.01-100.0
Default: 1.0
base_height : float, optional
Base thickness in mm (solid) or wall height below terrain (mold)
Default: 3.0
wall_thickness : float, optional
Shell wall thickness in mm (mold mode only, -m flag)
Allowed values: 1.0-20.0
Default: 3.0
resolution : int, optional
Resampling factor (1 = native, 2 = half resolution, etc.)
Allowed values: 1-16
Default: 1
size : float, optional
Longest model axis in mm
Default: 100.0
units : str, optional
Units declaration embedded in the 3MF file
Allowed values: millimeter, centimeter, inch, foot, meter
Default: millimeter
colors : str, optional
Color scheme for multi-color 3MF (requires multi-material slicer)
Allowed values: none, elevation
Default: elevation
format : str, optional
Output file format (3mf includes color metadata; stl is geometry-only but universally supported)
Allowed values: 3mf, stl
Default: 3mf
flags : str, optional
Allowed values: n, m, r
n
Normalize Z to 0-1 before applying zscale (useful for non-metric DEMs)
m
Hollow mold mode (open-bottom shell for kinetic sand or casting molds)
r
Export the full input raster extent instead of the current region
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
Returns:
result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.
Raises:
grass.tools.ToolError: When the tool ended with an error.
input : str, required
Name of input raster DEM
Used as: input, raster, name
output : str, required
Name of output file (extension follows the format option)
Used as: output, file, name
Default: output.3mf
zscale : float, optional
Vertical exaggeration factor; with -n flag, interpreted as mm of relief
Allowed values: 0.01-100.0
Default: 1.0
base_height : float, optional
Base thickness in mm (solid) or wall height below terrain (mold)
Default: 3.0
wall_thickness : float, optional
Shell wall thickness in mm (mold mode only, -m flag)
Allowed values: 1.0-20.0
Default: 3.0
resolution : int, optional
Resampling factor (1 = native, 2 = half resolution, etc.)
Allowed values: 1-16
Default: 1
size : float, optional
Longest model axis in mm
Default: 100.0
units : str, optional
Units declaration embedded in the 3MF file
Allowed values: millimeter, centimeter, inch, foot, meter
Default: millimeter
colors : str, optional
Color scheme for multi-color 3MF (requires multi-material slicer)
Allowed values: none, elevation
Default: elevation
format : str, optional
Output file format (3mf includes color metadata; stl is geometry-only but universally supported)
Allowed values: 3mf, stl
Default: 3mf
flags : str, optional
Allowed values: n, m, r
n
Normalize Z to 0-1 before applying zscale (useful for non-metric DEMs)
m
Hollow mold mode (open-bottom shell for kinetic sand or casting molds)
r
Export the full input raster extent instead of the current region
overwrite : bool, optional
Allow output files to overwrite existing files
Default: None
verbose : bool, optional
Verbose module output
Default: None
quiet : bool, optional
Quiet module output
Default: None
superquiet : bool, optional
Very quiet module output
Default: None
DESCRIPTION
r.out.3mf exports an input raster DEM to 3MF or STL format for 3D printing. By default the module creates a watertight solid composed of a terrain top surface, a flat base, and side walls between the top and base.
The model extent in XY is scaled so the longest axis matches size (in mm), preserving the geographic aspect ratio of the input region. The terrain is lifted so it starts at base_height mm above the base.
By default, Z differences from the input raster are preserved and scaled by zscale. With the -n flag, Z values are normalized to the 0 to 1 range before zscale is applied, in which case zscale is interpreted directly as the millimeters of relief. This is useful for non-metric or unitless DEMs.
By default the current computational region (extent and resolution) is respected, so the export covers exactly the area set with g.region. Use the -r flag to export the full extent of the input raster instead. Any region change, including the resolution coarsening, is made within a temporary region, so the user's region is restored when the tool finishes.
NOTES
Null cells are filled with r.fillnulls spline interpolation into a temporary raster (removed on exit) before meshing, so the resulting mesh is watertight.
The resolution parameter coarsens the computational region resolution for
export. A value of 1 uses the native resolution; larger values reduce the
triangle count and output file size.
With format=stl the output is a binary STL, which is geometry-only and
universally supported by slicers but carries no color. With format=3mf the
output is a 3MF package that can embed per-triangle color when colors is
set to elevation; rendering those colors requires a multi-material slicer.
When colors=elevation is combined with format=stl, the color request is
ignored and a warning is issued.
The -m flag produces a hollow mold: an open-bottom shell with outer walls, inner walls offset inward by wall_thickness, and a sealed bottom rim. This is intended for kinetic-sand impressions or casting molds rather than a solid display model.
The output file extension is forced to match format regardless of the name supplied in output.
EXAMPLES
Export a DEM as a solid 3MF model at native resolution:
r.out.3mf input=elevation output=terrain.3mf size=100
Export with reduced resolution for faster slicing:
r.out.3mf input=elevation output=terrain_lowres.3mf resolution=4 size=150
Export the full input raster extent regardless of the current region:
r.out.3mf input=elevation output=terrain.3mf -r size=120
Normalize Z and set 10 mm of relief:
r.out.3mf input=elevation output=terrain_norm.3mf -n zscale=10
Export a hollow mold for kinetic sand:
r.out.3mf input=elevation output=mold.3mf -m wall_thickness=4 base_height=5
Export a geometry-only STL:
r.out.3mf input=elevation output=terrain.stl format=stl size=120
SEE ALSO
r.fillnulls, r.out.gdal, r.out.vtk
AUTHORS
Corey T. White, Center for Geospatial Analytics, NC State University
SOURCE CODE
Available at: r.out.3mf source code
(history)
Latest change: Wednesday Aug 05 21:29:18 2026 in commit 5b5bcbf