Overview#

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 = [
    # this intentionally restricts the extension listing to native USD file types
    # rather than all supported Sdf File Formats. See OM-76297 for details.
    ("*.usd, *.usda, *.usdc, *.usdz", "USD Files"),
    ("*.*", "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:
    """
    Show only files whose names end with: *<postfix>.<ext>.
    Args:
        filename (str): The item's file name .
        filter_postfix (str): Whether file name match this filter postfix.
        filter_ext (str): Whether file name match this filter extension.
    Returns:
        True if file could show in dialog. Otherwise Flase.
    """
    if not filename:
        return True

    # Show only files whose names end with: *<postfix>.<ext>
    if filter_ext:
        # split comma separated string into a list:
        filter_exts = filter_ext.split(",") if isinstance(filter_ext, str) else filter_ext
        filter_exts = [x.replace(" ", "") for x in filter_exts]
        filter_exts = [x for x in filter_exts if x]

        # check if the file extension matches anything in the list:
        if not (
            "*.*" in filter_exts or
            any(filename.endswith(f.replace("*", "")) for f in filter_exts)
        ):
            # match failed:
            return False

    if filter_postfix:
        # strip extension and check postfix:
        filename = os.path.splitext(filename)[0]
        return filename.endswith(filter_postfix)

    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 :attr: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 Python.