Floorplan Loader

The FloorplanLoader provides methods to download and manage USD floorplan files for robotic simulation environments.

Quick Start

from lightwheel_sdk.loader import floorplan_loader, login_manager

# Login first
login_manager.login(username="your_username", password="your_password")

# Load a floorplan (async)
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1,
    backend="robocasa"
)

# Wait for download to complete
usd_path, metadata = future.result()

print(f"Floorplan downloaded to: {usd_path}")
print(f"Layout ID: {metadata['layout_id']}")
print(f"Style ID: {metadata['style_id']}")

Function Reference

acquire_usd

Parameter	Type	Required	Default	Description
`layout_id`	`int`	No	`None`	Exact layout identifier to retrieve.
`style_id`	`int`	No	`None`	Exact style identifier to pair with the layout.
`scene`	`str`	No	`"robocasakitchen"`	Logical scene grouping used to scope layouts and styles.
`backend`	`str`	No	`"robocasa"`	Rendering/runtime backend.
`cancel_previous_download`	`bool`	No	`True`	SDK behaviour flag; when `True`, an in-flight download is cancelled before issuing the next request.
`version`	`str`	No	`None`	36-character bundle UUID for a specific published USD version.
`exclude_layout_ids`	`List[int]`	No	`None`	Layouts that must be excluded from random selection.
`exclude_style_ids`	`List[int]`	No	`None`	Styles that must be excluded from random selection.
`split`	`str`	No	`None`	Dataset split tag.
`image`	`str`	No	`None`	Optional floorplan-to-USD render image identifier.
`layout_registry_names`	`List[str]`	No	`None`	Fallback lookup by registry name.

Output: concurrent.futures.Future

Calling future.result() returns (usd_path, metadata):

usd_path: Absolute path to the unpacked USD bundle inside the SDK cache.
metadata: Dictionary containing the following fields:

Field	Type	Description
`fileUrl`	`str`	Signed URL for downloading the USD bundle from storage.
`versionUuid`	`str`	Unique identifier (36-character UUID) for this specific version of the USD bundle.
`layoutId`	`int`	Layout identifier used to generate this floorplan.
`styleId`	`int`	Style identifier used to generate this floorplan.
`scene`	`str`	Scene name/identifier (e.g., `robocasakitchen`).
`backend`	`str`	Rendering/runtime backend identifier (e.g., `robocasa`).
`split`	`str`	Dataset split identifier (e.g., `train`, `test`, `custom`).
`image`	`str`	Optional floorplan-to-USD render image identifier if provided.

get_usd

Share the same parameters and returns the (usd_path, metadata) tuple immediately. Use this variant when you prefer blocking I/O over futures.

Loading Floorplans

By Layout and Style ID

# Load specific layout and style
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=5,
    style_id=3,
    backend="robocasa"
)

usd_path, metadata = future.result()

Random Floorplan

# Load random floorplan (omit layout_id and style_id)
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    backend="robocasa"
)

usd_path, metadata = future.result()

With Exclusions

# Load random, excluding specific layouts/styles
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    backend="robocasa",
    exclude_layout_ids=[1, 2, 3],
    exclude_style_ids=[1, 5]
)

usd_path, metadata = future.result()

By Version ID

# Load specific version
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    backend="robocasa",
    version="version-uuid-here"
)

usd_path, metadata = future.result()

With Split and Image

# Load from specific dataset split with image
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    backend="robocasa",
    layout_id=1,
    style_id=1,
    split="train",
    image="kitchen_001.png"
)

usd_path, metadata = future.result()

Asynchronous Downloads

The FloorplanLoader uses threading for non-blocking downloads:

# Start download (non-blocking)
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1
)

# Do other work while downloading
print("Download started...")

# Check if download is complete
if future.done():
    usd_path, metadata = future.result()
else:
    print("Still downloading...")
    
# Wait for completion
usd_path, metadata = future.result()  # Blocks until complete

Cancel Previous Downloads

# Start first download
future1 = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1,
    cancel_previous_download=True  # Default
)

# Start second download - automatically cancels first
future2 = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=2,
    style_id=2,
    cancel_previous_download=True
)

# Only future2 will complete
usd_path, metadata = future2.result()

Direct (Synchronous) Download

