Skip to content
← All articles
Project introduction

TrueMapData: from measured height maps to usable assets

Listen to the audio story

From a measured surface to a usable asset · 2:13 · AI-written script, synthetic voices

Transcript

Ava: Imagine scanning a metal surface so finely that you can see every scratch as a tiny hill or valley. What do you do with all those heights?

Andrew: Look at them, I suppose. Maybe turn them into a 3D model.

Ava: Both, and that's TrueMapData. This Python library reads surface captures from TrueMap and GelSight, exposes their heights as NumPy arrays, and gives you tools for analysis and graphics export from the same representation.

Andrew: What's inside one of these capture files?

Ava: A dot t m d file holds a header, spatial metadata and a grid of heights stored as float32 values, row by row. It reads both the older v1 format and the TrueMap v6-style v2 format. The metadata keeps the physical scan size, so the grid never loses its real-world scale.

Andrew: So it's like a topographic map of a tiny patch of material.

Ava: Exactly that. And you can explore it: a 2D heatmap, a 3D surface, row and column profiles, contour lines, and comparisons between files. Matplotlib makes static plots, Plotly saves an interactive HTML view, and optional Polyscope opens a 3D inspection window.

Andrew: Then where do the graphics assets come in?

Ava: From the same height grid, it derives normal maps, which describe local orientation for lighting, and displacement maps, which carry the height itself. It can also export meshes in formats like STL, OBJ, glTF and USD, and apply textures to a template model using the scan's millimeters per pixel to set the tiling.

Andrew: And the metrology side?

Ava: Roughness analysis uses Surfalize for the ISO 25178 areal parameters. Wear analysis compares captures over time: it aligns frames with translation or OpenCV and SIFT registration, subtracts the heights, and reports volume loss, scratch evolution and roughness trajectories.

Andrew: So one library, from raw scan to a game-ready mesh or a wear report.

Ava: Yes. The surface and profile figures in the post come from the project's own README examples. The full write-up has the diagram, the commands to try, and links to the guides.

TrueMapData: from measured height maps to usable assets
Surface visualization from the TrueMapData README. Heights are normalized in this example.
Table of contents

TrueMapData reads surface captures from TrueMap and GelSight, exposes their heights as NumPy arrays, and provides tools for analysis and graphics export. The same surface representation supports metrology work and assets such as displacement maps or meshes.

1. What a capture contains

A .tmd file contains a header, spatial metadata and a grid of heights. The library supports the legacy v1 format and the TrueMap v6-style v2 format. Both store float32 samples in row-major order: height_map[row, column], with shape (height, width). Scan lengths and offsets describe the capture’s physical extent.

That metadata matters when a grid leaves the file reader. A texture can stretch over any UV range; a measured surface needs its sample spacing to retain physical scale. The binary format guide[1] documents the byte layout and the reader’s checks for alternate v2 headers.

from tmd import TMD

capture = TMD.load("path/to/capture.tmd")
heights = capture.height_map
metadata = capture.metadata

The path above is a placeholder for a capture. The code reads the raster and metadata together.

2. Inspect the surface before exporting it

The visualization commands offer a 2D heatmap, a 3D surface, row and column profiles, contours, and comparisons between files. Matplotlib produces static plots; Plotly can save an interactive HTML view. Optional Polyscope support provides a 3D inspection window.

X profile from the TrueMapData README

A profile shows how height varies across one section of a surface. Source: TrueMapData README visual examples.

pip install "truemapdata[viz]"
tmd-process visualize basic path/to/capture.tmd
tmd-process visualize 3d path/to/capture.tmd --plotter plotly --output surface.html

I check the height field and its scale before choosing a derived map. A normal map describes local orientation for shading. A displacement map carries height information. Mesh export creates geometry in formats including STL, OBJ, PLY, glTF and USD, with the optional mesh dependencies installed.

flowchart TB
  Capture["TrueMap or GelSight capture"] --> Read["Height grid and spatial metadata"]
  Read --> Inspect["Heatmap, profile or 3D surface"]
  Inspect --> Metrics["Roughness and surface metrics"]
  Inspect --> Maps["Normal and displacement maps"]
  Inspect --> Mesh["Mesh export and template texturing"]

The apply-on-mesh path bundles derived textures with a template OBJ/MTL. It uses template bounds, mm_per_pixel and capture dimensions to set tiling. This connects the size of the scan to the surface receiving the texture.

3. Roughness and wear answer different questions

Roughness analysis describes a surface at a particular capture. The optional truemapdata[roughness] extra uses Surfalize for ISO 25178 areal parameters. Surfalize is GPL-3.0 and is installed separately from the MIT-licensed core package.

Wear analysis compares captures over time. Before subtracting heights, the frames need the same grid and the same in-plane region. The sequence guide[2] describes translation alignment and OpenCV/SIFT registration, including registration driven by normals.

The loss convention is reference height − current height. Positive loss means the current surface is lower than the reference. Computing a physical volume also needs the pixel spacing in both directions. Registration errors or inconsistent height units would change that result.

The tmd-wear commands cover volume series, scratch evolution, slip-axis heuristics and roughness trajectories. Those outputs complement the filters, defect detection, sequence export and compression tools in tmd-process.

4. Source and examples

The surface and profile figures here are original examples from the repository README, not measurements from my thesis. The surface figure uses normalized heights.

The TrueMapData project note links the repository and its code overview.

References

  1. ETSim. (). binary format guide. [Source file or documentation] github.com.
  2. ETSim. (). sequence guide. [Source file or documentation] github.com.
  3. ETSim. (). TrueMapData. [Software repository] github.com.
  4. Documentation. (). [Web page] etstribology.github.io.
  5. ETSim. (). Visualization guide. [Source file or documentation] github.com.

References use this article’s publication date.