Node Reference

Image-GS Splat Node

image_gs_splat converts one source image into a viewport-ready PLY Gaussian splat that can be viewed, transformed, layered, connected into scene, and processed alongside other splat assets.

Back to Catalog Main Docs

What It Creates

Exact Pixel mode writes a deterministic front-facing splat sheet with one Gaussian per visible source pixel. Image-GS mode uses the optional Image-GS runtime to fit a smaller optimized set of Gaussian primitives, then converts the checkpoint into the same PLY path.

This is not multi-view photogrammetry or a complete hidden-surface 3D scan. With one image, the node creates an image-driven splat surface or field rather than a complete object with a reliable backside.

Generate Flow

What Generate Does

  1. Reads a local image path or HTTP image URL from the node.
  2. In Exact Pixel mode, stages the source as RGBA PNG and writes one front-facing splat per visible pixel.
  3. In Image-GS mode, stages the source as an 8-bit RGB PNG so Image-GS receives a predictable image format.
  4. When Auto HQ is enabled in Image-GS mode, analyzes source resolution/detail and chooses quality-focused settings.
  5. Runs Image-GS from %QUBITMCP_HOME%\third_party\image-gs only when Image-GS mode is selected.
  6. Converts the exact image or latest checkpoint into a PLY Gaussian splat stored under logs\image_gs_splat.
  7. Writes QC data and updates the node output so View or a connected scene node can display the splat.

Setup and Debug

  • Exact Pixel mode does not require the optional Image-GS checkout.
  • Use setup.bat, accept the first-use setup prompt, or click Setup Image-GS only when Image-GS mode is needed.
  • Generated files are written under logs\image_gs_splat.
  • While generation is running, a bottom-row Stop button appears to interrupt the active converter or Image-GS process.
  • The debug icon opens an Image-GS report with dependency status, command line, generated paths, QC status, exit code, and captured stdout/stderr.
  • QC is a validation estimate; visual review in the viewport is still the final check.

Main Parameters

Parameter Default What It Controls
image_url / Image empty Local image path or HTTP/HTTPS image URL. The browse button selects a local image. This value is mirrored to source for compatibility.
generation_mode / Mode exact_pixel Selects deterministic Exact Pixel export or the optional Image-GS optimizer path.
auto_quality / Auto HQ 1 Image-GS mode only. Automatically chooses high-quality settings from source image size/detail and keeps progressive error-guided optimization enabled.
num_gaussians / Splats 2000 Number of Gaussian primitives Image-GS optimizes. Higher values can capture more detail but increase runtime, memory use, and output size.
max_steps / Steps 800 Optimization iterations. Higher values usually improve reconstruction quality but take longer.
render_height / Height 768 Training/render height passed to Image-GS. Larger values preserve more image detail but increase VRAM and runtime cost.
init_mode / Init gradient Initial placement strategy for splats. gradient follows image detail/edges, saliency favors visually important regions, and random distributes splats randomly.
sheet_scale / Sheet 2.0 Scale used when converting the source image or 2D Image-GS checkpoint into a viewport splat sheet.
radius_scale / Radius 1.0 Multiplier applied to exact pixel footprints or checkpoint splat radii.
alpha / Alpha 0.92 Opacity value assigned during PLY conversion. Lower values make the generated splat sheet more transparent.

Generated Outputs

Parameter Purpose
path Final generated PLY path after a successful run. This is the path consumed by scene/import-style viewport loading.
source_image Local staged PNG used as generation input. Exact Pixel preserves RGBA; Image-GS uses 8-bit RGB.
splat_ply Generated PLY splat path written after checkpoint conversion.
checkpoint Latest Image-GS checkpoint selected for conversion.
preview_image Preview image shown on the node when available.
render_image Latest rendered Image-GS reconstruction used for QC comparison when available.
manifest JSON manifest recording the source image, checkpoint, generated PLY, conversion settings, automatic settings, and QC report.
auto_quality_report JSON details for Auto HQ decisions, including detected source detail, selected density, progressive optimization strategy, and loss settings.
qc_report QC status, splat density, export cap status, source-vs-render similarity, PSNR-style score, and edge/detail retention when available.