Maintained Fork Available: Blender 4.2+ Compatibility || Now with Color And Orca/Bambu Support || Issues/Feature Requests Welcome#86
Open
Clonephaze wants to merge 64 commits intoGhostkeeper:masterfrom
Conversation
Refactored codebase for compatibility with Blender 4.2+, including import and export modules, annotations, constants, and metadata handling. Updated README with modernization notice, credits, and installation guidance. Improved reload logic, imports, and property annotation syntax. Added copyright for modernization work and enhanced code style consistency.
Deleted obsolete __init__ methods from Export3MF and Import3MF classes to streamline initialization. Added blender_manifest.toml for Blender 4.2+ compatibility and removed bl_info from __init__.py, transitioning metadata to the manifest file.
Major Issues Fixed -- Now works in 4.2+
Introduces integration tests for the Blender 3MF addon, including cross-platform runner scripts and documentation in test/README.md. Updates unit tests to use explicit imports, improves test initialization, and revises CI workflow to Python 3.11. Modernization checklist updated to reflect major milestone and test progress.
Updates documentation and test scripts for full compatibility with Blender 4.2+ and Python 3.11+. Adds multi-version integration test support, improves installation instructions, and documents comprehensive test coverage (142 unit tests, 16 integration tests). Modernization status and checklist are updated to reflect production readiness and CI/CD integration.
All major functions and methods in the 3MF addon have been annotated with type hints for improved code quality and IDE support. Updates include changes to __init__.py, annotations.py, constants.py, export_3mf.py, import_3mf.py, metadata.py, and unit_conversions.py. MODERNIZATION_CHECKLIST.md updated to reflect completion of type hinting and changelog for v1.1.0; manifest version bumped to 1.1.0.
Added __all__ definitions to all modules for improved IDE and documentation support. Replaced string concatenations with f-strings and updated error reporting to use self.report() for user feedback in export_3mf.py and import_3mf.py. Updated outdated comments and marked modernization checklist as complete for quality phase.
Introduces a safe_report method to both Export3MF and Import3MF classes to handle reporting messages in a way compatible with both Blender's operator system and unit tests. All direct calls to self.report are replaced with safe_report to improve robustness and testability.
Added W503 to the ignored pycodestyle errors in the test workflow to resolve conflicts with PEP8's recommendation to break before binary operators.
Corrected whitespace, indentation, and line breaks in export_3mf.py, import_3mf.py, and run_integration_tests.py for improved code readability and consistency. No functional changes were made.
Test Fixes, Integration Suite, Code Quality Enhancements, Doc Updates
Expanded and reorganized CHANGES.md to provide clearer feature, technical, and testing breakdowns for the Blender 3MF addon modernization. Deleted MODERNIZATION_CHECKLIST.md as the checklist is no longer needed after completion of modernization tasks.
Added checks to skip empty material slots when exporting 3MF files. This prevents errors when objects or triangles reference material slots without assigned materials. Fixes issue #4
Introduces a new 'tests/' directory with integration tests using the real Blender API, covering export, import, materials, archive structure, and edge cases. Includes test utilities, resources, and a test runner script. Updates legacy test README to clarify the distinction between legacy unit tests and new integration tests. Also fixes a line length error in `export_3mf.py`
Added BOM to the start of several Python files and normalized whitespace in io_mesh_3mf/export_3mf.py and all test files. This improves consistency and prevents issues with encoding or formatting in environments sensitive to BOM and whitespace.
Support non-standard scene scale / unit combinations. In particular, make sure the common scale=0.001 and unit=MILLIMETER combination is supported. In that case, blender units equal millimeters, and no scale changes are required for the scene on either import or export.
Make sub-objects more readable by setting the object name attribute. This makes them show up using the assigned name rather than the numerical IDs in applications like PrusaSlicer.
Handle per-object name attributes in the import path, giving precedence to the lowest level `Title` metadata or `name` attribute. Tested with exports from previous export path patch (round tripping), as well as prusa and 3mf reference objects.
Per subject. Still default to exporting visible objects only.
Float to decimal string conversion is a very hot export path. The format_number method previously tried to reduce the file size by stripping trailing zeroes and optional decimal point. In practice, I found this neither helped export times, nor exported file size after compression. In a moderately complex test file, I found the simpler method reduces compressed file size from 4mb to 3.6mb, and export time from about 9s to 8s.
Default to preserving 9 decimal places, which is lossless for 32 bit floats used in blender vertex coordinates. This avoids creating non-manifold edges / vertices in fine structures due to rounding errors. Better to have a safe / lossless default, while letting users reduce resolution for structures where full resolution is not needed. In my testing, the performance impact of full resolution is relatively minor, roughly canceling out what was gained with simplified / regularized number printing in the earlier diff.
Introduced standardized issue templates for bug reports and feature requests in the .github/ISSUE_TEMPLATE directory to streamline issue submission and improve project maintainability.
Introduces ThreeMFPreferences for user-configurable defaults in the 3MF addon, including coordinate precision, export hidden objects, apply modifiers, and global scale. Updates import and export operators to initialize properties from preferences. Adjusts unit scaling logic and test cases to match new behavior and formatting, and improves test robustness for floating point comparisons.
Refactored string formatting for property descriptions and test assertions to improve readability. Adjusted indentation in import_3mf.py for consistency. No functional changes were made.
Introduces a new preferences panel for the 3MF addon, allowing users to configure default coordinate precision, export of hidden objects, modifier application, and global scale. Enhances export functionality to notify users when hidden objects are skipped and adds comprehensive unit tests for preferences and hidden object export behavior. Updates documentation and test suite to reflect these new features and options.
Implements defensive string caching throughout the 3MF add-on to protect Unicode characters from Python's garbage collector, ensuring correct handling of non-ASCII characters in object names, material names, metadata, and file paths. Updates export and import logic to explicitly cache and convert strings, and adds a new Unicode test suite with 20+ tests for various scripts, emoji, and edge cases. Existing tests are updated for Unicode compatibility, and documentation is revised to reflect expanded Unicode support.
Introduce a pluggable 3MF extension system and vendor compatibility for Orca/BambuStudio. Key changes: - Add io_mesh_3mf/extensions.py (Extension, ExtensionManager, registry and helpers) and EXTENSIONS.md documentation. - Upgrade target 3MF spec to 1.3.0 and add constants for Materials, Production and Bambu namespaces plus OPC Core Properties (docProps/core.xml). - Export/import refactor to support Production and Materials extensions: added Orca multi-file export (per-object .model files with paint_color attributes), a dedicated Orca export codepath, and a standard export codepath. - Write OPC Core Properties (docProps/core.xml) and add Core Properties relationship/ MIME handling in annotations and constants. - Add preference to toggle importing materials and update README + blender_manifest.toml version. - Minor test adjustments (one test removed, another updated). Purpose: enable vendor-specific color-zone workflows (Orca/BambuStudio) while preserving core-spec compliance and providing an extensible mechanism for future 3MF extension support.
Remove unused imports (CORE_PROPERTIES_REL, CORE_PROPERTIES_MIMETYPE, MATERIALS_EXTENSION) from io_mesh_3mf.export_3mf, replace unnecessary f-string usage when setting XML namespace attributes with plain string literals for clarity, and simplify the import line in tests/unit/test_metadata.py by removing an inline comment. Minor cleanup to reduce noise and improve readability.
Add a new .github/copilot-instructions.md documenting the io_mesh_3mf Blender addon: project overview, architecture and file layout, import/export patterns, Orca Slicer/Production Extension export details (including paint color encoding), testing instructions, common coding patterns (namespaces, unicode safety, material color conversions), build/install steps, and key reference files. This guidance is intended for contributors and to help Copilot generate consistent code and tests for 3MF import/export functionality.
Clonephaze
changed the title
Introduce PrusaSlicer (slic3rpe) multi-material support and embed viewport thumbnails in exported 3MF files. - Add SLIC3RPE namespace constant and bump manifest version to 1.2.1. - Import: detect and handle multi-material attributes (Orca's paint_color and PrusaSlicer's slic3rpe:mmu_segmentation), create/lookup filament materials, and prefer paint attributes when available; keep graceful fallbacks for standard material references. - Export: add multi-material export preference and UI tweaks, default can be read from addon preferences; implement write_thumbnail() to render a 256×256 PNG from the viewport and embed it at Metadata/thumbnail.png (non-fatal on failure). - Annotations: add thumbnail relationship entry and register PNG MIME type for content types. - Import: avoid creating Blender objects for component-only resources (no mesh) to prevent empty objects; preserve component recursion behavior. - Docs: update README and tests README to document slicer compatibility, thumbnail feature, installation, and testing details. Thumbnail generation is optional and failures are logged but do not abort export. These changes improve cross-slicer compatibility (Orca/Bambu and PrusaSlicer) and add file preview support.
Add a new 3mfImportExport.png asset and update io_mesh_3mf/blender_manifest.toml to reflect the current maintainer and repository. The previous author field was removed, the website URL was updated to the Clonephaze repo, and the permissions key formatting was normalized to tidy the TOML metadata.
Bump io_mesh_3mf add-on version to 1.2.2, add a screenshot and thumbnail (3mfImportExportScreenshot.png, 3mfImportExportThumbnail.png), and update 3mfImportExport.png. Tidy blender_manifest.toml by adding tags = ["import-export"] and normalizing license/copyright fields.
Update repository to target 3MF Core Spec v1.4.0 (previously v1.3.0). Minor related edits were made to CHANGELOG.md, io_mesh_3mf/blender_manifest.toml, and io_mesh_3mf/constants.py to reflect the specification/version changes and keep metadata in sync.
Add full round-trip PrusaSlicer MMU export/import support and development roadmap. Changes include: - New ROADMAP.md documenting v1.2.4 features and priorities. - Bump addon version to 1.2.4 and update CHANGELOG/README with PrusaSlicer MMU notes and user-facing guidance. - Export: add mmu_slicer_format option (Orca/Prusa), progress messages, and execute_prusa_export path that writes mmu_segmentation attributes and a Metadata/blender_filament_colors.txt file for exact color round-trips. - Import: read Prusa filament colors from Metadata/blender_filament_colors.txt and use them when reconstructing materials. - Refactors and helpers: _finalize_export helper, write_prusa_filament_colors, _material_to_hex_color, _linear_to_srgb, srgb_to_linear, and adjustments to triangle/material handling to support both Orca and Prusa formats. - Minor UX: progress reports on import/export and improved logging. These changes enable accurate preservation of face colors between Blender and PrusaSlicer MMU workflows and consolidate exporter logic for multiple multi-material formats.
Add import/export validation and new import preferences: reuse existing materials, default import placement (Origin/Cursor/Keep), and origin-to-geometry option. Import: new properties, UI controls, invoke initialization from preferences, find_existing_material helper, reuse-or-create material logic, and placement/origin handling when linking objects. Export: validate selection contains mesh objects and added non-manifold geometry checker with user warning and logging. Update UI layout for import prefs, bump addon version to 1.2.5 in blender_manifest.toml, and clean up ROADMAP statuses/content accordingly.
Improve mesh validation in 3MF exporter by replacing the O(edges×faces) per-edge scan with a collections.Counter over polygon.edge_keys to count edge usage (detect edges used by != 2 faces). Replace loose-vertex detection by checking which vertices appear in polygons (faces) instead of scanning edges. These changes reduce complexity and make loose-vertex detection more accurate. Also remove an unused PRODUCTION_EXTENSION import and the unused combined_ns variable from the importer as a small cleanup.
Rework addon module reload behavior and bump addon version. - io_mesh_3mf/__init__.py: Simplify reload detection by using a _needs_reload flag before importing bpy, group import_3mf/export_3mf imports, and call importlib.reload when reloading is needed. Adds a reload confirmation print and preserves Export3MF/Import3MF class imports for registration. - 3mfImportExport.png: Update binary asset (icon/image) included in the addon. These changes improve clarity and correctness of the reload sequence when the add-on is reloaded within Blender and reflect the new release version.
Update README to clarify multi-material support: specify Orca/BambuStudio uses per-triangle multi-color zones,
* Delete EXTENSIONS.md * Refactor exporter; add PBR & triangle-sets Split the monolithic exporter into modular files and add new features: created export_formats.py and export_utils.py and refactored export_3mf.py to dispatch to format-specific exporters. Implemented full PBR Materials & Properties extension support and added Triangle Sets extension support (import/export) including a new preference and operator UI option. Bumped addon version (blender_manifest.toml → 1.2.7), updated README and CHANGELOG with release notes, and added a REFACTORING_GUIDE.md describing the refactor approach and test migration notes. Updated constants and tests to match the refactor, and added a .vscode settings file. * Delete settings.json * Pep 8
* Delete EXTENSIONS.md * Refactor exporter; add PBR & triangle-sets Split the monolithic exporter into modular files and add new features: created export_formats.py and export_utils.py and refactored export_3mf.py to dispatch to format-specific exporters. Implemented full PBR Materials & Properties extension support and added Triangle Sets extension support (import/export) including a new preference and operator UI option. Bumped addon version (blender_manifest.toml → 1.2.7), updated README and CHANGELOG with release notes, and added a REFACTORING_GUIDE.md describing the refactor approach and test migration notes. Updated constants and tests to match the refactor, and added a .vscode settings file. * Delete settings.json * Pep 8 * Add Materials Extension integration tests and samples Add comprehensive integration tests for the 3MF Materials Extension and accompanying sample files. Two new test modules were introduced: - tests/integration/test_materials_extension.py: a large suite of round-trip tests that verify preservation of all Materials Extension elements (colorgroup, texture2d, texture2dgroup, compositematerials, multiproperties, PB PBR and textured display properties, etc.), helper utilities for creating/extracting 3MF files, and minimal texture fixtures. - tests/integration/test_3mf_consortium_samples.py: integration tests that import/export official 3MF Consortium sample files and assert Materials Extension data is preserved. Also add a resources directory tests/resources/3mf_consortium containing official sample .3mf binaries, a BSD-2 license file, and a README describing the samples and a local namespace fix for two files (ms: -> m:) to enable testing. These tests improve real-world coverage and ensure compatibility with the 3MF spec. * Add tests for PBR and multiproperties materials Introduce tests that verify 3MF material extensions are applied to Blender Principled BSDF materials. Adds a reusable CUBE_MESH_WITH_MATERIAL fixture and a new TestActivePBRMaterials class that checks metallic/roughness values, per-base displayproperties overrides, and translucent properties (IOR/transmission). Also extends TestMultiproperties with a test ensuring multiproperties resolve to the underlying basematerial and that PBR display properties are applied. Helper _get_principled_node was added to locate Principled BSDF nodes in materials. * Add textured PBR tests; update importer init Add two integration tests for textured PBR materials that verify Image Texture nodes are created and connected to the Principled BSDF (metallic/roughness and group-level displaypropertiesid cases). Update unit tests to initialize new importer resource maps (resource_textures, resource_texture_groups, resource_composites, resource_multiproperties, resource_pbr_texture_displays, resource_colorgroups, resource_pbr_display_props) and adapt calls to read_triangles to unpack the added third return value. * Support Materials extension: PBR & textures Add full Materials Extension (v1.2.1) support including PBR (metallic/roughness/specular/translucent) and UV texture export. Update docs (README, ROADMAP) to reflect feature availability. Introduce texture relationship and MIME constants, skip preserving texture .rels on import, and write texture files into the 3MF archive with proper OPC relationships. Exporter changes detect PBR vs base-color-only textures, emit texture2d/texture2dgroup and pbmetallictexturedisplayproperties, and toggle the Materials extension as needed. Add many helpers in export_utils for detecting materials, saving textures, creating texture resources, deduplicating UV coords, and writing passthrough (round-trip) material data with ID remapping. Also minor adjustments: skip thumbnail generation in background and update write_materials return to include basematerials element.
Split the monolithic import/export material code into dedicated packages for better organization and maintainability. New packages: - io_mesh_3mf/export_materials (base, textures, pbr, passthrough) - io_mesh_3mf/import_materials (base, textures, pbr, passthrough) Also added standalone export_trianglesets.py and import_trianglesets.py, and reworked export_utils.py and import_3mf.py to use the new layout. CHANGELOG.md updated with a Code Organization entry and notes about backward-compatible re-exports to preserve the existing API. This refactor prepares the codebase for easier future enhancements and smaller, focused modules.
Rework the Installation section: add a recommended Blender 4.2+ workflow using the Official Blender Extensions Platform (with link and step-by-step Get Extensions instructions), replace the old review note, and clarify Manual Installation. Manual steps now instruct downloading the ZIP from Releases and either dragging the ZIP into Blender or using Edit → Preferences → Add-ons → Install…, and standardize the add-on enablement name to “3MF Import/Export”.
Enable drag-and-drop .3mf import and multi-file grid placement. Adds a FileHandler (ThreeMF_FH_import) so users can drop .3mf files into the 3D View/Outliner and registers it with the addon. Introduces a GRID import location with configurable grid spacing, and replaces the boolean origin option with an Origin Placement enum (KEEP/CENTER/BOTTOM) in both preferences and the Import3MF operator. The Import3MF UI now shows file count and conditional grid spacing, the operator tracks imported objects and applies a new _apply_grid_layout routine to arrange multiple imports in a roughly square grid, and origin handling includes a bottom-center placement. Also bumps addon version to 1.3.1 and updates CHANGELOG accordingly.
Replace Python-level edge counting with BMesh C-level manifold checks for faster detection and early exit on first offending object. export_utils.py: import bmesh, update check_non_manifold_geometry to use bm.from_mesh and edge.is_manifold / vert.is_manifold, free BMesh, stop after finding first non-manifold, and update docstring. export_3mf.py: adjust warning message to be more generic, add early-exit comment, and log only the first offending object name.
Introduce component/instance export+import to optimize repeated meshes (linked duplicates). Adds a new io_mesh_3mf/export_components.py module for detecting component groups and helpers, a use_components option (default True) in Export3MF and UI, and extends exporters to write component definitions and instance containers (_write_component_definition/_write_component_instance). Import logic is updated to reconstruct linked duplicates with caching, and integration tests (tests/integration/test_components.py) are added. Also bumps addon version to 1.3.2 and updates CHANGELOG and blender_manifest.toml.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
As of January 28th 2026 I've decided to start actively maintaining my own fork with no intention of the code ever going back up stream. The fork will begin making it's own decisions and adding in it's own features.
This PR is informational only - not intended for direct merging. I wanted to make you and the community aware that a modernized and maintained fork is available for users who need Blender 4.2+ support.