Inspect Asset

/inspect-asset — deep-inspect a USD asset

What this skill does

Deep inspection of one 3D asset addressed by a URL (s3://bucket/key, omniverse://server/path, or a local filesystem path when running in local-FS mode). Produces a single comprehensive report covering visual, structural, geometric, semantic, and indexing dimensions of the asset.

Fires when the user has (or can supply) a specific asset URL and wants to understand that one asset in depth — as opposed to /search (find candidates) or /search-in-scene (spatial queries inside a scene).

Environment

Required:

• USD_SEARCH_API_URL — base URL of the USD Search API (e.g. https://search.simready.omniverse.nvidia.com or http://localhost:8080)

Auth — pick whichever is set, in this priority order:

1. USD_SEARCH_API_USERNAME + USD_SEARCH_API_PASSWORD -> Basic auth
2. USD_SEARCH_API_TOKEN set and not x -> bearer-style auth header
3. None set / token is x -> no auth header (public/unauth deployments)

All endpoints go through the unified nginx API gateway (http://localhost:8080, NVIDIA-hosted): /images, /info, /asset_graph/..., /dependency_graph/.... The Info Endpoint and Asset Graph Service are internal interfaces; do not address them directly.

Endpoints used

Workflow

Set up the base URL and auth once. Basic auth takes precedence over token auth; an empty or x token means unauthenticated. Before asking for any token or password, grep ~/.zshrc ~/.zshenv ~/.zprofile ~/.profile ~/.bashrc ~/.bash_profile ~/.env* for export <NAME>=; if absent, ask the user to export it themselves and pass back only the env-var name — never accept a pasted secret.

set -euo pipefail

API="${USD_SEARCH_API_URL%/}"

AUTH_ARGS=()
if [ -n "${USD_SEARCH_API_USERNAME:-}" ] && [ -n "${USD_SEARCH_API_PASSWORD:-}" ]; then
  AUTH_ARGS=(-u "${USD_SEARCH_API_USERNAME}:${USD_SEARCH_API_PASSWORD}")
elif [ -n "${USD_SEARCH_API_TOKEN:-}" ] && [ "${USD_SEARCH_API_TOKEN}" != "x" ]; then
  AUTH_ARGS=(-H "Authorization: Bearer ${USD_SEARCH_API_TOKEN}")
fi

1. Identify the asset

• URL provided: use it directly (s3://..., omniverse://..., or a local filesystem path returned by local-FS mode).
• Name or description provided: run /search first, then inspect the best matching URL from ./search-results/<slug>/manifest.json.

ASSET_URL='<ASSET_URL>'
OUT_DIR="./search-results/inspect-$(printf '%s' "$ASSET_URL" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g' | cut -c1-80)"
mkdir -p "$OUT_DIR"

2. Fetch thumbnails

Fetch up to four rendered views. A 404 means that offset is not available; keep any earlier images.

for offset in 0 1 2 3; do
  code=$(curl -sS -G "${API}/images" \
    "${AUTH_ARGS[@]}" \
    --data-urlencode "asset_url=${ASSET_URL}" \
    --data-urlencode "img_offset=${offset}" \
    -o "${OUT_DIR}/thumb_${offset}.jpg" \
    -w '%{http_code}' || true)
  case "$code" in
    2*) ;;
    404) rm -f "${OUT_DIR}/thumb_${offset}.jpg" ;;
    *) rm -f "${OUT_DIR}/thumb_${offset}.jpg"; printf 'thumbnail offset %s returned HTTP %s\n' "$offset" "$code" ;;
  esac
done

3. Visual inspection

Inspect each saved image and report object identity, visual characteristics, material/texture, quality, artifacts, scale impression, and likely use cases. If multiple views are available, compare them and assess 3D completeness.

4. Check indexing status

curl -sS -G "${API}/info/indexing/asset/status" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "url=${ASSET_URL}" \
  --data-urlencode "return_asset_metadata=true"

Interpret plugin status values:

• in_sync — processed and current
• out_of_sync — asset changed since processing
• not_found — not processed

Also report storage_backend_info.asset_status when present.

On deployments with VLM metadata generation enabled, the index also carries per-asset generated fields (caption, description, object_type, category, tags, colors, materials, style, scale, state, and more — the full schema is packages/llm-client/llm_client/metadata/metadata_fields.yaml). Retrieve them with a /search_hybrid request filtered to this asset (file_name + return_vision_generated_metadata=true) and fold them into the report. The two quality flags are booleans:

• is_high_quality — complete, properly textured, clean geometry (renamed from is_sim_ready — assets indexed before the rename may still carry the old key; treat both as the same signal)
• has_issues — visible defects present

5. Get scene graph data

curl -sS -G "${API}/asset_graph/usd/scene_summary/" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "scene_url=${ASSET_URL}"

curl -sS -G "${API}/asset_graph/usd/prims" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "scene_url=${ASSET_URL}" \
  --data-urlencode "root_prim=true"

curl -sS -G "${API}/asset_graph/usd/prims" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "scene_url=${ASSET_URL}" \
  --data-urlencode "default_prim=true"

curl -sS -G "${API}/asset_graph/usd/prims" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "scene_url=${ASSET_URL}" \
  --data-urlencode "prim_type=Mesh"

The scene-summary response yields:

• n_prims — total number of prims (objects/nodes) in the scene
• prim_types — count per type (Mesh, Xform, Material, Scope, etc.)
• total_polygon_count — scene geometry complexity
• unique_property_keys — available USD attributes
• referenced_assets — external files referenced
• scene_mpu — meters per unit (for real-world scale)
• scene_up_axis — coordinate system (Y-up or Z-up)
• default_prim — entry-point prim for this asset

Use prim responses for hierarchy, mesh count, dimensions, semantic properties, and source asset references. Note prims use response_model_exclude_none=true, so a non-default prim omits the default_prim key entirely — read it defensively.

6. Get dependencies

curl -sS -G "${API}/dependency_graph/flat" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "root_node_url=${ASSET_URL}"

curl -sS -G "${API}/dependency_graph/inverse/flat" \
  "${AUTH_ARGS[@]}" \
  --data-urlencode "root_node_url=${ASSET_URL}"

7. Present the report

See Output below for the report layout.

Invoking this skill — or typing /inspect-asset <url-or-description> as a slash command — runs this workflow; it also auto-invokes when the user's natural-language request matches the triggers above.

Output

Comprehensive report: thumbnail(s) with detailed visual description, identity (URL / size / timestamps), scene structure (prim tree, types, default prim), geometry (polygon count, bounding box in real-world scale using scene_mpu), semantic properties / labels, forward + inverse dependencies, per-plugin indexing status, and an overall quality assessment.

Related skills

• /search — find candidate assets first if the user gave a description rather than a URL
• /search-in-scene — for spatial / scene-graph queries inside a USD scene rather than a single-asset deep dive