horizonrobotics Floorplan & Object Placement/Deletion
Overview
Parse indoor scenes from URDF, generate 2D floorplans, or place/remove 3D objects in scenes and write back to URDF/USD. After successful insertion/deletion, the corresponding file is automatically updated based on whether urdf_path/usd_path is provided.
When to use: Use this skill when you need to generate floorplans from URDF, place/delete objects on specified rooms/furniture surfaces, or batch update URDF/USD files.
⚠️ USD updates require
room-cli: To update USD files, you must useroom-cliinstead ofpython -m, and specify the USD file via--usd_path.room-cliruns on Blender Python which includes thebpymodule for OBJ→USD conversion; usingpython -mwith--usd_pathwill fail withModuleNotFoundError: No module named 'bpy'.# ✅ Correct: use room-cli to update both URDF and USD room-cli -m embodied_gen.skills.spatial-computing.cli.main \ --urdf_path .../scene.urdf --usd_path .../scene.usdc ...
Smart File Naming Strategy:
- Default behavior: First operation creates
scene_updated.urdf, subsequent operations automatically overwrite it - No file bloat: Prevents
*_updated_updated.urdffiles from accumulating - Safe: Original
scene.urdfis never modified unless explicitly requested - Works for both insert and delete: Seamless continuous scene editing
Best Practices & Constraints
1. Workflow for Continuous Scene Editing
Recommended workflow for multiple insert/delete operations:
# Step 1: View current scene
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --list_instances
# Step 2: First insert → creates scene_updated.urdf
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--asset_path .../apple.obj --instance_key apple_1
# Step 3: Second insert → overwrites scene_updated.urdf
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene_updated.urdf \
--asset_path .../lamp.obj --instance_key lamp_1
# Step 4: Delete operation → overwrites scene_updated.urdf
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene_updated.urdf \
--delete_instance apple_1
Key benefits:
- ✅ No multiple
*_updated_updated.urdffiles - ✅ Original file
scene.urdfalways preserved - ✅ Continuous insert/delete operations are seamless
Result: Clean workflow with only two files:
scene.urdf(original, untouched)scene_updated.urdf(final state)
2. When to Use Different Strategies
| Strategy | Use Case | Example |
|---|---|---|
| suffix (default) | Standard workflow, continuous editing | Most scenarios |
| timestamp | Version tracking, backup before risky changes | scene_20260311_180235.urdf |
| overwrite | Confident single operation, no backup needed | Automated pipelines |
3. Performance Optimization: Batch Insert
Problem: CLI commands re-parse URDF and process all meshes on every call, leading to slow performance when inserting multiple objects.
Solution: Use --batch_insert_config with JSON config for 3-4x speedup:
Step 1: Create JSON config file (batch_chairs.json):
[
{
"asset_path": "path/to/chair1.obj",
"instance_key": "chair_1",
"beside_instance": "table_dining_7178300",
"in_room": "dining_room_0_floor"
},
{
"asset_path": "path/to/chair2.obj",
"instance_key": "chair_2",
"beside_instance": "table_dining_7178300",
"in_room": "dining_room_0_floor"
},
{
"asset_path": "path/to/chair3.obj",
"instance_key": "chair_3",
"beside_instance": "table_dining_7178300",
"in_room": "dining_room_0_floor"
}
]
Step 2: Run batch insertion:
# Update URDF only
room-cli -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--batch_insert_config batch_chairs.json
# Update both URDF and USD
room-cli -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--usd_path .../scene.usdc \
--batch_insert_config batch_chairs.json
JSON Config Fields:
asset_path(required): Path to asset mesh file (.obj)instance_key(required): Unique instance identifierbeside_instance: Place beside target instance (on floor). Must be exact name.on_instance: Place on top of target instance. Must be exact name.in_room: Limit placement to specified room. Must be exact name.beside_distance: Max distance from target (default: 0.5m)place_strategy: "random" or "top" (default: "random")
⚠️ Batch insert does NOT support fuzzy/semantic matching.
beside_instance,on_instance, andin_roomrequire exact names. Use--list_instancesto get the exact instance / room names first:python -m embodied_gen.skills.spatial-computing.cli.main \ --urdf_path .../scene.urdf --list_instances
When to Use:
- ✅ Inserting 2+ objects at once
- ✅ Performance-critical workflows
- ✅ Automated scene generation pipelines
⚠️ Batch config file cleanup: The JSON config file for --batch_insert_config is a temporary file and must not be left in the project root directory. Always:
- Create the JSON config in the same directory as the target scene (e.g.,
.../House_seed5/batch_fruits.json). - Delete the JSON config file immediately after the batch command finishes, regardless of success or failure.
3. Important Constraints
USD prim hierarchy: When updating a USD file, inserted assets must be
authored under the stage's defaultPrim (for existing room exports this is
usually /World), for example /World/<instance_key>. Do not write inserted
objects as pseudo-root children like /<instance_key> because USD references in
IsaacSim load the defaultPrim only; root-level siblings outside defaultPrim
will be omitted.
❌ Wrong: Using scene.urdf for all operations (ignores previous changes)
# This will NOT see apple_1 from previous operation
python -m ... --urdf_path scene.urdf --asset_path lamp.obj
✅ Right: Chain operations using scene_updated.urdf
# This WILL see apple_1 and add lamp_1
python -m ... --urdf_path scene_updated.urdf --asset_path lamp.obj
LLM Environment (Required for Semantic Matching)
Before using resolve_instance_with_llm for semantic matching in Python, configure the LLM API and ensure access to the interface. Prompt the user if access is unavailable.
# Use the project-provided env (Azure + proxy, etc.), if outputs/env.sh exists:
source outputs/env.sh
Core Convention: Placement/Deletion/Query Requests Must Use This Skill's Interface
When users request "put A somewhere", "delete A", "find A", or "visualize urdf", you must implement it using this skill's interface:
| User Request Example | Corresponding Parameter & Usage |
|---|---|
| Put A on B (e.g., "put lamp on bookshelf") | on_instance (instance name, obtained from --list_instances) |
| Put A beside B (e.g., "put chair beside table") | beside_instance (instance name, obtained from --list_instances); placed on floor near target |
| Put A in a room (e.g., "put table in living room") | in_room (room name, obtained from --list_instances) |
| Put A beside B in a room (e.g., "put chair beside table in kitchen") | beside_instance + in_room |
| Put A on B in a room (e.g., "put apple on table in living room") | Decomposed into "apple" and "living room" as in_room and on_instance |
| Delete A (e.g., "delete lamp") | delete_instance (instance name or semantic description, supports fuzzy matching with LLM) |
| Delete A in a room (e.g., "delete sofa in living room") | delete_instance + delete_in_room (only deletes if instance is in specified room) |
| Find A (e.g., "find lamp", "where is the bed") | query_instance (returns center coordinates [x, y, z], supports fuzzy matching with LLM) |
| output_strategy | "suffix" / "timestamp" / "overwrite" | File naming strategy for output files. Default is "suffix" (non-destructive). |
| Visualize scene.urdf | cli.main --urdf_path .../scene.urdf --output_path .../floorplan.png; output_path defaults to same directory as urdf |
- When no match is found, prompt "The object/room does not exist, please re-enter" and provide the current scene object or room list.
- Instance names should not use the
<link name="...">from URDF. Recommended: Run--list_instancesbefore placement/deletion/query to view current instance name list, and select the closest semantic match.
CLI Examples
Tip: The URDF file is typically located at
<room_folder>/urdf/export_scene/scene.urdf(e.g.,outputs/rooms/Kitchen_seed0/urdf/export_scene/scene.urdf).
Example 1: View Instance Names and Room Names in Current Scene
# View instance names and room names in current scene (to fill in --on_instance / --in_room)
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --list_instances
Example 2: Visualize Floorplan Only
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --output_path .../floorplan.png
Example 3: Put Lamp on Bookshelf (Place on an Object)
--on_instance can be filled with the instance name returned by --list_instances or a semantic description.
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 书柜
Example 4: Put Table in Living Room (Place 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
Example 5: Put Apple 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
Example 7: Delete an Object (Exact Name)
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --output_path .../floorplan.png \
--delete_instance bed_192207
Example 8: Delete Object with Fuzzy Matching (Semantic Description)
Requires LLM environment (see "LLM Environment" section).
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --output_path .../floorplan.png \
--delete_instance "沙发"
Example 9: Delete Object in Specific Room
Only deletes the instance if it's located in the specified room.
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --output_path .../floorplan.png \
--delete_instance "沙发" --delete_in_room "客厅"
Update both URDF and USD using room-cli:
room-cli -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf --usd_path .../scene.usdc \
--output_path .../floorplan.png \
--delete_instance "沙发" --delete_in_room "客厅"
Example 10: Query Instance Position (Exact Name)
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--query_instance bed_192207
Expected output:
📍 Instance 'bed_192207' center: (-0.9250, -6.5830, 0.5000)
Example 11: Query Instance Position with Fuzzy Matching
Requires LLM environment (see "LLM Environment" section).
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--query_instance "床"
Alternative Strategies
Timestamp - Unique versioning for each operation:
# Output: scene_20260311_180235.urdf
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--asset_path .../apple.obj --instance_key apple_1 \
--output_strategy timestamp
Overwrite - Directly overwrite original (use with caution):
# Overwrites: scene.urdf
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path .../scene.urdf \
--asset_path .../apple.obj --instance_key apple_1 \
--output_strategy overwrite
Query Instance Position
Query the center coordinates of an instance in the scene. Supports fuzzy matching with LLM.
CLI Interface:
# Exact instance name
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path scene.urdf \
--query_instance bed_192207
# Fuzzy matching (requires GPT)
source outputs/env.sh
python -m embodied_gen.skills.spatial-computing.cli.main \
--urdf_path scene.urdf \
--query_instance "床"
6. Common Parameters
| Parameter | Meaning |
|---|---|
in_room |
Limit placement to specified room |
on_instance |
Place on top of specified instance; must be exact instance name (obtained via resolve_instance_with_llm) |
beside_instance |
Place beside specified instance on the floor; must be exact instance name (obtained via resolve_instance_with_llm). Mutually exclusive with on_instance |
beside_distance |
Max distance (meters) from target instance for beside placement. Default 0.5. Increase if placement fails |
place_strategy |
"random" random placement (default, e.g., bookshelf with 3 layers will randomly select one), "top" select highest surface |
rotation_rpy |
Not required by default; pass (roll, pitch, yaw) radians for special orientations |
delete_instance |
Instance name or semantic description to delete (supports fuzzy matching with LLM). Cannot delete protected items (walls, floors) |
delete_in_room |
Optional room constraint for deletion - only delete if instance is in this room |
query_instance |
Instance name or semantic description to query center coordinates (supports fuzzy matching with LLM). Returns [x, y, z] position |
Roaming Trajectory Generation (Optional)
Generate a smooth, collision-free robot roaming trajectory on a floorplan and overlay it on the floorplan image. Opt-in and off by default: the normal floorplan visualization never draws a trajectory unless you run this CLI. Doors are treated as open passages (excluded from obstacles).
CLI Interface:
python -m embodied_gen.scripts.room_gen.gen_trajectory \
--urdf_path .../scene.urdf \
--output_dir .../trajectory \
--clearance 0.4 --num_waypoints 8
Outputs <stem>_trajectory.json (equidistant {x, y, rot, t} waypoints at a
constant speed) and .png (red-path overlay). rot in degrees: 0° = +Y
(12 o'clock), counter-clockwise positive, tangent to the path (forward
heading); t is the timestamp in seconds.
Next Steps
- For complete API, configuration, errors, and dependencies, see REFERENCE.md.