truemapdata 0.1.3

A library for processing TMD files and visualizing height maps

TMD Library: TrueMap Data Processing & Visualization

A Python-based TMD file processor with visualization and export capabilities for height maps stored in TMD files generated by TrueMap v6 or GelSight. The tool includes comprehensive features for data processing, visualization, and export to various formats.

---

Table of Contents

• Features
• Installation
• Usage
• TMD File Format
  • TrueMap v6 Format
  • GelSight Format
• Visual Examples
• License

---

Features

Feature	Description
Rich Visualizations	Interactive 3D surface plots, 2D heatmaps, X-profile cross-section plots
Multiple Export Formats	Displacement maps (PNG), Normal maps (RGB PNG), STL files, NumPy data formats, etc.
Supported TMD Formats	TrueMap v6 & GelSight
Python Compatibility	Works with Python 3.12+

---

Installation

Ensure you have Python 3.12+ installed, then install dependencies:

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

---

Usage

from tmd import TMD
data = TMD('Dime.tmd')
height_map = data.height_map()
metadata = data.metadata()
data.plot_3D()

Run the provided Jupyter Notebook for step-by-step examples.

---

TMD File Format

TrueMap v6 Format

Field	Description
Header (32 bytes)	"Binary TrueMap Data File v2.0"
Comment (Variable)	Typically: "Created by TrueMap v6"
Dimensions (8 bytes)	Two 32-bit unsigned integers for width & height
Spatial Info (16 bytes)	Floats representing x_length, y_length, x_offset, y_offset
Height Map Data	Float32 array forming a height x width 2D grid

GelSight Format

Field	Description
Header (32 bytes)	Same as TrueMap: "Binary TrueMap Data File v2.0"
Comment (Variable)	May contain metadata or be empty
Dimensions (8 bytes)	Two 32-bit unsigned integers (width & height)
Spatial Info (16 bytes)	Four 32-bit floats for x_length, y_length, x_offset, y_offset
Height Map Data	Float32 array defining the height map

---

Visual Examples

1. Height Map Statistics

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

Image Visualizations

3D Surface Plot	X-Cross Section

Displacement Map	Y-Cross Section 75%

STL File	3D Crop

Plotly Visualisation	HeightMap

Bump maps	SmoothingHeightMap

Installation

Quick Install

pip install truemapdata

Ensure you have Python 3.12+ installed. Then, install the required packages:

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

from tmd import TMD
data = TMD('Dime.tmd')
height_map = data.height_map()
metadata = data.metadata()
data.plot_3D()

You can also run the provided Jupyter Notebook to see step-by-step examples.

---

TMD File Format

The TMD files processed by this tool follow a binary layout with similar structures for both TrueMap v6 and GelSight versions. The main difference lies in the comment field and the typical source of the file.

TrueMap v6 Format

1. Header (32 bytes): An ASCII string that starts with: Binary TrueMap Data File v2.0

2. Comment (Variable, up to 256 bytes): A null-terminated string, typically: Created by TrueMap v6

3. Dimensions (8 bytes): Two 32-bit unsigned integers for width and height (little-endian).

4. Spatial Information (16 bytes): Four 32-bit floats representing:

   • x_length (physical length in X)
   • y_length (physical length in Y)
   • x_offset
   • y_offset

5. Height Map Data: A sequence of 32-bit floats (4 bytes each) forming a 2D array with dimensions height x width.

GelSight Format

The GelSight TMD file format is very similar to the TrueMap v6 format with subtle differences:

1. Header (32 bytes): The header string is the same: Binary TrueMap Data File v2.0

2. Comment (Variable): A null-terminated string that may be empty or contain different metadata.

3. Dimensions (8 bytes): Two 32-bit unsigned integers for width and height (little-endian).

4. Spatial Information (16 bytes): Four 32-bit floats for:

   • x_length
   • y_length
   • x_offset
   • y_offset

5. Height Map Data: A float32 array representing the height values over a grid defined by the width and height.

The processor uses the file name (or structure hints) to choose the appropriate parser for TrueMap v6 or GelSight TMD files.

---

License

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