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 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

모든 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일