Skip to main content
Glama

capture_viewport

Read-only

Render a camera frame to PNG and save bounding-box and instance-segmentation maps, so you can see the scene and identify which prim is where.

Instructions

Render one frame from a camera at width x height and save 3 files to mcp_output/captures/:

  1. Image (PNG): what the camera sees.

  2. Bounding boxes (TXT): each mesh or shape under /World whose world box lies on the image, its box in pixels, world centre and size.

  3. Instance segmentation (PNG): each prim in a colour of its own, with a legend naming them.

Use it to see the scene and tell which prim is where: the boxes for places, the segmentation for prims that overlap. It renders camera_path, or the viewport's camera when empty, in a render of its own, so the viewport the user sees keeps its camera and size. Aim first with set_camera, at a point or a prim; for one prim from every side, use inspect_prim. An all-black image, or lighting that lights nothing (mode off, or stage with no scene lights) though Kit's grid shows, comes with a warning saying what to change with viewport_light. Without omni.syntheticdata only the image comes: the boxes and segmentation need it.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "capture_viewport"
  }
}

Input Schema

NameRequiredDescriptionDefault
widthNoImage width in pixels, up to 4096; the camera is rendered at this size
heightNoImage height in pixels, up to 4096; the camera is rendered at this size
camera_pathNoThe camera prim to capture from, which must be a camera; the viewport's when empty
include_imageNoAlso return the image inline, besides the file (uses more context)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.2.3
    • changedInput schema / properties / camera_path / description
      Previous value: -"The camera prim to capture from; the active one when empty"New value: +"The camera prim to capture from, which must be a camera; the viewport's when empty"
    • changedInput schema / properties / height / description
      Previous value: -"Image height in pixels"New value: +"Image height in pixels, up to 4096; the camera is rendered at this size"
    • changedInput schema / properties / width / description
      Previous value: -"Image width in pixels"New value: +"Image width in pixels, up to 4096; the camera is rendered at this size"
  2. First observedv0.2.2

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description is consistent with a non-mutating capture. Beyond annotations it discloses what would otherwise be surprising: the render is isolated so the user's viewport camera and size are preserved, an all-black image or inactive lighting returns a warning, and omni.syntheticdata is required for boxes and segmentation (image only without it).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The numbered output list is well structured and the usage guidance is front-loaded. The final paragraph is dense and packs several separate facts (isolation, aiming, lighting warning, syntheticdata prerequisite) into one block, but nearly every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully enumerates the return artifacts and file locations, plus the degraded-mode prerequisite and failure warnings. Nothing an agent needs to invoke and interpret the capture is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so width/height/camera_path/include_image are already fully documented in structured fields. The description only reinforces the render-size behavior and the empty-camera_path fallback, adding little per-parameter meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (render one frame) and resource (camera), and enumerates the three artifacts it writes (image, bounding boxes TXT, instance segmentation PNG), so the agent knows exactly what the tool produces versus siblings like inspect_prim or get_scene_tree.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('see the scene and tell which prim is where'), which output to prefer for which question (boxes for places, segmentation for overlapping prims), and routes to alternatives: set_camera to aim first, inspect_prim for one prim from every side, viewport_light for lighting problems.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.