3DViewer Model Embedding Guide

What is 3DViewer?

3DViewer is the unified 3D model viewing entry point of this blog project. Built on Three.js and OrbitControls, it can directly open SPZ, GLB, and STEP / STP files from local disk or public URLs, and provides commonly used camera controls, light controls, export, and URL parameter mechanisms.

It is not meant to be a single-purpose Gaussian splat player but a unified 3D model viewer: no matter what format the model is in, everything goes through the same entry point, /ToolBase/3DViewer/3DViewer.html. This keeps the embedding approach consistent across articles and avoids having to keep maintaining the old /ToolBase/spz/spzViewer.html solution.

Core Capabilities

• Multi-format support: .spz, .glb, .step, .stp
• Interactive controls: rotate / pan / zoom with the mouse, powered by OrbitControls
• Lighting adjustment: key light / ambient light / follow camera / show orientation
• Helper grid: the reference ground grid can be hidden as needed
• Export: supports exporting to GLB / STEP and other target formats
• URL parameterization: embed presets for camera, lights, and UI state directly

Minimal Embedding

Simply use 3DViewer.html as the iframe target page and pass the model address in the URL parameters:

<div class="splat-viewer-wrapper">
  <iframe
    src="/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fspz%2FDingZheng.spz"
    class="splat-viewer-iframe"
    frameborder="0"
    allowfullscreen
    loading="lazy"
    style="width:100%;height:480px;display:block;border-radius:12px;"
  ></iframe>
</div>

The same works for GLB / STEP:

/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fstep%2F3D_PCB3_1_2026-08-18.step
/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fglb%2Fexample.glb

Live Demo

The example below directly shows the SPZ model bundled with this project, demonstrating how 3DViewer is embedded in a page.

Note: the browser inside the iframe will load and display the 3D scene based on the current model file; if the resource is not accessible, make sure the path and public access permissions are correct.

Common URL Parameters

3DViewer supports defining the initial camera, target, and UI display state directly via query parameters. Here is a quick reference of the common ones:

Full example:

/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fstep%2F3D_PCB3_1_2026-08-18.step&camera=18,15,18&target=0,0,0&light=12,18,8&lightIntensity=2.5&ambient=1.3&ui=0&grid=0

Click-to-Load Version (saves bandwidth)

If the model is large and doesn't need to load right away, you can render a placeholder area first and inject the iframe after a click. This pattern is common on demo pages and for embedding large models in articles; the implementation matches the approach of DOM.spzInsertBtn in tool-editor-article.astro: place a placeholder box first, then run iframe.src = ... on click.

const iframe = document.createElement('iframe');
iframe.src = '/ToolBase/3DViewer/3DViewer.html?url=%2FToolBase%2F3DViewer%2Fspz%2FDingZheng.spz';
iframe.className = 'splat-viewer-iframe';
iframe.loading = 'lazy';
container.appendChild(iframe);

Recommended Practices

1. When showing 3D models in articles, prefer the unified entry point /ToolBase/3DViewer/3DViewer.html.
2. If what you're showing is a single SPZ model, still use the same entry point rather than the old SPZ viewer.
3. For large models, use a click-to-load placeholder to reduce first-screen resource consumption.
4. Add a one-line note: where the model came from, what to look at, and fallback text for load failures.