TopviewAI 開源 Topview 3D Builder，提供提示詞驅動的可編輯 3D 場景工作流

Describing a camera angle is easy. Getting the character, prop, and camera into exactly the arrangement you intended is harder. When you generate an AI video directly from a prompt, even a small spatial mistake can send you back to another generation. What if the layout itself were editable before you committed to that step?

We built Topview 3D Builder around that question. It is an open-source tool for blocking out a scene on your computer: place characters and simple props, choose poses, position cameras, inspect framing, and render reference images that can inform a later AI-video workflow. Compatible coding agents can drive the scene through a local CLI and an agent skill, using natural-language requests as the starting point.

This post explains what the tool does, how its pieces fit together, and how to try it without a Topview account. It also explains what it doesn't do yet.

The workflow in one minute

Think of a short scene: two people face each other across a small table. You want an over-the-shoulder shot, but the second person keeps getting obscured when you describe the shot in text.

With an editable 3D staging step, you can separate two decisions:

• Spatial intent: Where are the people and objects? Which character is the subject? Where is the camera?
• Visual generation: What should the finished footage look and feel like? In a compatible agent, an illustrative request might be:

Block out a simple dialogue scene with two characters facing each other across a table. Use a camera behind the first character, aimed at the second. Render a reference view. Keep the scene editable so I can adjust blocking and camera position afterward.

The agent uses the project’s skill and CLI to construct the scene, rather than expecting the video model to infer every spatial decision from that sentence. You can then inspect the reference frame, change the staging, and render again. The result is a staging plan—not a finished AI-generated movie clip.

What is actually running on your machine?

The repository contains more than a prompt wrapper. It has three distinct parts:

• An agent skill and plugin manifests. These tell supported agents how to work with the scene tool. The repository documents integrations for Codex, Cursor, Qwen, Claude Code etc.
• A Python CLI (topview-3d-cli). It owns a scene project, validates structured edits, manages assets, and orchestrates evaluation and rendering.
• A local Studio and renderer. A Node-based rendering path uses Chromium to produce PNG reference frames; the Studio can open local scene projects for visual inspection and human editing. A simplified mental model is:

Natural-language request
        |
Compatible AI agent + Topview 3D skill
        |
Local scene operations (topview-3d-cli)
        |
Project files: .topview-3d/
        |                 \
Camera/layout checks       Local Studio
        |                 /
Rendered reference frames (PNG)
        |
Optional downstream AI-video workflow

The scene lives in a .topview-3d/ directory inside your local project. The CLI contract documents a structured scene state, operation batches, asset manifests, camera views, and render metadata. That makes the workflow more inspectable than a chain of unrecorded prompt retries.

Getting started: install, check, then create

The published CLI currently requires Python 3.11+, Node.js 20.6+, and the relevant package tooling. Rendering also needs a one-time Playwright/Chromium setup. The release documented here is topview-3d-cli 0.1.6; confirm the latest compatible version before publishing or installing.

For a standalone CLI installation, the repository documents the following path:

pipx install topview-3d-cli==0.1.6
topview-3d-cli browser ensure
topview-3d-cli doctor

browser ensure downloads the rendering browser dependencies once. Core scene editing and rendering are local, but initial installation and any cloud-hosted AI agent may require internet access. Local rendering is not the same claim as “every component is always offline.”

Create an empty project, inspect its status, and open the local Studio:

topview-3d-cli project init my-scene
topview-3d-cli project status my-scene
topview-3d-cli studio open my-scene

The project starts with a default camera. studio open starts a local server and reports its URL; open that URL in your browser if it does not open automatically. The empty scene is intentional: it gives the Agent or the CLI a concrete project to edit.

Using an AI coding agent: install the repository’s plugin/skill for a documented compatible agent, start a new session, and provide the natural-language staging request above. The exact plugin installation differs for Codex, Cursor, and Claude Code; follow the current repository README rather than applying one agent’s commands to another. Before posting installation commands, confirm the current agent-specific instructions in the repository.

