Overview#

The omni.client.lib extension provides foundation APIs for uniformly accessing Nucleus filesystem, local filesystem, HTTP resources, and other storage backends through a single interface. This extension serves as the core client library that handles all file system operations across different protocols and storage systems in the Omniverse ecosystem.

Concepts#

Unified File System Access#

The extension abstracts different storage backends (Nucleus servers, local filesystem, HTTP resources) behind a consistent API. This allows applications to work with files regardless of where they are stored, using the same set of operations for reading, writing, listing, and managing files.

URL-Based Operations#

All file operations use URL-based addressing, supporting various schemes including omniverse://, file://, and http://. The extension provides utilities for URL manipulation, validation, and normalization to ensure consistent handling across different storage types.

Asynchronous Operations#

Most file operations are available in both synchronous and asynchronous variants, with the async versions returning Request objects that can be used to track operation progress or cancel operations before completion.

Functionality#

File System Operations#

Basic file operations include reading, writing, copying, moving, and deleting files and folders. These operations work uniformly across all supported storage backends.

Directory operations provide listing folder contents, creating directories, and managing folder hierarchies. The list function returns detailed metadata including file sizes, modification times, and access permissions.

Advanced operations support checkpointing for versioned storage systems, file locking/unlocking, and server-side operations when both source and destination are on the same server.

URL Utilities#

URL manipulation functions handle converting between different URL formats, making relative and absolute URLs, and normalizing URLs for consistent comparison. Functions like make_file_url_if_possible and normalize_url ensure proper URL formatting across different contexts.

URL validation checks if URLs are valid, point to local filesystem, or support advanced features like tagging and omni objects.

Authentication and Access Control#

Authentication support includes token-based authentication, device flow authentication, and integration with Nucleus server authentication systems. The refresh_auth_token function manages authentication token lifecycle.

Access control management provides getting and setting ACLs (Access Control Lists), managing user groups, and handling permission-based operations through functions like get_acls and set_acls.

Live Updates and Subscriptions#

Real-time notifications allow subscribing to file system changes, receiving updates when files are created, modified, or deleted. The list_subscribe_with_callback function establishes persistent subscriptions for monitoring folder changes.

Live collaboration support includes joining channels for real-time communication and processing live updates from collaborative editing sessions.

Usage Examples#

Here’s a basic example of reading a file from different storage backends:

import omni.client

# Read from Nucleus server
result, content = omni.client.read_file("omniverse://server/path/file.usd")
if result == omni.client.Result.OK:
    data = memoryview(content).tobytes()

# Read from local filesystem
result, content = omni.client.read_file("C:/path/to/file.usd")

# Async version for non-blocking operations
def callback(result, version, content):
    if result == omni.client.Result.OK:
        data = memoryview(content).tobytes()

request = omni.client.read_file_async("omniverse://server/file.usd", callback)

URL manipulation example:

import omni.client

# Normalize URLs for consistent comparison
url1 = omni.client.normalize_url("omniverse://server/../path/file.usd")
url2 = omni.client.normalize_url("omniverse://server/path/file.usd")

# Check if URLs are equal
if omni.client.equal_urls(url1, url2):
    print("URLs point to the same resource")

# Convert local path to file URL if appropriate
file_url = omni.client.make_file_url_if_possible("C:/absolute/path/file.usd")

Integration#

The extension integrates with omni.kit.async_engine to provide proper asynchronous operation handling within the Kit framework. This ensures that async file operations don’t block the main thread and integrate properly with Kit’s event loop system.

For more information, please check Omniverse Client Library documentation.