Metadata-Version: 2.4
Name: truemapdata
Version: 0.1.3
Summary: A library for processing TMD files and visualizing height maps
Author-email: Antoine Boucher <antoine@antoineboucher.info>
Maintainer-email: Antoine Boucher <antoine@antoineboucher.info>
License: MIT
Project-URL: Homepage, https://github.com/ETSTribology/TrueMapData
Project-URL: Bug Tracker, https://github.com/ETSTribology/TrueMapData/issues
Project-URL: Documentation, https://etstribology.github.io/TrueMapData/
Keywords: tmd,heightmap,3d,visualization,truemap,gelsight
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: plotly>=5.10.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: scipy>=1.8.0
Requires-Dist: rich>=12.0.0
Requires-Dist: typer>=0.7.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: meshio>=5.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: tox>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings>=0.20.0; extra == "docs"
Requires-Dist: mkdocstrings-python>=1.0.0; extra == "docs"
Requires-Dist: pymdown-extensions>=9.0; extra == "docs"
Requires-Dist: pygments>=2.13.0; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.0.0; extra == "docs"
Provides-Extra: viz
Requires-Dist: pyvista>=0.37.0; extra == "viz"
Provides-Extra: full
Requires-Dist: truemapdata[dev,docs,viz]; extra == "full"
Dynamic: license-file

# 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.
