Learn the panel.
Create your surface.

A visual reference for MotionSmith Surface in Blender. Follow the add-on from top to bottom, with every main panel explained in the order you see it.

MotionSmith Surface Video

Watch on YouTube ↗

01 / PANEL GUIDE

Server & Target Mesh

Open the 3D Viewport sidebar with N, then choose Surface. Start here before generating a texture.

Start Server: Starts the local ComfyUI backend configured in the add-on preferences. Wait for Server: Online before generating. Open Console Window shows the backend log when starting the server.
Refresh & browser buttons: Refresh checks the server connection. When online, the browser button opens the configured ComfyUI address. Stop Server shuts down the backend; use Cancel in the generation area to cancel a running job.
Texture / PBR Material: Texture generates and bakes views onto a target mesh. PBR Material extracts material maps from a single image. Page switching is disabled during generation.
Target Mesh: Select the mesh you want to texture. Its name, vertex count and face count appear here. A camera or another non-mesh object cannot be the texture target. Re-select the mesh after inspecting a camera.

02 / PANEL GUIDE

Texture Workflow

Choose how the surface is generated. The number of generated views is different from the number of Blender cameras you need.

6 Views — 1 Pass (Standard Fast): Generates six canonical views in one pass. In image-guided modes, it uses one reference image or one front-camera capture. A practical starting point before trying additional views.
10 Views — 2 Pass (Advanced Seamless): Generates six canonical views, then four diagonal views in a second pass. This takes more work than the six-view workflow and does not require ten Blender camera inputs.
Pass 2 Denoise: Controls how strongly the diagonal refinement changes the first-pass result. Lower values retain more of the first pass. Shown for the two-pass workflow.
10 Views — Manual Camera Inputs: Uses ten supplied views: front, left, back, right, top, bottom and four diagonals. Choose automatic Blender cameras, an image folder, or ten individual photos. Captured albedo is baked; the optional AI pass predicts metallic and roughness. Keep all views consistent with the same object and camera framing.
Low VRAM — GGUF: Uses the modular generation and baking workflow with quantized GGUF models. It exposes additional view, decode and unseen-surface repair settings. VRAM use still depends on model and resolution.

03 / PANEL GUIDE

Camera & Capture Setup

This section appears for image-guided Texture workflows. Prompt Only skips reference capture.

Setup Camera (1 Cam): Creates or aligns a calibrated front camera around the target mesh. The standard six-view and two-pass workflows use this single capture as their appearance reference when no image file is supplied.
View Camera: Switches the viewport to the chosen camera so you can inspect its framing. Keep the intended surface visible and avoid cropping the object.
Reference file or camera capture: A Reference Image selected under Generation Inputs supplies the image reference. If the field is empty, the front-camera capture is used. The camera capture includes the visible appearance of the scene, so check the material and lighting before capturing.
Manual 10 Views Input: This replaces the normal capture section for the manual workflow. Cameras renders the ten calibrated views; Folder and Individual Photos use your supplied files instead.

04 / PANEL GUIDE

Generation Inputs & Generate

Choose the source of the appearance, then submit the job. Presets are optional.

Input Mode: Prompt Only uses text and mesh geometry without an image reference. Image Only uses the reference file or front-camera capture and sends no text prompts. Prompt + Image combines both; an empty positive prompt uses image guidance only.
Preset: No Preset / Custom lets you keep or write your own prompt. Choosing Gold, Silver, Bronze, Marble, Wood or Leather replaces the positive prompt with that material description. A prompt describing gold can still steer the result toward gold even when you supply another reference image.
Positive Prompt: Describe the intended appearance. The default asks the model to preserve the reference colors, patterns and surface details. Edit it when you deliberately want a change. For strict image-only guidance, use Image Only.
Enable Negative Prompt / CFG: Enables separate negative conditioning. Negative Prompt describes unwanted features. This option uses additional compute and VRAM; leave it disabled unless you need it.
Reference Image: Choose an image from disk. Leave this empty to use the front-camera capture in image-guided modes. Prompt Only does not use this field.
Generate Texture: Starts the selected workflow for the active mesh. It requires an online server, a selected mesh and no active generation. Avoid changing the target while a job is running.
Cancel: Appears during generation and requests cancellation of the current job. It is separate from Stop Server.
Check / Apply Last Result: Checks the most recent submitted job and applies a completed result. Use this when generation finished but the result was not automatically applied. It does not submit a new generation.
Status & progress: Shows the current operation and, when available, progress and estimated time remaining for the current stage. The estimate is not the remaining time for the entire workflow. Applied to [mesh] confirms material application.

05 / PANEL GUIDE

Model Selection

Select installed model files for the Texture workflow. The refresh button reloads the available model choices.

