Transform your 3D texturing workflow with the power of generative AI, directly within Blender!
add user documentation
sakalond92ea4eca7771
diff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 0000000..f399a83--- /dev/null+++ b/docs/README.md@@ -0,0 +1,37 @@+# StableGen documentation++StableGen is a Blender add-on that generates and textures 3D assets through a [ComfyUI](https://github.com/comfyanonymous/ComfyUI) server. These pages describe how to install, configure and use it.++## Getting started++| Page | Contents |+|---|---|+| [Installation](installation.md) | Requirements, ComfyUI dependencies, installing the add-on and configuring its preferences. |+| [Manual installation](MANUAL_INSTALLATION.md) | Downloading ComfyUI custom nodes and models by hand instead of using `installer.py`. |+| [Quick start](quick-start.md) | Texturing an existing model and generating a mesh with TRELLIS.2 in the StableGen panel. |++## Texturing++| Page | Contents |+|---|---|+| [Architectures and presets](architectures-and-presets.md) | Supported model architectures, the built-in presets and saving your own. |+| [Generation modes](generation-modes.md) | The texture workflows: Separately, Sequentially, Grid, Refine, Local Edit, Masked Edit and UV Inpaint. |+| [Masked Edit](masked-edit.md) | Painting a selection on the model and regenerating only that region. |+| [Cameras](cameras.md) | Adding and placing cameras, per-camera resolution, generation order and view prompts. |+| [PBR maps](pbr.md) | Extracting roughness, metallic, normal and other maps, and baking them. |++## Mesh generation and rigging++| Page | Contents |+|---|---|+| [TRELLIS.2 mesh generation](trellis2.md) | Image and prompt to 3D, texture modes, the preview gallery, folder batches and third-party licenses. |+| [Rigging and animation](rigging-and-animation.md) | SkinTokens auto-rigging and retargeting FBX or BVH animation onto a rig. |++## Output and automation++| Page | Contents |+|---|---|+| [Export](export.md) | Baking textures, exporting for game engines, orbit GIF/MP4 renders and 3D printing. |+| [Batch processing and the Scene Queue](batch-and-queue.md) | Queuing scenes, TRELLIS.2 folder batches and DAE/GLB batch texturing. |+| [Output files](output-files.md) | Layout of the output directory. |+| [Troubleshooting](troubleshooting.md) | Common problems and how to resolve them. |diff --git a/docs/architectures-and-presets.md b/docs/architectures-and-presets.mdnew file mode 100644index 0000000..54f37cf--- /dev/null+++ b/docs/architectures-and-presets.md@@ -0,0 +1,93 @@+# Architectures and presets++## Architectures++The **Architecture** menu selects the model family. Each architecture needs its own models on the ComfyUI server; see [Installation](installation.md#2-install-comfyui-dependencies).++| Architecture | Checkpoint list comes from | Guidance | Notes |+|---|---|---|---|+| SDXL | `models/checkpoints` | ControlNet (Depth, Canny, Normal) and IPAdapter | Supports every [generation mode](generation-modes.md). |+| Qwen Image Edit | `models/diffusion_models` and GGUF models | Reference images: a guidance map, previous or initial views, or an external style image | Uses the Qwen workflows: Generate, Refine, Local Edit and Masked Edit. |+| Qwen Image 2.1 | `models/diffusion_models`, filtered to Qwen Image 2.1 files | As Qwen Image Edit | The presets prompt for RGBA views; transparent pixels are excluded from projection. Non-commercial use only ([Qwen Research License](https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE)). |+| TRELLIS.2 | — | — | Generates a mesh from an image or prompt, then optionally textures it with one of the other architectures. See [TRELLIS.2](trellis2.md). |++The Qwen architectures use their own set of workflows and do not offer Grid or UV Inpaint. See [Generation modes](generation-modes.md#qwen-workflows).++### Deprecated architectures++**FLUX.1** and **FLUX.2 Klein** no longer receive support. They are hidden from the architecture menus, and their presets are hidden, unless **Enable Deprecated Architectures** is enabled in the add-on preferences. A file saved with a deprecated architecture keeps that selection and remains readable, but you must enable the preference to apply its presets.++## Presets++A preset sets many generation and blending parameters at once. The built-in presets cover the common cases and are the recommended starting point.++In the StableGen panel, the **Preset** menu lists only the presets for the current architecture, and choosing one applies it immediately. In the legacy panel, choose a preset and click **Apply Preset**. Hover over a preset to read its description.++When you change a setting so that it no longer matches any preset, the menu shows **Custom**. Choosing the preset again restores its values.++There are 38 built-in presets. By default, 33 are shown: one is visible only with **Enable Experimental Texturing Features**, and four only with **Enable Deprecated Architectures**.++### SDXL (8)++| Preset | Workflow | Use |+|---|---|---|+| Default | Sequentially | General-purpose texturing. |+| Model Is Important | Sequentially | As Default, with stronger depth ControlNet guidance. |+| Characters | Sequentially | Characters; uses the first view as an IPAdapter reference. |+| Characters (Alternative Masking) | Sequentially | Alternative masking for more consistent views; may produce more artifacts. Try it if Characters fails. |+| Quick Draft | Grid | Fast previews. |+| Uv Inpainting | UV Inpaint | Fills untextured areas in UV space. Bake textures first to control the unwrap. |+| Architecture | Separately | Buildings and flat surfaces; each surface point takes the most direct camera. |+| Local Refine | Local Edit | Adds detail to specific areas using cameras pointed at them. |++### Qwen Image Edit (12)++| Preset | Workflow | Use |+|---|---|---|+| Qwen Precise | Generate | Detailed results when cameras overlap well. |+| Qwen Precise+ | Generate | Qwen Precise with Confidence-Gated Context, Acquisition Quality Weighting and Depth/Part Projection Guard. |+| Qwen Safe | Generate | Uses the first view as a reference for every later view; more consistent when coverage is limited. |+| Qwen Alt | Generate | Combines context renders with sequential references. |+| Qwen Voronoi | Generate | Assigns each surface point to its closest camera during generation, then blends softly. |+| Qwen Precise / Safe / Alt / Voronoi (Nunchaku) | Generate | The same four strategies for the Nunchaku model. Requires the Nunchaku nodes. |+| Local Edit (Qwen) | Local Edit | Targeted changes in areas the cameras point at. |+| Refine (Qwen) | Refine | Restyles the whole existing texture. |+| Qwen 2509 Full Steps (Experimental) | Generate | Base-model comparison without the Lightning LoRA. Shown only with experimental features enabled. |++### Qwen Image 2.1 (6)++| Preset | Workflow | Use |+|---|---|---|+| Qwen 2.1 Precise | Generate | Projected context renders; best with overlapping cameras. |+| Qwen 2.1 Precise+ | Generate | Qwen 2.1 Precise with Confidence-Gated Context, Acquisition Quality Weighting and Depth/Part Projection Guard. |+| Qwen 2.1 Safe | Generate | Uses the first view as an appearance reference for every later view. |+| Qwen 2.1 Context + Reference | Generate | Combines projected context with the first view as a persistent reference. |+| Local Edit (Qwen 2.1) | Local Edit | Targeted changes in areas the cameras point at. |+| Refine (Qwen 2.1) | Refine | Restyles the whole existing texture. |++### TRELLIS.2 Pipeline (8)++| Preset | Texture mode | Use |+|---|---|---|+| Default (Mesh + Texture) | SDXL | General objects. |+| Trellis.2 (Mesh Only) | None | Geometry only. |+| Characters (Mesh + Texture) | SDXL | Characters; does not texture downward-facing surfaces. |+| Architecture (Mesh + Texture) | SDXL | Buildings and objects with flat walls and sharp angles. |+| Qwen Precise (Mesh + Texture) | Qwen Image Edit | Detailed results when cameras overlap well. |+| Qwen Safe (Mesh + Texture) | Qwen Image Edit | Uses the TRELLIS.2 input image as a style reference. |+| Qwen Alt (Mesh + Texture) | Qwen Image Edit | General-purpose Qwen pipeline with additional context renders. |+| Qwen Voronoi (Mesh + Texture) | Qwen Image Edit | Hard camera segmentation during generation, then soft blending. |++### FLUX.2 Klein (Deprecated) (4)++Klein Precise, Klein Safe, Klein Alt and Klein Voronoi follow the same strategies as the Qwen presets of the same names.++## Saving your own presets++1. Adjust the settings. The preset menu shows **Custom**.+2. Click **Save** (StableGen panel) or **Save Preset** (legacy panel).+3. Enter a **Preset Name** and an optional **Description**. **Include ControlNet Units** and **Include LoRA Units** control whether those lists are stored.++The name is stored in upper case. Saved presets appear in the menu alongside the built-in ones, and the delete button removes them. Built-in presets cannot be deleted.++Saved presets are kept in memory only and are lost when Blender is closed.diff --git a/docs/batch-and-queue.md b/docs/batch-and-queue.mdnew file mode 100644index 0000000..424b2ae--- /dev/null+++ b/docs/batch-and-queue.md@@ -0,0 +1,115 @@+# Batch processing and the Scene Queue++StableGen has three ways to process many assets without supervision:++| Feature | Input | Use it to |+|---|---|---|+| [Scene Queue](#scene-queue) | Snapshots of `.blend` scenes | Run several prepared scenes, each with its own settings. |+| [TRELLIS.2 folder batches](#trellis2-folder-batches) | A folder of images | Generate one asset per image. |+| [DAE/GLB batch texturing](#daeglb-batch-texturing) | A folder of `.dae` or `.glb` models, or a CSV manifest | Import, texture, bake and export existing models. |++## Scene Queue++Enable **Enable Scene Queue** in the add-on preferences. In the StableGen panel, open **Scene queue** from the **More** menu.++### Adding scenes++Set up a scene completely, including cameras, prompt and preset, then click **Add Scene**. Enter a short name; it defaults to the start of the prompt. StableGen saves a copy of the current `.blend` file to `<output directory>/queue_jobs/<name>_<date>_<time>.blend` and adds it to the list. The open file is not changed, and later edits to it do not affect the queued copy. You can continue editing the scene and add it again with different settings.++An output directory must be set before you can add scenes.++### Processing++Click **Process Queue**. For each pending item, StableGen opens its snapshot, runs the generation and saves the snapshot when it finishes. Scenes with the TRELLIS.2 architecture run the full mesh pipeline (with the preview gallery turned off); other scenes run texturing with all cameras.++A failed item is retried from a fresh copy of its snapshot, up to three attempts in total. After that it is marked as failed with the reason, and the queue moves on. Items already completed are skipped when you process the queue again.++The queue is saved to `sg_scene_queue.json` in the output directory and survives restarting Blender. If Blender closes while the queue is running, processing resumes when a file is next opened.++| Command | Effect |+|---|---|+| Open | Opens the snapshot of the selected item, including its results once it has finished. |+| Reset | Marks a finished or failed item as pending again. For TRELLIS.2 items, it also removes the generated meshes and cameras from the snapshot. |+| Remove, Clear | Remove one or all items. The snapshot files of items that have not finished are deleted. |+| Move Up, Move Down | Change the processing order. |++### Orbit export after each item++Enable **Export Orbit GIF/MP4** to render a turntable after each item. The options match the [orbit export](export.md#orbit-gif-and-mp4) and use the camera whose name sorts first. **Also Export Without PBR** adds a second render without PBR maps, saved as `orbit_no_pbr.gif` and `.mp4`.++## TRELLIS.2 folder batches++With the TRELLIS.2 architecture and **Generate From** set to **Image**, click the folder button next to **Input Image** and choose a folder of images. StableGen processes every `.jpg`, `.jpeg`, `.png`, `.webp`, `.bmp`, `.tiff` and `.tif` file in the folder (not its subfolders) in name order, using the current TRELLIS.2 and texturing settings for all of them. Click **Generate Batch** to start and **Cancel Batch** to stop.++| Option | Default | Purpose |+|---|---|---|+| Name meshes after input files | On | Name each mesh after its image, with `_01`, `_02` suffixes when a model has several meshes. |+| Bake Textures after each model | On | Bake each model when its texturing finishes. **Bake Settings** sets the resolution, unwrap method, PBR maps, ORM packing and normal convention, as for [Bake Textures](export.md#bake-textures). |++While a model is being generated, all objects from before the batch and from earlier models are hidden, so that cameras, texturing and baking only see the current model. Finished models are moved to a **Batch Results** collection, excluded from rendering, and shown again when the batch ends. The cameras created for each model are deleted.++A plain-text log, `stablegen_batch_<date>_<time>.txt`, is written to the image folder. It records the shape, texture and bake times for each image and the total time.++## DAE/GLB batch texturing++**Batch texture DAE / GLB** on the **Tools** page imports a set of models, textures each one with the current scene settings, bakes it and exports a textured `.glb`. It requires a connected ComfyUI server.++For each model, StableGen:++1. Imports and prepares it. DAE files go through the [SketchUp cleanup](#sketchup-dae-import). GLB files receive light preparation only: non-mesh objects are removed, meshes are joined and the model is centered with its lowest point at zero.+2. Places cameras using the settings in the TRELLIS.2 **Camera Placement** section.+3. Applies the reference image, if any, as IPAdapter input for SDXL or as the external style image for Qwen.+4. Generates the textures, bakes them to a new UV map and exports the `.glb`.++### Options++| Option | Default | Purpose |+|---|---|---|+| Output Directory | `<input folder>/textured` | Where the textured `.glb` files are written, mirroring the input folder structure. |+| Recursive | On | Include subfolders. |+| Batch Manifest | — | A CSV file listing models, references and outputs. See below. |+| Reference Images | — | A folder of reference images, matched to models by file name. |+| Bake Textures | On | Bake before export. |+| Bake Resolution | 2048 | Size of the baked maps. |+| Replace Materials | On | Remove imported materials before texturing. |+| Generation Retries | 2 | How often a failed model is re-imported and retried. |+| Continue After Failed Model | On | Skip a model that still fails, instead of stopping the batch. |++Without a manifest, a model's reference image is the first image in **Reference Images** whose name contains the model's file name as a whole word, or else a file named `ref.png`, `ref.jpg` or `ref.jpeg` next to the model, in the reference folder, or in the top input folder.++### CSV manifest++A manifest gives an exact reference image and output path for each model. It is a UTF-8 CSV file with a header row and three required columns; other columns are ignored.++| Column | Contents |+|---|---|+| `model_path` | A `.dae` or `.glb` file. |+| `reference_path` | A `.png`, `.jpg`, `.jpeg`, `.webp`, `.bmp` or `.tiff` image. |+| `output_path` | The output file, ending in `.glb`, relative to the output directory. |++```csv+model_path,reference_path,output_path+models/house_01.glb,refs/house_01_front.png,out/house_01.glb+```++`model_path` and `reference_path` are relative to the folder containing the manifest and must stay inside it. StableGen rejects the whole manifest before starting if a file is missing, a path is absolute or leaves the folder, a type is unsupported, or a model or output path appears twice; the error names the row. If no manifest is set but the input folder contains `batch_manifest.csv`, that file is used. In manifest mode the reference image is required, and the batch stops if one cannot be found.++### Resuming and failures++Models whose output `.glb` already exists are skipped, so you can stop a batch and run it again to continue. Failed bakes are retried without regenerating the images. Models that still fail after all retries are recorded in `batch_failures.json` in the output directory, with the stage, error and number of attempts.++### SketchUp DAE import++**Import DAE** imports a single COLLADA file from SketchUp and prepares it for texturing. **Batch import DAE** converts a folder of `.dae` files to `.glb` or `.fbx` with the same cleanup, without texturing.++| Option | Default | Purpose |+|---|---|---|+| Merge Distance | 0.001 | Merge vertices closer than this. |+| Remove Interior Faces | On | Remove faces enclosed inside the mesh, such as internal walls. |+| Replace Materials | On | Replace imported materials with a plain Principled BSDF. |+| Join Meshes | On | Join all parts into one mesh. |+| Topology | Fix Triangle Fans | **None**, **Fix Triangle Fans** (re-triangulates the long thin triangles SketchUp produces), **Subdivide Large Faces**, **Dissolve + Subdivide** or **Voxel Remesh** (loses sharp edges). |+| Triangulate | On | Convert all faces to triangles. |+| Target Size (BU) | 0 | Scale the model to this size; 0 keeps its size. |+| Shading | Flat | **Flat**, **Smooth** or **Auto Smooth**. |+| Center at Origin | On | Center the model and place its lowest point at zero. |diff --git a/docs/cameras.md b/docs/cameras.mdnew file mode 100644index 0000000..00ee5ae--- /dev/null+++ b/docs/cameras.md@@ -0,0 +1,103 @@+# Cameras++StableGen generates one image per scene camera and projects it onto the meshes, so the cameras decide which surfaces receive texture and from which direction. Every camera in the scene is used. There is no fixed limit on the number of cameras; more cameras give better coverage but take longer.++The camera commands are in the panel toolbar. The **Cameras** page lists the scene cameras with their generated images, view prompts and generation order.++## Add Cameras++**Add cameras** opens a dialog for placing a set of cameras around the subject. By default it first removes all existing cameras (**Remove Existing Cameras**).++<!-- screenshot: add-cameras-dialog -->++### Placement modes++| Mode | Behavior |+|---|---|+| Orbit Ring | Places cameras in a circle around the center, at the elevation of the reference camera or viewport. |+| Sphere Coverage | Distributes cameras evenly over a sphere. |+| Auto (Normal-Weighted) | Default. Clusters the mesh's face normals, weighted by area, and places a camera for each cluster. |+| Auto (PCA Axes) | Places cameras along the mesh's principal axes. Produces at most six directions. |+| Auto (Greedy Coverage) | Adds cameras one at a time, each covering the most new surface, until **Coverage Target** is reached or **Max Cameras** cameras exist. Determines the count itself. |+| Fan from Camera | Spreads cameras in an arc of **Fan Angle** degrees around the active camera's position. |++Orbit Ring and Fan from Camera use the active camera, or the current view if there is none, as the reference, and its distance from the center as the radius. **Center Type** selects whether the center is the active object or the view center.++The four automatic modes (Sphere Coverage and the three Auto modes) compute each camera's distance from the mesh silhouette and offer further options:++| Option | Purpose |+|---|---|+| Occlusion Handling | How self-occlusion is considered. See below. Not shown for Sphere Coverage. |+| Auto Aspect Ratio | **Off**, **Shared** (one aspect ratio for all cameras) or **Per Camera** (default). See [Per-camera resolution](#per-camera-resolution). |+| Exclude Bottom Faces | Ignores downward-facing geometry, such as the underside of a building, beyond **Bottom Angle Threshold**. |+| Auto View Prompts | Gives each camera a direction prompt such as `front view` or `rear view, from above`. |+| Clamp Elevation | Limits cameras to between **Min** and **Max** elevation, avoiding extreme top-down or bottom-up views. |+| Consider Existing Cameras | When existing cameras are kept, treats them as already covering their directions. |++Running an automatic mode with **Auto View Prompts** off clears all existing view prompts.++### Occlusion handling++Occlusion handling is a separate option from the placement mode.++| Option | Behavior |+|---|---|+| None (Fast) | Back-face culling only; ignores self-occlusion. |+| Full Occlusion Matrix | Checks visibility with ray casting before placing cameras. Most accurate, slowest. |+| Two-Pass Refinement | A fast pass, then ray casting only for faces no camera sees. |+| Visibility-Weighted | Reduces the influence of mostly hidden faces. Normal-Weighted mode only; other modes use Full Occlusion Matrix. |+| Interactive Visibility | As Visibility-Weighted, with a live preview. Scroll (or press numpad plus and minus) to change the balance, **Enter** to confirm and **Esc** to cancel. Normal-Weighted mode only. |++Occlusion computation can take a while on dense meshes. Press **Esc** to cancel it.++### Reviewing the placement++With **Review Camera Placement** enabled (the default), the viewport looks through each new camera in turn using Blender's fly navigation. Adjust the camera if needed and confirm to move to the next one. Disable the option to create the cameras immediately.++## Other camera tools++| Toolbar button | Operator | Behavior |+|---|---|---|+| Clone | Clone Camera | Creates a camera at the active camera's position and starts fly navigation so you can move it. Useful for adding cameras one at a time. |+| Mirror | Mirror Camera | Creates a copy of the active camera mirrored across the X, Y or Z axis through the active mesh's origin (or the world origin if the active object is not a mesh), pointing at that center. |+| Auto aspect | Apply Auto Aspect | Recomputes aspect ratio, resolution and framing from the mesh silhouette for the selected cameras, or all cameras if none is selected. This keeps each camera's viewing direction but changes its distance and aim. |+| Display | Camera Display | Chooses which cameras show numbered labels and generated image previews, and whether actual image frames and state indicators are drawn. |++## Per-camera resolution++With **Auto Aspect Ratio** set to **Per Camera**, each camera gets its own resolution matched to the mesh silhouette, keeping roughly the same pixel count as the scene resolution. The values are stored on the camera object as the custom properties `sg_res_x` and `sg_res_y`, and StableGen switches to them while rendering and generating each view.++For display, the scene output resolution is set to a square of the largest side. Do not rely on **Output Properties > Resolution** to read a camera's actual size; the camera frame overlay shows it.++With **Shared**, StableGen instead sets the scene resolution to the average aspect ratio. With **Off**, every camera uses the scene resolution.++**Fit camera resolution** (in **Output & materials** on the **Texture** page, enabled by default) scales each camera's resolution to a target pixel budget while keeping its aspect ratio.++## Generation order++The **Cameras** page lists cameras in generation order. Without a custom order, cameras are processed in natural name order (`Camera_2` before `Camera_10`).++To set a custom order, drag a camera card by its handle, or click **Sort…** and choose a strategy. Either action enables **Custom generation order**.++| Strategy | Order |+|---|---|+| Alphabetical (Original) | By name. |+| Front → Back → Sides | Front-facing cameras first, then rear, then sides. |+| Back → Front → Sides | Rear first, then front, then sides. |+| Alternating (Opposites) | Alternates between opposite directions. |+| Top → Bottom | Highest elevation first. |+| Reverse Current | Reverses the current order. |++"Front" is the direction of the alphabetically first camera, not a world axis. The order matters most in **Generate Sequentially**, where the first view establishes the appearance that later views continue. The numbers on the viewport labels follow the same order.++## View prompts++A view prompt is extra text for one camera, such as `front view` or `close-up on face`. When **Use view prompts** is enabled on the **Cameras** page, it is placed before the main prompt for that camera's view.++There are three ways to edit view prompts:++- **Collect camera prompts** in the toolbar steps through the selected cameras, or all cameras, and asks for a prompt for each.+- On the **Cameras** page, select a camera card and edit its **View prompt** field.+- In the viewport, click the page icon on a camera's label to open an inline text field. **Ctrl Enter**, **Tab** or clicking outside saves; **Esc** cancels.++**Auto View Prompts** in Add Cameras fills the prompts from each camera's direction.diff --git a/docs/export.md b/docs/export.mdnew file mode 100644index 0000000..77f7230--- /dev/null+++ b/docs/export.md@@ -0,0 +1,114 @@+# Export++A StableGen texture is a projection material that combines the camera images at render time. To use the result elsewhere, bake it into ordinary UV textures, then export. All exported files are written to the current run folder in the output directory; see [Output files](output-files.md).++## Bake Textures++**Bake** in the panel footer (**Bake Textures** in the legacy panel) bakes the projected material of each target object into UV image maps with Cycles. It uses the **Target objects** setting to decide which meshes to bake. In the StableGen panel, the button is disabled while projection settings have changed but not been reprojected.++| Option | Default | Purpose |+|---|---|---|+| Texture Resolution | 2048 | Size of each baked map, 128 to 8192. |+| Render Samples | 16 | Cycles samples for the bake. |+| Denoise Baked Textures | On | Denoise the result. |+| Unwrap Method | Smart UV Project | How to create the bake UVs (see below). |+| Overlap Only | Off | Unwrap only objects whose existing UVs overlap. |+| Add Material | On | Create a material named `<object>_baked` that uses the baked maps. |+| Bake & Continue Refining | Off | Put the baked texture back into the StableGen projection material and remove the earlier projection images, so you can continue with Refine or Local Edit on a lighter material. |+| Bake PBR Maps | On | Bake each PBR channel to its own map. See [PBR maps](pbr.md#baking-pbr-maps). |+| Pack ORM Texture | Off | Also write a packed occlusion, roughness and metallic map. |+| Normal Convention | OpenGL (Y+) | **OpenGL (Y+)** or **DirectX (Y-)**. |++Unwrap methods:++| Method | Notes |+|---|---|+| None | Use the existing UVs. |+| Cube Project | Fast; suitable for very dense meshes such as TRELLIS.2 output. |+| Smart UV Project | A balance of quality and speed. |+| Basic Unwrap | Angle-based unwrap. Best quality but very slow on dense meshes. |+| Lightmap Pack | Lightmap Pack with default settings. |+| Pack Islands | Pack the existing islands. |++An object without its own UV map is always unwrapped, even with **None**. The bake is written to a UV map named `BakeUV`. The color map is saved as `baked/<object>.png`.++**Bake & Continue Refining** applies only to objects baked as a plain color map; objects baked through the PBR path keep their baked material.++## Export for Game Engine++**Export** in the panel footer (**Export for Game Engine** in the legacy panel) exports meshes and their rigs. It exports the materials currently on the objects and does not bake, so run **Bake** first.++| Option | Default | Purpose |+|---|---|---|+| Format | glTF Binary (.glb) | **glTF Binary (.glb)**, **glTF + Textures (.gltf)** (separate `.gltf`, `.bin` and image files), or **FBX (.fbx)** with embedded textures, for example for Unreal Engine. |+| Objects | Selected | **Selected** meshes or **All Mesh** visible meshes. Armatures that deform them are included automatically. |+| Apply Transforms | On | Apply object transforms. Skipped for rigged exports. |+| Export Animations | Off | Include animation actions. |++Selecting an armature also includes the meshes it deforms. Hidden objects and objects in collections whose names contain `not_exported` are excluded. glTF exports include tangents and use Y-up. The file is saved as `baked/<first mesh name>.glb` (or `.gltf` or `.fbx`).++FBX does not record which UV map a texture uses, so engines such as Unreal Engine read every texture through the first UV channel. When a mesh's materials all use one UV map, as after **Bake** (the `BakeUV` map), FBX export writes that map as the first channel. Material slots that no face uses, such as the projection material kept beside the baked one, are left out of the file. The mesh in Blender is unchanged.++## Orbit GIF and MP4++**Export orbit GIF / MP4** on the **Tools** page (**Export Orbit GIF/MP4** in the legacy panel) renders a turntable of the active object from the scene camera's distance and height, and saves both `orbit.gif` and `orbit.mp4` in the run folder. It requires an active mesh or empty and a scene camera.++| Option | Default | Purpose |+|---|---|---|+| Duration (seconds) | 5.0 | Length of one orbit. |+| Frame Rate (fps) | 24 | Frames per second. |+| Resolution % | 50 | Percentage of a 1024 × 1024 frame. |+| Samples | 32 | Render samples. |+| Render Engine | Cycles | **Workbench**, **Eevee** or **Cycles**. Use Cycles to show an unbaked projection material. |+| Rotation Curve | Linear | **Linear** or **Ease In/Out**. |+| HDRI Environment | Off | Use the world's environment texture, for example one added with **Add HDRI lighting**. Without one, a temporary sky is used. |+| Environment Rotation | 0° | Initial rotation of the environment. |+| Environment Mode | Fixed | **Fixed** (the environment stays still), **Locked** (it rotates with the camera, so lighting looks the same from every angle), **Counter-Rotate**, or **Environment Only** (the camera stays still and only the environment rotates). |+| Denoise | On | Denoise Cycles renders. |+| GPU Compute | On | Render Cycles on the GPU. Blender 5.1 and later. |++The background is rendered transparent.++## 3D printing++Enable **Enable 3D Printing** in the add-on preferences. The tools then appear on the **3D printing** page, opened from the **More** menu. In the legacy panel they are in a separate **StableGen Print** sidebar tab.++The exporters convert the texture into filament colors for multi-material printers.++### Filament palette++Choose a **Print Preset** or build your own palette:++| Preset | Palette |+|---|---|+| CMYW (Dithered) | Cyan, magenta, yellow and white, mixed by dithering. Default. |+| CMYK (Dithered) | Cyan, magenta, yellow and black, mixed by dithering. |+| CMYW + Mixes (Non-Dithered) | The four CMYW colors plus 1:1, 2:1 and 1:2 mixes of each pair, as solid colors. |+| CMYK + Mixes (Non-Dithered) | The same for CMYK. |+| Custom | Your own colors. Adding, removing or editing a color switches to Custom. |++With **Dithered (Full Spectrum)** enabled, colors are mixed by alternating filaments across layers. **Layer Height** (default 0.08 mm) and **Model Height** (default 50 mm) define the layer stack. Without dithering, each face is printed in the closest filament, and **Island cleanup passes** and **Saturation cutoff** remove small noisy color islands.++**Show Advanced Settings** exposes the color solver. **Color mixing model** defaults to **Kubelka-Munk**, a pigment-mixing model; **Linear Additive** and **Linear Subtractive** are alternatives. **Saturation Penalty** prevents desaturated colors from being mixed into saturated regions; high values favor primary colors.++### Preview++| Command | Effect |+|---|---|+| Preview Palette Colors | Shows the quantized colors on the active mesh in Solid shading. |+| Preview Slices | Slices and dithers the active mesh and shows the printed layers as a preview object, `SG_SlicedPreview`. Runs in the background. |+| Clear Preview | Removes the previews and restores material display. |++### Make Solid++AI-generated meshes are often open or have internal geometry. **Make Solid** (in the print settings, and as a command on the **Tools** page) keeps the outer shell found by ray casting from **Raycast Angles** directions, deletes internal geometry and fills holes at the bottom. When **Make Solid** is enabled in the print settings, the STL and 3MF exporters run it on a temporary copy; this requires running **Preview Palette Colors** first. **Keep Largest Island** removes disconnected fragments.++### Exporters++| Exporter | Output | Notes |+|---|---|---|+| Export 3MF | `baked/<first mesh>.3mf` | Multi-color 3MF with per-triangle colors and project metadata for OrcaSlicer, Bambu Studio and PrusaSlicer. |+| Export STL | `baked/<first mesh>.stl` | Geometry only, without color. Refuses meshes that are not closed unless Make Solid is used. |+| Export Textured OBJ | `baked/<object>_textured_print.obj` with `.mtl` and texture | For slicers that read image textures. Requires a baked base color image; run **Bake** first. Refuses open or non-manifold meshes. |++Each exporter offers **Objects** (**Selected** or **All Mesh**) and **Apply Transforms**.diff --git a/docs/generation-modes.md b/docs/generation-modes.mdnew file mode 100644index 0000000..2133118--- /dev/null+++ b/docs/generation-modes.md@@ -0,0 +1,88 @@+# Generation modes++The **Texture workflow** setting on the **Texture** page decides how StableGen creates or updates textures. (The legacy panel labels it **Generation Mode**.) Presets set it for you; change it when you want a different workflow.++Every workflow works from the scene cameras: StableGen renders guidance images from each camera, sends them to ComfyUI, and projects the returned images back onto the meshes. How the projections are combined is controlled on the **Blending** page. **Target objects** chooses whether all visible meshes or only selected meshes are textured.++The settings specific to the current workflow are in the **Mode settings** section of the **Texture** page.++## SDXL workflows++| Workflow | What it does |+|---|---|+| Generate Separately | Generates each camera's image independently. Earlier views are not used as context. |+| Generate Sequentially | Generates one camera at a time. Each new view inpaints the regions not yet covered by earlier views, using a render of the current texture as context. |+| Generate Using Grid | Generates all views together as a single grid image, then splits it into camera images. Fast, but at a lower resolution per view. |+| Refine/Restyle Texture (Img2Img) | Renders the existing texture from each camera and modifies it with the current prompt. Works on textures not made by StableGen. |+| Local Edit | Generates changes from existing views and blends them over the current projection with feathered edges. |+| Masked Edit | Regenerates only a region you paint on the model. See [Masked Edit](masked-edit.md). |+| UV Inpaint Missing Areas | Bakes the texture and inpaints untextured areas in UV space instead of camera space. |++### Generate Separately++Because views do not see each other, consistency depends on the shared prompt, geometry guidance and, optionally, IPAdapter. Enable **Use previous view as reference** to feed an earlier generated image to IPAdapter; **Reference source** selects the first or the most recent view, the original render, or the TRELLIS.2 input image. The **Architecture** preset uses this workflow with a high blending exponent, so each surface takes its texture from the most direct camera.++### Generate Sequentially++The camera [generation order](cameras.md#generation-order) matters in this workflow: the first view sets the appearance that later views continue. The visibility masks that decide what to inpaint are controlled by **Full-visibility tolerance**, **Coverage low point** and **Coverage high point**, and **Smooth previous-view coverage** produces soft rather than hard mask edges. The **Inpainting Options** section holds the masking settings shared with UV Inpaint, such as **Differential Diffusion**, **Blur Mask** and **Mask expansion (px)**.++**Use previous view as reference** works as in Separately. **Regenerate First Image** regenerates the first view with IPAdapter applied.++### Generate Using Grid++Enable **Refine generated views** to run an image-to-image pass over each view after the grid is split. The refinement has its own sampler, scheduler, **Edit strength**, steps, CFG and an optional **Refine Prompt**.++### Refine/Restyle Texture (Img2Img)++**Edit strength** controls how far each view may move from the current texture. Low values add detail; high values restyle.++### Local Edit++Point one or more cameras at the area to change and describe the change. The new images blend over the existing material instead of replacing it. Blending is controlled by:++| Setting | Effect |+|---|---|+| Edit strength | How much each view may change. |+| Use Angle-Based Blending | Fades contributions on surfaces seen at a grazing angle, between **Angle ramp low point** and **Angle ramp high point**. |+| Image-frame fade | Fades contributions toward the edges of each camera image. |+| Projection silhouette fade | Fades contributions near the silhouette edges of the projection. |+| Match Colors to Viewport | Matches each new view's colors to the current texture before blending. Methods: MKL, Histogram, Reinhard, MVGD, HM–MVGD–HM and HM–MKL–HM. |++### UV Inpaint Missing Areas++UV Inpaint works on baked UV textures. Bake first with your preferred unwrap so that the inpainting does not have to unwrap during generation; the **Uv Inpainting** preset description recommends this. **Allow updating textured areas** lets the model also change areas that already have texture. **Ask for Object Specific Prompts** uses a separate prompt for each object instead of the shared prompt.++## Qwen workflows++With **Qwen Image Edit** or **Qwen Image 2.1**, the workflow menu offers four entries:++| Workflow | What it does |+|---|---|+| Generate | Generates new per-camera images. The Qwen presets generate the views sequentially. |+| Refine | Restyles the existing texture across all views. |+| Local Edit | Changes the areas the cameras point at and blends them over the existing material, as Local Edit above. |+| Masked Edit | Regenerates only a painted region. See [Masked Edit](masked-edit.md). |++Qwen workflows are guided by reference images rather than ControlNet and IPAdapter. They are configured in the **Image guidance** section:++| Setting | Purpose |+|---|---|+| Guidance Map | The structural image for each view: **Depth Map**, **Normal Map**, **Workbench Render** or **Viewport Render**. |+| Use External Image as Style | Use an image file as the style reference. **External for Initial Only** applies it to the first view only. |+| Use previous view as reference | Use the first or most recent generated view as a reference. |+| Context Render | In sequential generation, how the render of the current texture is supplied: **Disabled**, **Replace Style Image** or **Additional Context**. |+| Hard view segmentation | Assigns each surface point to its closest camera during generation. Used by the Voronoi presets. |++In Refine and Local Edit, **Use Previous Refined View** adds the last edited view as a reference and **Use Depth Map** adds the depth map as structural guidance.++Qwen sends instruction prompts to the model in addition to your text. Enable **Custom Guidance Prompts** to edit them; the reset buttons restore the defaults.++## Regenerating selected views++After a generation, select one or more cameras. The generate button changes to **Regenerate selected views**, which regenerates only those views and keeps the others. It requires a previous generation and is available when the workflow is Generate Separately or Generate Sequentially; Qwen **Generate** qualifies because the Qwen presets run it sequentially. Click **All views** in the footer to clear the camera selection.++## Reprojecting++**Reproject** rebuilds the projection from the saved camera images using the current blending settings. It does not generate new images, so it is the quickest way to try blending changes. In the StableGen panel, the **Bake** button is disabled until you reproject after changing a setting that affects projection.++**Mirror last projection** on the **Tools** page duplicates the last projection camera and its image across the chosen axes (**X** by default), which helps complete symmetric objects.diff --git a/docs/installation.md b/docs/installation.mdnew file mode 100644index 0000000..67ff11e--- /dev/null+++ b/docs/installation.md@@ -0,0 +1,131 @@+# Installation++StableGen has two parts: the Blender add-on and a ComfyUI server that runs the models. The server can run on the same computer or on another machine on your network.++Installation takes four steps:++1. [Install ComfyUI](#1-install-comfyui).+2. [Install the custom nodes and models StableGen needs](#2-install-comfyui-dependencies).+3. [Install the add-on in Blender](#3-install-the-add-on).+4. [Configure the add-on preferences](#4-configure-the-preferences).++A video walkthrough of an earlier version is available from Polynox: [StableGen installation and basic usage](https://www.youtube.com/watch?v=EVNYAMnn_oQ). Some labels have changed since it was recorded.++## Requirements++| Component | Requirement |+|---|---|+| Blender | 4.2 to 4.5, or 5.1 and later. Blender 5.0 is not supported. |+| Operating system | Windows (x64), Linux (x64) or macOS on Apple Silicon. These are the platforms the add-on package declares. |+| GPU | An NVIDIA GPU with CUDA is recommended for the ComfyUI server. See the [ComfyUI documentation](https://github.com/comfyanonymous/ComfyUI) for other hardware. |+| VRAM | About 8 GB for SDXL. Plan for 16 GB or more for Qwen Image Edit. |+| ComfyUI | A working ComfyUI installation. |+| Installer script | Python 3 with the `requests` package (`tqdm` is optional and adds progress bars), and Git on the `PATH`. |+| Disk space | ComfyUI, its models (roughly 10 GB to over 50 GB depending on the packages) and generated output. |++On Blender 4.2 to 4.5, projection uses Open Shading Language and StableGen switches Cycles to CPU rendering while it builds projection materials. Blender 5.1 and later use native Raycast shader nodes and do not need OSL.++TRELLIS.2 depends on compiled CUDA extensions. The installer warns that pre-built wheels are not available for Python 3.13 and recommends running ComfyUI with Python 3.12 if you use TRELLIS.2.++## 1. Install ComfyUI++Follow the [official ComfyUI installation guide](https://github.com/comfyanonymous/ComfyUI#installing). Install it in a dedicated directory, referred to below as `<ComfyUI>`, and check that ComfyUI starts and runs before continuing.++If ComfyUI will run on a separate machine, do steps 1 and 2 on that machine.++## 2. Install ComfyUI dependencies++`installer.py` in the root of this repository downloads the ComfyUI custom nodes and models StableGen uses and places them in the correct folders.++```bash+pip install requests tqdm+python installer.py <ComfyUI>+```++If you omit the path, the script asks for it. It checks that the folder contains `models` and `custom_nodes`, then shows a menu of packages. After you choose a package, it lists every component and asks for confirmation. Files that already exist are skipped, so you can run it again to add packages. Restart ComfyUI afterwards so it loads the new custom nodes.++| # | Package | Enables | Approx. download |+|---|---|---|---|+| 1 | Minimal Core | IPAdapter and SDXL Lightning LoRA. You supply an SDXL checkpoint and ControlNet models. | 7.3 GB |+| 2 | Core + Preset Essentials | Package 1 plus the depth ControlNet the built-in SDXL presets use. You supply an SDXL checkpoint. | 9.8 GB |+| 3 | Full SDXL Setup (recommended) | Package 2 plus optional ControlNet and LoRA models and the PBR nodes (Marigold, StableDelight). You supply an SDXL checkpoint. | 19.3 GB |+| 4 | Complete SDXL | Package 3 plus the RealVisXL V5.0 checkpoint. | 26.3 GB |+| 5 | Qwen Core | Qwen Image Edit 2509 (GGUF), its VAE and text encoder, a Lightning LoRA and the GGUF loader node. | 20.3 GB |+| 6 | Qwen Extras | Package 5 plus additional Qwen Lightning LoRAs. | 22.6 GB |+| 7 | Qwen Nunchaku | Package 5 plus the Nunchaku nodes and the Int4 Nunchaku model. | 33.0 GB |+| 8 | TRELLIS.2 | The ComfyUI-TRELLIS2 custom node and its Python environment. The models (about 15.4 GB) download on first use. | 20.4 GB |+| 9 | Marigold IID | The Marigold node for PBR extraction. Its models download on first use. | 0.01 GB |+| 10 | StableDelight | The StableDelight node and model, plus the Marigold node. | 3.3 GB |+| 11 | FLUX.2 Klein | The FLUX.2 Klein 4B model, text encoder and VAE. FLUX.2 Klein is deprecated; see [Architectures and presets](architectures-and-presets.md). | 12.4 GB |+| 12 | Marigold V2 | Optional Marigold V2 albedo and normal models: the int8 Qwen Image Edit 2509 base plus LoRAs, VAEs and conditionings. Uses ComfyUI core nodes (September 2026 or newer). See [PBR maps](pbr.md). | 23.3 GB |++Sizes include first-use downloads where noted. The first run that needs those models takes longer.++Common combinations:++| Goal | Packages |+|---|---|+| Texturing with SDXL | 3, or 4 to include a checkpoint |+| Texturing with Qwen Image Edit | 5, 6 or 7 |+| Mesh generation and SDXL texturing | 3 (or 4) and 8 |+| Mesh generation and Qwen texturing | 6 and 8 |+| Add PBR extraction to a Qwen setup | 10 (packages 3 and 4 already include it) |++When you choose the TRELLIS.2 package, the installer shows a license notice about the NVIDIA libraries used by its native texture mode. See [TRELLIS.2 third-party licenses](trellis2.md#third-party-licenses).++### Components the installer does not cover++- **Qwen Image 2.1.** Place the diffusion model in `<ComfyUI>/models/diffusion_models/`, the text encoder `qwen3vl_8b_w4a8.safetensors` in `models/text_encoders/` and the VAE `qwen_image_2.1_vae_bf16.safetensors` in `models/vae/`. StableGen expects these file names for the text encoder and VAE. The files are published in the [Comfy-Org/Qwen-Image-2.1](https://huggingface.co/Comfy-Org/Qwen-Image-2.1) repository. Qwen Image 2.1 is released under the [Qwen Research License](https://huggingface.co/Qwen/Qwen-Image-2.1/blob/main/LICENSE), which allows non-commercial use only (research or evaluation). Qwen Image Edit 2509 is Apache 2.0.+- **FLUX.1.** See [Manual installation](MANUAL_INSTALLATION.md). FLUX.1 is deprecated.+- **SkinTokens auto-rigging.** Requires a ComfyUI node providing `StableGenSkinTokensAutoRig`. See [Rigging and animation](rigging-and-animation.md). The [SkinTokens](https://github.com/VAST-AI-Research/SkinTokens) code and [model weights](https://huggingface.co/VAST-AI/SkinTokens) are MIT-licensed.++To install everything by hand instead, follow [Manual installation](MANUAL_INSTALLATION.md).++### After updating ComfyUI++TRELLIS.2 runs in an isolated environment that can fall behind a ComfyUI update. Re-run the installer, or repair without the menu, then restart ComfyUI:++```+python installer.py <ComfyUI> --repair+```++`--check` only reports problems. The installer pins the TRELLIS.2 node to a tested commit, so updating the node through ComfyUI-Manager can break it until the next StableGen installer update.++## 3. Install the add-on++1. Download the add-on ZIP file from the [Releases page](https://github.com/sakalond/stablegen/releases). Do not extract it.+2. In Blender, open **Edit > Preferences > Get Extensions** (or **Add-ons**).+3. Open the drop-down menu in the top-right corner and choose **Install from Disk**.+4. Select the ZIP file. StableGen is enabled after installation; if it is not, enable it in the **Add-ons** list.++You can also drag the ZIP file into the Blender window.++The add-on bundles its Python dependencies as wheels, so nothing else needs to be installed into Blender.++## 4. Configure the preferences++Open **Edit > Preferences > Add-ons > StableGen**. In the StableGen panel, the gear icon in the panel header opens the same page.++| Preference | Purpose |+|---|---|+| Output Directory | Folder where StableGen saves generated images, bakes and exports. Generation is disabled until this is set to an existing folder. See [Output files](output-files.md). |+| Server Address | Host and port of the ComfyUI server. Default `127.0.0.1:8188`. The refresh button next to it checks the connection and reloads the model lists. |+| Use Legacy Panel | Show the original sidebar panel instead of the current one. **Reset Tips** shows dismissed hints again. |+| Save Blend File | Save a copy of the `.blend` file with packed textures in the output folder after each generation. |+| Enable 3D Printing | Show the 3D printing palette and exporters. See [Export](export.md#3d-printing). |+| Enable Experimental Texturing Features | Show research controls and let their saved values take effect. |+| Enable Deprecated Architectures | Show FLUX.1 and FLUX.2 Klein and their presets. |+| Enable Scene Queue | Show the Scene Queue. See [Batch processing](batch-and-queue.md#scene-queue). |+| ControlNet Model Assignments | Which guidance types (Depth, Canny, Normal) each ControlNet model on the server supports. Refresh the list after adding models. StableGen guesses the types from the file names; correct any that are wrong. |++**Advanced Preferences** contains the viewport camera overlay color, **Enable Debug Settings** (diagnostic tools) and network timeouts. Raise **Mesh Generation Timeout** if TRELLIS.2 post-processing on a slow server times out.++### Allow online access++StableGen communicates with ComfyUI over HTTP and WebSocket, so Blender's online access must be enabled even when the server runs locally. Open **Edit > Preferences > System > Network** and enable **Allow Online Access**. Without it, the generate button reads **Enable online access in preferences**.++## Using a remote ComfyUI server++Set **Server Address** to the remote machine's address and port, for example `192.168.1.20:8188`. ComfyUI only accepts connections from the local machine by default, so start it with `--listen` (for example `python main.py --listen 0.0.0.0`) and allow the port through the firewall.++StableGen uploads its renders to the server and downloads the results through the ComfyUI API, so the two machines do not need a shared file system. Large transfers are subject to **Transfer Timeout** in the advanced preferences.diff --git a/docs/masked-edit.md b/docs/masked-edit.mdnew file mode 100644index 0000000..892d464--- /dev/null+++ b/docs/masked-edit.md@@ -0,0 +1,104 @@+# Masked Edit++Masked Edit changes only a painted region of an existing texture. It is available+for the SDXL, Qwen Image Edit and Qwen Image 2.1 architectures. See+[Generation modes](generation-modes.md) for the other texture workflows.++In the StableGen panel, choose **Masked Edit** as the **Texture workflow** on the+**Texture** page. The prompt field becomes **Edit instructions**, the painting+commands appear below the workflow selector, and the remaining controls are in the+**Mode settings** section. The main button reads **Edit painted selection**. With+**Use Legacy Panel** enabled in the preferences, the same controls appear in a+separate **Masked Edit** sidebar panel. The controls remain available in Object+Mode and Texture Paint Mode so they can be used while painting the selection.++1. Set **Target objects** (**Paint Targets** in the legacy panel) to **All Visible** for a complete character, or **Selected** for+ selected mesh objects, then click **Paint Selection**. White selects a surface;+ black erases it, and X swaps the colors. The viewport displays the mask+ directly: white is selected, black is unselected. Use Blender's brush controls for brush falloff and the panel's+ size/strength controls. **Clear Mask** removes the selection from every current+ paint target without leaving paint mode. A temporary joined copy lets strokes cross component+ meshes, with a separate mask per original mesh. The original objects remain+ separate and are restored when you click **Finish Painting**. The panel shows+ how many meshes are included. Clear Selection follows the same target scope.+2. Describe the change in **Edit instructions** (**Edit** in the legacy panel), for example “add a stitched badge to the jacket”.+ Avoid instructions to zoom, crop or change the camera.+3. Click **Edit painted selection** (**Generate Masked Edit** in the legacy panel). It follows the normal All/Selected texture+ object scope and uses the currently selected model, sampler, steps and LoRAs.+ StableGen shows the current preparation or ComfyUI sampling stage and a second+ overall bar covering the camera visibility scan and sequential view edits.+4. Inspect the result and choose **Apply** or **Discard**. Apply retains the+ projection layers; normal StableGen baking can flatten them afterwards.+ Discard restores the original mesh and material datablocks.++Each mesh gets its own packed mask image and a separate non-overlapping mask UV+map. Existing texture UVs are preserved. **Mask Resolution** defaults to 4096 and+can be raised to 8192 for close detail. Existing masks are resized to the selected+resolution, while preserving their contents, when **Paint Selection** starts.+Painting and generation currently support meshes using one material+across their faces, with StableGen color graphs, Principled BSDF or emission.+At least one free UV-map slot is required. Paint masks can be reused for later edits.+Painting uses Solid shading with the active mask texture for immediate brush+ feedback. The previous viewport shading and color mode are restored after painting.+ The textured material is temporarily hidden by this mask view; it is not modified.+Ctrl+Z uses a Masked Edit-specific undo boundary while painting. Brush strokes can+be undone normally, but Blender is prevented from undoing only part of the temporary+multi-mesh proxy setup. Reaching the start of the paint session leaves the proxy intact.++## Generation++Existing cameras are ranked by visible selection area weighted by facing angle.+Invisible/tiny selections are skipped. Each view renders the current material+again after previous projections; completed regions become context rather than+being edited repeatedly. Partially covered boundaries can receive further views.+No cameras are created. Regions invisible to every existing camera remain unchanged.++Qwen receives the clean render as image1 and, by default, the same render with a+translucent magenta overlay as image2. **Send Selection Guide to Qwen** can be+disabled for instruction-only editing. With the guide enabled, the driving prompt+first identifies the highlighted region as the content to replace, then inserts the+user's Edit text as the requested result. It also tells Qwen to preserve the camera,+geometry and unselected content and not to reproduce the marker. This explicit+target-first form prevents short phrases such as "make this triangle golden" from+being applied to a similar unselected shape. The user does not need to mention the+marker or its color. The overlay is excluded from the reference latent chain.++Enable **Custom Guidance Prompt** to edit the complete driving prompt sent to+Qwen. Use `{main_prompt}` where the contents of the **Edit** field should be+inserted. The reset button restores the tested request-first template. The custom+template affects Qwen only; SDXL continues to receive the Edit text directly.++**Use Depth Map** renders the current camera's normalized depth and sends it as+Image3. It is disabled by default because depth can improve geometry-sensitive+replacement edits while weakening material changes or small additive details.+Masked Edit suppresses external style and previous-view reference slots for this+request without changing the user's saved options. It does not use Qwen+sampler-level masking.++SDXL receives the current render and an expanded inpainting mask. **Edit strength**+controls denoising. This path uses standard masked VAE inpainting, independently+of the base preset's generation mode, Differential Diffusion and ControlNet settings.++The generated image is projected with a frozen copy of the painted surface mask,+per-view write mask and visibility weights. Edge Softness feathers inward. The+**Expand Selection** control first grows the camera-space write mask outward, then+Edge Softness feathers inward from that expanded boundary. An expansion equal to+or greater than the softness makes the original painted edge receive full weight,+which helps cover jagged edges and traces of the old texture. At zero expansion,+the original painted UV selection remains a strict projection boundary. Positive+expansion intentionally permits projection into the immediately surrounding visible+surface. The generation mask can extend farther for model context. The original material's Principled or+emission shader remains around the edited color, preserving its other inputs.++Changes inside the selection can still be misplaced by the model. Spatial+alignment is not guaranteed by a language instruction. A mismatched output size+is rejected; other semantic/alignment errors require inspecting the preview.++**Stop After Current View** (or Esc) waits for the active backend request to finish+and keeps completed views available for Apply/Discard. Failures leave a recoverable+preview; use Discard to revert. Do not alter camera positions or geometry during a run.++Each run has a separate output directory with per-view clean renders, remaining+masks, generation masks, overlay guides, generated/composited images, workflow+graphs and `masked-edit.json`. The original generation output location is restored+after the run. Image assets used by edit layers are packed into the blend file.diff --git a/docs/output-files.md b/docs/output-files.mdnew file mode 100644index 0000000..8436b05--- /dev/null+++ b/docs/output-files.md@@ -0,0 +1,50 @@+# Output files++StableGen saves everything it produces under the **Output Directory** set in the add-on preferences. Each generation run gets its own folder:++```+<Output Directory>/+└── <file name>/+ └── <YYYY-MM-DDTHH-MM-SS>/+```++`<file name>` is the name of the `.blend` file without its extension, or the scene name if the file has not been saved. The timestamp is set when a new generation starts. **Reproject** and **Regenerate selected views** reuse the folder of the run they continue, so their files are added to it.++Folders are created as needed, and empty folders are removed when a generation finishes, so a run folder contains only the folders its workflow used.++## Run folder contents++| Path | Contents |+|---|---|+| `generated/` | The image generated for each camera, before projection. |+| `controlnet/depth/`, `canny/`, `normal/` | Depth, edge and normal guidance renders for each camera. |+| `controlnet/workbench/`, `viewport/` | Workbench and viewport guidance renders, used by Qwen guidance maps. |+| `inpaint/render/` | Renders of the current texture, used as context in sequential, refine and local edit workflows. |+| `inpaint/visibility/` | Visibility and feathering masks. |+| `uv_inpaint/uv_visibility/` | UV-space visibility masks for UV Inpaint. |+| `generated_baked/` | Per-object results of UV Inpaint. |+| `pbr/` | Extracted PBR maps per camera and the settings used to make them. |+| `baked/` | Results of **Bake** (`<object>.png`, `<object>_BaseColor.png` and the other PBR maps, `<object>_ORM.png`), game engine exports, and 3D print exports. |+| `misc/` | Other intermediate renders and temporary upload images. |+| `prompts/` | Every ComfyUI workflow submitted during the run, one JSON file per request. |+| `debug/` | Output of diagnostic tools, such as projection line reports. |+| `prompt.json` | The most recent ComfyUI workflow, useful for inspecting what was sent to ComfyUI. For Qwen Image 2.1, it is an editable workflow that can be dragged into ComfyUI, and the exact API graph is saved beside it as `prompt_api.json`. |+| `view_plan.json` | The cameras, order and prompts used for the run. |+| `orbit.gif`, `orbit.mp4` | Orbit exports. |+| `<file name>_<timestamp>.blend` | A copy of the scene with packed textures, written when **Save Blend File** is enabled in the preferences. |++TRELLIS.2 runs also write the generated mesh as `trellis2_<date>_<time>.glb` and, when generating from a prompt, the input image as `trellis2_input_<date>_<time>.png`. Auto-rigging writes `stablegen_autorig_source_<...>.glb` and `stablegen_autorig_rigged_<...>.glb`.++## Masked Edit runs++[Masked Edit](masked-edit.md) uses a separate folder next to the normal run folders, named `<timestamp>-masked-<id>`. It contains `masked-edit.json` and a `view-NNN/` folder for each edited view with the render, masks, generated image and composite.++## Other locations in the output directory++| Path | Contents |+|---|---|+| `queue_jobs/` | `.blend` snapshots of [Scene Queue](batch-and-queue.md#scene-queue) items. Queue runs produce run folders named after these snapshots. |+| `sg_scene_queue.json` | The saved Scene Queue. |+| `regression/` | Results of the debug texturing regression. |++DAE/GLB batch texturing writes its `.glb` files and `batch_failures.json` to the batch's own output directory, and TRELLIS.2 folder batches write their log to the image folder. See [Batch processing](batch-and-queue.md).diff --git a/docs/pbr.md b/docs/pbr.mdnew file mode 100644index 0000000..59575b7--- /dev/null+++ b/docs/pbr.md@@ -0,0 +1,81 @@+# PBR maps++StableGen can derive physically based material maps from the generated images. After texturing, it runs material-estimation models on each camera image and projects the resulting maps onto the mesh in the same way as the color texture. The maps are estimates made from images; they are not measured material properties.++## Requirements++PBR extraction needs two ComfyUI custom nodes, plus optional model files for Marigold V2:++| Node pack | Used for | Installer package |+|---|---|---|+| ComfyUI-Marigold | Albedo, roughness, metallic, normal, height and the lighting residual | 9 (also included in 3, 4 and 10) |+| ComfyUI StableDelight | Highlight-free albedo | 10 (also included in 3 and 4) |+| Marigold V2 models (ComfyUI core nodes, September 2026 or newer) | Optional sharper albedo and normals; about 23 GB | 12 |++StableGen checks for both when it connects to the server. If either is missing, the PBR section shows **PBR nodes not detected on server**. The Marigold models download from Hugging Face on first use.++## Enabling extraction++Enable **PBR map extraction** in the **Output & materials** section of the **Texture** page, then choose the maps under **Maps to Extract**.++| Map | Source |+|---|---|+| Albedo | Depends on **Albedo Source** (below). |+| Roughness | Marigold IID-Appearance. |+| Metallic | Marigold IID-Appearance. |+| Normal | Depends on **Normal Model**: Marigold Normals or Marigold V2. Converted from camera space to world space. May cause triangle artifacts on voxel-remeshed geometry. |+| Height | Marigold depth estimation. Connected to the material's Displacement node, scaled by **Material displacement scale**. |+| AO | Geometry-based ambient occlusion using Blender's AO shader node, not a model. Bake it to get an image map. |+| Emission | Experimental. Detects self-illuminating regions (see below). |++Albedo, Roughness, Metallic and Normal are enabled by default.++### Albedo source++| Option | Behavior |+|---|---|+| Marigold IID (Flat Albedo) | Removes all lighting. May lose texture detail and tends to desaturate colors. |+| StableDelight (Delighted) | Removes specular highlights only and keeps diffuse shading and detail. **Delight Strength** controls how strongly. |+| Marigold IID-Lighting (Vibrant) | Albedo from the IID-Lighting model; usually more saturated. |+| Marigold V2 (Sharp Albedo) | Removes lighting while keeping fine texture detail and color, at up to **Marigold V2 resolution (px)**. Albedo of metals tends to come out dark. |++**Correct Albedo Saturation** compares the albedo with the original render and adjusts saturation to match. Only the object is measured; the area outside the generated image's alpha is ignored. It is recommended for Marigold IID (Flat Albedo). **Saturation Mode** chooses how the per-camera correction ratios are combined: **Median** (default), **Mean** or **Per Camera**.++**Use Albedo as Base Color** (on by default) uses the extracted albedo instead of the generated color texture as the material's base color.++### Emission++| Method | Behavior |+|---|---|+| IID-Lighting Residual | Runs Marigold IID-Lighting and uses the residual between the image and albedo times shading. Costs an extra model pass. |+| HSV Threshold | Selects bright, saturated pixels using **Minimum saturation** and **Minimum brightness**, blurred by **Detection blur (px)**. Fast; suits neon or sci-fi styles. |++Both methods can mistake highlights for emission. **Emission detection cutoff** removes weak candidates; **Emission Strength** sets the material's emission multiplier.++## Resolution and quality++| Setting | Effect |+|---|---|+| Use source size for inference | Run the models at the generated image's size instead of **Inference resolution (px)** (default 768). On by default. |+| Tiling | Process maps as a grid of tiles for more pixels per region: **Off**, **Selective** (albedo only, default), **All**, or **Custom** (choose the maps). |+| Tile grid | 2, 3 or 4, giving 4, 9 or 16 tiles. Time grows with the tile count. |+| Tile inference | **Tile Source Size** (default) processes each tile upscaled to the source image's size; **Inference Resolution** processes each tile at **Inference resolution (px)**. |+| Keep tiled output resolution | Keep the larger tiled result instead of resizing to the source size. Uses more memory. |+| Inference steps | Sampling steps per map (default 4). |+| Predictions per map | Number of predictions averaged for each map (default 1). |+| Marigold V2 resolution (px) | Longest edge Marigold V2 processes at (default 2048). Images are processed at their own size within 1024 px and this limit. Marigold V2 ignores the other settings in this table. |++**Studio Lighting** adds a three-point light rig after projection to show the materials.++StableGen stores the settings used for each map and reuses existing maps when you reproject without changing them.++## Baking PBR maps++**Bake** turns the projected maps into UV image textures. With **Bake PBR Maps** enabled (the default), each channel connected to the material is baked to its own file in the `baked` folder: `<object>_BaseColor.png`, `_Roughness`, `_Metallic`, `_Normal`, `_Emission`, `_Height` and `_AO`. Normal maps are baked in tangent space.++| Option | Effect |+|---|---|+| Pack ORM Texture | Also writes `<object>_ORM.png` with ambient occlusion in red, roughness in green and metallic in blue. Requires roughness and metallic maps; red is white if there is no AO map. |+| Normal Convention | **OpenGL (Y+)** for glTF, Unity and Blender, or **DirectX (Y-)** for Unreal Engine, which flips the green channel. |++See [Export](export.md#bake-textures) for the other bake options.diff --git a/docs/quick-start.md b/docs/quick-start.mdnew file mode 100644index 0000000..57e9c8b--- /dev/null+++ b/docs/quick-start.md@@ -0,0 +1,73 @@+# Quick start++This page walks through two common tasks in the StableGen panel: texturing a model you already have, and generating a new textured mesh with TRELLIS.2. It assumes you have completed [Installation](installation.md) and that ComfyUI is running.++## The StableGen panel++Press **N** in the 3D Viewport and open the **StableGen** tab. The StableGen panel is the default interface. To use the original panel instead, enable **Use Legacy Panel** in the add-on preferences.++<!-- screenshot: panel-overview -->++From top to bottom, the panel contains:++| Area | Contents |+|---|---|+| Header | A search button (**Ctrl K**) for finding any setting, and a gear button that opens the add-on preferences. |+| Toolbar | **Add cameras** and **Collect camera prompts**, then **Clone**, **Mirror**, **Auto aspect** and **Display**. Hidden when TRELLIS.2 generates a mesh without diffusion texturing. |+| Architecture and Preset | The model family, and a preset menu filtered to that family. Choosing a preset applies it immediately. The buttons beside the menu save, apply or delete presets. |+| Page tabs | **Texture**, **Cameras**, **Blending** and **Tools** for texturing. With the TRELLIS.2 architecture, a **Mesh** tab comes first and **Tools** moves to the **More** menu. **More** also opens **Scene queue**, **Diagnostics**, **Mesh & rig**, **3D printing** and **Experiments** when they are available. |+| Footer | A status line, the main generate button, and **Reproject**, **Bake** and **Export**. While a job runs, the footer shows progress bars and a stop button. |++The status line shows the number of views and the target objects, or the reason generation is unavailable, such as **ComfyUI offline**. When the server is offline, a refresh button appears next to the generate button.++If the sidebar is narrow, the panel places settings in a single column. Drag the sidebar's left edge to widen it.++## Texturing an existing model++1. **Prepare the scene.** Add or open a mesh. StableGen textures all visible meshes by default; to texture only some, select them and set **Target objects** to **Selected** in step 5. Apply modifiers and convert curves to meshes first if needed; both commands are on the **Tools** page.++2. **Add cameras.** Select the mesh and click **Add cameras**. The defaults, **Auto (Normal-Weighted)** placement with four cameras, are a reasonable start. With **Review Camera Placement** enabled, the viewport flies through each camera; adjust it if needed and press **Space** to move on. See [Cameras](cameras.md) for the other placement modes.++ <!-- screenshot: add-cameras-dialog -->++3. **Choose an architecture and preset.** Set **Architecture** to **SDXL**, **Qwen Image Edit** or **Qwen Image 2.1**, depending on the models you installed. Then choose a preset. **Default** and **Characters** are good SDXL starting points; **Qwen Precise** and **Qwen Safe** are the corresponding Qwen Image Edit presets. Hover over a preset for its description. See [Architectures and presets](architectures-and-presets.md).++4. **Choose a checkpoint.** On the **Texture** page, under **Texture input**, select a model in **Checkpoint**. If the list is empty, click the refresh button beside it.++5. **Write the prompt.** Describe the surface in **Texture prompt**, for example `weathered bronze statue, green patina`. Leave **Texture workflow** as set by the preset; the presets mostly use **Generate Sequentially** (shown as **Generate** for Qwen). See [Generation modes](generation-modes.md).++ <!-- screenshot: texture-page -->++6. **Generate.** Click **Generate textures**. The footer shows the overall progress and the current step. You can follow the camera images as they arrive on the **Cameras** page.++7. **View the result.** Switch the viewport to **Rendered** shading. The projection material is built for Cycles, which StableGen selects as the render engine, so the texture does not appear in Solid or Material Preview shading until you bake it.++8. **Refine or finish.** Change blending settings on the **Blending** page and click **Reproject** to rebuild the material from the same images without generating new ones. To regenerate individual views, select their cameras; the button changes to **Regenerate selected views**. When you are satisfied, click **Bake** to convert the result into ordinary UV textures, then **Export**. See [Export](export.md).++Generated files are saved in the output directory. See [Output files](output-files.md).++## Generating a mesh with TRELLIS.2++This requires the TRELLIS.2 package from the installer. On first use, ComfyUI downloads the TRELLIS.2 models (about 15 GB).++1. **Choose the architecture.** Set **Architecture** to **TRELLIS.2**. The **Mesh** tab appears.++2. **Choose a preset.** The **(Mesh + Texture)** presets generate a mesh and then texture it with SDXL or Qwen Image Edit. **Trellis.2 (Mesh Only)** produces geometry only. **Default (Mesh + Texture)** is a general starting point; the Qwen variants suit stylized objects, legible text and image-to-3D work.++3. **Provide the input.** On the **Mesh** page, under **Mesh input**, set **Generate mesh from**:+ - **Image**: choose an image in **Input Image**. The mesh follows that image.+ - **Prompt**: describe the object. StableGen first generates an image from the prompt, then builds the mesh from that image. Enable **Preview gallery** to generate several candidate images and pick one before the mesh is built.++ <!-- screenshot: mesh-page -->++4. **Check the texture settings.** On the **Texture** page, **Texture mode** selects how the mesh is textured: **None**, **Native (TRELLIS.2)**, or a diffusion architecture. By default the mesh prompt is also used for texturing; enable **Use separate texture prompt** to describe the texture separately.++5. **Optional: PBR maps.** Enable **PBR map extraction** in the **Output & materials** section of the **Texture** page. See [PBR maps](pbr.md).++6. **Generate.** Click **Generate asset**. StableGen generates the mesh, imports it, places cameras around it and runs the selected texturing workflow.++7. **Refine.** Adjust view prompts and regenerate individual views as for any textured model, or switch to the **Local Edit** workflow to change specific areas. See [Generation modes](generation-modes.md#local-edit).++To use the result in a game engine, click **Bake**. Meshes from TRELLIS.2 usually need new UVs: keep **Unwrap Method** at **Smart UV Project**, or use **Cube Project** for very dense meshes. Then click **Export**. See [Export](export.md).++See [TRELLIS.2 mesh generation](trellis2.md) for all settings, batch generation from a folder of images, and the third-party license terms.diff --git a/docs/rigging-and-animation.md b/docs/rigging-and-animation.mdnew file mode 100644index 0000000..1cd5bb9--- /dev/null+++ b/docs/rigging-and-animation.md@@ -0,0 +1,71 @@+# Rigging and animation++StableGen can add a skeleton to a character mesh with SkinTokens, running on the ComfyUI server, and retarget FBX or BVH animation onto a rig in Blender.++## Where the tools are++| Tool | Location in the StableGen panel |+|---|---|+| Auto-rig selected character | **Tools** page, **Mesh & rig utilities**. Available with any architecture. |+| Auto-Rig during TRELLIS.2 generation, rig display, reference poses and animation | **Rigging & Animation** section of the **Mesh** page. Shown only when **Architecture** is **TRELLIS.2**. |++In the legacy panel, the same controls are in the **Auto-Rigging (SkinTokens)** section, also only for TRELLIS.2.++## Auto-rigging with SkinTokens++Auto-rigging requires a ComfyUI node named `StableGenSkinTokensAutoRig`. It is not installed by `installer.py`. StableGen checks for it when connecting to the server; until it is found, the auto-rig controls are disabled with the message **StableGen SkinTokens node was not detected in ComfyUI**.++### Rigging an existing mesh++1. Select the character's mesh, or the empty or armature that is the root of an imported character. Multiple selected mesh parts are joined into a temporary copy for rigging.+2. Click **Auto-rig selected character** (**Auto-Rig Selected Character**).+3. Review the options in the dialog and confirm.++StableGen exports the mesh as a GLB, uploads it to ComfyUI, runs SkinTokens and imports the rigged GLB: an armature and a mesh skinned to it with vertex-group weights. **Preserve Original Source** (on by default) hides the original mesh; when off, the original is deleted after a successful rig.++### Rigging during TRELLIS.2 generation++Enable **Auto-Rig** in the **Rigging & Animation** section. The rigging step runs on the server in the same job, after mesh generation and before texturing. Local decimation, local remeshing and **Solidify Mesh** are skipped when auto-rigging is enabled, and local collapse decimation is performed on the server instead.++### Rig options++| Option | Default | Purpose |+|---|---|---|+| Transfer Original | On | Transfer the generated rig back to the original mesh, preserving its texture and scale. |+| Use Existing Skeleton | Off | If the input already has a skeleton, keep it and generate only skin weights. |+| Skin Postprocess | Off | SkinTokens voxel skin post-processing before export. |+| Clean Limb Weights | On | Remove weights that cross between limbs. |+| Garment Handling | Original Weights | **Original Weights**, **Stabilized Dress** or **Smooth Leg Follow**, post-import weighting for long dresses and skirts. |+| Bone Direction | Fortune / Child-Directed | How bone orientation is reconstructed on import: **Fortune / Child-Directed**, **Blender / Legacy Round-Trip** or **Temperance / Nearest Axis**. |+| Bone Display | Octahedral (Mixamo-like) | Viewport display of the bones. **Apply** changes it on existing armatures. |++The sampling options (**Rig candidate limit (top-k)**, **Rig probability cutoff (top-p)**, **Rig sampling temperature**, **Repetition Penalty** and **Rig beam count**) control how SkinTokens generates the skeleton. **Rig checkpoint path** and **Hugging Face model path** override the model; leave them empty to use the defaults.++## Animation retargeting++Retargeting bakes motion from an FBX or BVH file onto a humanoid rig, such as one made by auto-rigging. All commands act on the selected armature or rigged mesh.++1. **Analyze Rig.** Infers which bones form the spine, arms, legs, pelvis and head and stores this mapping on the armature.+2. **Check the mapping.** The eye button next to **Edit Mapping** shows the mapping in the viewport. **Edit Mapping** lets you correct the start and end bones of each chain. **Proxy** shows the collision capsules used to keep limbs out of the body.+3. **Set a reference pose.** The rig's pose should match the pose the animation starts from. Either:+ - pose the rig with **Rest**, **A-Pose** or **T-Pose**, adjust it if needed, and click **Set Ref Pose**; or+ - click **Match Source Ref**, choose the animation file, and let StableGen pose the rig to match the animation's reference frame. Each arm's upper arm, elbow bend, forearm and hand are turned to the source's directions, so the elbows and wrists move like the source's; on a rig without finger bones the hand follows its skinned mesh rather than its bone. **Protect Body Clearance** then moves a forearm or hand that cuts into the body out to the side, only as far as the skinned mesh needs. This stores the reference pose by default.+4. **Apply Animation.** Choose the FBX or BVH file and confirm the options. StableGen imports the source, retargets it and bakes a new action named `<armature>_<file>_<engine>` over the source's frame range.++Main options of **Apply Animation**:++| Option | Default | Purpose |+|---|---|---|+| Retarget Engine | Reference-Aware (Recommended) | **Reference-Aware** maps motion relative to the reference poses. **Legacy Compatibility** keeps the older behavior. |+| Reference Pose | Stored Ref Pose | The target pose matched to the source's neutral pose: **Stored Ref Pose**, **Current Pose** or **Rig Rest Pose**. |+| Source Neutral | First Frame | **First Frame** or **Source Rest Pose** of the animation. |+| Auto-Match First Frame | On | Poses the rig to the source's first frame automatically. |+| Key Every N Frames | 1 | Keyframe interval for the bake, 1 to 10. |+| Skeletal Proxy Collisions | On | Keeps forearms and hands out of the body. On a skinned rig every frame is checked against the mesh and the arms open sideways only where they would cut in, eased over the neighboring frames so a hand moves smoothly around a belt pouch. Collision capsules keep the arms apart and stand in for rigs without a skinned mesh. |+| Replace Existing Action | On | Replace the rig's current action. |+| Copy Root Motion | Off | Transfer root translation. |+| Show Source Preview | Off | Keep a preview of the source animation. The eye button next to **Apply Animation** shows or hides it. |++Further options control hand orientation and roll, arm corrections, collision margins and body clearance; hover over each for details.++If **Reference Pose** is **Stored Ref Pose** and no reference pose has been stored, Apply Animation stops with a message asking you to use **Set Ref Pose**, unless the reference-aware engine can match the first frame automatically.diff --git a/docs/trellis2.md b/docs/trellis2.mdnew file mode 100644index 0000000..8f689bd--- /dev/null+++ b/docs/trellis2.md@@ -0,0 +1,131 @@+# TRELLIS.2 mesh generation++With the **TRELLIS.2** architecture, StableGen generates a 3D mesh from an image or a text prompt using Microsoft's [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) through the [ComfyUI-TRELLIS2](https://github.com/PozzettiAndrea/ComfyUI-TRELLIS2) custom node. It can then texture the mesh with TRELLIS.2's own texture model or with any diffusion architecture.++Install the node with package 8 of `installer.py` (see [Installation](installation.md#2-install-comfyui-dependencies)). StableGen detects it by checking the server for the `Trellis2ImageToShape` node. If the node is missing, the generate button reads **TRELLIS.2 nodes not found**.++For a walkthrough, see [Quick start](quick-start.md#generating-a-mesh-with-trellis2).++## Pipeline++A run has up to four phases:++1. **Input image.** With **Generate From** set to **Prompt**, StableGen first generates an image from the prompt.+2. **Mesh.** TRELLIS.2 removes the background, builds the shape and, in Native mode, the texture. StableGen downloads the result as a GLB, imports it and scales it to **Import Scale (BU)**.+3. **Rigging.** Optional; see [Rigging and animation](rigging-and-animation.md).+4. **Texturing.** In a diffusion texture mode, StableGen places cameras around the new mesh and runs the selected texturing workflow.++## Input++| Setting | Purpose |+|---|---|+| Generate From | **Image** builds the mesh from **Input Image**. **Prompt** generates the input image first. |+| Initial Image Architecture | With **Prompt** and the **None** or **Native** texture mode, the architecture used to generate the input image. In diffusion texture modes, the texturing architecture is used. |+| Background Removal | **Auto (BiRefNet)** removes the background; **Skip (Use Alpha)** uses the image's alpha channel. |+| Background Color | Color placed behind transparent areas: **Black**, **Gray** or **White**. |++The prompt and checkpoint for the input image are the normal texturing prompt and checkpoint. Enable **Use separate texture prompt** on the **Texture** page to texture with a different prompt.++### Preview gallery++With **Generate From** set to **Prompt**, enable **Preview gallery** to choose the input image before the mesh is built. StableGen generates **Image count** candidates (1 to 16, default 4) and shows them in the viewport. Click an image to continue with it, or click **Generate More** for another set. **Cancel** or **Esc** stops the run.++The candidates use seeds derived from the main **Seed** setting. With a seed of 0 they are random; otherwise the same seed gives the same candidates. The chosen image's seed is written back to **Seed**.++## Mesh settings++These are in the **Mesh & Post-Processing** section of the **Mesh** page.++| Setting | Default | Purpose |+|---|---|---|+| Mesh generation resolution | 1024 Cascade | **512**, **1024 Cascade** or **1536 Cascade**. Higher values give more geometric detail and use more time and memory. |+| Sparse voxel budget | 49152 | Token budget for the cascade modes. |+| Precision | BF16 | **Auto**, **BF16**, **FP16** or **FP32**. |+| Attention Backend | Auto | **Auto**, **Flash Attention**, **xFormers**, **SDPA** or **SageAttention**. |+| Seed | 0 | TRELLIS.2 seed, separate from the image generation seed. |+| Structure guidance / steps | 7.5 / 12 | Sparse structure stage. |+| Shape guidance / steps | 7.5 / 12 | Shape stage. |++### Post-processing++| Setting | Default | Purpose |+|---|---|---|+| Post-Processing | On | Enables the options below. |+| Decimation Method | Server-Side QEM | **None (Raw)**, **Server-Side QEM**, or **Collapse Decimate (Local)** in Blender. |+| Remesh/Retopo Method | QDC (Server) | **None (Trimesh)**, **QDC (Server)**, or **Quadriflow (Local) [Experimental]**. |+| Decimation Target | 100000 | Target face count. |+| Solidify Mesh | Off | Makes the mesh solid. Skipped when auto-rigging. |++**Run Local Post-Processing** applies the local decimation and remeshing methods to the active mesh after import. Raise **Mesh Generation Timeout** in the preferences if server-side post-processing times out.++### Import++| Setting | Default | Purpose |+|---|---|---|+| Import Scale (BU) | 2.0 | Size of the imported mesh in Blender units. 0 keeps the original size. |+| Shading | Flat | **Flat**, **Smooth** or **Auto Smooth**. |+| Auto Studio Lighting | On | Adds a three-point light rig. Native texture mode only. |++## Texture modes++**Texture mode** is on the **Texture** page.++| Mode | Behavior |+|---|---|+| None | Shape only. No texture is generated. |+| Native (TRELLIS.2) | TRELLIS.2 generates PBR textures and bakes them to UV maps. Settings: **Texture guidance**, **Texture steps** and **Texture size (px)** (default 4096) in the **Native Textures** section. See the [license note](#third-party-licenses). |+| SDXL, Qwen Image Edit, Qwen Image 2.1 | The mesh is generated without texture, then textured by projection with the selected architecture, using the current texturing settings (workflow, sampling, blending and so on). FLUX.1 and FLUX.2 Klein are also listed when deprecated architectures are enabled. |++### Camera placement for diffusion texturing++The **Camera Placement** section on the **Cameras** page controls the cameras placed around the generated mesh. The options match [Add Cameras](cameras.md#add-cameras); the defaults differ.++| Setting | Default |+|---|---|+| Placement Mode | Normal-Weighted |+| Camera Count | 8 (2 to 32) |+| Auto View Prompts | On |+| Auto Aspect Ratio | Per Camera |+| Occlusion Handling | None (Fast) |+| Exclude Bottom Faces | On |+| Consider Existing Cameras | On |+| Delete Cameras After | Off. When on, the placed cameras are deleted after texturing. |++## Batch generation from a folder++To generate one asset per image in a folder:++1. Set **Generate From** to **Image**.+2. Click the folder button next to **Input Image** and choose a folder. StableGen counts the `.jpg`, `.jpeg`, `.png`, `.webp`, `.bmp`, `.tiff` and `.tif` files in it. Subfolders are not searched.+3. Optionally enable **Name meshes after input files** and **Bake Textures after each model**. **Bake Settings** sets the bake options for the batch.+4. Click **Generate Batch**.++See [Batch processing](batch-and-queue.md#trellis2-folder-batches) for how the results and log are stored.++## Third-party licenses++This section applies only to the TRELLIS.2 feature. StableGen's standard texturing pipelines (SDXL, Qwen Image Edit, Qwen Image 2.1 and the deprecated FLUX architectures) do not use any of the libraries listed below and are unaffected by these restrictions.++The TRELLIS.2 feature relies on several third-party components, each with its own license. Be aware of these licenses, particularly the non-commercial restrictions on the NVIDIA libraries used in the TRELLIS.2 native texture pipeline.++| Component | License | Commercial use permitted |+|---|---|---|+| [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) (Microsoft) | MIT | Yes |+| [TRELLIS.2-4B model weights](https://huggingface.co/microsoft/TRELLIS.2-4B) | MIT | Yes |+| [ComfyUI-TRELLIS2](https://github.com/PozzettiAndrea/ComfyUI-TRELLIS2) | MIT | Yes |+| [DINOv3](https://github.com/facebookresearch/dinov3) (Meta, image conditioning) | [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/) | Yes |+| [BiRefNet](https://github.com/ZhengPeng7/BiRefNet) (background removal) | MIT | Yes |+| [FlexGEMM](https://github.com/JeffreyXiang/FlexGEMM) (sparse convolutions) | MIT | Yes |+| [CuMesh](https://github.com/JeffreyXiang/CuMesh) (mesh operations) | MIT | Yes |+| O-Voxel (voxel processing, part of TRELLIS.2) | MIT | Yes |+| [nvdiffrast](https://github.com/NVlabs/nvdiffrast) (NVIDIA) | NVIDIA Source Code License | **No, non-commercial only** |+| [nvdiffrec](https://github.com/NVlabs/nvdiffrec) (NVIDIA) | NVIDIA Source Code License | **No, non-commercial only** |++The NVIDIA libraries nvdiffrast and nvdiffrec are used only when **Texture mode** is set to **Native (TRELLIS.2)**, for UV rasterization and PBR texture baking. Their license restricts use to "research or evaluation purposes only and not for any direct or indirect monetary gain" (Section 3.3). Only NVIDIA and its affiliates may use these libraries commercially.++The other texture modes do not introduce these restrictions:++- **None** (shape only) does not use nvdiffrast or nvdiffrec. All other pipeline components are permissively licensed (MIT or Apache 2.0, plus the DINOv3 License).+- **Projection-based texture modes** (SDXL, Qwen Image Edit and the others) do not use nvdiffrast or nvdiffrec. The license terms of the selected diffusion model apply as usual; for example, FLUX.1-dev has its own license terms, separate from the TRELLIS.2 pipeline.++If you need to use the Native (TRELLIS.2) texture mode commercially, contact NVIDIA about commercial licensing for nvdiffrast and nvdiffrec.diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdnew file mode 100644index 0000000..f5015d9--- /dev/null+++ b/docs/troubleshooting.md@@ -0,0 +1,111 @@+# Troubleshooting++When something fails, check two places first:++- **Blender's system console.** On Windows, open it with **Window > Toggle System Console**; on Linux and macOS, start Blender from a terminal. StableGen prefixes its messages with `[StableGen]`.+- **The ComfyUI console.** Errors about missing nodes, missing models or memory appear here.++## The StableGen tab is missing++Check that the add-on is installed and enabled under **Edit > Preferences > Add-ons**, then press **N** in the 3D Viewport and look for the **StableGen** tab. If you prefer the original interface, enable **Use Legacy Panel** in the add-on preferences.++## The generate button is disabled++The button, or the status line above it in the StableGen panel, states the reason.++| Message | Fix |+|---|---|+| Output Path Invalid | Set **Output Directory** in the preferences to a folder that exists. |+| Server Address Missing | Set **Server Address** in the preferences. |+| ComfyUI offline | Start ComfyUI, check **Server Address**, then click the refresh button next to the generate button. |+| Enable online access in preferences | Enable **Edit > Preferences > System > Network > Allow Online Access**. See [Installation](installation.md#allow-online-access). |+| Model Directory Empty | No model for the selected architecture was found on the server. See below. |+| TRELLIS.2 nodes not found | Install the TRELLIS.2 package and restart ComfyUI. See below. |+| Select an image first | Choose an **Input Image** for TRELLIS.2, or switch **Generate From** to **Prompt**. |++While the StableGen tab is open, the add-on checks the server every 10 seconds, so the status updates shortly after ComfyUI starts or stops. The refresh button checks immediately and also reloads the model lists.++## Connection problems++- Confirm that ComfyUI is running and that you can open its web interface at the configured address.+- For a server on another machine, start ComfyUI with `--listen` and allow the port through the firewall. See [Using a remote ComfyUI server](installation.md#using-a-remote-comfyui-server).+- On slow connections or busy servers, raise the timeouts under **Advanced Preferences**. **Generation Heartbeat** only decides how long StableGen waits for progress messages before checking the ComfyUI queue; it does not cancel a generation.++## Models are missing++The **Checkpoint** list is read from different ComfyUI folders depending on the architecture:++| Architecture | Folder |+|---|---|+| SDXL | `models/checkpoints` |+| Qwen Image Edit, Qwen Image 2.1 | `models/diffusion_models` (and `models/unet` for GGUF files) |++After adding models, click the refresh button next to **Checkpoint**. If ComfyUI reports a missing model during generation, the preset expects a file you do not have, usually a ControlNet or LoRA. Run `installer.py` with the matching package, or check the file names in [Manual installation](MANUAL_INSTALLATION.md). Restart ComfyUI after adding custom nodes.++If a ControlNet unit uses the wrong model type, review **ControlNet Model Assignments** in the preferences.++## TRELLIS.2 or PBR nodes are not detected++StableGen looks for specific nodes on the server: `Trellis2ImageToShape` for TRELLIS.2, and `MarigoldModelLoader` and `LoadStableDelightModel` for PBR extraction. If they are missing:++1. Run `installer.py` with package 8 (TRELLIS.2) or packages 9 and 10 (PBR).+2. Restart ComfyUI and check its console for errors while it loads the custom nodes.+3. Click the refresh button in the StableGen panel.++TRELLIS.2 uses compiled CUDA extensions without pre-built wheels for Python 3.13. If its nodes fail to load, run ComfyUI with Python 3.12.++If TRELLIS.2 times out during mesh post-processing, raise **Mesh Generation Timeout** in **Advanced Preferences**.++## TRELLIS.2 stops working after a ComfyUI update++TRELLIS.2 runs in its own isolated Python environment managed by comfy-env, but it still imports ComfyUI's core code. When ComfyUI updates and raises a package requirement, that environment falls behind. The ComfyUI console then shows errors such as `No module named 'comfy_aimdo.storage'` or `cannot import name 'ColorPrimaries' from 'av.video.reformatter'`.++Run the installer's repair mode, then restart ComfyUI:++```+python installer.py <path to ComfyUI> --repair+```++It re-applies StableGen's patches to the TRELLIS.2 node, brings the isolated environment in line with ComfyUI's `requirements.txt`, and checks that ComfyUI core imports inside it. `--check` reports the same without changing anything. Installs made with this installer also re-check automatically on every ComfyUI start.++## ComfyUI crashes or hangs while loading a model++Symptoms include ComfyUI exiting with `Windows fatal exception: access violation` during a model load, `The paging file is too small for this operation to complete`, `aimdo` read errors with Windows error 1450, or a sampler that stops at the first step while the GPU shows full load at low power.++These point to the system running out of memory, not to a broken model. Qwen Image 2.1 with its text encoder, TRELLIS.2 and Blender together need a lot of RAM and page file.++- Restart Windows if it has been running for a long time, and close memory-heavy programs (WSL and Docker reserve several GB).+- Give Windows a larger page file: a fixed 32–64 GB on a fast drive.+- Start ComfyUI with `--reserve-vram 2` (or more) when Blender and other GPU programs are open, so models are offloaded instead of overflowing into shared memory.+- If crashes continue, try `--disable-dynamic-vram` and `--disable-pinned-memory`.++## Out of GPU memory++- Lower **Target megapixels**, or keep **Fit camera resolution** enabled, in **Output & materials**.+- Use fewer cameras.+- For Qwen Image Edit, use a smaller GGUF model or the Nunchaku presets.+- For TRELLIS.2, choose a lower **Mesh generation resolution** or another **Attention Backend**.+- Close other applications that use the GPU.++## The texture is not visible++The projection material is evaluated by Cycles. Switch the viewport to **Rendered** shading. In Solid or Material Preview shading, the texture appears only after you bake it.++Blender 5.0 is not supported. Use Blender 4.2 to 4.5 or Blender 5.1 and later.++## All meshes are textured++**Target objects** defaults to **All Visible**. Set it to **Selected** and select the meshes to texture, or hide the others.++## Poor results++- Start from a built-in preset for your architecture. See [Architectures and presets](architectures-and-presets.md).+- Check camera coverage. Every surface you care about should face at least one camera directly. Try another placement mode or more cameras; see [Cameras](cameras.md).+- Add view prompts such as `rear view` to stop the model from drawing a front on every side.+- In **Generate Sequentially**, the first camera sets the look. Change the [generation order](cameras.md#generation-order) so a characteristic view comes first.+- Adjust ControlNet strength for SDXL. Too low ignores the geometry; too high can flatten the result.+- To fix individual views, select their cameras and use **Regenerate selected views**, or use [Local Edit or Masked Edit](generation-modes.md).++## A generation appears stuck++Click the stop button in the footer and wait for the current ComfyUI request to finish. If StableGen still reports that it is busy, enable **Enable Debug Settings** in the preferences and use **Reset stalled generation** in the **Recovery** group of the **Diagnostics** page.