Houdini 20.0 Nodes Geometry nodes

Labs Mapbox 3.0 geometry node

Downloads real-world terrain tiles from Mapbox.

On this page
Since 19.5

This node downloads DEM (digital elevation model) data, satellite images, or other styles of color maps from Mapbox. It can output both terrain heightfields and terrain meshes.

Note

Please refer to Mapbox for account registration, pricing, and attribution requirements.

Tip

If you are going to place this node inside another HDA, you need to add this node to the list of Editable Nodes on that HDA.

Using this node requires one or two string tokens provided by Mapbox. The steps to acquire and set these tokens are described below.

Setting Tokens

API Access Token

This is a long string token, needed for launching the interactive map, downloading maps, and acquiring the SKU token. To set it:

1. Go to Mapbox and create an account if you do not already have one.

2. Go to your Mapbox account page. Find your API access token under Default public token. Copy it.

3.a. Go to your Houdini user preference directory $HOUDINI_USER_PREF_DIR (on Windows OS, it is typically C:\Users\...\Documents\houdiniX.Y). Open houdini.env with a text editor. Add a new line at the end: MAPBOX_API = pk.*** (replace the pk.*** part with your actual token). This sets the token as a Houdini environment variable, which is more convenient because the token does not change often.

3.b. Alternatively, paste the token to Location and Maps > Mapbox Download Tokens > API Access Token. This is less convenient because you have to do this for every Labs Mapbos SOP you create.

SKU Token

This is a short string token, needed for downloading elevation maps. To set it:

1. On the Location and Maps tab, launch the interactive map from either of the Look Up buttons. On the interactive map window, pressing either Set Location Only or Set Location and Download will automatically set the SKU token.

2. If for whatever reason the SKU token is not set or not working, press Mapbox Download Tokens > Rrefesh SKU Token, and then on the pop-up window, press Get New SKU Token.

Creating Seamless Terrain Tiles

Seamless Elevations, Colors, and Materials

You can join the output tiles of multiple Labs Mapbox SOPs together to form a larger piece of terrain. To do so:

1. Create multiple Labs Mapbox SOPs that use the same location settings and tokens.

2. Move each tile to its intended location by setting Location and Maps > Tile Offset X/Y. The unit of this parameter is one full tile width.

3. All the tiles must share the same width. The easiest way to do this is using one node to provide the reference tile width. On all the other nodes, set Tile Scale > Tile Width to From Reference Mapbox SOP, and then pointing Reference Mapbox to the reference node.

4. Download all the selected maps on all the nodes.

5. Turn on Seamless Tiling > Enable Seamless Tiling with Neighbour Tiles on all the nodes.

6. Set the correct Top Neighbour, Right Neighbour, and Top-Right Neighbour on all the nodes. Leave it blank if a tile does not have a certain neighbour.

7. (Optional) If you want to use the tileable color map for the materials, press Seamless Tiling > Tileable Material > Render Tileable Color Map on all the nodes.

8. (Optional) If the location has changed, please re-download all the selected maps, re-render all the tileable color maps (if they are used), and re-enable any material/color parameters on the Output tab that have been automatically turned off during the downloads to avoid texture sync issues.

Seamless Normals

For both heightfield tiling and mesh tiling, it is impossible to make normals seamless with this node alone, because normals are inherently inconsistent between two sides of unfused borders. However, you can make normals seamless with a downstream Labs Mapbox Post-process SOP that works on all the tiles at once.

Troubleshooting

“Your file was not found / ERR_FILE_NOT_FOUND”

When launching the interactive map, if you see this error message, simply create a new Labs Mapbox SOP in your network. That should immediately fix the problem and you can delete the new node you created. (Whenever this node is created, it automatically copies several HTML files to $HOUDINI_USER_PREF_DIR/SideFXLabs/misc/mapbox/. This error message means the node cannot find the necessary HTML files.)

Black screen

When launching the interactive map, if you see a black screen (often followed by a crash), there is likely some issue with connecting to the server or rendering the map view. Give it some time and then open a temporary, blank Houdini scene. Create a Labs Mapbox SOP and try re-launching the interactive map. If the map is back to normal, you can return to your original Houdini scene.

