From b2288e802f5f80110f8ac91dc3f7bb6a31a7c580 Mon Sep 17 00:00:00 2001 From: Peterino2 Date: Sat, 11 Jul 2026 11:10:55 -0700 Subject: [PATCH] Document Material ID Baker and tune bake margin --- README.md | 2 +- blender/material_id_baker/__init__.py | 2 +- .../material_id_baker/blender_manifest.toml | 2 +- blender/tests/smoke_test.py | 1 + docs/README.md | 3 +- docs/material-id-baker.md | 207 ++++++++++++++++++ 6 files changed, 213 insertions(+), 4 deletions(-) create mode 100644 docs/material-id-baker.md diff --git a/README.md b/README.md index 75af3b8..16b2ca3 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ install-all.bat The Blender extension bakes the active mesh's material-slot assignments to a flat-color texture using its active UV map. It works on a temporary mesh copy, so the source mesh and materials are not modified. -Features include 256px–8K output, configurable island margin, optional evaluated modifiers, and three palette modes: deterministic distinct colors, material viewport colors, and exact slot-index encoding. It can write a PNG plus a JSON legend used by the standalone merger. The optional **Create Export Copy** setting leaves behind a selected duplicate with one `baked ids` material connected to the baked image. Its dependent **Quick Export GLB** option immediately writes that one-material copy to a chosen `.glb` path for Substance Painter. +Features include 256px–8K output, a configurable island margin defaulting to 1 px, optional evaluated modifiers, and three palette modes: deterministic distinct colors, material viewport colors, and exact slot-index encoding. It can write a PNG plus a JSON legend used by the standalone merger. The optional **Create Export Copy** setting leaves behind a selected duplicate with one `baked ids` material connected to the baked image. Its dependent **Quick Export GLB** option immediately writes that one-material copy to a chosen `.glb` path for Substance Painter. ### Install or update diff --git a/blender/material_id_baker/__init__.py b/blender/material_id_baker/__init__.py index 2ec22b2..f07f385 100644 --- a/blender/material_id_baker/__init__.py +++ b/blender/material_id_baker/__init__.py @@ -230,7 +230,7 @@ class MIDB_Settings(PropertyGroup): margin: IntProperty( name="Margin", description="Extend IDs beyond UV island edges by this many pixels", - default=16, + default=1, min=0, max=256, subtype="PIXEL", diff --git a/blender/material_id_baker/blender_manifest.toml b/blender/material_id_baker/blender_manifest.toml index dbdbd3c..13b7496 100644 --- a/blender/material_id_baker/blender_manifest.toml +++ b/blender/material_id_baker/blender_manifest.toml @@ -1,7 +1,7 @@ schema_version = "1.0.0" id = "material_id_baker" -version = "1.2.0" +version = "1.2.1" name = "Material ID Baker" tagline = "Bake mesh material assignments to a color ID texture" maintainer = "Sear" diff --git a/blender/tests/smoke_test.py b/blender/tests/smoke_test.py index b707785..4ec5427 100644 --- a/blender/tests/smoke_test.py +++ b/blender/tests/smoke_test.py @@ -78,6 +78,7 @@ def main() -> None: original_cycles_samples = bpy.context.scene.cycles.samples settings = bpy.context.scene.material_id_baker + assert settings.margin == 1 settings.resolution = "256" settings.margin = 4 settings.palette_mode = "DISTINCT" diff --git a/docs/README.md b/docs/README.md index 97590b2..f160f1b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,8 @@ - [Building Blender extensions](blender-extension-guide.md): package layout, manifests, permissions, registration, operators, UI, safe data handling, storage, dependencies, builds, and installation. +- [Material ID Baker](material-id-baker.md): installation, settings, Substance + Painter workflow, GLB export, recovery workflow, and troubleshooting. - [Blender Python API notes](blender-api-notes.md): context and mode pitfalls, data-block ownership, lifecycle cleanup, evaluated meshes, materials, images, baking, file effects, and compatibility probes. @@ -12,4 +14,3 @@ These guides target modern add-on extensions in Blender 5.x. Repository-wide contributor requirements live in [AGENTS.md](../AGENTS.md). - diff --git a/docs/material-id-baker.md b/docs/material-id-baker.md new file mode 100644 index 0000000..7e71745 --- /dev/null +++ b/docs/material-id-baker.md @@ -0,0 +1,207 @@ +# Material ID Baker + +Material ID Baker is a Blender 5.x extension for turning per-face material-slot assignments into a flat-color texture. It is designed for Blender-to-Substance Painter workflows where one mesh needs a single texture set plus a material ID map. + +Current extension version: **1.2.1**. + +## What it produces + +A bake can produce: + +- a generated Material ID image inside Blender; +- a PNG copy of that image; +- a JSON legend mapping material slots and names to their exact RGB colors; +- an optional duplicate mesh with one material named `baked ids`; +- an optional `.glb` containing that one-material duplicate and embedded ID image. + +The original object, mesh, material assignments, render engine, Cycles sample count, and bake settings are preserved. When an export copy is requested, that new copy remains selected after the bake. + +## Install or update + +Close Blender before replacing an installed extension. + +From the repository root on Linux or macOS: + +```bash +./install-all.sh +``` + +If Blender is not on `PATH`: + +```bash +BLENDER_BIN=/path/to/blender-5.2 ./install-all.sh +``` + +On Windows Command Prompt: + +```bat +set "BLENDER_BIN=C:\Program Files\Blender Foundation\Blender 5.2\blender.exe" +install-all.bat +``` + +The packaged ZIP can also be installed through **Edit → Preferences → Extensions → Install from Disk**. + +## Prepare the mesh + +Before baking: + +1. Select one mesh object. +2. Switch to Object Mode. +3. Confirm the mesh has an active UV map. +4. Assign the intended material slot to every face. +5. Avoid overlapping UV islands when overlapping faces use different materials. +6. Save the `.blend` if using an output path beginning with `//`. + +The extension uses the active UV map. Different material IDs cannot be recovered reliably where UV islands overlap. + +## Bake an ID map + +Open the 3D Viewport sidebar and select the **Material ID** tab. + +Choose the settings, then click **Bake Material ID**. The extension creates temporary bake geometry and emission materials, performs a one-sample Cycles emission bake, and removes the temporary data afterward. + +## Settings reference + +### Resolution + +Output size from 256 px through 8K. Match the resolution planned for Substance Painter when practical. + +Pixel cost grows quadratically: + +- 2K has four times as many pixels as 1K. +- 4K has four times as many pixels as 2K. +- 8K has sixteen times as many pixels as 2K. + +### Margin + +Extends each ID beyond the UV-island boundary. The default is **1 px**, which is normally sufficient for a material ID texture while reducing the chance of expansion into nearby islands. + +Increase it only when downstream texture filtering exposes island-edge seams. + +### Colors + +- **Distinct:** Generates deterministic, vivid colors from material-slot order. This is the recommended general-purpose mode. +- **Material Viewport Colors:** Uses each material's Blender viewport display color. Use this when colors were deliberately assigned and are unique. +- **Exact Slot Index:** Encodes the one-based slot number into a 24-bit RGB value. Black remains the empty/background value. This is useful for tools that decode integer IDs rather than selecting visually distinct colors. + +### Apply Modifiers + +Bakes the evaluated modifier result instead of the base mesh. The generated export copy also uses that evaluated geometry and has no remaining modifiers. + +Leave this disabled when the base mesh and its active UV map are the intended Substance mesh. Enable it when Substance must receive the final evaluated topology. + +### Create Export Copy + +Creates `_Baked_IDs` and leaves it selected. + +The copy has: + +- independent mesh data; +- one material slot; +- one new material named `baked ids`; +- every polygon assigned to slot 0; +- the baked ID image connected to Principled Base Color. + +This keeps the original multi-material object intact while producing a one-material object suitable for a single Substance texture set. + +### Quick Export GLB + +Available only when **Create Export Copy** is enabled. + +Immediately exports the generated copy to the configured **GLB Path**. The extension: + +- adds `.glb` when the path has another or no extension; +- creates missing parent directories; +- exports only the generated copy; +- includes one mesh and the `baked ids` material; +- embeds the ID image; +- disables animation export. + +For predictable Substance geometry, enable **Apply Modifiers** before using Quick Export GLB when the source relies on topology-changing modifiers. + +### Image Name + +Name of the generated image data-block inside Blender. Blender adds a numeric suffix when that name already exists. + +### Save PNG + +Writes the baked image to disk. Paths beginning with `//` are relative to the current `.blend` file. + +### Save JSON Legend + +Writes a JSON file beside the PNG. It records the source object, UV map, palette mode, material names, slots, and RGB values. + +The legend is also consumed by the repository's Substance texture-set merger. + +## Recommended Substance Painter workflow + +1. Keep the useful per-face material assignments on the original Blender object. +2. Use a non-overlapping UV map at the intended texture resolution. +3. In Material ID Baker, select **Distinct** colors and leave the margin at 1 px. +4. Enable **Apply Modifiers** if Substance should receive evaluated geometry. +5. Enable **Create Export Copy**. +6. Enable **Quick Export GLB** and choose the Substance import path. +7. Enable **Save PNG** and **Save JSON Legend**. +8. Click **Bake Material ID**. +9. Import the resulting GLB into Substance Painter. It contains one material, so Substance creates one texture set. +10. Import the PNG as the mesh's material ID map and use it for color-selection masks. + +The generated Blender copy remains selected if another export format or manual inspection is needed. + +## Recovering separate Substance texture sets + +If the mesh was already imported with one Substance texture set per Blender material, export every texture set with a consistent naming pattern, then use: + +```bash +.venv/bin/python tools/combine_substance_textures.py \ + --id-map recovery/Material_ID.png \ + --legend recovery/Material_ID.json \ + --input-dir substance-export \ + --output-dir combined +``` + +The merger detects material names in filenames or texture-set directories and writes one combined texture per channel. It uses the ID map instead of alpha, so opaque Substance padding cannot overwrite another material region. + +Use `--material-alias 'Blender Material=Substance Name'` when a Substance texture-set name differs from the material name in the legend. + +## Performance + +The extension uses Cycles because Blender's image-bake pipeline is reliable and handles UV margins. Material IDs are flat emission values, so the extension temporarily forces one Cycles sample and restores the previous sample count afterward. + +The first bake can still spend time initializing Cycles and synchronizing the scene. Resolution, evaluated modifiers, mesh complexity, PNG compression, and a cold Cycles startup remain the main costs. + +For faster iteration, test at 1K or 2K before producing a final 4K or 8K map. + +## Troubleshooting + +### The Bake Material ID button is disabled + +Confirm that the active object is a mesh, Blender is in Object Mode, and the mesh has a UV map. + +### IDs appear in the wrong places + +Check the active UV map and look for overlapping islands. Confirm face material assignments in Edit Mode. + +### Two materials have the same ID + +Use **Distinct** or **Exact Slot Index**, or give every material a unique viewport color before using **Material Viewport Colors**. + +### The GLB does not match the visible modifier result + +Enable **Apply Modifiers** before baking and exporting. + +### The output path is unexpected + +`//` paths are relative to the saved `.blend`. Save the file first or choose an absolute path. + +### The bake still feels slow + +Reduce resolution while iterating. A cold Cycles startup and evaluated topology can dominate a simple ID bake even at one sample. + +### Substance creates more than one texture set + +Import the generated GLB or export only the generated `_Baked_IDs` copy. The original object intentionally retains its multiple material slots. + +## Safety and cleanup + +The baker works on temporary copies rather than replacing source materials. It restores temporary render and selection state in a `finally` cleanup path. A requested export copy and requested output files are intentional persistent results; all temporary bake objects, meshes, and materials are removed.