TrueMapData

1. Aperçu

Pourquoi il existe. Une même représentation de surface qui sert à la métrologie et aux ressources graphiques comme les cartes de déplacement ou les maillages.

Cas d’usage. Inspecter des surfaces mesurées, comparer des captures dans le temps (usure) et exporter cartes de normales, cartes de déplacement ou maillages en conservant l’échelle physique.

3. Démarrage

Paquet. TrueMapData est publié sur PyPI sous le nom truemapdata (licence MIT, Python 3.8 ou plus récent). La dernière version sur PyPI est la 1.0.5 ; le pyproject.toml du dépôt en est déjà à 1.0.6. Il n’existe pas de paquet .NET ni NuGet : la bibliothèque est uniquement en Python, et le nom d’import est tmd.

pip install truemapdata

Les extras ajoutent des fonctions optionnelles. Chacun est déclaré dans pyproject.toml :

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

Le paquet installe deux commandes, tmd-process (la boîte à outils complète) et tmd-wear (le sous-ensemble consacré à l’usure).

Un premier script. Cet exemple suit tests/core/test_tmd.py et fonctionne donc sans fichier de capture : il construit une carte de hauteurs en mémoire, l’enregistre au format TMD v2, la relit et l’examine.

import numpy as np
from tmd import TMD

# Une grille de 200 x 200 hauteurs, 0,05 mm entre deux points
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 par défaut, renvoie le chemin .tmd

loaded = TMD.load(path)
print(loaded.shape)                              # (200, 200)
print(loaded.dimensions)                         # largeur et hauteur physiques : 10,0 x 10,0
print(loaded.stats["min"], loaded.stats["max"])  # calculées au premier accès

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

TMD.load lève FileNotFoundError ou TMDProcessingError si le fichier manque, et dimensions multiplie la taille de la grille par resolution_x et resolution_y tirés des métadonnées (1,0 s’ils sont absents). Avec une vraie capture, remplacez la grille synthétique par TMD.load("capture.tmd"). Le dépôt suit des captures d’exemple pour cela : des fichiers TrueMap dans examples/v1/ et examples/v2/ (une pièce de dix cents, une marche, des pièces de monnaie, du papier et, en v2, un marquage laser et une empreinte Vickers) et trois captures GelSight dans examples/gelsight/, prises après 0, 150 et 300 mm de glissement sous 100 g.

En ligne de commande. Les exemples d’usure du README tournent sur ces fichiers :

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

La première commande d’usure affiche la courbe de portance (Abbott–Firestone) d’une capture ; la seconde compare des captures de même grille et donne la perte par rapport à la première (z_ref - z_i, positive là où la surface a baissé).

4. Fonctions et composants

5. Architecture

flowchart TB
  Capture["Capture TrueMap ou GelSight"] --> Read["Grille de hauteurs et métadonnées spatiales"]
  Read --> Inspect["Carte de chaleur, profil ou surface 3D"]
  Inspect --> Metrics["Rugosité et métriques de surface"]
  Inspect --> Maps["Cartes de normales et de déplacement"]
  Inspect --> Mesh["Export de maillage et texturage de gabarit"]

6. Limites et points à vérifier

• La rugosité décrit une capture ; l’usure compare des captures dans le temps et exige la même grille et la même région dans le plan avant de soustraire les hauteurs.
• Convention de perte : hauteur de référence − hauteur courante ; une perte positive signifie une surface courante plus basse. Le volume physique demande aussi l’espacement des pixels dans les deux directions.
• Des erreurs de recalage ou des unités de hauteur incohérentes changent les résultats d’usure.
• Les figures du README sont des exemples du dépôt avec des hauteurs normalisées, pas des mesures du mémoire.

7. Liens

• Dépôt
• Paquet PyPI truemapdata
• tests/core/test_tmd.py, source de l’exemple d’utilisation
• Documentation
• Guide du format binaire · Analyse séquentielle de l’usure
• MistubaVideo rend les champs de surface enregistrés que cet outillage mesure

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 · demande de fusion"])
  t1(["demande de fusion"])
  t2(["push · demande de fusion · lancement manuel"])
  t3(["lancement manuel"])
  d0[("GitHub Pages")]
  d1[("PyPI")]
  d2[("Versions GitHub")]
  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[("Dépôt GitHub")]
  ci[["GitHub Actions<br/>7 workflows"]]
  pub_GitHub_Pages[("GitHub Pages")]
  pub_PyPI[("PyPI")]
  pub_GitHub_Releases[("Versions GitHub")]
  host_MkDocs_site("Site de documentation (MkDocs)<br/>mkdocs.yml")
  repo -->|"push ou demande de fusion"| ci
  ci -->|"publie"| pub_GitHub_Pages
  ci -->|"publie"| pub_PyPI
  ci -->|"publie"| pub_GitHub_Releases
  ci -.->|"configuré"| host_MkDocs_site