omni.kit.window.file_importer¶

The file_importer extension provides a standardized dialog for importing files. It is a wrapper around the FilePickerDialog, but with reasonable defaults for common settings, so it’s a higher-level entry point to that interface. Nevertheless, users will still have the ability to customize some parts but we’ve boiled them down to just the essential ones. Why you should use this extension:

Present a consistent file import experience across the app.

Customize only the essential parts while inheriting sensible defaults elsewhere.

Reduce boilerplate code.

Inherit future improvements.

Checkpoints fully supported if available on the server.

Quickstart¶

You can pop-up a dialog in just 2 steps. First, retrieve the extension.

# Get the singleton extension.
file_importer = get_file_importer()
if not file_importer:
    return

Then, invoke its show_window method.

file_importer.show_window(
    title="Import File",
    import_handler=self.import_handler,
    #filename_url="omniverse://ov-rc/NVIDIA/Samples/Marbles/Marbles_Assets.usd",
)

Note that the extension is a singleton, meaning there’s only one instance of it throughout the app. Basically, we are assuming that you’d never open more than one instance of the dialog at any one time. The advantage is that we can channel any development through this single extension and all users will inherit the same changes.

Customizing the Dialog¶

You can customize these parts of the dialog.

Title - The title of the dialog.

Collections - Which of these collections, [“bookmarks”, “omniverse”, “my-computer”] to display.

Filename Url - Url of the file to import.

Postfix options - Show only files of these content types.

Extension options - Show only files with these filename extensions.

Import label - Label for the import button.

Import handler - User provided callback to handle the import process.

Note that these settings are applied when you show the window. Therefore, each time it’s displayed, the dialog can be tailored to the use case.

Filter files by type¶

The user has the option to filter what files get shown in the list view.

One challenge of working in Omniverse is that everything is a USD file. An expected use case is to show only files of a particular content type. To facilitate this workflow, we suggest adding a postfix to the filename, e.g. “file.animation.usd”. The file bar contains a dropdown that lists the default postfix labels, so you can filter by these. You have the option to override this list.

DEFAULT_FILE_POSTFIX_OPTIONS = [
    None,
    "anim",
    "cache",
    "curveanim",
    "geo",
    "material",
    "project",
    "seq",
    "skel",
    "skelanim",
]

You can also filter by filename extension. By default, we provide the option to show only USD files.

DEFAULT_FILE_EXTENSION_TYPES = [
    ("*.usd*", usd.readable_usd_file_exts_str()),
    ("*", "All files"),
]

If you override either of the lists above, then you’ll also need to provide a filter handler. The handler is called to decide whether or not to display a given file. The default handler is shown below as an example.

def default_filter_handler(filename: str, filter_postfix: str, filter_ext: str) -> bool:
    if not filename:
        return True

    _, ext = os.path.splitext(filename)
    if filter_ext == DEFAULT_FILE_EXTENSION_TYPES[0][0]:
        # Show only USD files
        if ext[1:] not in usd.readable_usd_file_exts():
            return False
    elif filter_ext == DEFAULT_FILE_EXTENSION_TYPES[1][0]:
        # Show all files
        pass

    if filter_postfix:
        return f".{filter_postfix}." in filename
    else:
        return True

Import options¶

A common need is to provide user options for the import process. You create the widget for accepting those inputs, then add it to the details pane of the dialog. Do this by subclassing from ImportOptionsDelegate and overriding the methods, ImportOptionsDelegate._build_ui_impl() and (optionally) ImportOptionsDelegate._destroy_impl().

class MyImportOptionsDelegate(ImportOptionsDelegate):
    def __init__(self):
        super().__init__(build_fn=self._build_ui_impl, destroy_fn=self._destroy_impl)
        self._widget = None

    def _build_ui_impl(self):
        self._widget = ui.Frame()
        with self._widget:
            with ui.VStack():
                with ui.HStack(height=24, spacing=2, style={"background_color": 0xFF23211F}):
                    ui.Label("Prim Path", width=0)
                    ui.StringField().model = ui.SimpleStringModel()
                ui.Spacer(height=8)

    def _destroy_impl(self, _):
        if self._widget:
            self._widget.destroy()
        self._widget = None

Then provide the controller to the file picker for display.

self._import_options = MyImportOptionsDelegate()
file_importer.add_import_options_frame("Import Options", self._import_options)

Import handler¶

Provide a handler for when the Import button is clicked. The handler should expect a list of selections made from the UI.

def import_handler(self, filename: str, dirname: str, selections: List[str] = []):
    # NOTE: Get user inputs from self._import_options, if needed.
    print(f"> Import '{filename}' from '{dirname}' or selected files '{selections}'")

Demo app¶

A complete demo, that includes the code snippets above, is included with this extension at “scripts/demo_file_importer.py”.

Changelog

class omni.kit.window.file_importer.FileImporterExtension¶

A Standardized file import dialog.

add_import_options_frame(name: str, delegate: omni.kit.window.filepicker.detail_view.DetailFrameController)¶

Adds a set of import options to the dialog. Should be called after show_window().

Parameters

name (str) – Title of the options box.
delegate (ImportOptionsDelegate) – Subclasses specified delegate and overrides _build_ui_impl() to provide a custom widget for getting user input.

click_apply(filename_url: Optional[str] = None)¶: Helper function to progammatically execute the apply callback. Useful in unittests

click_cancel()¶: Helper function to progammatically execute the cancel callback. Useful in unittests

hide_window()¶: Hides and destroys the dialog window.

show_window(title: Optional[str] = None, width: int = 1080, height: int = 450, show_only_collections: Optional[List[str]] = None, file_postfix_options: Optional[List[str]] = None, file_extension_types: Optional[List[Tuple[str, str]]] = None, file_filter_handler: Optional[Callable[[str], bool]] = None, import_button_label: str = 'Import', import_handler: Optional[Callable[[str, str, List[str]], None]] = None, filename_url: Optional[str] = None)¶

Displays the import dialog with the specified settings.

Keyword Arguments

title (str) – The name of the dialog
width (int) – Width of the window (Default=1250)
height (int) – Height of the window (Default=450)
show_only_collections (List[str]) – Which of these collections, [“bookmarks”, “omniverse”, “my-computer”] to display.
file_postfix_options (List[str]) – A list of filename postfix options. Nvidia defaults.
file_extension_types (List[Tuple[str, str]]) – A list of filename extension options. Each list element is a (extension name, description) pair, e.g. (“.usd”, “USD format”). Nvidia defaults.
file_filter_handler (Callable) – The filter handler that is called to decide whether or not to display a file. Function signature is filter_handler(menu_option: int, filename: str) -> bool
import_button_label (str) – Label for the import button (Default=”Import”)
import_handler (Callable) – The callback to handle the import. Function signature is import_handler(filename: str, dirname: str, selections: List[str]) -> None
filename_url (str) – Url of the file to import, if any.

omni.kit.window.file_importer.get_file_importer() → omni.kit.window.file_importer.extension.FileImporterExtension¶: Returns the singleton file_importer extension.