SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstopview-3d-cli

topview-3d-cli

Design & creation

View repository

Updated 10-16 18:23

About this skill

topview-3d-cli

topview-3d-cli edits and renders a local director project: a directory with a .topview-3d/ folder. The goal is an abstract, physically consistent staging reference for video generation: simple shapes, correct scale and support, clear blocking, one world seen from several static cameras. Character positions come first, then plausibility and camera continuity, then composition. Fine visual detail is not a goal; a phone can be a slab. Respond in the user's language.

Scope in this version: primitive props, the four built-in characters (Child, Youth, Female, Man), 121 static poses, static cameras and root keyframes. There is no motion library: never promise walk cycles or other body animation. To suggest movement, give the character a fitting static pose (for example a walking stride) and, only when the user asks for movement, add transform.position / transform.rotation keyframes (see references/edit.md). Preserve existing animation and editorial data rather than extending them.

Step 1: check the environment

Run this before anything else in a session:

topview-3d-cli doctor --json

It always exits 0; gate on the top-level ok. When ok is false, read each failing checks.<name>.hint and follow references/doctor-browser.md:

  • topview-3d-cli not found: it is installed once per machine, in an environment every project shares. Look there before installing anything: ~/.local/share/topview-3d-cli/venv/bin/topview-3d-cli on macOS and Linux, $env:LOCALAPPDATA\topview-3d-cli\venv\Scripts\topview-3d-cli.exe on Windows. When it exists and its doctor --json reports the cliVersion of this skill's pin, topview-3d-cli==0.1.8, use that path for every command. Otherwise install it once as references/doctor-browser.md describes (Installing topview-3d-cli). Never create a virtual environment inside the user's project or workspace, and do not use pip install --user.
  • node fails: Node.js 20.6 or newer (with npm) is required; ask the user to install it.
  • Checkout: when the folder that holds this skill also has agent/ and editor/ (plugin installs are checkouts), install by running its scripts/install.sh (or install.ps1 on Windows) once. It puts the CLI into the shared environment and installs the renderer and Studio's Next.js together. Do not install only the renderer package.
  • playwright or chromium fails: run topview-3d-cli browser ensure once (it downloads the pinned Chromium into the user cache).
  • Rendering fails inside an agent sandbox although doctor passes: the sandbox blocks the browser, not topview-3d-cli. Say so, ask the user to approve running the render command outside the sandbox, and keep working on everything that does not need a browser. Never build a substitute renderer (image libraries, SVG, hand-drawn frames).

CLI contract

  • Every command prints one JSON object on stdout. Failures print {"ok": false, "code", "error"} on stderr, with details (such as the failing index) when available. Exit 0 is success, 2 is invalid input, including an id that names no existing node, asset, pose or camera (fix the input), 1 is a command that could not be carried out (conflict, missing dependency, renderer failure).
  • Spec files are JSON objects; - reads stdin. Write them to a temporary file first.
  • Validate before writing: --dry-run on document apply, node batch and pose batch, and topview-3d-cli evaluate <dir> plan.json for a plan's numbers. Nothing is written when a command fails.
  • Pass expectedSceneSequence from the latest result. On SCENE_SEQUENCE_CONFLICT re-read and re-plan; never bump the number blindly.
  • Copy ids (libraryId, poseId, presetId, node ids) verbatim from command output. Never invent ids, dimensions or measurements.
  • After a render, open the returned PNG files and look at them before judging. A render that was not viewed is not visual evidence.
  • Change the 3D scene with topview-3d-cli (node batch, pose batch, document apply). Do not click, drag, or type in the Studio page, and do not use browser automation to move or edit nodes. The In-App Browser only opens Studio so the user can look at the scene.
  • One writer at a time: do not run a writing command while Studio is saving the same project. After the user edits in Studio, re-read with document get before planning the next change. Studio writes back through project adopt, so the project on disk is the edited scene.

Each session starts with context

topview-3d-cli project status <dir>            # or: topview-3d-cli project init <dir> for a new scene
topview-3d-cli document get <dir> --summary    # nodes, cameras, sceneSequence
topview-3d-cli bom get <dir>                   # the plan record: intent, relations, cameras, verification

