Document Material ID Baker and tune bake margin

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
 

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",

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"

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"

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

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 `<original name>_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.