Metadata-Version: 2.2
Name: truemapdata
Version: 0.1.0.post0
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 License
        
        Copyright (c) 2025 ETSTribology
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/yourusername/tmd-processor
Project-URL: Bug Tracker, https://github.com/yourusername/tmd-processor/issues
Project-URL: Documentation, https://yourusername.github.io/tmd-processor
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"
Provides-Extra: full
Requires-Dist: tmd-processor[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 numpy plotly pillow
```

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.