Diffusion (UNET): The FLUX.2 Klein diffusion model. Choose the appropriate installed GGUF or supported safetensors model for your workflow.
Text Encoder (CLIP): The text encoder used to turn prompt text into conditioning. The supplied setup uses the Qwen text encoder.
VAE: Encodes and decodes images for FLUX.2. Use the matching FLUX.2 VAE.
Decoder: The UltraTex foreground decoder used by the texture workflow.
Albedo LoRA / MR LoRA: UltraTex adaptation weights for base-color generation and metallic/roughness prediction. They are separate files.
BG Removal: The background-removal model, such as BiRefNet, used to isolate the reference foreground.

06 / PANEL GUIDE

Workflow Parameters

These settings control sampling, image resolution, UV baking and material placement. Available fields change with the workflow.

Albedo Steps: Sampling steps for generated base color. More steps increase processing time; the manual camera workflow does not show this control.
Guidance / CFG: Controls text guidance where supported by the selected workflow. Negative CFG conditioning is controlled separately by Enable Negative Prompt / CFG.
Seed: The random seed used for sampling. Keep it fixed when comparing changes to the same workflow and inputs.
View Resolution: Resolution used per generated/captured view. It is separate from final Texture Size. Higher values increase memory use and processing time.
Generate Metallic / Roughness: Enables the additional metallic and roughness prediction pass. MR Sampling Steps and MR View Resolution control this pass independently.
Texture Size: Resolution of the final baked UV texture maps. A larger atlas cannot recover detail absent from the source views.
UV Mode: Comfy GPU creates a UV layout through the backend GPU path. xatlas uses the CPU chart packer. Keep Existing UVs uses the mesh’s current UV coordinates.
Material Slot Policy: Entire Mesh (All Slots) applies the atlas across the mesh. Active Slot Only replaces the active material slot. Append New Slot preserves existing slots and adds the new material, assigning it to selected faces or to all faces when none are selected.
Geometry Render Size / Alignment: For the standard workflows, geometry render size sets the geometry-projection render resolution. Alignment fits the reference to the front silhouette or centers it.
Generated Views / UV Padding: For Low VRAM — GGUF, choose 6 or 12 generated views and the padding around UV islands. More views add generation work; padding helps prevent color bleeding across island edges.

07 / PANEL GUIDE

Advanced Tuning

Start with the defaults. Change one setting at a time so you can judge the effect on the bake.

Albedo LoRA Strength / MR LoRA Strength: Control the contribution of the corresponding UltraTex LoRA. Albedo strength is hidden for the manual camera workflow.
Drop Background Tokens: Allows the native sampling path to discard background tokens.
Activation Memory Factor: Controls activation-memory reservation in the native sampler. Zero selects automatically.
Attention / Sparse Retention / Token Chunk: Select the native attention implementation and tune sparse retention and token processing chunks. These influence memory and sampling behavior.
Reprojection Keep Threshold / Feather: Two-pass controls for retaining and blending reprojected first-pass information during refinement.
View Weight Power / Best View Mix / Edge Feather: Native baking controls for camera-view weighting, blending with the preferred view and feathering projection edges.
Low VRAM: decode & bake: Tiled VAE Decode splits decoding into tiles. Fill Unseen Surfaces enables filling uncovered areas; Bake Blend selects the projection blend mode, and Unseen Surface Repair selects the repair method.
Low VRAM: extra angles: With 12 generated views, Extra Angle Mode chooses guided reprojection or independent generation. Extra Angle Steps and Extra Angle Denoise control the additional pass.

08 / PANEL GUIDE

PBR Material

Choose the PBR Material tab to extract maps from one image using the Chord workflow.

Image: Choose the source image. This page uses the image_to_material workflow and does not require the Texture page’s camera setup, presets or text prompts.
Generate PBR Material: Requires an online backend and an image path. Chord produces Base Color, Normal, Roughness, Metallic and Height maps.
Apply to mesh: Select a mesh in Object Mode with an active UV map before generating to apply the result to its active material slot. Without a suitable mesh, a material is created in Blender’s material list for manual assignment.
Height map: The height image is retained as a texture node; displacement is not connected automatically. Configure displacement or bump yourself if needed.
Cancel / Check / Apply Last Result: Use the same cancellation and result-recovery controls as on the Texture page. Generated image maps are packed into the blend file.

09 / PANEL GUIDE

Preferences & First Setup

Open Blender Preferences → Add-ons → MotionSmith Surface. Configure the backend before using the sidebar.

Overview: A short introduction to the Texture and PBR Material workflows and the basic startup sequence.
Backend: Set ComfyUI Directory to the extracted backend folder. Check Python Executable, Server URL and Server Port. The local installation checks show whether main.py, Python and the models directory exist. Show Server Console controls the backend console window.
Requirements: Lists the tested environment and dependencies. The add-on requires Blender 5.0 or later; the supplied Windows backend is intended for an NVIDIA CUDA setup. Actual memory use depends on the chosen model and workflow.
Models: Provides separate model download links, destination filenames and installed-file checks. Follow any rename notes, then refresh the installed models. Downloading the backend alone does not install model weights.

Backend and add-on files: MotionSmith Surface Backend on Hugging Face ↗

motionsmith-surface-docs