Materials displays no texture

If a material does not display any texture, even if the texture file exists on disk, check if the viewport material toggle is on and that the material is enabled on the Output tab. If everything looks normal, try pressing Refresh Viewport before pressing Reload Textures. If there is still no texture, then this is most likely a rare deadlock that the viewport can enter when a material is being displayed while its texture path is pointing to a nonexistent file. If the viewport is already in this deadlock, you have to make sure the required texture is present on disk, and then restart Houdini.

Parameters

Mode

Controls whether to defer cooking until the maps are downloaded, or to immediately cook output geometries with existing maps.

Download

Downloads the selected maps from Mapbox’s servers.

When the download starts, all material/color parameters are automatically turned off to avoid texture sync issues. When you manually turn a material/color parameter back on, a safety check for texture dependencies is enforced through that parameter’s callback script.

Refresh Viewport

Press this if a terrain material in the viewport is displaying an out-of-date texture.

Reload Textures

Press this to reload all the textures used by this node’s internal COPs and SOPs. This is much slower than Refresh Viewport, so only press this when necessary.

While this should fix most texture sync issues, there is one rare exception when a material does not display any texture. Please see the Troubleshooting section of the Help page.

Location and Maps

Maps

The map(s) to include. This affects both the downloads and the output geometries.

Location Mode

Specifies how to set the location of this tile. In most cases, it is probably easier to set the location using latitude and longitude, but the tile indices option is also provided for special use cases.

Latitude and longitude allow you to pin specific coordinates. Depending on Tile Alignment, you can either use the pinned coordinates as the center of your tile or coordinates your tile must contain.

Mapbox’s APIs divide Earth’s surface into a grid of square tiles. We refer to these as “precut tiles” because their tile borders are predetermined and fixed. At each zoom level, a tile contains exactly 4 evenly divided tiles of the next zoom level. At zoom level 0, there is only 1 tile covering the whole Earth; at zoom level 1, 4 tiles; at zoom level 2, 16 tiles; and so on.

The X index and Y index refer to a pair of integer indices associated with each tile at each zoom level. X increases from west to east. Y increases from north to south. The highest index at a given zoom level equals pow(2, zoom) - 1.

Tile Alignment

Specifies whether you want to center your tile at the pinned coordinates. The centered option requires more map downloads. Mapbox APIs only allow you to download “precut tiles” (see Location Mode for the definition), and only at the maximum resolution of 1024×1024 for color maps or 512×512 for elevation maps. In order to obtain higher resolution 2048×2048 color maps or 1024×1024 elevation maps, multiple maps of the next zoom level will be downloaded to composite the final maps.

Custom-Cut Tile Centered at Lat/Lon: 9 next-zoom-level maps will be downloaded, combined, and cropped to generate a custom tile centered at the pinned coordinates.

Precut Tile Containing Lat/Lon: 4 next-zoom-level maps will be downloaded and combined to generate a precut tile containing the pinned coordinates.

Note

Please refer to your Mapbox account for detailed pricing information and usage statistics.

View Precut Tile

Displays the precut tile containing the pinned coordinates. If Tile Offset X/Y is {0, 0}, then this view should match the map you download.

This is different from Look Up, which when pressed, shows a view that is always centered at the pinned coordinates.

Lat/Lon/Zoom

Latitude, longitude, and the zoom level. The zoom level must be an integer. If you keep the latitude and longitude fixed while changing the zoom level, it has the effect of zooming in/out at the same location.

Look Up

Launches an interactive map that allows you to set a new location and zoom level. The initial view is centered at the current latitude and longitude.

If you only see a black screen instead of the satellite image, please refer to the Troubleshooting section of the Help page.

X/Y/Zoom

X and Y are precut tile indices (see Location Mode for more information) at the given zoom level. Unlike with Lat/Lon/Zoom, it is meaningless to keep the X and Y fixed while changing the zoom level.

Look Up

Launches an interactive map that allows you to set a new location and zoom level. The initial view shows the precut tile at the current precut tile indices.

If you only see a black screen instead of the satellite image, please refer to the Troubleshooting section of the Help page.

