embodied_gen/skills/spatial-computing/REFERENCE.md

Floorplan Skill — API Reference

This document provides API details, configuration items, errors, and dependencies for reference beyond the usage instructions in SKILL.md.

Contents

• Floorplan Skill — API Reference
  • Contents
  • LLM Environment Configuration
  • FloorplanManager
    • Constructor
    • Methods
  • Convenience Functions
  • CLI Features
    • Command Line Parameters
  • Configuration and Ignore Items
  • Smart File Naming Strategy
  • USD and Blender
  • Errors and Return Values
  • Dependencies
  • Usage Recommendations

---

LLM Environment Configuration

Before using semantic matching (resolve_* methods), configure the LLM API:

# Use the project-provided env (Azure + proxy), if outputs/env.sh exists:
source outputs/env.sh

If access to the LLM interface is unavailable, prompt the user.

---

FloorplanManager

Constructor

from importlib import import_module

FloorplanManager = import_module(
    "embodied_gen.skills.spatial-computing.api"
).FloorplanManager

manager = FloorplanManager(
    urdf_path="scene.urdf",      # Required
    usd_path=None,               # Optional; USD write after insert/delete if provided
    mesh_sample_num=50000,
    ignore_items=None,           # Default ["ceiling", "light", "exterior"]
    output_strategy="suffix",    # "suffix" (default) / "timestamp" / "overwrite"
)

Methods

Method	Description
visualize(output_path)	Generate floorplan and save as image
insert_object(asset_path, instance_key, in_room=..., on_instance=..., beside_instance=..., place_strategy=..., n_max_attempt=2000, rotation_rpy=...)	Place object, automatically write back to URDF/USD on success, return [x,y,z] or None
delete_object(instance_key, in_room=..., urdf_output_path=..., usd_output_path=...)	Delete instance from scene, return True/False. Supports room constraint via in_room
query_instance_center(instance_key)	Query instance center coordinates, return [x,y,z] or None
update_scene(urdf_output_path=..., usd_output_path=...)	Manually write back currently placed instances; generally not needed (called inside insert_object)
get_room_names()	List of room names
get_instance_names()	List of instance names (excluding walls/floor)
get_instance_names_in_room(in_room)	List of instance names within a specific room
resolve_on_instance(on_instance, gpt_client=None)	Resolve user description to exact instance name
resolve_in_room(in_room, gpt_client=None)	Resolve user description to exact room name
resolve_beside_instance(beside_instance, gpt_client=None, in_room=None)	Resolve user description to exact instance name for beside placement
resolve_delete_instance(delete_instance, gpt_client=None, in_room=None)	Resolve user description to exact instance name for deletion
resolve_and_query_instance(query_instance, gpt_client=None)	Resolve and query instance center in one call, return (resolved_name, [x,y,z]) or (None, None)
get_occupied_area()	Occupied area Shapely geometry
get_floor_union()	Floor area union geometry

Key parameters:

• on_instance / beside_instance / delete_instance: Exact instance name or semantic description (with gpt_client)
• in_room: Room constraint for placement/deletion/query
• place_strategy: "random" (default) or "top" (select highest surface)
• beside_distance: Max distance in meters for beside placement (default 0.5)

---

Convenience Functions

Function	Description
visualize_floorplan(urdf_path, output_path, ...)	Generate floorplan only
insert_object_to_scene(urdf_path, asset_path, instance_key, output_path, ...)	Insert object and generate floorplan, return [x,y,z] or None
delete_object_from_scene(urdf_path, instance_key, in_room=..., output_path=...)	Delete instance and optionally generate floorplan, return True/False
query_instance_position(urdf_path, instance_key)	Quick query instance center coordinates, return [x,y,z] or None
resolve_instance_with_llm(gpt_client, instance_names, user_spec, ...)	Use LLM to match user description to exact instance name

---

CLI Features

Command Line Parameters

