Skip to content

Transform your 3D texturing workflow with the power of generative AI, directly within Blender!

let masked edit and refine follow a reference image

sakalond998299469f2b
diff --git a/stablegen/texturing/masked_edit.py b/stablegen/texturing/masked_edit.py
index cf967b3..d9b11fa 100644
--- a/stablegen/texturing/masked_edit.py
+++ b/stablegen/texturing/masked_edit.py
@@ -42,6 +42,13 @@ def unified_paint(scene):
else settings.unified_paint_settings)
+def reference_path(scene):
+ """The reference image the edit follows (an absolute path), or None when none is used."""
+ if scene.model_architecture not in QWEN_ARCHITECTURES or not scene.sg_masked_use_reference:
+ return None
+ return bpy.path.abspath(scene.sg_masked_reference_image) if scene.sg_masked_reference_image else ''
+
+
def qwen_edit_instruction(instruction, overlay, template=None):
instruction = instruction.strip()
if template is not None:
@@ -1058,7 +1065,10 @@ class SG_OT_MaskedEdit(bpy.types.Operator):
raise ValueError('Set a valid output directory in StableGen preferences')
if not context.scene.sg_masked_prompt.strip():
raise ValueError('Describe the requested edit first')
- self.objects = [o for o in eligible_objects(context) if o.sg_edit_mask and MASK_UV in o.data.uv_layers]
+ reference = reference_path(context.scene)
+ if reference is not None and not Path(reference).is_file():
+ raise ValueError('Choose a reference image, or turn off Use Reference Image')
+ self.objects =[o for o in eligible_objects(context) if o.sg_edit_mask and MASK_UV in o.data.uv_layers]
if not self.objects:
raise ValueError('Paint a selection on a target mesh first')
for obj in self.objects:
@@ -1139,6 +1149,7 @@ class SG_OT_MaskedEdit(bpy.types.Operator):
'expand_selection_px': int(self.scene.sg_masked_expand),
'edge_softness_px': int(self.scene.sg_masked_feather),
'use_depth': bool(self.scene.sg_masked_use_depth),
+ 'reference_image': reference_path(self.scene),
'custom_prompt': bool(self.scene.sg_masked_use_custom_prompt),
'pbr_channels': sorted(getattr(self, 'pbr_channels', ())),
'prompt_template': (self.scene.sg_masked_custom_prompt
@@ -1199,6 +1210,8 @@ class SG_OT_MaskedEdit(bpy.types.Operator):
paths['overlay'] = overlay
if depth:
paths['depth'] = depth
+ if reference_path(context.scene):
+ paths['reference'] = reference_path(context.scene)
for key, path in paths.items():
uploaded = upload_image_to_comfyui(server, str(path), operator=self)
if not uploaded:
@@ -1213,7 +1226,8 @@ class SG_OT_MaskedEdit(bpy.types.Operator):
'prompt': context.scene.sg_masked_prompt,
'overlay': self.uploads.get('overlay'),
'depth': self.uploads.get('depth'),
- 'prompt_template': (context.scene.sg_masked_custom_prompt
+ 'reference': self.uploads.get('reference'),
+ 'prompt_template':(context.scene.sg_masked_custom_prompt
if context.scene.sg_masked_use_custom_prompt else None),
})
else:
@@ -1523,6 +1537,13 @@ def draw_masked_edit_controls(layout, context):
if scene.model_architecture in QWEN_ARCHITECTURES:
layout.prop(scene, 'sg_masked_overlay')
layout.prop(scene, 'sg_masked_use_depth')
+ layout.prop(scene, 'sg_masked_use_reference', toggle=True, icon='FILE_IMAGE')
+ if scene.sg_masked_use_reference:
+ box = layout.box()
+ box.prop(scene, 'sg_masked_reference_image', text='Image')
+ if scene.model_architecture == 'qwen_image_edit' and scene.sg_masked_use_depth:
+ box.label(text='Qwen Image Edit takes three images: the reference replaces the depth map.',
+ icon='INFO')
layout.prop(scene, 'sg_masked_use_custom_prompt', text='Custom Guidance Prompt', toggle=True, icon='TEXT')
if scene.sg_masked_use_custom_prompt:
box = layout.box()
@@ -1573,6 +1594,14 @@ def register_properties():
bpy.types.Scene.sg_masked_use_depth = bpy.props.BoolProperty(
name='Use Depth Map', default=False,
description='Send the current camera depth as Image3 for structural guidance; useful for shape-sensitive edits but may weaken material or additive changes')
+ bpy.types.Scene.sg_masked_use_reference = bpy.props.BoolProperty(
+ name='Use Reference Image', default=False,
+ description='Send an image whose design the edit follows inside the selection, such as a logo, a pattern '
+ 'or a print, fitted to the surface. Qwen Image Edit takes three images, so the reference '
+ 'replaces the depth map there')
+ bpy.types.Scene.sg_masked_reference_image = bpy.props.StringProperty(
+ name='Reference Image', default='', subtype='FILE_PATH',
+ description='Image the edit follows, scaled to about 1 MP for the model')
bpy.types.Scene.sg_masked_use_custom_prompt = bpy.props.BoolProperty(
name='Use Custom Guidance Prompt', default=False,
description='Override the default Qwen Masked Edit guidance prompt')
@@ -1609,6 +1638,6 @@ def unregister_properties():
keymap.keymap_items.remove(item)
_paint_keymaps.clear()
for owner, names in ((bpy.types.Object, ('sg_edit_mask', 'sg_mask_paint_original', 'sg_mask_original', 'sg_mask_original_mesh')),
- (bpy.types.Scene, ('sg_mask_previous_canvas', 'sg_masked_prompt', 'sg_masked_overlay', 'sg_masked_use_depth', 'sg_masked_use_custom_prompt', 'sg_masked_custom_prompt', 'sg_masked_resolution', 'sg_masked_expand', 'sg_masked_feather', 'sg_masked_strength', 'sg_masked_update_pbr', 'sg_masked_status'))):
+ (bpy.types.Scene, ('sg_mask_previous_canvas', 'sg_masked_prompt', 'sg_masked_overlay', 'sg_masked_use_depth', 'sg_masked_use_reference', 'sg_masked_reference_image', 'sg_masked_use_custom_prompt', 'sg_masked_custom_prompt', 'sg_masked_resolution', 'sg_masked_expand', 'sg_masked_feather', 'sg_masked_strength', 'sg_masked_update_pbr', 'sg_masked_status'))):
for name in names:
delattr(owner, name)
diff --git a/stablegen/texturing/workflows.py b/stablegen/texturing/workflows.py
index 8d1ba04..d382279 100644
--- a/stablegen/texturing/workflows.py
+++ b/stablegen/texturing/workflows.py
@@ -2,6 +2,7 @@ from ..core.feature_flags import experimental_enabled
import bpy
import os
import json
+import re
import uuid
import random
import urllib.request
@@ -69,6 +70,11 @@ def _immutable_view_prompt(operator):
return ""
+def _image_slots(inputs):
+ """The legacy encoder's image inputs (image1, image2, ...) in slot order."""
+ return sorted((key for key in inputs if re.fullmatch(r'image\d+', key)), key=lambda key: int(key[5:]))
+
+
def _texturing_prompt(scene):
"""Return the texturing portion of the prompt.
@@ -184,11 +190,7 @@ class _TexturingWorkflowMixin:
"""
old_encoder = prompt[nodes['pos_prompt']]
old_inputs = old_encoder.get('inputs', {})
- image_refs = [
- old_inputs[key]
- for key in ('image1', 'image2', 'image3')
- if key in old_inputs
- ]
+ image_refs = [old_inputs[key] for key in _image_slots(old_inputs)]
prompt_text = old_inputs.get('prompt', '')
if projected_context_target and len(image_refs) >= 2:
# The legacy graph routes structure/depth as image 1 and projected
@@ -385,11 +387,7 @@ class _TexturingWorkflowMixin:
which would no longer register with the camera.
"""
old_inputs = prompt[nodes['pos_prompt']].get('inputs', {})
- image_refs = [
- old_inputs[key]
- for key in ('image1', 'image2', 'image3')
- if key in old_inputs
- ]
+ image_refs = [old_inputs[key] for key in _image_slots(old_inputs)]
mapping = {}
if projected_context_target and len(image_refs) >= 2:
image_refs[0], image_refs[1] = image_refs[1], image_refs[0]
@@ -1092,13 +1090,33 @@ class _TexturingWorkflowMixin:
del prompt[NODES['pos_prompt']]['inputs']['image2']
del prompt[NODES['neg_prompt']]['inputs']['image2']
+ # --- Reference images the edit follows ---
+ # Masked Edit sends its own reference (a logo, a pattern). Refine sends
+ # the external style image next to the previous refined view, which
+ # used to take its slot and drop it on every view after the first.
+ references = []
+ if masked_edit is not None:
+ if masked_edit.get('reference'):
+ references.append(('edit', masked_edit['reference']))
+ elif (context.scene.qwen_use_external_style_image and use_prev_ref
+ and style_image_info is not None):
+ external = self.operator._get_uploaded_image_info(
+ context, "custom", filename=bpy.path.abspath(context.scene.qwen_external_style_image))
+ if external:
+ references.append(('style', external))
+
# --- Configure Depth Map (Image 3) ---
use_depth = (bool(masked_edit.get('depth')) if masked_edit is not None
else context.scene.qwen_refine_use_depth)
depth_info = masked_edit.get('depth') if masked_edit is not None else None
if use_depth and masked_edit is None:
depth_info = self.operator._get_uploaded_image_info(context, "controlnet", subtype="depth", camera_id=camera_id)
-
+ if (depth_info and references and not native_graph
+ and 'image2' in prompt[NODES['pos_prompt']]['inputs']):
+ # Qwen Image Edit takes three images: the reference takes the depth map's place.
+ print("[StableGen] Qwen Image Edit takes three images; the reference image replaces the depth map")
+ depth_info = None
+
if depth_info:
prompt[NODES['context_render_loader']]['inputs']['image'] = depth_info['name']
else:
@@ -1107,6 +1125,30 @@ class _TexturingWorkflowMixin:
del prompt[NODES['pos_prompt']]['inputs']['image3']
del prompt[NODES['neg_prompt']]['inputs']['image3']
+ # Each reference takes the next free image slot, scaled to ~1 MP like
+ # the external style image (user files can be arbitrarily large).
+ reference_slots = []
+ for kind, info in references:
+ used = {int(key[5:]) for key in prompt[NODES['pos_prompt']]['inputs']
+ if re.fullmatch(r'image\d+', key)}
+ slot = min(set(range(1, len(used) + 2)) - used)
+ loader = str(max(int(key) for key in prompt if key.isdigit()) + 1)
+ prompt[loader] = {
+ "inputs": {"image": info['name']},
+ "class_type": "LoadImage",
+ "_meta": {"title": f"Reference Image {slot}"},
+ }
+ scale = str(int(loader) + 1)
+ prompt[scale] = {
+ "inputs": {"upscale_method": "lanczos", "megapixels": 1,
+ "resolution_steps": 1, "image": [loader, 0]},
+ "class_type": "ImageScaleToTotalPixels",
+ "_meta": {"title": "Scale Reference to 1MP"},
+ }
+ for encoder in (NODES['pos_prompt'], NODES['neg_prompt']):
+ prompt[encoder]['inputs'][f'image{slot}'] = [scale, 0]
+ reference_slots.append((kind, slot))
+
# --- Prompt ---
user_prompt = _texturing_prompt(context.scene)
final_prompt = f"Modify image1 to {user_prompt}"
@@ -1116,17 +1158,27 @@ class _TexturingWorkflowMixin:
masked_edit['prompt'], bool(style_image_info), masked_edit.get('prompt_template'))
if depth_info:
final_prompt += "\n\nImage3 is a depth map of the same view; use it to preserve scene geometry."
-
+ for kind, slot in reference_slots:
+ if kind == 'edit':
+ final_prompt += (
+ f"\n\nImage{slot} is a reference for the edit: follow its design, shapes, colours and "
+ "any lettering inside the highlighted region, fitted to the surface's perspective, "
+ "material and lighting.")
+ else:
+ final_prompt += f"\n\nImage{slot} is the appearance reference."
+
prompt[NODES['pos_prompt']]['inputs']['prompt'] = final_prompt
if native_graph:
self._convert_native_edit_graph(prompt, NODES, context)
else:
# --- Reference Latent chain (Qwen unzoom fix) ---
- # The overlay is a semantic selection guide, never an appearance latent.
+ # The overlay is a semantic selection guide, never an appearance
+ # latent; a reference image is one, since its design is reproduced.
self._build_qwen_reference_latent_chain(
prompt, NODES,
- **({'latent_slots': ('image1',)} if masked_edit is not None else {}),
+ **({'latent_slots': ('image1',) + tuple(f'image{slot}' for _, slot in reference_slots)}
+ if masked_edit is not None else {}),
)
prompt[NODES['sampler']]['inputs']['seed'] = context.scene.seed
prompt[NODES['sampler']]['inputs']['steps'] = context.scene.steps
diff --git a/stablegen/ui/panel.py b/stablegen/ui/panel.py
index 80bb32c..4930061 100644
--- a/stablegen/ui/panel.py
+++ b/stablegen/ui/panel.py
@@ -1758,7 +1758,11 @@ class StableGenPanel(bpy.types.Panel):
style_box = content_box.box()
row = style_box.row()
row.prop(scene, "qwen_external_style_image", text="Style Image")
-
+ if (scene.model_architecture == 'qwen_image_edit' and scene.qwen_refine_use_prev_ref
+ and scene.qwen_refine_use_depth):
+ style_box.label(text="Qwen Image Edit takes three images: the style image replaces the depth map.",
+ icon='INFO')
+
# Timestep-zero reference method — shared across all Qwen modes
row = content_box.row()
row.prop(scene, "qwen_timestep_zero_ref", text="Timestep-Zero References (color shift fix)", toggle=True, icon="COLORSET_08_VEC")