Compute X/Y using Current Lat/Lon

Computes the indices of the precut tile that contains the current latitude and longitude. This syncs locations for when you want to switch Location Mode.

Compute Lat/Lon using Current X/Y

Computes the center coordinates of the precut tile at the current precut tile indices. This syncs locations for when you want to switch Location Mode.

Tile Offset X/Y

In integers, the number of full tile widths by which to offset the location. Positive X values offset the location to the east. Positive Y values offset the location to the south. This is mainly used for seamless tiling, where you want to join the output tiles of multiple Labs Mapbox SOPs together to form a larger piece of terrain.

Color Map Style

The style of the color map. Please visit Mapbox Styles API to find out more about each style.

Custom Style

You can use Mapbox Studio to design your own color map styles.

Mapbox Download Tokens

API Access Token Already Set as Environment Variable

Automatically set based on whether the environment variable MAPBOX_API exists. Generally, you do not need to change this.

API Access Token

A long string token tied to your Mapbox account. You can find it on your Mapbox account page. This is needed for launching the interactive map, downloading maps, and acquiring the SKU token. You can set it as a Houdini environment variable MAPBOX_API because this token does not change often.

Please follow the instructions on the Help page to set this token.

SKU Token

A short string token needed for downloading elevation maps. According to Mapbox, this is only used to count MAU (monthly active users). Please refer to Mapbox for more usage guidelines.

Please follow the instructions on the Help page to set this token.

Refresh SKU Token

Launches a pop-up window that allows you to acquire a new SKU token through Mapbox GL JS API.

Download Paths

Color Map

The file path to the color map.

Elevation Map

The file path to the elevation map.

Temp File Directory

The folder for the temporary next-zoom-level maps used to composite the higher resolution final maps. When Advanced > Auto Clean Up Temp Directory is on, this folder is deleted after the final maps are generated.

Tile Scale

Width

Tile Width

Specifies what to use as the width (west-east arc length) of the terrain tile. Since the terrain tiles are always squares, the height (north-south arc length) of a tile will be the same as its width. The real-world widths are computed based on the latitude and the zoom level, using the WGS 84 reference ellipsoid.

Custom Width: A custom width.

Real-World Width (Northern Border): The real-world width measured at the tile’s northern border.

Real-World Width (Center): The real-world width measured at the tile’s center.

Real-World Width (Southern Border): The real-world width measured at the tile’s southern border.

From Reference Mapbox SOP: The final tile width from a reference Labs Mapbox SOP.

Custom Tile Width

In metres, the custom tile width.

Reference Mapbox

The operator path to the reference Labs Mapbox SOP. When Tile Width is From Reference Mapbox SOP, this node copies its final tile width and final elevation scale from the reference Labs Mapbox SOP.

Width Scale

A final multiplier to the tile width. This is ignored when Tile Width is From Reference Mapbox SOP.

Elevation

Clamp Input Elevation Range

Clamps the elevation values sampled from the elevation map when generating the initial heightfield. This is applied before the height parameters on the Output tab.

Clamp Minimum

Applies a lower limit to input elevation values.

Elevation Min

In metres, the lower elevation limit. The sea level is at 0.

Clamp Maximum

Applies a higher limit to input elevation values.

Elevation Max

The higher elevation limit. The peak of Mount Everest is at around 8848.

Preserve Output Elevation to Real-World Width Ratio

Keeps elevation values proportional to the tile width. This allows you to uniformly scale the terrain. The elevation values in the elevation map are real-world values. The real-world tile width is the width measured at the tile center.

Custom Elevation Scale

A custom multiplier to the input elevation. This is applied after Clamp Input Elevation Range but before the height parameters on the Output tab.

Tile Geographical Details

Refresh

Updates the tile’s geographical details. These are also automatically updated when you download maps.

Real-World Tile Width Calculator

Latitude

The latitude at which to compute the real-world tile width.

Zoom

The zoom level at which to compute the real-world tile width.

Compute Real-World Tile Width from Latitude and Zoom

Computes the exact length of a west-east arc spanning a tile on Earth’s surface.

Real-World Tile Width

