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