tmhsdigital/blender-developer-tools

bake-high-to-low

Cage-bake high-poly surface detail onto a low-poly target as a tangent-space normal map with bpy.ops.object.bake (Cycles, selected-to-active, active Image Texture node, UV layer, saverender).

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/tmhsdigital/blender-developer-tools --skill bake-high-to-low

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Bake High to Low

Trigger

Use this skill when the user:

  • Wants a tangent-space normal map from a dense source onto a game-resolution mesh
  • Mentions cage bake, use_selected_to_active, cage_extrusion, or bpy.ops.object.bake
  • Has an LOD from DECIMATE COLLAPSE (or a retopo) and needs the missing surface detail in a map
  • Is about to call bake from EEVEE, on GPU in CI, or with bake_type=

This skill is the bake step. It composes ai-mesh-cleanup (identity scale, applied transforms, a UV layer that already exists) and the LOD contract in `examples/lod-decimate-chain/` / `snippets/decimate_to_budget.py` (collapse onto a budget; UVs survive well enough to bake). It does not unwrap, transfer UVs, or pack an atlas — those are a later phase. It does not generate meshes.

The core misunderstanding

Baking is not a render. EEVEE has no bake path. The operator writes into an Image Texture node in the active object's material, not into a file and not into "the selected image datablock." The node it picks is the material's active texture node, and on 5.x that node must also be selected. The active-texture node is the Image Texture node most recently made nodes.active, or the first one created if none ever was. Making a non-texture node (Principled, Output) active later does not move it.

The safe pattern sets both: nodes.active = tex and tex.select = True. The failure modes are not equally loud. Measured on 4.5.11 LTS and 5.2.1 LTS (the selection rows also on 5.0.1 and 5.1.2):

Setup mistakeWhat bpy.ops.object.bake does
Target mesh has no UV layerRaises RuntimeError: No active UV layer found in the object "Low"
Target material has no Image Texture nodeReturns {'CANCELLED'}, raises nothing, writes nothing
Image Texture node is active but tex.select = False5.0 and later: {'CANCELLED'}, Info No active and selected image texture node found in material ..., pixels untouched. 4.5 LTS: {'FINISHED'}, bakes into it anyway
Two Image Texture nodes, the one you mean is selected but the other is the active texture5.0 and later: {'CANCELLED'}, same Info. 4.5 LTS: bakes into the active texture node, not the selected one
The only Image Texture node is selected but nodes.active is PrincipledBakes into it ({'FINISHED'}); it is still the active texture node

So a headless job must check the returned set: {'CANCELLED'} is the silent one. Do not "clean up" a tex.select = True line that looks redundant: on 5.x it is what lets the bake find its target. With several Image Texture nodes, make the one you mean nodes.active and selected.

The pass type RNA is type, not bake_type. bake_type is not on bpy.ops.object.bake. Passing it is a TypeError.

Cycles bake is stochastic. Pixel buffers are not byte-identical across 4.5 / 5.1 / 5.2, even at one sample on CPU. Assert with tolerances and a flat-source control, not a hash.

RNA (verified)

Live dump of bpy.ops.object.bake.get_rna_type() on 4.5.11 LTS, 5.1.2, and 5.2.1 LTS: 22 properties, identical identifiers and enums. No version shim. The kwargs below are the contract.

Docs:

  • 5.2: https://docs.blender.org/api/current/bpy.ops.object.html#bpy.ops.object.bake
  • 5.1: https://docs.blender.org/api/5.1/bpy.ops.object.html#bpy.ops.object.bake
  • 4.5: https://docs.blender.org/api/4.5/bpy.ops.object.html#bpy.ops.object.bake

cage_object is a string name, never an Object pointer.

The canonical pattern

Every step is a silent-failure point. Do them in this order.

1. Engine and device

python
scene = bpy.context.scene
scene.render.engine = "CYCLES"
scene.cycles.device = "CPU"
scene.cycles.samples = 1
scene.cycles.use_denoising = False

Do not rely on the default device. Headless CI has no GPU. samples = 1 is enough for a statistical check; raise it for production maps, not for smoke.

2. Target: UV layer, image, active Image Texture node

The low-poly object needs a UV layer (mesh.uv_layers). Confirm it; do not unwrap here.

python
img = bpy.data.images.new("BakeNrm", 128, 128, alpha=True, float_buffer=False)
img.colorspace_settings.name = "Non-Color"

mat = bpy.data.materials.new("BakeTarget")
if bpy.app.version < (5, 0, 0):
    mat.use_nodes = True  # 4.5 LTS only; the tree exists and use_nodes is deprecated on 5.x
nodes = mat.node_tree.nodes
tex = nodes.new("ShaderNodeTexImage")
tex.image = img
nodes.active = tex
tex.select = True

if obj.data.materials:
    obj.data.materials[0] = mat
else:
    obj.data.materials.append(mat)

The Image Texture does not need to be linked into Principled for the bake to land. It must be the active texture node (nodes.active = tex) and, on 5.x, selected (tex.select = True). A new node is created selected, but code that deselects nodes or edits the tree afterwards can clear that. After the bake, wire ShaderNodeNormalMap for display or export; do not plug Image Texture Color into Principled Normal.

Snippet: `snippets/setup_bake_target_image.py`.

