truemapdata 0.1.3
A library for processing TMD files and visualizing height maps
License: MIT
Requires Python: >=3.8
Keywords: tmd, heightmap, 3d, visualization, truemap, gelsight

# TMD Library: TrueMap Data Processing & Visualization

[![PyPI version](https://img.shields.io/pypi/v/truemapdata)](https://pypi.org/project/truemapdata/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/truemapdata)](https://pypi.org/project/truemapdata/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/truemapdata)](https://pypi.org/project/truemapdata/)
[![License](https://img.shields.io/github/license/ETSTribology/TrueMapData)](https://github.com/ETSTribology/TrueMapData/blob/main/LICENSE)
[![Documentation Status](https://img.shields.io/readthedocs/truemapdata)](https://truemapdata.readthedocs.io)

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.

<p align="center">
  <img src="https://raw.githubusercontent.com/ETSTribology/TrueMapData/refs/heads/main/image.svg" width="300" alt="TMD Processor Logo">
</p>

---

## **Table of Contents**

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [TMD File Format](#tmd-file-format)
  - [TrueMap v6 Format](#truemap-v6-format)
  - [GelSight Format](#gelsight-format)
- [Visual Examples](#visual-examples)
- [License](#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:

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

---

## **Usage**

```python
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** |
|---------------------|---------------------|
| <img src="https://github.com/user-attachments/assets/faa4db7d-62ee-47e9-8883-4b8d4af13eb9" width="400"> | <img src="https://github.com/user-attachments/assets/fcf95e3c-5810-4dfd-93f0-06e98297490b" width="400"> |

| **Displacement Map** | **Y-Cross Section 75%** |
|----------------------|--------------------|
| <img src="https://github.com/user-attachments/assets/0a89659c-5af0-4a53-969b-9a96f04dac0a" width="400"> | <img src="https://github.com/user-attachments/assets/d48e4158-76ba-42fa-8399-7ceb60241925" width="400"> |

| **STL File** | **3D Crop** |
|---------------|-------------------------|
| <img src="https://github.com/user-attachments/assets/885b363a-10da-44b8-a574-bcd4848c2837" width="400"> | <img src="https://github.com/user-attachments/assets/f00dcec9-6a2c-4080-b643-cb42ee5f3193" width="400"> |

| **Plotly Visualisation** | **HeightMap** |
|-------------|----------------------|
| <img src="https://github.com/user-attachments/assets/2cb7d052-6b63-4435-af7b-04becaf1a594" width="400"> | <img src="https://github.com/user-attachments/assets/f4a4b855-cf83-4971-ad15-f393fb52e03b" width="400"> |

| **Bump maps** | **SmoothingHeightMap** |
|-------------|----------------------|
| <img src="https://github.com/user-attachments/assets/cf1cc89a-0a35-4f6c-966c-22ea193e0a70" width="400"> | <img src="https://github.com/user-attachments/assets/d227f561-6d39-45fb-94eb-0a94d66fc948" width="400"> |

## Installation

### Quick Install


```bash
pip install truemapdata
```

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

```bash
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](LICENSE) file for details.