Maintained Fork (4.2+)|| Now on the Blender Extensions Platform || Now with full Paint Support for Orca/Bambu and Prusa/Super || Issues/Feature Requests Welcome#86
Open
Clonephaze wants to merge 135 commits into
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.
Generate Slic3r_PE_model.config during 3MF export when none is stashed: add material->extruder mapping using object materials and triangle counts (new _generate_model_config in prusa.py) and import material_to_hex_color. Ensure generated config is written into the archive and log debug messages. Fix UV iteration bug in segmentation (use consistent loop variable for uv access). Bump addon version to 2.4.1 and apply minor formatting/import ordering cleanups in paint package and quantize file. This fixes #24
Preserve original texture paths when available (round-trip) and fall back to sanitized filenames otherwise. Only add a default .png content type if no more specific content type was recorded to avoid overriding imported types. Namespace-qualify relationship attributes and write the rels XML with a default namespace to avoid ns0: prefixes. Accumulate texture relationships across PBR, standard, and passthrough pipelines and write them once at the end to prevent each pass from overwriting the rels file. Found thanks to #25, hadn't realized a spec difference that was leading to this tool's 3mf files being rejected by tools needing spec compliance.
Add coverage for texture packaging and relationship serialization. - Add integration test (tests/integration/test_3mf_consortium_samples.py) to verify sphere_logo.3mf roundtrip preserves the 3MF texture OPC content type, includes texture files, writes 3D/_rels/3dmodel.model.rels, avoids ns0: prefixes, and ensures rel targets exist in the archive. - Extend unit tests (tests/unit/test_annotations.py) to exercise Annotations.write_content_types() behavior: preserve the 3MF texture content type for .png, default to image/png when no annotations exist, ensure valid XML, and avoid ns0: prefixes. Also add required imports. - Add new unit tests (tests/unit/test_texture_rels.py) for write_texture_relationships() covering namespace declarations, absence of ns0: prefixes, valid XML, correct Relationship elements (Type, Target, Id uniqueness), empty-dict behavior, path preservation, and ensuring the global ElementTree namespace registry is not mutated. These tests catch and prevent regressions around OPC content types, texture relationships, namespace handling, and archive entry targets.
Add changelog entry for v2.4.2 describing fixes to 3MF texture export (OPC content-type correctness, texture path preservation, accumulating texture relationships, and namespace prefix serialization) and new tests covering relationship and content-type behavior. Also bump io_mesh_3mf/blender_manifest.toml version to 2.4.2.
Introduce a new export option `flatten_hierarchy` (API bump to 1.1.0) and propagate it to operator UI, ExportOptions, and exporter logic to write child meshes as top-level build items. Improve 3MF spec compliance: skip faceless mesh objects and objects producing no triangles, add OPC texture content type constant and default .png/.jpg/.jpeg mapping, set model root attributes (`unit="millimeter"`, `xml:lang="en-US"`), remove duplicate core property xmlns declarations, and ensure proper namespace prefix registration and required-extensions declaration. Misc: rename texture archive folder to `3D/Textures`, remove unused basematerials when all faces use textures, and add related warnings/logging. Unit tests updated to reflect content type and extension prefix behavior. Officially fixes #25
Bump API_VERSION patch to 1.1.1 and ensure explicit object lists are exported correctly by bypassing visibility and render-disable filters (set options.export_hidden and options.include_disabled when caller provides objects). Also add a [Content_Types].xml Override for /Metadata/thumbnail.png when the .png default MIME type isn't image/png so Windows Explorer's OPC thumbnail handler recognises the thumbnail as image/png.
Forward export_hidden/include_disabled through collection and detection code: collect_face_colors and detect_linked_duplicates now accept export_hidden/include_disabled and callers (orca, prusa, standard, and api non-manifold check) pass ctx.options values. Bump addon version to 2.4.4 and update CHANGELOG. Add integration tests covering include_disabled export behavior, component detection, API explicit-object exports, and thumbnail OPC content-type override.
Replace multipletextures.3mf with sphere_logo.3mf in the multipletextures test to avoid Blender headless hanging during roundtrip (multipletextures.3mf is ~2 MB). Update the test docstring to explain the change; sphere_logo.3mf covers the same Materials Extension elements and keeps expected_elements=['texture2d','texture2dgroup'].
Import and export support for Orca/BambuStudio modifier part subtypes (normal_part, modifier_part, support_enforcer, support_blocker, negative_part). Reads/writes part subtype and per-object/per-part slicer overrides from Metadata/model_settings.config, preserves wrapper->part hierarchy (creates Empty parents for multi-part assemblies), and round-trips settings via custom properties (3mf_part_subtype, 3mf_orca_settings, 3mf_orca_wrapper_settings). Non-normal parts no longer get paint/segmentation data on Orca export; viewport-coloured shared materials are applied for modifier/support/negative parts. Adds API capability and bumps API_VERSION to 1.2.0 with inspect_3mf returning part_subtypes, updates docs and changelog, increments addon manifest version, and adds integration tests plus sample 3mf resources. Also includes helper utilities for reading/writing stashed settings and prevents part ID collisions by using composite (wrapper_id, part_id) keys.
Add support for part display names from slicer model_settings: introduce ctx.part_names in ImportContext and initialize it in api and operator. Collect part names when parsing ORCA/BambuStudio metadata (stored keyed by (wrapper_id, part_id)). Use these names as the highest-priority Blender object name when building objects (falling back to <object> Title metadata or "3MF Object"). Also reuse the composite key for applying part subtype. Improves object naming fidelity when importing multi-part 3MF files.
Introduce a rating nudge that prompts users to rate the addon after a number of successful exports. Adds hidden prefs (export_count, rating_prompt_after) and a THREEMF_OT_rating_nudge operator/UI in __init__.py, schedules the popup from export_3mf/operator.py via _maybe_show_rating_nudge (uses bpy.app.timers and temp_override so it doesn't block export), and only triggers after a successful export. Bumps addon version to 2.5.1 and documents the feature in CHANGELOG.md. Includes integration tests for counting, scheduling, and operator actions (snooze/dismiss/rate). Safeguards ensure the nudge never breaks the export flow if errors occur.
Add a detailed FullSpectrum implementation guide (docs/fullspectrum-implementation-guide.md) and expand ROADMAP.md with an OrcaSlicer-FullSpectrum section describing detection, parsing/serialization, virtual filament mapping, FilamentMixer color model, config keys, and implementation tasks. Also update .gitignore to ignore ReferenceFiles. These changes provide reference material and an implementation plan for FullSpectrum support (import, display, round-trip export) and include pointers to audited reference files.
…rt Dialogue Enhancements (#29) * Add Filament Mixer and mixed-filament support Introduce full mixed-filament support and the FilamentMixer model used for color blending. Adds an auto-generated polynomial model data file (_filament_mixer_data.py), mixer implementation (filament_mixer.py), and mixed_filaments helper module, plus a CLI tool (tools/extract_filament_mixer.py) used to produce the model data. Update 3MF import/export contexts, Orca exporter, material base, and slicer paint/colour handling to integrate mixed-filament semantics. Documentation updated with UI/visibility spec for the new "Mix Colors" sub-panel and preference/scene visibility logic. * Add Phase 2 UI implementation plan Add Phase 2 authoring UI implementation plan to docs/fullspectrum-implementation-guide.md. Describes a hidden-by-default mixed-filament authoring UI that appears when a FullSpectrum file is imported or enabled in Preferences. Breaks the work into five chunks with file-level notes: preference toggle and scene property plumbing (properties, registration, import population), syncing virtual slots into the filament palette (helpers/import), a "Mix Colors" sub-panel (panel layout and polling), Mix Colors operators (add/remove/recompute operator behavior), and export round-trip support (export serialization of MMUMixedFilamentItem → MixedFilament). Provides field lists, UI behavior, and integration details to guide implementation. * Improve import perf, MMU paint & FullSpectrum Multiple imports and MMU paint enhancements: - Performance: cache external .model paths to avoid re-opening archives; add timing/debug logs across import pipeline; fast-path for geometry-only imports; avoid per-face loops for unsegmented triangles; reuse Color UV layout for seam/support layers; scale UV island margin with texture size. - Filament mixer: vectorize polynomial evaluation using numpy arrays for a large speedup in blend computations. - MMU / FullSpectrum: add preferences and operator option for mixed-filament UI and shared paint texture; populate mixed-filament UI collection on import and sync UI edits back into exporter (serialize mixed definitions); ensure filament palette is force-synced after import to fix empty palette in shared-texture imports. - Paint textures: support deferred creation of solid-color textures for per-part extruder assignments; implement batching to produce a single shared texture when requested; create per-extruder solid materials where appropriate. - Import robustness: improved vertex parsing error handling and early-out for external resource-only model files. - Misc: expose helper functions, add tests and an inspect script, update docs and changelog. Also note: debug logging flag was enabled to aid development/tracing. * Add FullSpectrum parts-mode round-trip support Implement FullSpectrum (OrcaSlicer) parts-mode import/export and related fixes: bump addon version to 2.6.0 and update CHANGELOG. Key changes: - Export (io_mesh_3mf/export_3mf/orca.py): detect FullSpectrum mixed_filament_definitions and treat files as parts-mode; collect only physical filament colors for filament_colour, do not append virtual/mixed display colours; skip per-triangle paint segmentation and adaptive subdivision for parts-mode objects; preserve per-part 1-based extruder values from mesh metadata (3mf_paint_default_extruder) so virtual slots are round-tripped. - Import (io_mesh_3mf/import_3mf/builder.py): apply per-part extruder when present, and fall back to the wrapper/object default extruder when part-level extruder is absent (fixes inherited Base part colors); defer solid-paint handling unchanged. - Import operator (io_mesh_3mf/import_3mf/operator.py): stop writing scene['3mf_num_physical_filaments'] (mixed filament definitions are still stored on scene). - CHANGELOG: update release header, document FullSpectrum multi-material support, per-part extruder inheritance, virtual filament swatches, export format behavior, UI editing, and performance notes. These changes ensure correct FullSpectrum round-tripping (per-part extruder metadata, correct filament_colour length) and avoid exporting virtual mixed slots as physical filaments, while also improving import/export performance and UV/paint handling. * Reformat filament mixer constants and minor fixes Reformat large constant arrays in io_mesh_3mf/common/_filament_mixer_data.py (POWERS) to improve readability and satisfy line-length linting (added noqa: E501). Includes additional small updates to io_mesh_3mf/import_3mf/builder.py, io_mesh_3mf/paint/mmu_panel.py, and io_mesh_3mf/paint/properties.py — primarily minor refactors/formatting and linting fixes. * Preserve stashed filament colors on export When re-exporting FullSpectrum files, preserve the stashed physical filament list from stashed_config so mixed_filament_definitions slot indices remain valid; append any new colours while retaining original order. Tests updated: switch ORCA export mode to AUTO in fullspectrum roundtrip, adjust import_triangles material expectation for NONE fast-path, add unit tests for mixed_filaments (and remove the old standalone roundtrip script), refine annotation content-type assertion, and simplify paint quantization tests to assert brightness-based snapping. * Add "Add Color" operator, finds closest desired match Replace single "Add mixed filament" operator in the MMU UI with a popup menu and introduce three new add-mix operators. Adds MMU_MT_add_mix_menu and operators MMU_OT_add_mix_gradient, MMU_OT_add_mix_pattern and MMU_OT_add_mix_by_color, and exports them in the paint package. Panel buttons now open the menu instead of invoking a single operator. The new operators create gradient or pattern virtual mixed filaments (setting defaults, stable id, enabled flag, recomputing display color and refreshing virtual slots). The color-based operator includes a solver that searches 2-way gradients (varying mix ratios) and a set of 3-way pattern candidates to pick the best color match from the current physical palette. * Persist physical filaments and adjust add/remove Only write physical (non-virtual) filament colors to the mesh properties and store a 3mf_num_physical_filaments value so the physical/virtual boundary can be restored on import. Operators now compute num_physical (preferring settings.num_physical_filaments when set), enforce the 2..16 physical filament limits, trim virtual slots before adding, mark added filaments as physical, prevent removing virtual slots, reindex only physical items, clamp the active index to the physical range, update settings.num_physical_filaments, and refresh virtual slots after changes. These changes prevent virtual/display-only slots from being treated as real filament slots and improve slot management and round-trip fidelity. * Add inline mixed-filament UI and handlers Introduce an inline "Add Mix" form and supporting logic for mixed filaments. Add new properties to MMUPaintSettings (mix_target_color, show_add_mix_section, add_mix_mode and related fields) and a shared UI helper draw_add_mix_form used by the paint panel and bake panel. Implement two new operators MMU_OT_add_mix_confirm and MMU_OT_cancel_add_mix to confirm/cancel the inline form and reuse the existing color-solver operator for target-color mode. Refactor operator helpers to reliably compute the physical filament palette via _physical_hex_colors and update callers (_next_unused_pair, _recompute_display_color_for_item, add-mix logic) to use it. Update MMU_OT_add_mix_by_color to read the target color from the new panel setting instead of an operator property. Bake and quantize changes: write only physical filament colors to the mesh palette, store the number of physical filaments (3mf_num_physical_filaments), and prefer filament colors from settings (including mixed virtual slots) when quantizing; fall back to mesh-stored colors if needed. Add a collapsible "Mixed Filaments" section to the bake panel that can show the inline add form. Register new operators/classes in __init__ and wire the new UI into mmu_panel for a consistent inline workflow. These changes ensure a clearer physical-vs-virtual filament separation and let users define mixed slots before baking while preserving painted mixed colors during quantization. * Show mixed filaments in bake UI; update changelog Add UI to display active mixed (virtual) filaments in the bake confirmation panel and update changelog for 2.6.0. io_mesh_3mf/paint/bake.py now collects enabled, non-deleted mixed_filaments (guarded by has_mixed_filaments) and renders read-only color swatches in a grid_flow so users can confirm mixed slots will be included in the bake. CHANGELOG.md was reorganized for 2.6.0 (Features, Bug Fixes, Performance) and documents FullSpectrum 3MF import/export, Mix Colors UI changes, bake behavior including mixed filaments, UI fixes for filament add/remove, and several performance improvements. * Support scene units on import and paint options Add scene unit controls and MMU paint defaults across the addon and operator. Preferences now include default_scene_unit, default_paint_uv_method, default_paint_texture_size and default_shared_paint_texture; the Import3MF operator gains a scene_unit enum and applies scene unit settings to context.scene.unit_settings before computing import scale. The public API import_3mf gained a scene_unit parameter and an _apply_scene_unit_api helper that maps 3MF units to Blender units/systems. Also renamed the operator scale label to "Scale Multiplier" with a clarifying description, and disabled verbose debug output by default (DEBUG_MODE = False). UI tweaks ensure the new preferences are shown when relevant.
Replace legacy Markdown issue templates with structured GitHub Issue Forms. Deleted bug_report.md and feature_request.md and added bug_report.yml and feature_request.yml with validated fields (addon/blender version, OS, area, reproduction steps, etc.), default labels/assignees, and improved guidance for reporters. Also added ISSUE_TEMPLATE/config.yml to disable blank issues and provide contact links, and introduced a PULL_REQUEST_TEMPLATE.md for consistent PR descriptions.
Add repository config files: .github/CODEOWNERS to auto-request reviews from @Clonephaze; .github/workflows/stale.yml to run daily (06:00 UTC) and mark issues stale after 60 days and close after 14 days (exempting labels: pinned, bug, in progress) while ignoring PRs; and SECURITY.md documenting supported versions and a private vulnerability reporting process via the repo Security tab.
Update CI to actions/checkout@v4 and setup-python@v5 (Python 3.12) and include tests/ in pycodestyle checks. Apply widespread stylistic changes across test files: normalize to double quotes, add trailing commas, adjust whitespace and line breaks, tweak regex/string literal quoting, use clearer with(...) contexts, and minor readability refactors. Changes are formatting-only and do not alter test logic or behavior.
Generates a Slic3r_PE_model.config with one <object> and one <volume> per original part (firstid/lastid cumulative) and preserves world transforms (vertex positions baked). Improve material_to_hex_color() to walk node trees and read colours from Principled BSDF and other shader nodes (Diffuse, Glossy, Emission, Glass, Toon, Velvet, standalone RGB nodes, and legacy diffuse_color), skipping the default auto-generated gray. Add scripts/inspect_blend.py for inspecting scene objects/materials. Update tests to assert a single combined object/build item, validate generated model config volumes and IDs, and check Z-position preservation and segmentation handling.
Add five discussion templates under .github/DISCUSSION_TEMPLATE: announcements, bug-reports, feature-ideas, showcase, and support. Each template provides structured fields, labels, and validations (e.g., addon/blender version, area dropdowns, reproduction steps, media) to standardize community reporting, triage, idea brainstorming, and showcases.
Rename .github/DISCUSSION_TEMPLATE/showcase.yml to .github/DISCUSSION_TEMPLATE/showcase-gallery.yml to clarify the template's purpose. This is a pure rename (100% similarity) with no content changes.
Rename .github/DISCUSSION_TEMPLATE/support.yml to .github/DISCUSSION_TEMPLATE/support-troubleshooting.yml to better reflect the template's purpose for support/troubleshooting discussions. No content changes (100% similarity).
Updated badge links to be clickable in README.
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.
Important
The fork found here is incompatible with Ghostkeepers Original work. A slew of new features have been added, including a full re-write of the api intended for those using/creating scripts. This PR is informational only
Download Here
Official Blender Extensions Platform – Includes automatic updates!
New Features!
TL;DR:
MMU painting
Segmentation encoding
Slicer support
Materials and Properties Extension
Production Extension
3D/Objects/*.model)Triangle Sets Extension
<triangleset>import/exportImport workflow
.3mfinto the viewportExport workflow
Public API
Extensions & standards
Robustness & quality