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
  • USD and Blender
  • Errors and Return Values
  • Dependencies
  • Usage Recommendations

---

LLM Environment Configuration

Before using resolve_instance_with_llm or FloorplanManager.resolve_on_instance/resolve_in_room for semantic matching, configure the LLM API and ensure access to the interface.

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

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

---

FloorplanManager

Constructor

from embodied_gen.skills.spatial_computing.api import FloorplanManager

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

Methods

Method	Description
visualize(output_path)	Generate floorplan and save as image
insert_object(asset_path, instance_key, in_room=..., on_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. on_instance must be an exact instance name
update_scene(urdf_output_path=..., usd_output_path=...)	Manually write back currently placed instances; generally not needed (called inside insert_object). Use for custom output paths
get_room_names()	List of room names
get_instance_names()	List of instance names (excluding walls/floor)
resolve_on_instance(on_instance, gpt_client=None)	Resolve user description (e.g., "柜子", "书柜") to exact instance name; if already exact, return directly. With gpt_client, use LLM semantic matching, return None if no match
resolve_in_room(in_room, gpt_client=None)	Resolve user description to exact room name; if already exact, return directly. With gpt_client, use LLM semantic matching, return None if no match
resolve_beside_instance(beside_instance, gpt_client=None)	Resolve user description to exact instance name for beside placement; if already exact, return directly. With gpt_client, use LLM semantic matching, return None if no match
get_occupied_area()	Occupied area Shapely geometry
get_floor_union()	Floor area union geometry

Common insert_object parameters: in_room to limit room; on_instance to place on top of an instance (exact instance name, can be resolved via resolve_on_instance); beside_instance to place beside an instance on the floor (exact instance name, can be resolved via resolve_beside_instance); beside_distance max distance in meters for beside placement (default 0.5); place_strategy is "random" (default) or "top"; rotation_rpy not required by default; n_max_attempt maximum placement attempts before failure. Note: on_instance and beside_instance are mutually exclusive.

---

Convenience Functions

Function	Description
visualize_floorplan(urdf_path, output_path, mesh_sample_num=50000, ignore_items=None)	Generate floorplan only, do not write back to scene
insert_object_to_scene(urdf_path, asset_path, instance_key, output_path, usd_path=None, in_room=None, on_instance=None, beside_instance=None, beside_distance=0.5, place_strategy="random", rotation_rpy=...)	Create manager, place, automatically write back, generate floorplan; on_instance must be exact instance name; beside_instance places beside target on floor; returns placement center [x,y,z] or None. URDF output does not overwrite original file by default
resolve_instance_with_llm(gpt_client, instance_names, user_spec, prompt_template=None)	Use LLM to semantically match user description to one exact instance name in the scene; return None if no match, caller should prompt "does not exist, please re-enter". Depends on embodied_gen.utils.gpt_clients.GPTclient

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	Placeholder object mesh file path (.obj)
--instance_key	Unique identifier for the new instance, default inserted_object
--in_room	Limit placement to specified room, supports semantic description (requires LLM environment)
--on_instance	Place on top of specified instance, supports semantic description (requires LLM environment)
--beside_instance	Place beside specified instance on the floor, supports semantic description (requires LLM environment)
--beside_distance	Max distance (meters) from target instance for beside placement, default 0.5
--place_strategy	Placement strategy: "random" (default) or "top" (select highest surface)
--rotation_rpy	Initial rotation angle (roll, pitch, yaw radians)
--output_path	Floorplan output path
--list_instances	List instance names and room names in current scene, print and exit
--max_placement_attempts	Maximum placement attempts before failure, default 2000

CLI Usage Examples

View scene instance names and room names:

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

Visualize floorplan only:

python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png

Put lamp on bookshelf (supports semantic description):

source outputs/env.sh
python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png \
  --asset_path .../lamp.obj --instance_key lamp_on_bookcase \
  --on_instance 书柜

Put table in a room:

python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png \
  --asset_path .../table.obj --instance_key table_1 \
  --in_room living_room

Place object on table in living room (room + on object):

python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png \
  --asset_path .../apple.obj --instance_key apple_1 \
  --in_room living_room --on_instance table --place_strategy top

Place chair beside table (on floor, collision-free):

source outputs/env.sh
python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png \
  --asset_path .../chair.obj --instance_key chair_beside_table \
  --beside_instance 桌子

Place beside with room constraint and custom distance:

python -m embodied_gen.skills.spatial_computing.cli.main \
  --urdf_path .../scene.urdf --output_path .../floorplan.png \
  --asset_path .../chair.obj --instance_key chair_beside_table \
  --in_room kitchen --beside_instance table --beside_distance 0.8

URDF Output Note: The updated URDF is written to *_updated.urdf by default (e.g., scene.urdf → scene_updated.urdf), and will not overwrite the original scene.urdf unless the user specifies a custom output path.

---

Configuration and Ignore Items

Parameter	Default	Description
mesh_sample_num	50000	Number of mesh sampling points, larger values yield more precise floor plan polygons
ignore_items	["ceiling", "light", "exterior"]	Link name patterns to skip during URDF parsing

---

USD and Blender

• Writing USD converts .obj to .usdc, requiring Blender (bpy). For USD writing in this project, use the room-cli environment (bpy installed).
• 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 in the same directory as the visual mesh, it will be written to URDF for collision.

---

Errors and Return Values

Exceptions

• ValueError: Room or instance name does not exist; update_scene() called before insert_object() or after failed insertion; instance_key already exists.

Return Values

• insert_object / insert_object_to_scene: Returns [x, y, z] on success, None on failure (e.g., no valid placement after n_max_attempt attempts).

---

Dependencies

Type	Package	Description
Core	trimesh, shapely, matplotlib, numpy	Parsing and visualization
USD Writing	pxr (e.g., pip install usd-core), bpy	Required only when using usd_path; bpy requires Blender
LLM Semantic Matching	openai, project gpt_config	resolve_instance_with_llm requires GPTclient instance (see embodied_gen.utils.gpt_clients) and corresponding API configuration
CLI	tyro	Required only for CLI entry point

---

Usage Recommendations

• Upright objects: Default orientation applies, no need to set rotation_rpy; for special orientations, pass (roll, pitch, yaw) radians, e.g., upright (1.57, 0, 0).
• Placing on furniture: First use resolve_instance_with_llm(gpt_client, get_instance_names(), user_input) to get the exact instance name, then insert_object(..., on_instance=resolved, place_strategy="top"); if matching fails, prompt user to re-enter. For random ground placement, use place_strategy="random" (default).
• Placing beside furniture: Use insert_object(..., beside_instance=resolved, beside_distance=0.5) to place the new object on the floor beside the target instance, collision-free. Increase beside_distance if placement fails (e.g., when the area around the target is crowded).
• Collision meshes: If *_collision.obj exists in the same directory as the visual mesh, it will automatically be used for the collision node in URDF.