# Use get_usd for synchronous download
usd_path, metadata = floorplan_loader.get_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1,
    backend="robocasa"
)

print(f"Downloaded: {usd_path}")

Cache Management

Floorplans are cached to avoid re-downloading:

Cache Location

~/.cache/lightwheel_sdk/floorplan/

Cache Structure

~/.cache/lightwheel_sdk/floorplan/
├── robocasa-robocasakitchen-1-1/
│   ├── scene.usd
│   ├── assets/
│   └── ...
├── robocasa-robocasakitchen-2-2/
│   └── scene.usd
└── usd_version.json

Version Tracking

The SDK tracks floorplan versions to detect updates:

# First download - retrieves from server
future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1
)
usd_path, metadata = future.result()

# Subsequent calls check version
# If server has newer version, re-downloads
# Otherwise uses cached version
future2 = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1
)
usd_path2, metadata2 = future2.result()

Download Progress

The loader shows progress bars during download:

future = floorplan_loader.acquire_usd(
    scene="robocasakitchen",
    layout_id=1,
    style_id=1
)

# Output shows progress:
# Downloading Floorplan Package: 45%|████▌     | 23.5MB/52.3MB [00:12<00:15, 1.85MB/s]

Metadata

The metadata dictionary contains floorplan information:

usd_path, metadata = future.result()

print(metadata)
# {
#     'layout_id': 1,
#     'style_id': 1,
#     'version_id': 'uuid-here',
#     'backend': 'robocasa',
#     'scene': 'robocasakitchen',
#     'split': 'train',
#     ...
# }

Complete Example

from lightwheel_sdk.loader import floorplan_loader, login_manager
from concurrent.futures import TimeoutError

# Login
login_manager.login(username="your_username", password="your_password")

# Load multiple floorplans
floorplans = []
for layout_id in range(1, 4):
    for style_id in range(1, 3):
        future = floorplan_loader.acquire_usd(
            scene="robocasakitchen",
            layout_id=layout_id,
            style_id=style_id,
            backend="robocasa",
            cancel_previous_download=False  # Don't cancel
        )
        floorplans.append(future)

# Wait for all downloads
for i, future in enumerate(floorplans):
    try:
        usd_path, metadata = future.result(timeout=300)  # 5 min timeout
        print(f"Floorplan {i+1}: {usd_path}")
    except TimeoutError:
        print(f"Floorplan {i+1} download timed out")
    except Exception as e:
        print(f"Floorplan {i+1} failed: {e}")

Configuration

Custom Workers

Control the number of parallel downloads:

from lightwheel_sdk.loader import LightwheelClient
from lightwheel_sdk.loader.floorplan import FloorplanLoader

client = LightwheelClient(host="https://api.lightwheel.net")
client.login(username="user", password="pass")

# Create loader with custom worker count
floorplan_loader = FloorplanLoader(client, max_workers=8)

Custom Timeout

# Set custom timeout on client
client = LightwheelClient(host="https://api.lightwheel.net", base_timeout=120)
floorplan_loader = FloorplanLoader(client)

Error Handling

from lightwheel_sdk.loader import floorplan_loader
from lightwheel_sdk.loader.exception import ApiException

try:
    future = floorplan_loader.acquire_usd(
        scene="invalid_scene",
        layout_id=999,
        style_id=999
    )
    usd_path, metadata = future.result()
except ApiException as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Download failed: {e}")

Best Practices

Use async loading: Let downloads happen in background
Cancel previous downloads: Set cancel_previous_download=True to avoid wasted bandwidth
Cache awareness: Reuse layout_id/style_id combinations to leverage cache
Error handling: Always wrap in try-except for network issues
Timeouts: Set reasonable timeouts for large downloads

Quick Start​

Function Reference​

acquire_usd​

get_usd​

Loading Floorplans​

By Layout and Style ID​

Random Floorplan​

With Exclusions​

By Version ID​

With Split and Image​

Asynchronous Downloads​

Cancel Previous Downloads​

Direct (Synchronous) Download​

Cache Management​

Cache Location​

Cache Structure​

Version Tracking​

Download Progress​

Metadata​

Complete Example​

Configuration​

Custom Workers​

Custom Timeout​

Error Handling​

Best Practices​