Planet Materializer Manual

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>] [–data-source-dir <data-source-dir>] [–output-dir <output-dir>]

Positional arguments:

  • model_format: x3dgeospatial or obj
  • model_type: Texture or Color
  • data_source: DemArcSec3

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))
  • –data-source-dir <data source path>: default: current directory
  • –output-dir <output path>: default: current directory
  • –help: displays usage information

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 this file.

Data Source Type

At the moment only one data source type is available, namely Arc3Sec SRTM DEM data. This data consists of a set of files in a single directory with a special naming convention.

Files must be named such as N00E052.hgt or S00W052.hgt. Each file contains elevation data from a range of one degree of longitude and one degree of latitude.

Output Model Formats

Currently two output formats are implemented.

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.

OBJ model with colored vertices (model size: 256). Colored X3D model of the same size looks similar.
OBJ model with colored polygon faces (model size: 256)
OBJ model with texture overlay (model size: 256)

Sample Obj models can be downloaded.