TrueMapData

1. Overview

Why it exists. One surface representation that serves metrology work and graphics assets such as displacement maps or meshes.

Best fit. Inspecting measured surfaces, comparing captures over time (wear), and exporting normal maps, displacement maps or meshes with physical scale preserved.

3. Getting started

Package. TrueMapData is on PyPI as truemapdata (MIT, Python 3.8 or later). The latest release on PyPI is 1.0.5; the repository’s pyproject.toml is already at 1.0.6. There is no .NET or NuGet package: the library is Python only, and the import name is tmd.

pip install truemapdata

The extras pull in optional features. Each one is declared in pyproject.toml:

pip install "truemapdata[mesh,viz]"
pip install "truemapdata[roughness]"

Installing the package adds two commands, tmd-process (the full toolkit) and tmd-wear (the wear subset).

A first script. This example follows tests/core/test_tmd.py, so it runs without a capture file: it builds a height map in memory, saves it in the TMD v2 format, reads it back and looks at it.

import numpy as np
from tmd import TMD

# A 200 x 200 grid of heights, 0.05 mm between samples
y, x = np.mgrid[0:200, 0:200]
heights = (np.sin(x / 25) * np.cos(y / 30)).astype(np.float32)

surface = TMD(heights, {"comment": "synthetic", "resolution_x": 0.05, "resolution_y": 0.05})
path = surface.save("synthetic.tmd")            # version 2 by default, returns the .tmd path

loaded = TMD.load(path)
print(loaded.shape)                              # (200, 200)
print(loaded.dimensions)                         # width and height in physical units: 10.0 x 10.0
print(loaded.stats["min"], loaded.stats["max"])  # computed on first access

patch = loaded.crop(50, 50, 64, 64)              # x_start, y_start, width, height
small = loaded.resize(100, 100)

TMD.load raises FileNotFoundError or TMDProcessingError for a missing file, and dimensions multiplies the grid size by resolution_x and resolution_y from the metadata (1.0 when they are missing). With a real capture, replace the synthetic grid with TMD.load("capture.tmd"). The repository tracks sample captures for this: TrueMap files in examples/v1/ and examples/v2/ (a dime, a step height, coins, paper, and in v2 a laser marking and a Vickers indentation) and three GelSight captures in examples/gelsight/ taken after 0, 150 and 300 mm of sliding at 100 g.

From the command line. The README’s wear examples run on those fixtures:

tmd-process visualize basic examples/v2/Dime.tmd
tmd-wear bearing curve examples/gelsight/circle_0mm_100g_heightmap_linear_detrend.tmd --json
tmd-wear volume-series examples/gelsight/circle_0mm_100g_heightmap_linear_detrend.tmd \
  tests/fixtures/gelsight_wear_volume_second_frame.tmd --json

The first wear command prints the bearing (Abbott–Firestone) curve of one capture; the second compares captures of the same grid and reports the loss against the first one (z_ref - z_i, positive where the surface went down).

4. Features and components

5. Architecture

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"]

6. Constraints and checks

• Roughness describes one capture; wear compares captures over time and needs the same grid and in-plane region before heights are subtracted.
• Loss convention: reference height − current height; positive loss means the current surface is lower. Physical volume also needs the pixel spacing in both directions.
• Registration errors or inconsistent height units change wear results.
• The README figures are repository examples with normalised heights, not thesis measurements.

7. Links

• Repository
• PyPI package truemapdata
• tests/core/test_tmd.py, the source of the usage example
• Documentation
• Binary format guide · Sequential wear analysis
• MistubaVideo renders the recorded surface fields this tooling measures

flowchart LR
  subgraph wf0["Build"]
    direction LR
    wf0_build["build<br/>ubuntu-latest"]
  end
  subgraph wf1["Dependabot Auto-Merge"]
    direction LR
    wf1_dependabot["dependabot<br/>ubuntu-latest"]
  end
  subgraph wf2["Dependency submission"]
    direction LR
    wf2_dependency_submission["dependency-submission<br/>ubuntu-latest"]
  end
  subgraph wf3["Documentation"]
    direction LR
    wf3_build[["build<br/>ubuntu-latest"]]
    wf3_deploy[["deploy<br/>ubuntu-latest"]]
  end
  subgraph wf4["Release and publish"]
    direction LR
    wf4_test[["test<br/>ubuntu-latest"]]
    wf4_release_and_pypi[["release-and-pypi<br/>ubuntu-latest"]]
  end
  subgraph wf5["Ruff"]
    direction LR
    wf5_ruff["ruff<br/>ubuntu-latest"]
  end
  t0(["push · pull request"])
  t1(["pull request"])
  t2(["push · pull request · manual run"])
  t3(["manual run"])
  d0[("GitHub Pages")]
  d1[("PyPI")]
  d2[("GitHub Releases")]
  t0 --> wf0_build
  t1 --> wf1_dependabot
  t2 --> wf2_dependency_submission
  t0 --> wf3_build
  wf3_build --> wf3_deploy
  wf3_deploy -.-> d0
  t3 --> wf4_test
  wf4_test --> wf4_release_and_pypi
  wf4_release_and_pypi -.-> d1
  wf4_release_and_pypi -.-> d2
  t0 --> wf5_ruff

flowchart LR
  repo[("GitHub repository")]
  ci[["GitHub Actions<br/>7 workflows"]]
  pub_GitHub_Pages[("GitHub Pages")]
  pub_PyPI[("PyPI")]
  pub_GitHub_Releases[("GitHub Releases")]
  host_MkDocs_site("Documentation site (MkDocs)<br/>mkdocs.yml")
  repo -->|"push or pull request"| ci
  ci -->|"publishes"| pub_GitHub_Pages
  ci -->|"publishes"| pub_PyPI
  ci -->|"publishes"| pub_GitHub_Releases
  ci -.->|"configured"| host_MkDocs_site