Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/armory3d/armorpaint/llms.txt

Use this file to discover all available pages before exploring further.

Neural nodes bring local AI inference directly into ArmorPaint’s material node graph. Each neural node, when triggered, spawns an external inference process — the iris binary for image and diffusion tasks, or llama_vulkan / llama_metal for language models — passes an input image or prompt, waits for the process to complete, then loads the output back as a GPU texture that feeds downstream nodes. All inference runs locally on your machine; no data is sent to external servers. The results are cached in the neural_node_results map keyed by output socket ID, and are immediately visible as node preview thumbnails in the canvas.

​
How Neural Nodes Work

When you click Run on a neural node:
  1. The node writes the upstream node’s preview image to models/input.png in the ArmorPaint data directory.
  2. It assembles a command-line argument array and calls iron_exec_async to launch the iris binary (or Python for Hunyuan3D).
  3. ArmorPaint polls each frame via sys_notify_on_update. When iron_exec_async_done == 1, it reads models/output.png (or the relevant output file) and uploads it as a GPU texture.
  4. The texture is stored in neural_node_results under the output socket ID and triggers a redraw of the node canvas and 2D view.
If the required model file has not been downloaded yet, the button shows Setup instead of Run and opens the Neural preferences panel where you can download models.
Neural nodes require downloading large model files (ranging from ~70 MB for Real-ESRGAN to ~15.7 GB for Qwen). Ensure you have sufficient disk space and GPU VRAM before running inference. Minimum GPU memory requirements vary by model — see the table below. Inference may be slow on CPUs or older GPUs.

​
Available Neural Nodes

Text to Image

Node type: NEURAL_TEXT_TO_IMAGEGenerates an image from a text prompt using the FLUX 2 klein diffusion model (4B parameters, requires ~4 GB VRAM, model size ~8.7 GB). Enter your prompt in the text area, select the model, then click Run.
  • Output resolution is controlled by config.neural_res. At 2048 or higher, --vae-tiling is automatically added to reduce VRAM usage.
  • The Tile checkbox adds --tile to produce seamlessly tiling output.
  • A random seed (-1) is used by default, so each run produces a different result.
  • Output socket: Color (RGBA).

Image to PBR

Node type: NEURAL_IMAGE_TO_PBRConverts a single base color image into a full PBR map set using the DA3MONO depth estimation model (requires ~6 GB VRAM, model size ~1.4 GB). The node reads the upstream node’s preview image, runs monocular depth estimation, then derives normal, occlusion, height, and roughness maps on the CPU using render passes.Output sockets: Base Color (RGBA), Occlusion (VALUE), Roughness (VALUE), Normal Map (VECTOR), Height (VALUE).The Tile checkbox enables tiling-aware processing.

Upscale Image

Node type: NEURAL_UPSCALE_IMAGEAI super-resolution upscaling using the Real-ESRGAN x4 model (requires ~1 GB VRAM, model size ~70 MB). Increases the texture resolution by 4× while preserving and enhancing fine detail. Useful as a post-processing step after generation.Input: Color (RGBA). Output: Color (RGBA).The Tile checkbox enables tile-based processing for very large inputs.

Edit Image

Node type: NEURAL_EDIT_IMAGEAI-guided image editing using the FLUX 2 klein model. Modifies an existing image according to a text prompt. Accepts an optional Mask input — white pixels in the mask define the region to be edited (inpainting).Inputs: Color (RGBA), Mask (VALUE). Output: Color (RGBA).Additional controls: Variance slider (0–1) adds controlled variation to the edit; Tile checkbox for seamless output. At neural_res >= 2048, --vae-tiling is automatically enabled.

Image to 3D Mesh

Node type: NEURAL_IMAGE_TO_3D_MESHReconstructs a 3D mesh from a single image using the Hunyuan3D shape pipeline (requires ~12 GB VRAM, model size ~12.6 GB). The input image’s near-black background is automatically removed before inference. The output mesh is exported as output.obj and immediately imported into the ArmorPaint scene.Input: Color (RGBA). Output: Mesh (VALUE).

Text to Text

Node type: (standalone utility, not a material graph node)LLM-based text generation using the Qwen 3.6-27B model (requires ~16 GB VRAM, model size ~15.7 GB). Maintains a conversation history file and a prompt cache for efficient multi-turn inference. Used by the ArmorPaint console and AI assistant features.

Texture Mesh

Node type: NEURAL_TEXTURE_MESHAI-driven full-mesh texturing. Captures 6 orthographic viewport renders of the scene (bottom, top, back, left, right, front), assembles them into a 3×2 image grid, runs a diffusion model (either Qwen Image Edit or FLUX 2 klein) to generate a consistent multi-view texture, upscales the result with Real-ESRGAN, then projects each view back onto the mesh as a camera-aligned decal.Input: In (BOOL trigger). Output: Color (RGBA).Enter a descriptive prompt in the text area to guide the texture style. The projection step uses the Decal tool internally and finalizes with a dilation pass to eliminate seams.

Repeat

Node type: NEURAL_REPEATLoops a connected Text to Image node a configurable number of times. Each iteration loads the result back into neural_node_results before triggering the next run, enabling iterative refinement workflows.Output: Out (BOOL, used to trigger downstream Text to Image nodes). Set the Count slider to the desired number of iterations.

​
Save Image Node

The Save Image node (NEURAL_SAVE_IMAGE) is a terminal utility node that saves any incoming color texture to a sequentially numbered PNG file (output001.png, output002.png, …) in the same directory as the current project file. It has no output sockets and is automatically triggered when a node linked upstream finishes inference. Input: Color (RGBA).

​
Model Reference

Model NameUsed ByVRAMSizeLicense
FLUX 2 kleinText to Image, Edit Image, Texture Mesh4 GB8.7 GBApache 2.0
DA3MONOImage to PBR6 GB1.4 GBApache 2.0
Real-ESRGANUpscale Image, Texture Mesh1 GB70 MBBSD-3-Clause
Hunyuan3DImage to 3D Mesh12 GB12.6 GBHunyuan3D
QwenText to Text16 GB15.7 GBApache 2.0

​
Resolution Configuration

The neural_res field in the application config controls the output resolution for generative neural nodes:
  • Default values produce images at the configured resolution (e.g., 512 or 1024).
  • When neural_res >= 2048, the --vae-tiling flag is automatically appended to FLUX 2 klein inference commands, splitting the VAE decode step into tiles to stay within GPU memory limits.

​
The iris Binary and Model Directory

All neural inference binaries and model weights are stored in the models/ subdirectory inside ArmorPaint’s internal save path. On first use, ArmorPaint downloads the iris binary from Hugging Face (armory3d/iris_bin) and the llama_vulkan / llama_metal binary (armory3d/llamacpp_bin). Model weights are downloaded separately per node from their respective Hugging Face repositories. On Linux, the iris and llama_vulkan binaries are automatically chmod +x’d after download.The directory layout is:
models/
  iris(.exe)
  llama_vulkan(.exe) / llama_metal
  flux-2-klein-4b-Q8_0.gguf
  Qwen3-4B-Q8_0.gguf
  vae.safetensors
  da3-mono-large.safetensors
  RealESRGAN_x4plus.safetensors
  Hunyuan3D_win64/        (Windows, extracted from .tar)
  input.png               (temporary: inference input)
  output.png              (temporary: inference output)
  history.txt             (text-to-text conversation history)
  context.bin             (llama.cpp prompt cache)

Build docs developers (and LLMs) love

Get started for freeTalk to us