Although a pip setup.py file (and requirements.txt) are provided, note that it can be non-trivial to get all the required Python libraries to install locally, especially those that are wrappers around C/C++, such as GDAL. It may therefore be easier to run Touchterrain inside a docker container (see touchterrain_jupyter docker container) or to use a jupyter notebook on Colab or Binder (see below).

TouchTerrain_standalone.py

This defines the processing parameters either directly inside the file (parameters are basically values in a dictionary) of via a JSON file it reads in. An example of such a JSON config is *example_config.json- in the stuff folder. See Processing Parameters below for details. TouchTerrain_standalone.py has only one argument, the path to the JSON file, e.g. python TouchTerrain_standalone.py stuff/example_config.json would run the example configuration. Running it without an argument will create a default JSON file (same as the example) that you can then modify. TouchTerrain_standalone.py can be used in conjuction with shell scripts for batch processing (e.g. see https://github.com/ansonl/DEM2STL)

The recommended way to run the standalone version is to use our touchterrain_jupyter docker container.

To use touchterrain in standalone mode (i.e. not via a web server), either run TouchTerrain_standalone.py or TouchTerrain_standalone_jupyter_notebook.ipynb. Both sit in the project root folder and require that the touchterrain module has been installed.

The jupyter notebook version of standalone also

Jupyter Notebook version for standalone

For most users, espcially those new to Python, the preferred way to run the standalone version of TouchTerrain is via a jupyter notebook file. Inside the notebook, the same processing parameters described in the JSON config file are defined in Python (as a dictionary). The parameters are explained below for the JSON file version but the python syntax is very similar to JSON. After processing the DEM and saving the model(s) in a zip file. All notebooks offers a map interface (geemap) for digitizing the area of the model, either as box, circle or polygon.

We have created four versions of notebooks:

1. TouchTerrain_standalone_jupyter_notebook.ipynb is meant to be run locally or via a docker container and is meant for those familiar with Python. The setup part is now somewhat outdated but the notebook may still form a useful basis. It allow the preview of the model for k3d.
2. TouchTerrain_jupyter_for_starters.ipynb is a modification of 1) meant for Python beginners. It tries to walk a beginner through the process in much more detail by providing a template (workflow) for all major parameters. As such is may be unnecessarily verbose for non-beginners. It also can preview the model via k3d and is again meant to be run locally on via a docker container.
3. TouchTerrain_jupyter_for_starters_colab.ipynb is a modification of 2) specifically for running on colab (free but Google account required). To run it just click on this badge: and follow the instructions! With some caveats, this is by far the easiest and fastest way to process DEM data with TouchTerrain standalone! The free runtime environment has plenty CPU power and disk space and, as most of the required Python packages are already installed, installation (despite being a bit quirky) is usually done under a minute. Sadly, k3d cannot be run and so it has now model preview.
4. TouchTerrain_jupyter_for_starters_binder.ipynb is similar to 3) but tailored to run on Binder Binder sets up a free docker container within a slick web interface (nice!) and uses JupyterLab. But, in my experience the installation phase is slower and less reliable than Colab. As lots of Python packages have to be installed (more than 750 Mb!), installation can take 10 - 15 minutes, with long paused w/o progress indication. Refreshing the browser sometimes helps but I've had cases where the installation simply stopped and never finished. In addition, a created instance seems to time out quite quickly, meaning that if your don't use it right away after its lengthy installation, the instance will shut down, requiring a new installation.

EarthEngine_authentication_guide.md has some notes on how to authenticate with EarthEngine, which is required when processing their online DEM data (but not when only processing uploaded local DEM raster files!).

General Processing parameters

These parameters can be used in the JSON config file or in a python dictionary for hardingcoding them in the jupyter notebook or TouchTerrain_standalone.py.

The JSON config file has the following format:

{
"CPU_cores_to_use": 0,
"DEM_name": "USGS/3DEP/10m",
"basethick": 1,
"bllat": 44.50185267072875,
"bllon": -108.25427910156247,
"bottom_image": null,
"clean_diags": false,
"fileformat": "STLb",
"fill_holes": null,
"ignore_leq": null,
"lower_leq": null,
"importedDEM": null,
"max_cells_for_memory_only": 1000000,
"min_elev": null,
"no_bottom": false,
"no_normals": true,
"ntilesx": 1,
"ntilesy": 1,
"only": null,
"printres": 0.5,
"tile_centered": false,
"tilewidth": 80,
"trlat": 44.69741706507476,
"trlon": -107.97962089843747,
"unprojected": false,
"zip_file_name": "terrain",
"zscale": 1.0
}

Note that for Python, None and True/False need to be different:

• CPU_cores_to_use: Number of CPU cores (processes) to use.

  • 0: use all available cores, which will improve multi-tile processing times but has no effect for single tile processing.
  • null: forces use of only a single core, even for multiple tiles, which is useful when running the multi-tile code in a Debugger.

• DEM_name: (resolutions are approximate and strictly true only at the equator!)

  • USGS/3DEP/10m: 10 m, continental USA only. link
  • JAXA/ALOS/AW3D30/V3_2: Global: 30 m, worldwide, but has some small "holes". link
  • USGS/SRTMGL1_003: 30 m, "worldwide", but not very far north (lower quality and older than ALOS!). link
  • MERIT/DEM/v1_0_3: 90 m, worldwide, with less error in low relief areas. link
  • USGS/GMTED2010: ~230 m, truly worldwide. link
  • GTOPO30: 30 Arc-Second, 1000 m, 1996, worldwide. link
  • CryoSat-2 Antarctica: 1000 m, antarctica only. link
  • NOAA/NGDC/ETOPO1: 2000 m, worldwide, with bathymetry. link

• basethick: (in mm) A layer of material this thick will be added below the entire model, i.e. its thickness is counted down from the lowest elevation of the entire model. This is particularly important for models with long, deep valleys, which can cause the model to shine through if the base is not thick enough. A base thickness of at least twice the filament thickness is recommended.

• bllat: Bottom-left latitude of area to be printed

• bllon: Bottom-left longitude

• trlat: Top-right latitude

• trlon: Top-right longitude

• Polygon to define the area: The web app version of TouchTerrain can load a polygon (or poly line) from an uploaded kml file which will supersede the bllat, etc. extent settings.

  The standalone version can read a kml file using the poly_file or polyURL parameters. For both, the first polygon found will be used as a mask, i.e. the model will only cover terrain inside the polygon. If no polygon is found, the first polyline is used instead. (Holes in polygons are ignored). kmz files are not supported at this time. To convert kmz to kml, unzip it (will be doc.kml) and rename doc to the (pre-dot) name of the kmz file.

  • poly_file : path to a local kml file
  • polyURL : URL to a publicly readable(!) kml file on Google Drive

  The standalone version also supports: polygon : a GeoJSON polygon,

• bottom_image: (default: null). If a filename to a valid greyscale (1-band) 8-bit local image is given (e.g. TouchTerrain_bottom_example.png in the stuff folder), the image is centered, uniformly resized to have a generous fringe and used to create a relief on the bottom. Low values (black pixels, 0) create a high relief (with a large gap from the buildplate), white pixels (255) make no relief. Must have a base thickness > 0.5 mm. The highest reli