Object Loader

The ObjectLoader provides methods to acquire 3D objects (USD, MJCF) from the Lightwheel registry.

Quick Start

from lightwheel_sdk.loader import object_loader, login_manager

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

# Load an object
file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["chair"],
    file_type="USD"
)

print(f"Object downloaded to: {file_path}")
print(f"Object name: {object_name}")
print(f"Metadata: {metadata}")

Function Reference

acquire_by_registry

Parameter	Type	Required	Default	Description
`registry_type`	`str`	Yes	-	Registry collection to search (`objects`, `fixtures`, `textures`, etc.).
`registry_name`	`List[str]`	No	`[]`	Primary registry names to match exactly.
`exclude_registry_name`	`List[str]`	No	`[]`	Registry names to omit from the result pool.
`file_type`	`str`	No	`"USD"`	Desired asset format. Accepted values align with `FileType` enum (for example `USD`, `MJCF`).
`file_name`	`str`	No	`""`	Specific file base-name to request.
`source`	`List[str]`	No	`[]`	Filter by asset source/vendor.
`quality_levels`	`List[int]`	No	`[]`	Filter by authoring quality (`1=BASIC`, `2=GOOD`, as defined in `QualityLevel`).
`projects`	`List[str]`	No	`[]`	Restrict to assets tagged with these project names.
`equals`	`Dict[str, Any]`	No	`None`	Exact metadata/property matches (`key=value`). Treated as empty dict `{}` when `None`.
`contains`	`Dict[str, Any]`	No	`None`	Substring/contains match within array or string metadata/property fields. Treated as empty dict `{}` when `None`.

Output: tuple (file_path, object_name, metadata)

file_path: Local cache path where the USD/MJCF payload is downloaded.
object_name: Asset display name resolved from the registry metadata.
metadata: Dictionary containing the following fields:

Field	Type	Description
`fileId`	`str`	Unique identifier (36-character UUID) for the asset file.
`fileUrl`	`str`	Signed URL for downloading the asset file from storage.
`fileName`	`str`	Base filename of the asset (e.g., `chair.usd`).
`assetName`	`str`	Human-readable name of the asset.
`filePath`	`str`	Original file path in the source system.
`fileVersionId`	`str`	Unique identifier (36-character UUID) for this specific version of the file.
`source`	`str`	Source/vendor identifier for the asset (e.g., `ikea`, `vendor_name`).
`fileType`	`str`	File format type (e.g., `USD`, `MJCF`).
`property`	`Dict[str, Any]`	Registry-level properties as key-value pairs. These are searchable attributes defined at the registry level.
`metadata`	`Dict[str, Any]`	Registry-level metadata as key-value pairs. Additional descriptive information about the registry entry.
`fileMetadata`	`Dict[str, Any]`	File-specific metadata as key-value pairs. Information specific to this file version.
`removed`	`bool`	Whether this file version has been soft-deleted.
`qualityLevel`	`int`	Quality level of the asset (`1` = BASIC, `2` = GOOD).
`projectNames`	`List[str]`	List of project names this asset is associated with.
`free`	`bool`	Whether the asset is freely accessible without restrictions.
`internalName`	`str`	Internal identifier name used by the system.
`registryUuid`	`str`	Unique identifier (36-character UUID) of the parent registry entry.
`registryName`	`str`	Name of the registry entry this file belongs to.
`registryType`	`str`	Type of registry (`objects`, `fixtures`, `textures`, etc.).

acquire_by_file_version

Parameter	Type	Required	Default	Description
`file_version_id`	`str`	Yes	-	Exact 36-character UUID for the asset file version to download.

Output: tuple (file_path, object_name, metadata) identical in shape to acquire_by_registry. The loader resolves the request to a single asset payload and hydrates the local cache before returning.

The metadata dictionary contains the same fields as described in acquire_by_registry above.

list_registry

Parameter	Type	Required	Default	Description
No parameters	-	-	-	This function takes no parameters and returns all registry entries.

Output: list of dictionaries, each mirroring a RegistryData record:

id, name, internal_names, registry_type, file_types, sources, property, metadata, removed.

RegistryQuery.query_file

RegistryQuery instances encapsulate defaults (registry_type, registry_name, filters) and forward parameters to the backend registry service. Calling query_file returns the raw response dictionary with metadata fields, which is useful when you need structured information without downloading the payload through ObjectLoader.

Registry Types

