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

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








## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "truemapdata",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Antoine Boucher <antoine@antoineboucher.info>",
"keywords": "tmd, heightmap, 3d, visualization, truemap, gelsight",
"author": null,
"author_email": "Antoine Boucher <antoine@antoineboucher.info>",
"download_url": "https://files.pythonhosted.org/packages/32/7d/9cd187afb19225a921c6850c316400693922ccc1f87968249c0f0be22458/truemapdata-0.1.1.tar.gz",
"platform": null,
"description": "# TrueMap & GelSight TMD Processor\n\nA Python-based TMD file processor with visualization and export capabilities for height maps stored in TMD files generated by\n**TrueMap v6** or **GelSight**. The tool includes comprehensive features for data processing, visualization, and export to various formats.\n\n\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [TMD File Format](#tmd-file-format)\n - [TrueMap v6 Format](#truemap-v6-format)\n - [GelSight Format](#gelsight-format)\n- [License](#license)\n\n---\n\n## Features\n\n- **Rich Visualizations:**\n - Interactive 3D surface plots with adjustable Z-scale\n - 2D heatmaps using Plotly, Matplotlib, or Seaborn\n - X-profile cross-section plots\n- **Multiple Export Formats:**\n - Displacement maps (grayscale PNG)\n - Normal maps (RGB PNG)\n - Bump maps with adjustable parameters\n - Ambient Occlusion (AO) maps\n - BSRF (Bidirectional Scattering Reflection Function) maps\n - Multi-channel maps (RGBE, RG formats)\n - STL files for 3D printing (ASCII or binary)\n - NumPy data formats (.npy, .npz)\n---\n\nHeight Map Statistics\n====================\nShape: (200, 200)\nMin: 0.0\nMax: 1.0\nMean: 0.4120621979236603\nStd Dev: 0.188633993268013\n\n\n\n\n\n\n\n\n\n\n\n\n\n## Installation\n\n### Quick Install\n\nEnsure you have Python 3.12+ installed. Then, install the required packages:\n\n```bash\npip install numpy plotly pillow\n```\n\nYou can also run the provided Jupyter Notebook to see step-by-step examples.\n\n---\n\n## TMD File Format\n\nThe 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.\n\n### TrueMap v6 Format\n\n1. **Header (32 bytes):**\n An ASCII string that starts with:\n `Binary TrueMap Data File v2.0`\n\n2. **Comment (Variable, up to 256 bytes):**\n A null-terminated string, typically:\n `Created by TrueMap v6`\n\n3. **Dimensions (8 bytes):**\n Two 32-bit unsigned integers for **width** and **height** (little-endian).\n\n4. **Spatial Information (16 bytes):**\n Four 32-bit floats representing:\n - **x_length** (physical length in X)\n - **y_length** (physical length in Y)\n - **x_offset**\n - **y_offset**\n\n5. **Height Map Data:**\n A sequence of 32-bit floats (4 bytes each) forming a 2D array with dimensions **height x width**.\n\n### GelSight Format\n\nThe GelSight TMD file format is very similar to the TrueMap v6 format with subtle differences:\n\n1. **Header (32 bytes):**\n The header string is the same:\n `Binary TrueMap Data File v2.0`\n\n2. **Comment (Variable):**\n A null-terminated string that may be empty or contain different metadata.\n\n3. **Dimensions (8 bytes):**\n Two 32-bit unsigned integers for **width** and **height** (little-endian).\n\n4. **Spatial Information (16 bytes):**\n Four 32-bit floats for:\n - **x_length**\n - **y_length**\n - **x_offset**\n - **y_offset**\n\n5. **Height Map Data:**\n A float32 array representing the height values over a grid defined by the width and height.\n\nThe processor uses the file name (or structure hints) to choose the appropriate parser for TrueMap v6 or GelSight TMD files.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library for processing TMD files and visualizing height maps",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/yourusername/tmd/issues",
"Documentation": "https://yourusername.github.io/tmd",
"Homepage": "https://github.com/yourusername/tmd"
},
"split_keywords": [
"tmd",
" heightmap",
" 3d",
" visualization",
" truemap",
" gelsight"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "38750bfe101e2556fcf09c4dab96e2c2a464b82cf1861b78d3f761a8abb2b8e5",
"md5": "fd7b1abff80635fb7742279258f8aab0",
"sha256": "f3a19d3d5d991960a42176542d2692087d179ee206961083830ef734fa25910f"
},
"downloads": -1,
"filename": "truemapdata-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd7b1abff80635fb7742279258f8aab0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7746,
"upload_time": "2025-03-11T02:17:41",
"upload_time_iso_8601": "2025-03-11T02:17:41.209506Z",
"url": "https://files.pythonhosted.org/packages/38/75/0bfe101e2556fcf09c4dab96e2c2a464b82cf1861b78d3f761a8abb2b8e5/truemapdata-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "327d9cd187afb19225a921c6850c316400693922ccc1f87968249c0f0be22458",
"md5": "6e13b46aeb61ec16a3dd9049e3fce59e",
"sha256": "5ed271301385c3fb06aab046b96044d496e6e0492b2b32ac83bb395c76bcf472"
},
"downloads": -1,
"filename": "truemapdata-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6e13b46aeb61ec16a3dd9049e3fce59e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25861,
"upload_time": "2025-03-11T02:17:42",
"upload_time_iso_8601": "2025-03-11T02:17:42.411764Z",
"url": "https://files.pythonhosted.org/packages/32/7d/9cd187afb19225a921c6850c316400693922ccc1f87968249c0f0be22458/truemapdata-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-11 02:17:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "tmd",
"github_not_found": true,
"lcname": "truemapdata"
}