Read them before planning; re-read only after your own writes or a conflict. `topview-3d-cli document get

Workflow stages

Read the reference for a stage once per session, before its first command:

Guide the user at every stage boundary

Core principle: guidance makes the next useful action clear. Pause at creative decision points; use progress updates for execution steps inside an already approved action.

By default, complete one stage below, make its result reviewable, then ask whether the user wants to continue to the named next stage or revise the current result. Wait for their answer before starting that next stage. Do not silently run the entire table and ask only after rendering. This applies to new scenes, edits and revisions, including the final delivery. Exception: once the user authorizes video generation for the current task, Stage 10 proceeds through preparation, service submission and delivery without further stage-boundary approval questions. This authorization covers the current generation round, not every future version of the 3D plan. If feedback sends the work back to the scene, model, pose or camera stages, complete and verify the revised preview, then stop and ask whether to generate from it or adjust it further. Do not carry the previous round's yes across this decision point. An explicit request to revise AND regenerate already answers that choice; see references/generate.md.

  • Briefly state what is ready, show the relevant plan, preview or result, and mention any unresolved limitation that affects the next choice. For nonvisual stages, a concise summary is enough.
  • Recommend a concrete next action and explain its purpose in one sentence. End with one clear question in the user's language. Name the actual action and what can be revised, rather than asking only “Continue?” or “What next?”. Examples (written in English; localize when responding):
    • After the layout plan: “Would you like me to build this scene in 3D, or revise the layout first?”
    • After scene construction: “Would you like me to set up the camera movement, or modify this scene first?”
    • After camera setup: “Would you like me to render a preview video, or adjust the camera movement first?”
    • After the reference and generation prompt are ready: “Would you like to proceed to video generation, revise this scene, or edit the generation prompt first?”
    • After revising the 3D preview following feedback: “The revised camera preview is ready. Would you like me to generate a new realistic video from it, or adjust the scene or camera movement further?” Use only options appropriate to the current result and available capabilities. If the reference video is not ready, offer to render or export it before offering the generation handoff.
  • A stage is a user-facing milestone, not each CLI call. Finish the reads, measurements, dry-runs, rendering and necessary corrections that make that stage reviewable before asking. Do not ask permission for each tool invocation or stop on an unverified intermediate result.
  • If the user requests changes, make and verify those changes within the current stage, present the updated result, then offer the next-stage-or-revise choice again. A request to revise does not by itself authorize proceeding to later stages. Silence is not an answer.
  • Apply only stages relevant to the request: an edit does not restart completed setup or rebuild unrelated objects. For the last applicable stage, offer a concrete follow-up or further revision; respect “stop”, “not now”, or a request for no further questions.
  • If the user explicitly asks to complete several stages or the whole workflow without pauses, honor that scope and ask at its end instead. Do not repeatedly reconfirm stages they have already approved. Ordinary “build a scene” requests use the guided stage boundaries above.
  • At the rendered-output handoff, follow Stage 10: prepare and show the generation prompt. Ask whether to generate only if the user has not already authorized generation from this version. An explicit request such as “render and generate the video” already authorizes it. After authorization, use progress updates rather than repeated approval questions about preparation or execution.
Stage What to do Reference
1. Understand Resolve intent from the conversation and current state; record it in the BOM references/state-intent.md
2. Layout Relationships, support, facing, clearance; BOM fields references/layout.md
3. Props 1–4 primitives first; imported models only when needed references/add-prop.md
4. People Pick from the built-in characters; place before posing references/add-character.md
5. Pose Reviewed text mappings; seat fitting references/pose.md
6. Cameras Mandatory bird's-eye overview plus story coverage scaled to the number of people references/camera.md
7. Edit Change only what was asked; batch syntax; keyframes references/edit.md
8. Check Numbers, renders, look at the PNGs, revise references/checks.md
9. Studio Open the finished scene in the local Studio with the In-App Browser references/doctor-browser.md
10. Generate Write and show the prompt; obtain generation authorization once if missing, then generate and record the result without repeated confirmation references/generate.md, references/video-prompt.md

After the frames are ready

Stage 10 is part of every workflow that ends in a rendered video or frames: do not close the session on the renders without it. Read references/generate.md and follow it. As soon as the video is rendered, you write the generation prompt yourself, without being asked, by following references/video-prompt.md, show it to the user, and ask whether to generate if authorization for this version is missing. Once authorized, complete service selection, generation and result recording without repeated approval prompts. A video generation uses the rendered or exported video as its reference.

Building, checking and rendering stay offline. Stage 10 is the only stage that may reach an outside service, within the user's authorized generation task. Never contact a generation service from any other stage.

Asset search rules for props, characters and poses are in references/asset-selection.md. Installation, the browser and sandbox limits are in references/doctor-browser.md.

Commands

Need Command
New project / state topview-3d-cli project init <dir>, topview-3d-cli project status <dir>
Read the document topview-3d-cli document get <dir> --summary, topview-3d-cli document get <dir> --entity <id>
Add, change, delete nodes topview-3d-cli node batch <dir> changes.json [--dry-run], topview-3d-cli node delete <dir> <id>
Low-level operations (scene settings, keyframes) topview-3d-cli document apply <dir> ops.json [--dry-run]
Find assets topview-3d-cli asset search <words> --kind character|pose|prop, topview-3d-cli asset show <id>
Pose list topview-3d-cli pose catalog [--category sit]
Pose people topview-3d-cli pose batch <dir> poses.json [--dry-run], topview-3d-cli pose apply <dir> <nodeId> <poseId>
Camera presets topview-3d-cli camera presets
Numbers without a browser topview-3d-cli evaluate <dir> [plan.json] [--frames 0,24] [--camera <id>]
Mesh measurements topview-3d-cli inspect nodes <dir> <id>... [--frame N]
Numbers plus renders per camera topview-3d-cli inspect views <dir> --camera <id> ... --primary <id>
One render topview-3d-cli render <dir> [payload.json]
Find a rendered PNG topview-3d-cli renders list <dir>, topview-3d-cli renders show <dir> [runId] [--frame N]
Plan record topview-3d-cli bom get <dir>, topview-3d-cli bom checkpoint <dir> patch.json
Structural validation topview-3d-cli document validate <dir>
Open in Studio topview-3d-cli studio open <dir>, then open the returned url in the In-App Browser

Hard rules

  1. Coordinates are right-handed, Y up, metres; rotations are Euler degrees; scale is a positive multiplier (0.001 for a paper-thin axis). Node ids match [A-Za-z0-9_-]{1,128}.
  2. Measure before grounding or seating (topview-3d-cli inspect nodes); frustum and ground checks in evaluate use node origins and primitive boxes only.
  3. Every scene keeps one dedicated bird's-eye camera (BOM camera role layout_overview), refitted after layout changes. It is layout evidence, never the primary story image.
  4. Choose one BOM story camera as --primary for inspect views. Unless the user sets the count, cover multi-person scenes per the minimums in references/camera.md (3 or more people: a group master, one view per interacting group and one close-up per main character).
  5. Ordinary "sitting" means a chair, sofa, bench or stool unless floor sitting, cross-legged sitting or kneeling is explicit. Reuse a seat or build one from 1–4 primitives first.
  6. Report gaps honestly: a simplified substitute is described as such; an unverified constraint stays unknown.
  7. Thin lines, stripes, z-fighting and aliasing are renderer artifacts, not defects. Edit only with a measurement or a failed BOM hard relation behind it. One inspect views per correction pass.
  8. Default timeline: 24 fps, 120 frames. Never paste image bytes or Base64 into messages; give paths.
  9. Change the 3D scene with the CLI. Do not edit it through the Studio page or browser automation.
  10. Open the local Studio in the In-App Browser so the user can view it. studio open only starts the server and returns url; open that url in the In-App Browser, not the system browser. If it fails because Next.js is not installed, run pnpm install in the checkout's editor/ directory once and retry studio open once. See references/doctor-browser.md.