USD: basic support for on_import USD hooks

Added support for defining an on_import() function in
bpy.types.USDHook subclasses.  If on_import() is defined
on a given USD hook, it will be invoked in import_endjob().

The implementation closely follows the existing design of
export hooks.  USDHook.on_import() takes as an argument
an instance of an internally defined USDSceneImportContext
class which provides an accessor to the USD stage.

Also updated the USDHook documentation with an example
on_import() callback implementation.

Pull Request: https://projects.blender.org/blender/blender/pulls/117822

doc/python_api/examples/bpy.types.USDHook.py

@@ -3,9 +3,9 @@ USD Hook Example
 ++++++++++++++++
 
 This example shows an implementation of ``USDHook`` to extend USD
-export functionalty.
+export and import functionalty.
 
-One may optionally define one or both of the following callback functions
+One may optionally define any or all of the following callback functions
 in the ``USDHook`` subclass.
 
 Hook function ``on_export()`` is called before the USD export finalizes,
@@ -31,13 +31,21 @@ USD stage to be saved.
 Note that the target USD material might already have connected shaders created by the USD exporter or
 by other material export hooks.
 
-The hook functions should return ``True`` on success or ``False`` if the operation was bypasssed or
+Hook function ``on_import()`` is called after the USD import finalizes. This function takes
+as an argument an instance of an internally defined class ``USDSceneImportContext`` which provides the
+following accessors to the scene data:
+
+- ``get_stage()`` returns the USD stage which was imported.
+
+The hook functions should return ``True`` on success or ``False`` if the operation was bypassed or
 otherwise failed to complete.  Exceptions raised by these functions will be reported in Blender, with
 the exception details printed to the console.
 
-The ``USDHookExample`` class in this example impements an ``on_export()`` function to add custom data to
-the stage's root layer and an ``on_material_export()`` function to create a simple ``MaterialX`` shader
-on the USD material.
+The ``USDHookExample`` class in this example impements the fllowing functions:
+
+- ``on_export()`` function to add custom data to the stage's root layer.
+- ``on_material_export()`` function to create a simple ``MaterialX`` shader on the givne USD material.
+- ``on_import()`` function to create a text object to display the stage's custom layer data.
 
 """
 
@@ -96,6 +104,45 @@ class USDHookExample(bpy.types.USDHook):
 
         return True
 
+    @staticmethod
+    def on_import(import_context):
+        """ Create a text object to display the stage's custom data.
+        """
+        stage = import_context.get_stage()
+
+        if stage is None:
+            return False
+
+        # Get the custom data.
+        rootLayer = stage.GetRootLayer()
+        customData = rootLayer.customLayerData
+
+        # Create a text object to display the stage path
+        # and custom data dictionary entries.
+
+        bpy.ops.object.text_add()
+        ob = bpy.context.view_layer.objects.active
+
+        if (ob is None) or (ob.data is None):
+            return False
+
+        ob.name = "layer_data"
+        ob.data.name = "layer_data"
+
+        # The stage root path is the first line.
+        text = rootLayer.realPath
+
+        # Append key/value strings, enforcing text wrapping.
+        for item in customData.items():
+            print(item)
+            text += '\n'
+            line = str(item[0]) + ': ' + str(item[1])
+            text += textwrap.fill(line, width=80)
+
+        ob.data.body = text
+
+        return True
+
 
 def register():
     bpy.utils.register_class(USDHookExample)