The computed result, autofilled when you press Compute Real-World Tile Width from Latitude and Zoom. If you want to use the real-world width measured at a specific latitude as your tile width, set Tile Width to Custom Width and use this result as Custom Tile Width.

Seamless Tiling

Enable Seamless Tiling with Neighbour Tiles

Configures the tile to fetch maps from neighbour tiles in order to make elevations, colors, and materials seamless along the tile borders.

Seamless tiling only requires one-way awareness, meaning if every single tile syncs its border values with its top, right, and top-right neighbours, there is no need for any tile to sync with its left, bottom, or other corner neighbours.

On this node alone, it is impossible to make normals seamless, because normals are inherently inconsistent between two sides of unfused borders. However, you can make normals seamless with a downstream Labs Mapbox Post-process SOP that works on all the tiles at once.

Please see the Creating Seamless Terrain Tiles section of the Help page for more information.

Neighbour Tile Mapbox SOPs

Enable Top Neighbour

Enables seamless tiling with the top (northern) neighbour tile, if it exists.

Top Mapbox

The operator path to the Labs Mapbox SOP that generates the top (northern) neighbour tile. This is ignored if blank.

Enable Right Neighbour

Enables seamless tiling with the right (eastern) neighbour tile, if it exists.

Right Mapbox

The operator path to the Labs Mapbox SOP that generates the right (eastern) neighbour tile. This is ignored if blank.

Enable Top-Right Neighbour

Enables seamless tiling with the top-right (north-eastern) neighbour tile, if it exists.

Top-Right Mapbox

The operator path to the Labs Mapbox SOP that generates the top-right (north-eastern) neighbour tile. This is ignored if blank.

Reload Neighbour Color

Forces all the neighbour nodes listed above, as well as this node itself, to reload color maps.

Reload Neighbour Elevation

Forces all the neighbour nodes listed above, as well as this node itself, to reload elevation maps.

Tileable Material

Material Diffuse Texture

Specifies which diffuse texture to use for materials. For both terrain heightfields and terrain meshes, the border UVs are aligned to the centers of the border pixels. Since the terrain tile textures are not self-repeating, the texture tiling mode (in whatever application that uses this texture) should be set to “clamp” or its equivalents, not “wrap” or its equivalents.

Color Map on Disk: The original color map, not entirely seamless (when tiled at mipmap level 0). Since the border pixels have no knowledge of the neighbour color maps, most texture filtering modes (except for point filtering) will result in seams.

Tileable Color Map on Disk: A new tileable color map that needs to be rendered to disk first, completely seamless (when tiled at mipmap level 0). This new map shares border pixel values with the top, right, and top-right neighbours. Consequently, texture filtering will not result in seams. You can render it when all the neighbours' color maps are available.

Render Tileable Color Map

Renders to disk a new tileable color map. This map contains border pixel values copied from the neighbour nodes' color maps, so you should only render it when all the neighbour nodes' color maps are available.

Due to the dependencies on neighbour nodes, this map is not automatically updated when you press Download, so please remember to render this map again if the location has changed.

Render

Resample Filter

In order to generate the tileable color map, the original color map is extended by 1 column of pixels to the right and 1 row of pixels to the top. The extended pixels copy the values from the neighbour nodes' color maps. That makes the texture tiling seamless, but the texture resolution becomes 2049×2049. To fix that, when you press Render Tileable Color Map, the new map is downsampled back to 2048×2048 using this filter.

Point (Original Sharpness): Preserves the original sharpness but creates two subtle seams running horizontally and vertically through the center. Due to material texture filtering, these center seams are rather hard to notice compared to the border seams between the original color maps. In other words, using the tileable color map is probably still worth it.

Catmull-Rom (Smoother): Avoids any center seams but loses some of the sharpness.

Soften Subtle Center Seams from Point Filter

Makes the already subtle center seams even harder to notice by blending the tileable color map with the original color map along the center seams.

Seam Mask Radius

In pixels, the maximum blend distance away from the center seams. The blend mask has a soft falloff.

Seam Mask Intensity

Adjusts the opacity of the blend mask. Higher values mean more influence from the original color map.

