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.
| 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+ |
Ensure you have Python 3.12+ installed, then install dependencies:
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()Run the provided Jupyter Notebook for step-by-step examples.
| 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 |
| 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 |
| Metric | Value |
|---|---|
| Shape | (200, 200) |
| Min | 0.0 |
| Max | 1.0 |
| Mean | 0.41206 |
| Std Dev | 0.18863 |
| 3D Surface Plot | X-Cross Section |
|---|---|
 |
 |
| Displacement Map | Y-Cross Section 75% |
|---|---|
 |
 |
| STL File | 3D Crop |
|---|---|
 |
 |
| Plotly Visualisation | HeightMap |
|---|---|
 |
 |
| Bump maps | SmoothingHeightMap |
|---|---|
 |
 |
pip install truemapdataEnsure 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.
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.
-
Header (32 bytes): An ASCII string that starts with:
Binary TrueMap Data File v2.0 -
Comment (Variable, up to 256 bytes): A null-terminated string, typically:
Created by TrueMap v6 -
Dimensions (8 bytes): Two 32-bit unsigned integers for width and height (little-endian).
-
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
-
Height Map Data: A sequence of 32-bit floats (4 bytes each) forming a 2D array with dimensions height x width.
The GelSight TMD file format is very similar to the TrueMap v6 format with subtle differences:
-
Header (32 bytes): The header string is the same:
Binary TrueMap Data File v2.0 -
Comment (Variable): A null-terminated string that may be empty or contain different metadata.
-
Dimensions (8 bytes): Two 32-bit unsigned integers for width and height (little-endian).
-
Spatial Information (16 bytes): Four 32-bit floats for:
- x_length
- y_length
- x_offset
- y_offset
-
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.
The repository includes a script to visualize GelSight sensor data as a sequence:
# Run with default GelSight files
python visualize_gelsight_sequence.py --show
# Specify custom TMD files and visualization options
python visualize_gelsight_sequence.py --files path/to/file1.tmd path/to/file2.tmd --format 3d --z-scale 1.5 2.0 --showThis creates interactive visualizations including:
- 3D surface plots with a time slider
- Animations of changes between frames
- Statistical analysis of the sequence
- Difference maps between consecutive frames
This project is licensed under the MIT License. See the LICENSE file for details.