Skip to content

README.md

Latest commit

 

History

History
192 lines (130 loc) · 10.4 KB

README.md

File metadata and controls

192 lines (130 loc) · 10.4 KB

TMD Library: TrueMap Data Processing & Visualization

PyPI version PyPI - Python Version PyPI - Downloads License Documentation

Python library and tmd-process CLI for TrueMap v6 and GelSight .tmd height maps: binary I/O, filters and transforms, visualization, derived maps (normal, displacement, bump, hillshade, ambient occlusion, tribology proxy maps, and related generators), defect detection, multi-frame sequences (GIF, video, PowerPoint), compression helpers, synthetic terrain for fixtures, and mesh export including apply-on-mesh OBJ/MTL bundles with tiling from template bounds and TMD metadata.

Areal ISO 25178 roughness uses the optional truemapdata[roughness] extra, which installs Surfalize under GPL-3.0 (see pyproject.toml; it is intentionally not part of the permissive full extra).

Typical users: tribology and surface metrology, lab pipelines that need NumPy height arrays, and graphics workflows that want measured displacement or normal maps.

TMD Processor Logo

Table of contents

Features

Feature Description
Visualizations 3D surfaces, 2D heatmaps, profiles via matplotlib, plotly, and seaborn; optional Polyscope in the advanced extra
Map export maps CLI and library generators: normal, displacement, bump, hillshade, ambient occlusion, parallax-style stacks, roughness-style textures, and related outputs
Meshes STL, OBJ, PLY, glTF, USD; optional mesh extra for trimesh, pygltflib, and numpy-stl
Apply-on-mesh Bundle height-derived textures onto a template OBJ/MTL with physically motivated tiling from template span, mm_per_pixel, and capture size metadata (see the CLI reference)
Sequences sequence commands align and crop stacks, with exporters for GIF, video, and PowerPoint (OpenCV-backed)
Defects defect commands for pits, peaks, scratches, cracks, and directionality-style anomalies
Roughness roughness subcommands for ISO 25178 areal metrics via optional Surfalize (truemapdata[roughness]; GPL-3.0, not bundled in full)
Tribology tribology CLI and tmd.surface.metrics helpers: preferred texture axis, bearing-style contact curve, tribology plot PNG dashboard, shear/debris/summit map types; lubrication ISO volumes via Surfalize subcommand
Wear toolkit tmd-process wear (also installed as tmd-wear) for Abbott / bearing curves, wear volume series, hazard maps, debris-pocket scores, scratch evolution, slip axis, and roughness trajectories on aligned sequences
Compression compress subcommands for npy, npz, zip, mat, and pickle-oriented workflows
Terrain terrain CLI and TMDTerrain helpers for synthetic heightmaps used in tests and demos
Formats TrueMap v6-style TMD (v2) and legacy v1; GelSight-compatible layouts
Python 3.8+ (requires-python in pyproject.toml); optional groups viz, mesh, advanced, dev, and docs are listed there

Documentation

Full guides, developer notes, and the CLI reference live on GitHub Pages (same URL as pyproject.toml [project.urls] Documentation).

Section What you will find
User guide Install, getting started, TMD binary layout, visualization, export, tribology metrics, sequential wear analysis
CLI reference Command tables, mesh and apply-on-mesh notes, defect defaults
Developers Contributing, building docs, doc style, optional MCP tooling

Installation

From PyPI:

pip install truemapdata

Optional dependency groups (see pyproject.toml for pins and Python version gates):

pip install "truemapdata[mesh,viz,advanced]"
pip install "truemapdata[roughness]"   # Surfalize (GPL-3.0); Python 3.10+ only

From a git checkout:

pip install -r requirements.txt
pip install -e .

The console entry point is tmd-process. From the repository you can also run python tmd_cli.py.

Usage

from tmd import TMD

data = TMD.load("path/to/your/file.tmd")
height_map = data.height_map
metadata = data.metadata

Use a real .tmd from your instrument or pipeline; no sample .tmd files are committed to this repository (size, licensing). You can generate synthetic terrain for tests via TMDTerrain / the terrain CLI.

CLI

Entry points: tmd-process (full toolkit) and tmd-wear (wear-oriented subset; same flags as tmd-process wear). From a repository checkout you can also run python tmd_cli.py. Global help: tmd-process --help. Embedded examples: tmd-process visualize examples.

Top-level groups include config, cache, compress, maps, mesh, sequence, roughness, tribology, wear, defect, visualize, and terrain, plus info, version, and check.

The CLI reference lists flags, maps / mesh details, apply-on-mesh tiling notes, defect defaults, and the full tribology and wear subcommand tables. For aligned stacks, volume series, slip axis, and scratch evolution, see Sequential wear analysis. Use --help on each subcommand for the live flag list.

TMD file format

The canonical byte layout, version 1 vs 2, GelSight quirks, and endianness are documented under Working with TMD files on the doc site (tables and diagrams). At a glance: v2 uses a fixed header plus float32 heights in row-major order (height, width); v1 is a shorter header with the same raster layout.

Sample data

Examples in docs and tests use paths like path/to/file.tmd or synthetic heightmaps. The repository includes tracked .tmd fixtures at the canonical paths used by tests/cli/test_example_tmds_smoke.py and notebooks (examples/gelsight/circle_0mm_…, examples/v1/Dime.tmd, examples/v2/Dime.tmd), plus a grid-matched second frame for wear-volume smoke tests under tests/fixtures/gelsight_wear_volume_second_frame.tmd. Other .tmd files under examples/ remain gitignored so you can drop in large or proprietary captures locally without committing them.

Try wear metrics on the shipped fixtures, for example:

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

Visual examples

Height map statistics (illustrative)

Metric Value
Shape (200, 200)
Min 0.0
Max 1.0
Mean 0.41206
Std Dev 0.18863

Image gallery

3D surface X profile
Displacement Y profile
STL 3D crop
Plotly HeightMap
Bump maps Smoothing

GelSight sequence visualization

python visualize_gelsight_sequence.py --show
python visualize_gelsight_sequence.py --files path/to/a.tmd path/to/b.tmd --format 3d --z-scale 1.5 2.0 --show

Contributing

See CONTRIBUTING.md for local setup, tests, Ruff, docs, and how to use the GitHub issue and PR templates. Report security issues privately as described in SECURITY.md. For a reproducible editor environment, use the Dev Container definition in .devcontainer/devcontainer.json.

License

This project is licensed under the MIT License. See the LICENSE file for details.