This project contains scripts that automate the process of producing height and diffusion maps from a pointcloud file. The scripts were developed for Ubuntu but will most likely work in other Unix-based operating systems. with a few adjustements.
The scripts can be extremely resource intensive depending on the size of the given pointcloud file.
The rasterize.sh script is not fully optimized in that it creates temporary .laz and .tif files with a total size that is approximately double that of the given pointcloud file. Make sure that the necessary disk space is available when processing gigabyte-sized pointcloud files.
The rasterize.sh script uses PDAL which can be resource intensive with memory allocations and result in a malloc error. This can be mitigating against by reducing the target output size of the diffusion map image.
Third party applications are invoked throughout the rasterize.sh bash script. The mentioned versions are those used while the script was developed:
- LAStools 1.8
- PDAL 1.6.0
- GDAL 2.2.3, released 2017/11/20
- python-gdal
- ImageMagick 6.9.7-4 Q16 x86_64 20170114
- jq 1.5
In Ubuntu, the latest version of these third party applications can be installed as follow:
sudo apt install liblas-bin
sudo apt install pdal
sudo apt install gdal-bin
sudo apt install python-gdal
sudo apt install imagemagick
sudo apt install jq
This project contains two bash scripts:
- rasterize.sh: Rasterizes xyzRGB pointcloud files into height and diffusion map files.
- makemap.sh: Create files for a 3D model environment that can be loaded into the MARS simulator.
Both scripts share the following options:
Option | Description | Default value |
---|---|---|
-i | Input filename | |
-h | Height map image size | 512 |
-d | Diffusion map image size | 4096 |
-r | PDAL resolution | 0.05 |
-t | PDAL output type | mean |
Although not enforced, the diffusion map size should be a power of 2 when producing a diffusion map for the MARS simulator.
The makemap.sh has an additional option to set the model environment name that will be specified in the produced heightmap.yml file:
Option | Description |
---|---|
-n | Name of the model environment |
-o | Overwrite previously created rasters |
The given map name must not include whitespaces.
The height map or diffusion map sizes can be set to a greater value than the maximum defined by the intermittent digital terrain model (DTM) GeoTiff file generated by PDAL (i.e. the dtm.tif in the tmp directory). This will result in stretch images that may or not be what was intended. If this was not intended then this can be resolved by either increasing the resolution of the resulting DTM GeoTiff file via the -r
option or decrease the sizes of the height and diffusion maps using the -h
and -d
options.
- PDAL resolution: The length of raster cell edges in X/Y units. The smaller this value the higher the resolution.
- PDAL output type: The raster layer to be produced. The supported values are min, max, mean, idw, count, and stdev. There is no error checking implemented for unsupported values.
The default PDAL resolution of 0.05 is set through trial and error based on testing with 4cm resolution pointcloud files and the PDAL processing memory constraints. If lower resolution pointcloud files are inputted then the PDAL resolution value must be increased. Not doing so will result in heightmap and diffusion map image files with transparent pixel patches where data is missing. By way of example, a PDAL resolution of 0.14 is the smallest value that can be set for a 25cm resolution pointcloud so that the resulting image files not miss any texture pixels.
Read more about PDAL options here.
This script produces two image files and a json file with the pointcloud's bounding box information:
- heightmap.map
- diffusionmap.png
- bbox.json
Create height map and diffusion map image files with default parameters:
bash rasterize.sh -i pointcloud.xyz
Create 1024x1204px height map file and 3600x3600px diffusion map file:
bash rasterize.sh -i pointcloud.xyz -h 1024 -d 3600
This script produces the files that are part of a model environment project for the MARS simulator:
- README.md
- manifest.xml
- heightmap.yml
- fragment_shader.yml
- vertex_shader.yml
- ground.bobj
The script will invoke rasterize.sh if it has not already been done for the given pointcloud file. This is determined by checking if the heightmap.png, diffusion.png, and bbox.json files already exist. Overwriting already existing heightmap.png and diffusion.png files might be desired if different sizes for those files are required. In this case, simply delete at least one of the three files — heightmap.png, diffusion.png, or bbox.json — so that rasterize.sh will be invoked when running makemap.sh.
Create MARS map files with default parameters:
bash makemap.sh -n my_map_name -i pointcloud.xyz
Create MARS map files with a 1024x1204px height map file, a 3600x3600px diffusion map, and overwrite any previously created raster files:
bash makemap.sh -n my_map_name -i pointcloud.xyz -h 1024 -d 3600 -o
- Memory: Invoking PDAL can throw a malloc error when too low of a value is set for the resolution option. To resolve this, decrease the target resolution by increasing the value of this option (e.g. use the
-r
option to set it to 0.04 instead of the default 0.05).