The SDK supports three registry types:

objects - 3D objects (furniture, props, etc.)
fixtures - Fixed objects (walls, doors, windows)
textures - Material textures

Loading Objects

By Registry Name

# Load a specific object by name
file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["chair"],
    file_type="USD"
)

By Multiple Criteria

# Load with multiple filters
file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["modern_chair"],
    source=["vendor_name"],
    file_type="USD",
    quality_levels=[2],  # GOOD quality
    projects=["project_name"]
)

By File Version ID

# Load a specific version
file_path, object_name, metadata = object_loader.acquire_by_file_version(
    file_version_id="version-uuid-here"
)

Registry Query

Basic Query

from lightwheel_sdk.loader.object import RegistryQuery

# Create query
query = RegistryQuery(
    registry_type="objects",
    registry_name=["chair", "table"]
)

# Query for USD files
query_dict = query.query_file(
    file_type="USD",
    source=["ikea"],
    quality_levels=[2]
)

Advanced Query with Filters

# Query with equals filter
query = RegistryQuery(
    registry_type="objects",
    registry_name=["chair"],
    equals={"color": "red", "style": "modern"}
)

# Query with contains filter
query = RegistryQuery(
    registry_type="objects",
    contains={"tags": "outdoor", "description": "wooden"}
)

# Query with exclusions
query = RegistryQuery(
    registry_type="objects",
    exclude_registry_name=["old_chair", "broken_table"]
)

Query File Types

# Query USD files
query_dict = query.query_file(file_type="USD")

# Query MJCF files
query_dict = query.query_file(file_type="MJCF")

Quality Levels

Objects are available in different quality levels:

1 - BASIC: Lower polygon count, smaller file size
2 - GOOD: Higher polygon count, better detail

# Request high-quality version
file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["chair"],
    file_type="USD",
    quality_levels=[2]  # GOOD quality
)

List Available Objects

# Get list of all available objects in registry
registry_list = object_loader.list_registry()

for item in registry_list:
    print(f"Name: {item['name']}")
    print(f"Type: {item['type']}")
    print(f"Source: {item['source']}")

File Types

USD Files

file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["chair"],
    file_type="USD"
)
# Returns: ~/.cache/lightwheel_sdk/object/chair/chair.usd

Complete Example

from lightwheel_sdk.loader import object_loader, login_manager
from lightwheel_sdk.loader.object import RegistryQuery

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

# List available objects
registry = object_loader.list_registry()
print(f"Available objects: {len(registry)}")

# Create a query for modern chairs
query = RegistryQuery(
    registry_type="objects",
    registry_name=["modern_chair"],
    equals={"style": "modern"}
)

# Acquire high-quality USD file
file_path, object_name, metadata = object_loader.acquire_by_registry(
    registry_type="objects",
    registry_name=["modern_chair"],
    file_type="USD",
    quality_levels=[2],
    source=["premium_vendor"]
)

print(f"Downloaded: {object_name}")
print(f"Path: {file_path}")
print(f"Version: {metadata.get('fileVersionId')}")
print(f"Quality: {metadata.get('qualityLevel')}")

# Use the USD file in your application
# import pxr
# stage = pxr.Usd.Stage.Open(file_path)

Error Handling

from lightwheel_sdk.loader import object_loader
from lightwheel_sdk.loader.exception import ApiException

try:
    file_path, object_name, metadata = object_loader.acquire_by_registry(
        registry_type="objects",
        registry_name=["nonexistent_object"],
        file_type="USD"
    )
except ApiException as e:
    print(f"Failed to acquire object: {e}")
except ValueError as e:
    print(f"Invalid parameters: {e}")

Deprecated Methods

acquire_object (Deprecated)

# DEPRECATED - Use acquire_by_registry instead
file_path = object_loader.acquire_object(
    rel_path="source/registry/filename",
    file_type="USD"
)

This method is deprecated and may be removed in future versions. Use acquire_by_registry instead.

Quick Start​

Function Reference​

acquire_by_registry​

acquire_by_file_version​

list_registry​

RegistryQuery.query_file​

Registry Types​

Loading Objects​

By Registry Name​

By Multiple Criteria​

By File Version ID​

Registry Query​

Basic Query​

Advanced Query with Filters​

Query File Types​

Quality Levels​

List Available Objects​

File Types​

USD Files​

Complete Example​

Error Handling​

Deprecated Methods​

acquire_object (Deprecated)​