Planet Materializer (plmat) is a tool for creating 3d planet models using geospatial elevation data. Such data can be obtained by photographing planetary surfaces or by using procedural generation.
Command line
Usage: plmat <model_format> <model_type> <data_source> [–planet-name <planet-name>] [–model-size <model-size>] [–jobs <jobs>] [–approx-method <approx-method>] [–data-source-dir <data-source-dir>] [–output-dir <output-dir>]
Positional arguments:
- model_format: x3dgeospatial or obj
- model_type: Texture or Color
- data_source: Hgts
Options:
- –planet-name <planet name>: this name will be used in output file names
- –model-size <model size>: number of polygons in vertical (south-north) direction (may be implicitly changed to the nearest valid value)
- –jobs <jobs>: number of threads for doing model calculations (default: min(2, available parallelism))
- –approx-method <approx-method>: elevations approximation method (default: Nearest)
- –data-source-dir <data source path>: default: current directory
- –output-dir <output path>: default: current directory
- –help: displays usage information
Valid approximation methods: Nearest, Bilinear. Use Bilinear only for very detailed models.
Settings file
In addition to command line arguments, model parameters can be specified in a configuration file (settings.yaml). It’s in a YAML format with two root sections: DataSource and Model. The Model section include settings for two current model formats: Obj and X3DGeospatial. The Common section applies to both Color and Texture model types.
Command line arguments have precedence over configuration file parameters (namely, data_source_dir and output_dir). File settings.yaml must be in current directory when launching the app.
Default content of settings.yaml:
DataSource:
DemArcSec3:
nodata: -32767,
sea_level: 0,
data_source_dir:
Model:
Obj:
Common:
template_file_obj: "obj.template"
template_file_mtl: "mtl.template"
output_dir: "./"
radius: 6378000.0
scale: 50.0
Texture:
texture_uri: "texture.png"
Color:
color_profile_file: "color_profile"
color_precision: 4
X3DGeospatial:
Common:
template_file_x3d: "geospatial.x3d.template"
output_dir: "./"
Texture:
texture_uri: '"texture.png"'
Color:
color_profile_file: "color_profile"
Some of these settings have default hardcoded values (nodata, sea_level, etc). But try not to change the location of the parameters and especially not to delete them in settings file.
color_precision parameter for Obj model can be set to 0. In this case, the color will be associated with each vertex, not with the faces. The faces will be filled with a gradient. This option is not supported by some 3D applications.
Data Source Type
Currently, only the hgts file format is supported. Each file must contain a square grid of elevation values with arbitrary (>4) square’s side.
File naming rules are the same as for Arc3Sec SRTM DEM: files must be named such as N01E052.hgt or S12W052.hgt. Each file contains elevation data from a range of one degree of longitude and one degree of latitude.
In case of a square’s side of 1200 nodes files become conforming to the Arc3Sec SRTM DEM format. Therefore, only with this square’s side value they are compatible with various GIS tools.
Output Model Formats
Currently two output formats are implemented.
- OBJ, a geometry definition file format first developed by Wavefront Technologies.
- X3D, Extensible 3D Graphics developed by Web3D® Consortium.
OBJ file format is a simple data-format that represents 3D geometry. Can be used for 3d printing, be imported in various 3d software, and be converted to other 3d formats. Usually an obj model consists of two files with .obj and .mtl extensions.
Templates obj.template and mtl.template are headers of output files and will be included as is.
Extensible 3D (X3D) Graphics is the open international standard for 3D on the Web. X3D is used for building 3-dimensional models, both simple and sophisticated. x3d provides several encodings (ClassicVRML, Compressed Binary, JSON, and more); Plmat app output data are one file with ‘.x3d’ extension (XML encoding).
Template geospatial.x3d.template is a skeleton for constructing the output file; the template elements _GeoElevationGrid and _Color are placeholders for actual elevation array and color array elements. Since generated X3D file is XML file, you can easily modify result X3D file as you wish.
The template file must contain the line<component level='1' name='Geospatial'/>
Model Type
Two types of models are created: Color and Texture.
Color model type is for colored models with a gradient specified in a color profile file (color_profile_file parameter). Depending on the color_precision parameter, the color can be applied to the model vertices or to the polygon faces. This is actual only for Obj model format: color_precision=0 means that the vertices are colored, other positive integers specify the number of colors that will be used to color the model polygons. In X3D model format colors are always applied to vertices.
Texture model type is for models with texture overlay. For OBJ models texture specified by texture_uri parameter is simply a file name (“texture.png”, for example). For X3D models there should be a list of addresses, which can be either a file name or an internet address (‘”texture.png” “https://<some_internet_site>/texture.png”‘, for example).
Color profile
Each line of color profile file defines a gradient boundary. First number is an elevation in meters; negative values are allowed.
Following three numbers are RGB color components. A component value must be between 0.0 and 1.0, which define component saturation.
Default color profile file content:
0 0.1 0.1 0.6 1 0.1 0.7 0.1 400 0.6 0.8 0.0 1800 0.75 0.75 0.0 4000 0.75 0.5 0.0 6600 0.7 0.2 0.0 7000 0.9 0.9 0.9
Examples
You can view examples of X3D models in X_ITE X3D Browser by following the links on the main page.
Following screenshots are taken from MeshLab program. This program is capable of showing OBJ models with colored vertices.
Sample Obj models can be downloaded.