3. Selection: high selected, low active

python
high.select_set(True)
low.select_set(True)
bpy.context.view_layer.objects.active = low

use_selected_to_active=True bakes selected sources onto the active target. Reverse that and the map is empty or self-bakes the low.

4. Cage normal bake

python
result = bpy.ops.object.bake(
    type="NORMAL",
    use_selected_to_active=True,
    cage_extrusion=0.20,
    use_cage=False,
    normal_space="TANGENT",
    margin=4,
    margin_type="ADJACENT_FACES",
    use_clear=True,
    target="IMAGE_TEXTURES",
)
if result != {'FINISHED'}:
    # {'CANCELLED'} raises nothing: e.g. no Image Texture node in the material.
    raise RuntimeError(f"bake did not finish: {result}")

cage_extrusion inflates the active object along its normals so rays hit the high mesh. It must clear the high-frequency amplitude (ribs at 0.10 need extrusion > 0.10; 0.20 is the worked value). If extrusion alone skims past concavities, set use_cage=True and cage_object="CageName" (the object's .name). Do not pass the Object.

margin_type is ADJACENT_FACES or EXTEND. Prefer ADJACENT_FACES at UV seams.

Snippet: `snippets/bake_normal_high_to_low.py`.

5. Save the datablock

The bake writes the image in memory. Image.save() on a GENERATED image flips source to 'FILE' and drops the buffer — the trap `examples/image-pixels-testcard/` witnesses. Use save_render().

save_render() writes in the format of the scene's render.image_settings, not img.file_format: setting img.file_format = "OPEN_EXR" and calling save_render still writes a PNG on a default scene. Set the scene's format for the call and restore it:

python
settings = scene.render.image_settings
previous = settings.file_format
settings.file_format = "OPEN_EXR"  # or "PNG"
try:
    img.save_render(filepath, scene=scene)
finally:
    settings.file_format = previous

Snippet: `snippets/save_baked_image.py`. Folded save is the wrong size: the trap is its own contract.

Common mistakes

WrongRight
bake_type='NORMAL'type='NORMAL'
scene.render.engine = 'BLENDER_EEVEE' then bakeCYCLES only
GPU / default device in CIscene.cycles.device = 'CPU'
Low selected, high activeHigh selected, low active
Image Texture present but not nodes.activeSet nodes.active = tex
Image Texture active but deselected (5.x CANCELLED)Also set tex.select = True
No UV layerConfirm mesh.uv_layers before bake
Image.save() after bakeImage.save_render(path)
Hash / byte-compare maps across versionsFraction / MAD vs (0.5, 0.5, 1.0) plus a flat-source control

Version notes

Bake operator RNA is identical on 4.5 LTS, 5.1, and 5.2 LTS. Branch on bpy.app.version only for unrelated neighbors (EEVEE engine id for a gallery still, NodesModifier inputs). Do not invent a bake shim.

Witness: `examples/bake-normal-high-to-low/`. --flat-source feeds an undisplaced high into the same detail assertion and must exit non-zero.

<!-- examples:begin (generated by scripts/buildexamplesindex.py from examples/skills.json; do not edit) -->

Runnable examples

Each example runs headless, asserts the contract, and exits non-zero when it breaks. Run one with blender --background --python <script> --; pass a falsifier flag to watch the check fail.

  • `bake-normal-high-to-low`: A collapse-decimated hatch plate receiving a Cycles cage-baked tangent normal map from a ribbed high-poly source Falsify: --flat-source (exit 5).

Snippets

Short standalone patterns to copy. Each one runs in CI on 5.2 and 4.5 with a check and a falsifier.

<!-- examples:end -->

来自同一仓库

更多 Skills

全部 Skills
tmhsdigital
社区

bl-info-migration

Migrate a legacy blinfo add-on to the Extensions Platform in three steps, with a before/after diff and the dual-format pattern. Use when the user has a blinfo dictionary in init.py, asks whether blinfo is deprecated or still supported, wants to publish to extensions.blender.org or ship an extension .zip, or sees warnings about legacy add-ons at install time. Targets 5.2 LTS; manifests work from 4.2.

1小时安装量
1
GitHub Stars
20
最近更新
11月3日
tmhsdigital
社区

drivers-and-app-handlers

Drive properties from expressions with the Driver API (driveradd, drivernamespace for custom Python functions) and react to events with bpy.app.handlers (loadpost, savepre, framechangepost, depsgraphupdatepost, exitpre in 5.1+). Use when the user wants one property to follow another, runs code on load, save, frame change or exit, or has a driver failing with NameError or the Python security block, including drivers that die after reopening a file.

1小时安装量
1
GitHub Stars
20
最近更新
11月3日
tmhsdigital
社区

engine-export-presets

Export presets for Unity, Godot and Unreal. glTF is +Y up and meters by spec, so every engine gets exportyup=True with no scale bake (Unreal converts to centimeters on import); FBX takes axisforward/axisup plus globalscale. Use when the user exports for a game engine, mentions exportyup, axisforward, axisup, globalscale, Y-up or centimeters, passes FBX axis kwargs to exportscene.gltf, or gets a model that imports lying on its back or 100x too large. Targets 5.2 LTS with 4.5 LTS fallback.

1小时安装量
1
GitHub Stars
20
最近更新
11月3日