Tileable Color Map

The file path to the tileable color map.

Output

HeightField

Grid Resolution

The resolution of the heightfield. The total voxel count is this number squared. The resolution of the converted mesh will be this number multiplied by Terrain Mesh Conversion > Relative Density.

Blur HeightField

Makes the heightfield smoother by blurring the height values.

Blur Radius

In UV units, the blur radius. Highever values mean strong blurs. This is applied before Height Scale and Height Offset.

Height Scale

Scales the height values. This is applied before Height Offset.

Height Offset

Offsets the height values. This is applied after Height Scale.

Add Material

Performs a safety check for texture dependencies, and if the check is passed, adds a material to the terrain heightfield.

There is an important Python function in this parameter’s callback script. If you are going to set this parameter through code, that callback script may not be triggered, in which case, please explicitly call that Python function in your code.

Terrain Mesh Conversion

Relative Density

The ratio of the mesh’s resolution to the heightfield’s resolution.

Sample Point Color from Color Map

Performs a safety check for texture dependencies, and if the check is passed, samples point colors from the color map.

Point color sampling never uses the tileable color map, which is strictly for materials.

Color Sample Filter

The filter for sampling point colors from the color map.

Source Color Space

Specifies the color space of the color map. After sampling, the point colors stored in the mesh will typically be linear, and then the viewport will transform them to whatever color space the viewport is using.

Add Material

Performs a safety check for texture dependencies, and if the check is passed, adds a material to the terrain mesh.

There is an important Python function in this parameter’s callback script. If you are going to set this parameter through code, that callback script may not be triggered, in which case, please explicitly call that Python function in your code.

Border Point Group

The name of the point group to be created that contains all the border points. This is used by a downstream Labs Mapbox Post-process SOP to make border normals seamless between adjacent tiles.

Advanced

Look Up Window Size

The size of the window containing the interactive map. The interactive map itself has a fixed size of 512×512, which is the required size to match what you see in the window with what you actually download.

Color Map Size

Currently only 2048×2048 is supported.

Elevation Map Size

Currently only 1024×1024 is supported.

Retry If Download Fails

Attempts to re-download a next-zoom-level map if the first attempt fails. This node downloads 9 or 4 next-zoom-level maps to composite a final map. The retries will happen per next-zoom-level map, so do not set Retry Limit too high.

Retry Delay

In seconds, the delay before attempting to re-download the same next-zoom-level map.

Retry Limit

The maximum number of retries allowed for each next-zoom-level map.

Auto Clean Up Temp Directory

Deletes the folder containing the temporary next-zoom-level maps after the final maps are generated. The path to this folder is specified by Location and Maps > Download Paths > Temp File Directory.

Show Hidden Autofilled Parameters

Unhides the autofilled parameters, which are a list of parameters automatically set by various parameter callback scripts when you interact with this node.

Autofilled Parameters

Pin Relative Position

The pinned coordinates' relative UV position within the center next-zoom-level map. This is only used when Location Mode is Latitude / Longitude / Zoom and Tile Alignment is Custom-Cut Tile Centered at Lat/Lon.

This is automatically set when you download maps.

Real-World Tile Width

The real-world tile widths measured at the tile’s northern border, the center, and the southern border, in that order. This is referenced by Tile Scale > Tile Geographical Details.

This is automatically set when you download maps or press Tile Geographical Details > Refresh.

Tile Bounds

The longitude of the tile’s western border, the latitude of the southern border, the longitude of the eastern border, and the latitude of the northern border, in that order. This is referenced by Tile Scale > Tile Geographical Details.

This is automatically set when you download maps or press Tile Geographical Details > Refresh.

Center Lat/Lon

The latitude and longitude of the tile center. This is referenced by Tile Scale > Tile Geographical Details.

This is automatically set when you download maps or press Tile Geographical Details > Refresh.

Enable HeightField Material

What actually enables the heightfield material internally.

This is automatically set when you click on Output > HeightField > Add Material.

Enable Mesh Material

What actually enables the mesh material internally.

This is automatically set when you click on Output > Terrain Mesh Conversion > Add Material.

Examples

Geometry nodes