From first install to advanced CLI tuning, this guide covers the full add-on stack.
3D2AI is a Blender add-on that uses a locally-running AI image generation pipeline to produce final images from rough viewport compositions. It captures the current 3D view — including camera, layout, and lighting — as a conditioning reference, accepts a text prompt, and produces an image in under a minute without rendering.
When you run the guided installer, the add-on downloads the following components to your machine:
sd-cli.exe, the inference engine)flux-2-klein-4b-Q4_K_M.gguf) — the base diffusion modelqwen3-4b-q4_k_m.gguf) — the text encoder that processes your promptfull_encoder_small_decoder.safetensors) — the VAE that decodes latents to pixelsFlux_Klein_4B_3D2AI_BF16_R16.safetensors) — a custom adapter fine-tuned on real Blender scene data so the output respects 3D structureAll components are downloaded automatically. You do not need to fetch them manually.
Nothing is ever uploaded after installation. Downloads happen once. After that, the add-on is fully offline.
The add-on captures the current 3D View through Blender's render-block mechanism, producing a low-cost reference image that preserves camera angle, framing, perspective, and object placement.
A custom LoRA adapter trained on synthetic and real Blender scene data. Loaded automatically during generation and configurable from 0.0 to 2.0 strength. A value of 1.0 provides balanced scene-structure adherence; values above 1.0 increase structural fidelity at the cost of prompt flexibility.
Optionally supply an external image as conditioning input. The uploaded image is resized to match the target render resolution before being passed to the backend.
Every generation is tracked with a UUID, prompt excerpt, seed, elapsed time, and output path. The Recent Jobs panel lets you scroll past runs, copy CLI arguments from any job, and reproduce results by reusing the seed.
Errors from download operations, subprocess execution, or backend communication are surfaced in a dedicated Error Logs panel. Each error can be copied to the clipboard for reporting.
The prompt field is mirrored into a native Blender text block named D2AI_Prompt. Prompts are stored inside your .blend file and travel with it.
Advanced users can hand-edit stable-diffusion.cpp arguments in a dedicated field or in the mirrored D2AI_RawArgs text block. The UI maintains bidirectional sync.
Each model component has its own download URL, with a primary source and a fallback mirror. Dependencies are managed independently — install or delete any component without affecting the others.
For GPUs with limited VRAM, each sub-model's computation device and weight storage can be set independently. Available options are CUDA (GPU), CPU (RAM), and Disk (streaming). When stream layers is active, the add-on automatically pins params backends to CPU to maintain consistency.
Download the release .zip from the product page.
Open Blender and go to Edit → Preferences → Extensions.
Click Install from Disk and select the downloaded .zip file. Enable the add-on if needed and restart Blender.
Set Render Engine to 3D2AI, open the Dependencies panel, and click Install. Wait for Status: Installed.
Set your output path in the Output panel, enter a prompt in Generate, and click Generate.
| Component | Approximate Size |
|---|---|
| stable-diffusion.cpp backend | ~0.33 GiB |
| CUDA 12 runtime | ~0.52 GiB |
| FLUX.2-klein-4B GGUF | ~2.43 GiB |
| Qwen3-4B GGUF | ~2.33 GiB |
| FLUX.2-small VAE | ~0.23 GiB |
| 3D2AI LoRA | < 0.1 GiB |
| Total (default) | ~5.84 GiB |
Free disk recommendation after extraction and with space for generated images: 7–10 GiB.
The add-on uses a primary + fallback mirror system for all downloads. If a primary source is unreachable, the installer automatically retries from the fallback mirror. You do not need to take any action.
All 3D2AI panels are located in the Render Properties tab, accessible when the render engine is set to 3D2AI.
| Panel | Internal ID | Purpose |
|---|---|---|
| Dependencies | D2AI_PT_dependencies_panel | Install, delete, and monitor backend + model downloads. Shows progress bar and error status. |
| Generate | D2AI_PT_generate_panel | Primary panel. Prompt input, seed, steps, resolution factor, generate button, and collapsible Advanced / Performance section. |
| Reference Image | D2AI_PT_reference_panel | Upload an external conditioning image. Resizes to match target resolution automatically. |
| Output | D2AI_PT_output_panel | File path for generated PNGs. |
| Recent Jobs | D2AI_PT_recent_jobs_panel | Scrollable list of past generations with prompt excerpt, seed, elapsed time, and copy button. |
| Error Logs | D2AI_PT_error_logs_panel | Shows the most recent error message with a one-click copy button. |
Panel rendering order: Dependencies (0), Generate (1), Reference Image (2), Output (3), Recent Jobs (4), Error Logs (5).
D2AI_Prompt — Mirrors the prompt field. Stored inside the .blend file with your scene.D2AI_RawArgs — Mirrors the advanced raw CLI arguments string. Editable by hand; changes sync back to the UI.The fastest path from install to first image:
Generations complete in under a minute on an RTX 4070 (12 GiB VRAM) at Full HD.
A greyboxed living room with a window, a sofa block, a coffee table, and a warm area light.
"Modern living room, warm minimalist interior, oak floors and linen sofa, soft afternoon window light, cozy atmosphere, clean detailed"
Steps: 4 · Seed: random · Stream Layers: off (GPU has 12 GiB) · Flash Attention: on · LoRA Strength: 1.0 · Output: /renders/3d2ai/living_room_v1.png
The reference image defines composition, perspective, and camera. The prompt adds detail, never overrides.
Use this order every time:
A brutalist concrete house, minimalist architecture, raw cement and glass, soft overcast lighting, calm atmosphere, high detail
| Variable | Examples |
|---|---|
| Material | wood, metal, fabric, stone, concrete, glass |
| Style | cyberpunk, modernist, baroque, brutalist, art deco, scandinavian |
| Lighting | sunset, studio, neon, foggy, overcast, volumetric |
| Mood | eerie, warm, sterile, cozy, tense |
| Detail | ultra detailed, clean, rough, polished, weathered |
Do not attempt to change these through the prompt. They are determined entirely by your viewport scene.
Your scenes, prompts, and generated images are never transmitted or uploaded after the guided install is complete. All generation runs locally on your hardware.
The add-on requires internet access only during the initial guided install, while it downloads the backend and models. After all dependencies are installed, the add-on is fully offline.
The add-on does not send usage data, crash reports, prompt content, or generation results to any server. There is no analytics or phoning home.
The add-on stores runtime data under:
Windows: %APPDATA%\3D2AI\
| Path | Contents |
|---|---|
%APPDATA%\3D2AI\captures\references\ | Greybox reference images captured before generation |
%APPDATA%\3D2AI\captures\workbench\ | Workbench captures |
%APPDATA%\3D2AI\dependencies\models\diffusion\ | FLUX diffusion model |
%APPDATA%\3D2AI\dependencies\models\llm\ | Qwen3 text encoder |
%APPDATA%\3D2AI\dependencies\models\vae\ | FLUX VAE |
%APPDATA%\3D2AI\dependencies\models\lora\ | 3D2AI LoRA adapter |
%APPDATA%\3D2AI\dependencies\backend\sd\ | stable-diffusion.cpp binaries |
%APPDATA%\3D2AI\jobs.json | Generation job history |
%APPDATA%\3D2AI\history.json | Runtime state |
Generated PNGs are written to whichever output path you configure in the Output panel. This is separate from the add-on's runtime directory.
| Component | Requirement | Notes |
|---|---|---|
| OS | Windows 10 / 11 x64 | Only officially supported platform |
| Blender | 4.2 LTS or later | Built against 4.2.0 API; should work on later LTS releases |
| GPU | NVIDIA with CUDA 12+ driver | Primary compute device |
| VRAM (minimum practical) | 6 GiB | Enable Stream Layers below this |
| VRAM (recommended) | 8–12 GiB | Full HD output without offloading |
| System RAM | 16 GiB | More helps when weights are offloaded to CPU |
| Disk space | 7–10 GiB free | ~5.84 GiB downloads + extraction + captures + outputs |
| Internet | One-time during install | Required only for the guided installer |
| Parameter | Supported | Not supported |
|---|---|---|
| Windows x64 + NVIDIA CUDA 12 | Fully supported | — |
| Windows x64 + CPU only | Supported (slow) | — |
| Linux x64 | Not officially supported; may work with manual backend replacement | No installer support |
| macOS (Intel / Apple Silicon) | Not supported | No installer support |
| AMD GPU | Not supported | CUDA-only backend |
Because the add-on communicates with stable-diffusion.cpp via the CUDA 12 runtime, you need a CUDA 12-compatible NVIDIA driver. Check your driver version in the NVIDIA Control Panel or with nvidia-smi.
The bundled backend package (sd-master-...-bin-win-cuda12-x64.zip) and the executable sd-cli.exe are compiled for Windows x64. A Linux or macOS installation would require replacing the backend package with a platform-appropriate build of stable-diffusion.cpp and adjusting the executable path and permissions manually. This is outside the scope of official support.
The Advanced / Performance section in the Generate panel exposes controls for performance, memory management, and model behavior.
Enabled by default via the lora_enabled checkbox. LoRA Strength slider from 0.0 to 2.0. Default 1.0. 0.0 disables the adapter (vanilla FLUX). > 1.0 increases scene-structure adherence at the cost of prompt flexibility. Values above 1.5 are likely to overfit the reference.
When enabled, model weights are paged into GPU memory incrementally rather than loaded all at once. This reduces peak VRAM usage at the expense of longer generation times. When enabled, the add-on pins all params backends to CPU automatically.
Enables the flash attention kernel in stable-diffusion.cpp (CUDA-only). This can reduce peak VRAM usage and speed up generation. If you encounter errors, disable it.
Manually constrain the backend's memory allocation by entering your GPU's VRAM budget in GiB. The add-on passes this value to stable-diffusion.cpp via --max-vram.
Three sub-models can each be assigned independently: Diffusion, Text Encoder, and VAE. Each can be set to CUDA, CPU, or Disk. Setting a params backend to Disk requires Stream Layers to be active; the add-on enforces this automatically.
The Raw Args field is a single source of truth for generation parameters, expressed as stable-diffusion.cpp command-line arguments. It is editable directly in the UI or in the D2AI_RawArgs text block. The two representations are bidirectionally synced.
| Flag | Default | Effect |
|---|---|---|
--seed N | random | RNG seed for reproducibility |
--steps N | 4 | Number of diffusion steps. Values above 4 do not produce materially higher quality for the FLUX-based pipeline. |
--backend device | cuda0 | Runtime compute device. Options: cuda0, cpu. |
--params-backend spec | cpu | Per-model weight storage. Format: diffusion=M,te=V,vae=W where M, V, W are cuda0, cpu, or disk. te is an alias for the text encoder (LLM). |
--stream-layers | off | Enable incremental weight paging for low-VRAM operation. |
--diffusion-fa / --flash-attention | off | Enable flash attention kernel. CUDA only. |
--max-vram N | — | Manually set a VRAM budget in GiB. Only included when the VRAM Override toggle is enabled. |
--seed 42 --steps 4 --backend cuda0 --stream-layers --diffusion-fa
--seed 42 --steps 4 --backend cuda0 --params-backend diffusion=cpu,te=cpu,vae=cuda0
The add-on exposes URL fields for the diffusion model, LLM model, VAE, and LoRA adapter. These are pre-filled with bundled defaults. You can override them to point to compatible model files on other hosts.
Paths resolve to:
%APPDATA%\3D2AI\dependencies\models\diffusion\%APPDATA%\3D2AI\dependencies\models\llm\%APPDATA%\3D2AI\dependencies\models\vae\%APPDATA%\3D2AI\dependencies\models\lora\scene.D2AI_last_error.Check the error message in the Dependencies panel and in the Error Logs panel. Common causes: disk space exhausted during download — free up space and click Delete then Install again; network interruption — click Install to retry; antivirus blocking write access to %APPDATA%\3D2AI\ — add an exclusion for that folder and retry.
1. Open the Error Logs panel and copy the error message. 2. Verify the stable-diffusion.cpp binary exists at the path shown in the Dependencies panel. 3. Confirm your NVIDIA driver supports CUDA 12 (nvidia-smi). 4. If you have less than 6 GiB VRAM, enable Stream Layers. 5. If the error persists with Stream Layers on, try CPU for the runtime backend to isolate a GPU driver issue.
Enable Stream Layers. Lower the Resolution Factor in the Generate panel. Set VRAM Override to your GPU's known VRAM if you want to explicitly constrain the backend's memory allocation. Reduce the number of parallel operations by closing other GPU-intensive applications.
Confirm the reference image was captured. The capture is required for conditioning. Without it, generation may fall back to text-only mode. Keep the prompt focused on detail that the reference does not fix (materials, lighting, mood). Do not restate camera position, object placement, or scene layout. Reduce LoRA Strength if the output is overfitting the greybox and ignoring your prompt.
Confirm you are in Object Mode when generating. The viewport capture draws the current shading mode. Ensure the camera is correctly framed. The capture uses the active viewport camera. If you are in Look Dev or Material Preview mode, those settings are captured as-is. Switch to Solid or Rendered for repeatable conditioning.
The add-on automatically falls back to its mirror if primary sources are slow. If both are slow, your network may be congested. Downloads can be interrupted and resumed by clicking Install again.
3D2AI is licensed under GNU General Public License v3.0 or later (GPL-3.0).
The add-on downloads and invokes the following external components at runtime. They are not distributed with the add-on source code; they are acquired by the add-on during the guided install.
| Component | License | Copyright | Source |
|---|---|---|---|
| stable-diffusion.cpp | MIT | leejet | github.com/leejet/stable-diffusion.cpp |
| FLUX.2-klein-4B GGUF | Apache 2.0 | Unsloth | huggingface.co/unsloth/FLUX.2-klein-4B-GGUF |
| Qwen3-4B GGUF | Apache 2.0 | Alibaba | huggingface.co/unsloth/Qwen3-4B-GGUF |
| FLUX.2-small-decoder (VAE) | Apache 2.0 | Black Forest Labs | huggingface.co/black-forest-labs/FLUX.2-small-decoder |
| 3D2AI LoRA | Apache 2.0 | Latentiq | huggingface.co/Latentiq/Flux2_Klein_4B_3D2AI_LoRA |
MIT and Apache 2.0 licenses are compatible with GPL-3.0. The add-on communicates with the stable-diffusion.cpp backend via subprocess and command-line interface, which does not create a combined work under copyright law.
The add-on source code is available in the release archive and in its development repository. Because the add-on is GPL-3.0 licensed, you have the right to inspect, modify, and redistribute the source in accordance with the license terms.
Got questions, ideas, or work-in-progress shots? The Discord is the fastest way to get help, share feedback, and see what other artists are building with 3D2AI.
Join Discord →