3MF Utility

A Python utility for working with 3MF (3D Manufacturing Format) files using the official Lib3MF library. This tool allows you to manage thumbnails and extract 3D models to STL format.

Features

Thumbnail Operations

• Extract existing thumbnails from 3MF files
• Replace existing thumbnails with new images
• Insert new thumbnails into 3MF files
• Check if a thumbnail exists in a 3MF file

STL Conversion

• Extract 3D models from 3MF files and convert to STL format
• Support for both binary and ASCII STL formats
• Automatic normal vector calculation for proper mesh orientation
• Handles multiple mesh objects within a single 3MF file

Requirements

• Python 3.7 or higher
• Lib3MF - Official 3D Manufacturing Format library

Installation

1. Clone or download this repository:

git clone <repository-url>
cd 3mfUpdater

2. Install dependencies:

pip install -r requirements.txt

This will install:

• lib3mf>=2.4.0 - Official Lib3MF Python bindings

Usage

Thumbnail Operations

Extract Thumbnail

Extract the thumbnail from a 3MF file and save it as an image:

python main.py extract input.3mf output.png

Replace Thumbnail

Replace the existing thumbnail in a 3MF file:

python main.py replace input.3mf new_thumbnail.png

Insert Thumbnail

Insert a new thumbnail into a 3MF file (same as replace):

python main.py insert input.3mf thumbnail.png

Check for Thumbnail

Check if a 3MF file contains a thumbnail:

python main.py check input.3mf

STL Conversion

Convert to ASCII STL (Default)

Extract the 3D model and save as an ASCII STL file:

python main.py stl input.3mf output.stl

Convert to Binary STL

Extract the 3D model and save as a binary STL file:

python main.py stl input.3mf output.stl --binary

Testing

A comprehensive test suite is included to verify all functionality.

Running Tests

Run the complete test suite:

python tests/test_3mf_operations.py

Test Coverage

The test suite includes 10 tests covering:

1. Thumbnail Extraction (2 tests)

   • Extract thumbnail from 3MF file
   • Check if thumbnail exists

2. Thumbnail Replacement (2 tests)

   • Replace existing thumbnail
   • Insert new thumbnail

3. STL Conversion (2 tests)

   • Extract to binary STL format
   • Extract to ASCII STL format

4. Error Handling (2 tests)

   • Handle non-existent 3MF files
   • Handle non-existent thumbnail files

5. File Integrity (2 tests)

   • Verify original test files remain unchanged
   • Verify 3MF files remain valid after modifications

Test Output

Test results are displayed with a summary showing all passed and failed tests:

================================================================================
TEST SUITE SUMMARY
================================================================================

Total Tests Run: 10
Passed: 10
Failed: 0

--------------------------------------------------------------------------------
PASSED TESTS:
--------------------------------------------------------------------------------
  [PASS] TestThumbnailExtraction.test_extract_thumbnail_exists
  [PASS] TestThumbnailExtraction.test_has_thumbnail
  ...
================================================================================

Test Files

• Test input files are located in tests/
  • asu-test-original.3mf - Sample 3MF file
  • asu-thumbnail.png - Sample thumbnail image
• All test outputs are saved to tests/test_output/ for inspection
• Original test files are never modified during testing

File Format Details

3MF Format

3MF (3D Manufacturing Format) is a ZIP-based archive format that contains:

• 3D/3dmodel.model - XML file with mesh data (vertices and triangles)
• 3D/Objects/*.model - External object files (optional)
• Metadata/thumbnail.png - Preview thumbnail image
• _rels/.rels - Relationships file defining connections between components

STL Format

The tool generates STL (STereoLithography) files in two formats:

• ASCII STL - Human-readable text format (default)
• Binary STL - Compact binary format (smaller file size)

API Usage

You can also use the classes directly in your Python code:

Thumbnail Management

from main import ThreeMFThumbnailManager

# Initialize manager
manager = ThreeMFThumbnailManager("model.3mf")

# Check for thumbnail
has_thumb = manager.has_thumbnail()

# Extract thumbnail
manager.extract_thumbnail("output.png")

# Replace thumbnail
manager.replace_thumbnail("new_thumbnail.png")

STL Conversion

from main import ThreeMFToSTLConverter

# Initialize converter
converter = ThreeMFToSTLConverter("model.3mf")

# Convert to ASCII STL (default)
converter.extract_to_stl("output.stl")

# Convert to binary STL
converter.extract_to_stl("output.stl", binary=True)

Technical Details

Library Used

This tool uses the official Lib3MF library from the 3MF Consortium, which provides:

• Robust 3MF file parsing and writing
• Full compliance with 3MF specification
• Support for all 3MF features including thumbnails, attachments, and metadata
• Cross-platform compatibility (Windows, Linux, macOS)

Thumbnail Management

• Thumbnails are managed using Lib3MF's package thumbnail API
• HasPackageThumbnailAttachment() checks for thumbnail existence
• GetPackageThumbnailAttachment() retrieves thumbnail data
• CreatePackageThumbnailAttachment() creates/replaces thumbnails
• Supports PNG format thumbnails
• Automatically handles 3MF package relationships

STL Conversion

• Uses Lib3MF's mesh object iterator to access all meshes
• Extracts vertices and triangles using GetVertex() and GetTriangle() methods
• Automatically detects and parses external object files (3D/Objects/*.model)
• Supports both inline meshes and external object references
• Calculates surface normals using cross product
• Supports multiple mesh objects in a single 3MF file
• Binary STL format follows standard 80-byte header + triangle data structure
• ASCII STL format uses standard solid/facet/vertex syntax
• Works with 3MF files from various slicer software (BambuStudio, PrusaSlicer, OrcaSlicer, etc.)

Error Handling

• All operations include error handling and informative error messages
• Validates file existence before operations
• Proper exception handling for library errors
• Test suite verifies error handling for edge cases

Limitations

• Thumbnail format is limited to PNG images
• STL conversion exports geometry only (no colors, materials, or textures)
• Multiple mesh objects are merged into a single STL output
• External object transformations (position, rotation, scale) are not applied during STL conversion

Examples

Complete Workflow

# Check if model has a thumbnail
python main.py check mymodel.3mf

# Extract existing thumbnail
python main.py extract mymodel.3mf current_thumb.png

# Replace with new thumbnail
python main.py replace mymodel.3mf better_thumbnail.png

# Convert to STL for editing
python main.py stl mymodel.3mf mymodel.stl

# Run tests to verify everything works
python tests/test_3mf_operations.py

Project Structure

3mfUpdater/
├── main.py                          # Main application with CLI
├── requirements.txt                 # Python dependencies (lib3mf)
├── README.md                        # This file
└── tests/
    ├── test_3mf_operations.py      # Comprehensive test suite
    ├── asu-test-original.3mf       # Test 3MF file (not modified)
    ├── asu-thumbnail.png           # Test thumbnail (not modified)
    └── test_output/                # Test output directory (generated)

License

This project is provided as-is for use with 3MF files.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

References

• Lib3MF Official Documentation
• 3MF Specification
• Lib3MF GitHub Repository

Donations

To support this project, you can make a donation to the current maintainer:

Paypal:

Cashapp: $MuadDibttv