If you prefer to explore without an agent first, these commands expose the scene-tooling model:

topview-3d-cli asset list --kind character
topview-3d-cli camera presets
topview-3d-cli document get my-scene --summary

They list available character assets, camera presets, and the project's current scene summary. The package's assets are deliberately limited; do not expect an unlimited catalog of production-ready actors or environments.

The useful part is editing, not the first render

A single natural-language prompt is a convenient start, but the real advantage comes after the scene exists. Suppose the first view is geometrically correct but visually weak: both faces overlap, the table cuts through the frame, or the camera is too high.

Instead of regenerating an entire video to learn whether the angle works, you can revise the scene:

• Reposition the characters and props relative to one another.
• Select a different static pose from the built-in catalog.
• Move a camera or change its target and framing.
• Render another reference view from the same scene state. The documented CLI exposes node batch for grouped node changes and pose batch for pose changes. It also exposes checks such as:

topview-3d-cli evaluate my-scene
topview-3d-cli inspect views my-scene
topview-3d-cli renders show my-scene

evaluate checks aspects such as framing, transforms, and ground penetration numerically. inspect views combines view checks with rendering. renders show reports the latest render’s file path. These commands do not promise cinematic judgment; they help catch measurable geometry or framing problems before you spend time on downstream generation.

There is also a practical software-engineering distinction here: a scene is state, not merely an image. The CLI records a scene sequence and validates operations; failed write commands are designed not to partially apply. When an agent proposes a change, the skill can check or dry-run it before saving. That matters when users want to revise a scene rather than ask the model to recreate the whole shot from memory.

Where this approach helps—and where it stops

We see three promising use cases.

1. Previsualizing composition. Before generating the expensive shot, establish relative positions and camera direction. A rough 3D blockout is useful even if none of its textures resemble the final video.

2. Comparing camera options. An identical spatial setup can be viewed from multiple cameras. That separates changes in framing from changes in content.

3. Making iterations explainable. “Move the second character half a step left” has a spatial meaning in a scene. A request such as “make the output more cinematic” is far less constrained.

But a reference frame is not a guarantee that a downstream video model will preserve character identity, composition, or movement exactly. Model behavior, input controls, and image-conditioning fidelity vary. A previs workflow can make intent more explicit; it cannot remove uncertainty from generative video.

The current skill describes four built-in characters, 121 static poses, simple primitives, static cameras, and root-level keyframing. There is no built-in walk-cycle or full-body motion library in this release. Position and rotation keyframes can suggest movement, but they are not the same thing as a fully animated character rig. We would rather state that plainly than market the project as a full 3D animation suite.

What about privacy, cost, and licensing?

The tool creates and renders local scene projects without requiring a Topview account or uploading scene files to Topview. Sending a render into Topview Canvas is a separate, optional workflow that asks for sign-in. An external AI agent may have its own cloud processing and privacy terms, so users should assess that provider independently.

Using the local 3D builder does not incur a Topview account fee. Whether it saves money on final video generation depends on your workflow, the model you use, and whether the extra previsualization work offsets avoided retries. We are not claiming a measured cost-reduction percentage here.

The source code, schemas, and documentation are Apache-2.0. Bundled characters, poses, and other specified built-in assets use CC BY 4.0, including attribution obligations. Review both notices before redistributing the assets.

Try it, break it, and tell us what is missing

The project is still early. We are especially interested in the moments where a staging tool helps—or gets in the way: awkward framing, incomplete asset choices, unhelpful validation output, agent installation friction, and the handoff from reference images to video generation.

Explore the source, installation instructions, and CLI contract in the Topview 3D Builder repository. If you try the workflow, open an Issue with the agent, operating system, relevant error, and a minimal reproduction (with private scene data removed). That feedback is more useful to us than a star count.