Parameter	Description
--urdf_path	Input URDF scene file path (required)
--usd_path	Optional USD scene file path, update USD simultaneously if specified
--asset_path	Object mesh file path (.obj) for insertion
--instance_key	Unique identifier for the new instance, default inserted_object
--in_room	Limit placement to specified room, supports semantic description
--on_instance	Place on top of specified instance, supports semantic description
--beside_instance	Place beside specified instance on floor, supports semantic description
--beside_distance	Max distance (meters) from target instance, default 0.5
--place_strategy	Placement strategy: "random" (default) or "top"
--rotation_rpy	Initial rotation angle (roll, pitch, yaw radians)
--output_path	Floorplan output path
--output_strategy	File naming strategy: "suffix" (default) / "timestamp" / "overwrite"
--list_instances	List instance names and room names, then exit
--delete_instance	Instance name to delete (supports semantic description)
--delete_in_room	Room constraint for deletion
--query_instance	Instance name to query position (supports semantic description)
--max_placement_attempts	Maximum placement attempts, default 2000

CLI Usage Examples

View scene info:

python -m embodied_gen.skills.spatial-computing.cli.main \
  --urdf_path .../scene.urdf --list_instances

Insert object with semantic matching:

source outputs/env.sh
python -m embodied_gen.skills.spatial-computing.cli.main \
  --urdf_path .../scene.urdf --asset_path .../lamp.obj --instance_key lamp_1 \
  --on_instance 书柜

Delete object with room constraint:

python -m embodied_gen.skills.spatial-computing.cli.main \
  --urdf_path .../scene.urdf --delete_instance 沙发 --delete_in_room 客厅

Query instance position:

python -m embodied_gen.skills.spatial-computing.cli.main \
  --urdf_path .../scene.urdf --query_instance 床

Update both URDF and USD (room-cli):

room-cli -m embodied_gen.skills.spatial-computing.cli.main \
  --urdf_path .../scene.urdf --usd_path .../scene.usdc \
  --delete_instance 沙发

---

Configuration and Ignore Items

Parameter	Default	Description
mesh_sample_num	50000	Number of mesh sampling points
ignore_items	["ceiling", "light", "exterior"]	Link name patterns to skip during URDF parsing
output_strategy	"suffix"	File naming strategy for output files

---

Smart File Naming Strategy

Default output_strategy="suffix" provides intelligent continuous operation support:

Operation	Input File	Output File	Behavior
First insert	scene.urdf	scene_updated.urdf	Creates new file
Second insert	scene_updated.urdf	scene_updated.urdf	Overwrites (continuous)
Delete	scene_updated.urdf	scene_updated.urdf	Overwrites (continuous)

Key features:

• ✅ No *_updated_updated.urdf accumulation
• ✅ Original scene.urdf never modified
• ✅ Seamless insert/delete workflow

Alternative strategies:

• "timestamp": Unique versioning (scene_20260311_180235.urdf)
• "overwrite": Direct overwrite (use with caution)

---

USD and Blender

• Writing USD requires Blender (bpy). Use room-cli environment for USD operations.
• Without usd_path, only URDF is updated (no bpy needed).
• Assets in .usd/.usdc/.usda format are directly referenced; only .obj files are converted via bpy.
• If *_collision.obj exists alongside visual mesh, it will be used for URDF collision.

---

Errors and Return Values

Exceptions

• ValueError: Room/instance not found; update_scene() called before insertion; instance_key already exists; attempting to delete protected instances (walls, *floor*).

Return Values

• insert_object / insert_object_to_scene: [x, y, z] on success, None on failure.
• delete_object / delete_object_from_scene: True on success, False on failure.
• query_instance_center / query_instance_position: [x, y, z] or None.

Exit Codes (CLI)

• 0: Success
• 1: Instance/room not found, deletion failed, or placement failed

---

Dependencies

Type	Package	Description
Core	trimesh, shapely, matplotlib, numpy	Parsing and visualization
USD Writing	pxr, bpy	Required only when using usd_path; bpy requires Blender
LLM Semantic Matching	openai, project gpt_config	resolve_* methods require GPTclient instance
CLI	tyro	Required only for CLI entry point

---

Usage Recommendations

• Upright objects: Default orientation applies; for special orientations, pass (roll, pitch, yaw) radians.
• Placing on furniture: Use resolve_on_instance() to get exact name, then insert_object(..., on_instance=resolved, place_strategy="top").
• Placing beside furniture: Use insert_object(..., beside_instance=resolved, beside_distance=0.5) for floor placement near target.
• Deleting objects: Use resolve_delete_instance() for semantic matching, then delete_object(..., in_room=room) for room-specific deletion.
• Protected instances: Cannot delete walls or instances containing floor in their names.
• Continuous editing: Use scene_updated.urdf as input for subsequent operations to maintain changes.