Metadata-Version: 2.2
Name: truemapdata
Version: 0.1.2
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/yourusername/tmd
Project-URL: Bug Tracker, https://github.com/yourusername/tmd/issues
Project-URL: Documentation, https://yourusername.github.io/tmd
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
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: full
Requires-Dist: tmd[dev,docs]; extra == "full"

# TrueMap & GelSight TMD Processor

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.

![TMD Processor Logo](image.svg)

---

## 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)
- [License](#license)

---

## Features

- **Rich Visualizations:**
  - Interactive 3D surface plots with adjustable Z-scale
  - 2D heatmaps using Plotly, Matplotlib, or Seaborn
  - X-profile cross-section plots
- **Multiple Export Formats:**
  - Displacement maps (grayscale PNG)
  - Normal maps (RGB PNG)
  - Bump maps with adjustable parameters
  - Ambient Occlusion (AO) maps
  - BSRF (Bidirectional Scattering Reflection Function) maps
  - Multi-channel maps (RGBE, RG formats)
  - STL files for 3D printing (ASCII or binary)
  - NumPy data formats (.npy, .npz)
---

Height Map Statistics
====================
Shape: (200, 200)
Min: 0.0
Max: 1.0
Mean: 0.4120621979236603
Std Dev: 0.188633993268013

![height_map_3d_matplotlib](https://github.com/user-attachments/assets/faa4db7d-62ee-47e9-8883-4b8d4af13eb9)
![x_cross_section](https://github.com/user-attachments/assets/fcf95e3c-5810-4dfd-93f0-06e98297490b)
![displacement_map](https://github.com/user-attachments/assets/0a89659c-5af0-4a53-969b-9a96f04dac0a)
![profile_75_percent](https://github.com/user-attachments/assets/d48e4158-76ba-42fa-8399-7ceb60241925)
![image](https://github.com/user-attachments/assets/885b363a-10da-44b8-a574-bcd4848c2837)

![image](https://github.com/user-attachments/assets/f00dcec9-6a2c-4080-b643-cb42ee5f3193)

![image](https://github.com/user-attachments/assets/2cb7d052-6b63-4435-af7b-04becaf1a594)
![image](https://github.com/user-attachments/assets/f4a4b855-cf83-4971-ad15-f393fb52e03b)


## Installation

### Quick Install

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.
