Initial version of USD Importer #81257

New Issue

The goal of this task is to create a USD importer loosely based on the Alembic importer. This means the following:

Simple one-time importing (via File → Import → USD).
Mesh animation loaded via a modifier.
Transform animation loaded via a constraint.
Feature parity with the current USD Exporter.
No support for the collection-based workflow (#68933) yet.
Separation of the code that translates USD datastructures into Blender datastructures, so that this can be reused by a future collection-based importer.

The goal of this task is to create a USD importer loosely based on the Alembic importer. This means the following: - Simple one-time importing (via File → Import → USD). - Mesh animation loaded via a modifier. - Transform animation loaded via a constraint. - Feature parity with the current [USD Exporter](https://docs.blender.org/manual/en/2.90/files/import_export/usd.html). - No support for the collection-based workflow (#68933) yet. - Separation of the code that translates USD datastructures into Blender datastructures, so that this can be reused by a future collection-based importer.

Changed status from 'Needs Triage' to: 'Confirmed'

Added subscriber: @dr.sybren

Added subscriber: @fsiddi

Tested a build based on the usd-importer-#81257 branch . The basic Pixar kitchen loads fairly quickly, and instancing saves memory as expected.

Without instancing

With instancing

Tested a build based on the [usd-importer-#81257 branch ](https://developer.blender.org/diffusion/B/history/usd-importer-#81257/). The basic Pixar kitchen loads fairly quickly, and instancing saves memory as expected. ### Without instancing ![import_set.jpg](https://archive.blender.org/developer/F9247384/import_set.jpg) ### With instancing ![import_set_instance.jpg](https://archive.blender.org/developer/F9247382/import_set_instance.jpg) ![import_set_instance_detail.jpg](https://archive.blender.org/developer/F9247383/import_set_instance_detail.jpg)

Added subscriber: @Noto

Added subscriber: @Pipeliner

As an update, I recently extended the USD importer experimental instancing option to support collection instances, to allow editing of instance prototypes after import. (The change is committed to the usd-importer-#81257 branch .)

As an update, I recently extended the USD importer experimental instancing option to support collection instances, to allow editing of instance prototypes after import. (The change is committed to the [usd-importer-#81257 branch ](https://developer.blender.org/diffusion/B/history/usd-importer-#81257/).)

Added subscriber: @slumber

@makowalski Please don't include icons from proprietary software in any comment. These are covered by copyright and other nastyness; see Ton's recent post on devtalk for more context.

@makowalski Please don't include icons from proprietary software in any comment. These are covered by copyright and other nastyness; see [Ton's recent post on devtalk](https://devtalk.blender.org/t/copyright-guidelines-for-devtalk/17331) for more context.

Thanks for pointing this out, Sybren, and I apologize for the oversight. I've removed the video.

Added subscriber: @PhilippeCrassous

Added subscriber: @semimetallic

Added subscriber: @bao007fei

Added subscriber: @jta

Added subscriber: @Zandman

I love this gets added to Blender! I just tested the "usd-importer-#81257-merge" branch on a couple of USDs of Apple products I downloaded from Apple's website (like this AirTag ). In fact they are USDZ files. I noticed these aren't supported. Are there any plans to support USDZ files?

I extracted the USDs from the USDZ archives and imported them. But unfortunately the results weren't very good. Materials were off/missing. I had better results using an old Blender USDZ add-on ( https://github.com/robmcrosby/BlenderUSDZ ). Did I expect too much? Is there still a lot of work to do on this feature?

I love this gets added to Blender! I just tested the "usd-importer-#81257-merge" branch on a couple of USDs of Apple products I downloaded from Apple's website (like this [AirTag ](https://www.apple.com/105/media/us/airtag/2021/2b2438dc-8391-42b3-ab6d-1dbe2c2253ab/quick-look/airtag_ios14.usdz)). In fact they are USDZ files. I noticed these aren't supported. Are there any plans to support USDZ files? I extracted the USDs from the USDZ archives and imported them. But unfortunately the results weren't very good. Materials were off/missing. I had better results using an old Blender USDZ add-on ( https://github.com/robmcrosby/BlenderUSDZ ). Did I expect too much? Is there still a lot of work to do on this feature?

Another issue I noticed: when I select an USD file in the USD import file dialog the background of the filename input box turns red. This normally only happens when you try to save/overwrite an existing file. But since I'm only importing the file I don't think it should turn red.

@Zandman Hi Leon. Thank you very much for the feedback regarding the USD importer! I'll reply to your second comment first.

Indeed, there was a bug where the USD import file selection dialog was being opened incorrectly. Thank you for catching this! I just pushed a fix to the branch.

I will reply to your first question about usdz and materials shortly.

@Zandman Hi Leon. Thank you very much for the feedback regarding the USD importer! I'll reply to your second comment first. Indeed, there was a bug where the USD import file selection dialog was being opened incorrectly. Thank you for catching this! I just pushed a fix to the branch. I will reply to your first question about usdz and materials shortly.

@Zandman To reply to your first comment: importing USDZ wasn't a specific requirement of this task, but I'm sure the importer will be extended to handle this format at some point.

As for materials, by default the importer creates materials without nodes, just setting the material's color, metallic and roughness properties. If a material with the same name already exists in the Blender scene, the existing material will be assigned. This is roughly equivalent to what the Alembic importer does.

However, there is an experimental feature for converting USD Preview Surface shaders to Blender Principled BSDF node networks. This can be enabled by checking the 'Import USD Preview' option in the 'Experimental' section at the bottom of the USD import dialog. This feature is still a work in progress, in that it doesn't handle all USD Preview node types. There is certainly work to be done to improve this and there are some bugs that I intend to fix (e.g., incorrect color space settings in some cases).

However, I haven't noticed missing materials. (I believe all the materials in the AirTag example imported for me.) Do you have an example where some materials didn't import?

@Zandman To reply to your first comment: importing USDZ wasn't a specific requirement of this task, but I'm sure the importer will be extended to handle this format at some point. As for materials, by default the importer creates materials without nodes, just setting the material's color, metallic and roughness properties. If a material with the same name already exists in the Blender scene, the existing material will be assigned. This is roughly equivalent to what the Alembic importer does. However, there is an experimental feature for converting USD Preview Surface shaders to Blender Principled BSDF node networks. This can be enabled by checking the 'Import USD Preview' option in the 'Experimental' section at the bottom of the USD import dialog. This feature is still a work in progress, in that it doesn't handle all USD Preview node types. There is certainly work to be done to improve this and there are some bugs that I intend to fix (e.g., incorrect color space settings in some cases). However, I haven't noticed missing materials. (I believe all the materials in the AirTag example imported for me.) Do you have an example where some materials didn't import?

In #81257#1159016, @makowalski wrote:
However, there is an experimental feature for converting USD Preview Surface shaders to Blender Principled BSDF node networks. This can be enabled by checking the 'Import USD Preview' option in the 'Experimental' section at the bottom of the USD import dialog.

However, I haven't noticed missing materials. (I believe all the materials in the AirTag example imported for me.) Do you have an example where some materials didn't import?

I just imported the AirTag file on a build that includes your latest changes. The file dialog bug has indeed been fixed.

However, when I import the USD I do see several materials. But in the viewport it doesn't look right. The object is all gray in all modes (resembles Solid Preview Mode). When I enable that experimental feature things look a little bit better. The Material Preview mode now shows the metallic material of the AirTag. But when I switch to Render Preview the AirTag consists of grey material. Or when I switch to Cycles, it is all black. Even when I add more light.

Maybe I'm doing something wrong?

> In #81257#1159016, @makowalski wrote: > However, there is an experimental feature for converting USD Preview Surface shaders to Blender Principled BSDF node networks. This can be enabled by checking the 'Import USD Preview' option in the 'Experimental' section at the bottom of the USD import dialog. > > However, I haven't noticed missing materials. (I believe all the materials in the AirTag example imported for me.) Do you have an example where some materials didn't import? I just imported the AirTag file on a build that includes your latest changes. The file dialog bug has indeed been fixed. However, when I import the USD I do see several materials. But in the viewport it doesn't look right. The object is all gray in all modes (resembles Solid Preview Mode). When I enable that experimental feature things look a little bit better. The Material Preview mode now shows the metallic material of the AirTag. But when I switch to Render Preview the AirTag consists of grey material. Or when I switch to Cycles, it is all black. Even when I add more light. Maybe I'm doing something wrong?

Another issue is that some of Apple's USDs contain textures in HEIC format (like this iMac USD). This format currently isn't supported by Blender, so they will fail to load. I've converted them to JPG, which fixed the Material Preview. But still the render preview is black.

Another issue is that some of Apple's USDs contain textures in HEIC format (like this [iMac USD](https://www.apple.com/105/media/us/imac-24/2021/5e004d75-3ad6-4bb9-ab59-41f891fc52f0/ar/imac24_blue_ios14.usdz)). This format currently isn't supported by Blender, so they will fail to load. I've converted them to JPG, which fixed the Material Preview. But still the render preview is black.

@Zandman Hi Leon. I found the issue: due to an oversight on my part, the render preview worked for Eevee but not Cycles. I pushed a fix to the branch. I very much appreciate your testing and feedback, which helped me address these two bugs. Thank you!

(As I previously mentioned, the material import is a work in progress and more improvements and fixes will be coming to get a closer match.)

@Zandman Hi Leon. I found the issue: due to an oversight on my part, the render preview worked for Eevee but not Cycles. I pushed a fix to the branch. I very much appreciate your testing and feedback, which helped me address these two bugs. Thank you! (As I previously mentioned, the material import is a work in progress and more improvements and fixes will be coming to get a closer match.)

Added subscriber: @gopi.vfx

Great! This is much needed addition.
Couldn't find the latest windows version in daily builds section.
When can we expecting instance geometry import?

Great! This is much needed addition. Couldn't find the latest windows version in daily builds section. When can we expecting instance geometry import?

@gopi.vfx I developed an experimental prototype for importing USD scene graph instances as Blender collection instances, but this is not included in the current patch under review. I plan to work on integrating the instancing support after the current patch has been merged into master, and I will try to make a temporary branch available with instancing support for testing sometime in the next few weeks.

@makowalski Great work so far. Cant wait to load test the instance feature.

@gopi.vfx Thank you so much. I will post an update here when the build with instancing support is available.

Added subscriber: @kevinzhow

Added subscriber: @mr.marcodivita

I imported the Playdate game console USDZ (unzipped it first; used the experimental USD preview option). When switching to Cycles and to Render Preview I noticed the whole thing turned purple. This of course implied missing textures. A little experimenting showed all materials had a faulty node setup connected to the Emission node of the Principled BSDF. When I disconnected it the model had its original colors again.

Did I stumble upon a bug? Or am I holding it wrong? ;-)

I imported the [Playdate game console USDZ ](https://assets.play.date/media/playdate-flat.usdz) (unzipped it first; used the experimental USD preview option). When switching to Cycles and to Render Preview I noticed the whole thing turned purple. This of course implied missing textures. A little experimenting showed all materials had a faulty node setup connected to the Emission node of the Principled BSDF. When I disconnected it the model had its original colors again. Did I stumble upon a bug? Or am I holding it wrong? ;-)

@Zandman Hi Leon. Thank you for reporting this! I looked at that USD and it turns out that some of the UsdUVTexture shaders don't have file inputs specified. The material reader prints warnings about this in the Blender console, e.g.,

WARNING: Couldn't get file input for USD shader /rootPrim/Materials/StingrayPBS_0/emissive_map
WARNING: Couldn't get file input for USD shader /rootPrim/Materials/StingrayPBS_0/normal_map

Inspecting the USD confirms that the file inputs are missing. For example:

 def Shader "emissive_map"
            {
                uniform token info:id = "UsdUVTexture"
                float4 inputs:default = (0, 0, 0, 1)
                float2 inputs:st.connect = </rootPrim/Materials/StingrayPBS_7/Primvar.outputs:result>
                token inputs:wrapS = "repeat"
                token inputs:wrapT = "repeat"
                float3 outputs:rgb
            }

The USD importer still creates Image Texture nodes for these shaders, but with empty file paths, hence the missing texture color. I'm not sure why the waning color goes away after disconnecting and reconnecting those nodes.

Again, thank you for testing, and I always welcome your feedback!

Incidentally, as I mentioned before, I'm working on some additional bug fixes and improvements to the UsdPreviewSurface translation code. For example, the code currently creates redundant UV Map nodes, instead of sharing a single UV Map instance, and the texture inputs aren't always handled correctly (e.g., the code fails to create Separate RGB nodes to split out the channels). These improvements are coming soon.

@Zandman Hi Leon. Thank you for reporting this! I looked at that USD and it turns out that some of the UsdUVTexture shaders don't have file inputs specified. The material reader prints warnings about this in the Blender console, e.g., ``` WARNING: Couldn't get file input for USD shader /rootPrim/Materials/StingrayPBS_0/emissive_map WARNING: Couldn't get file input for USD shader /rootPrim/Materials/StingrayPBS_0/normal_map ``` Inspecting the USD confirms that the file inputs are missing. For example: ``` def Shader "emissive_map" { uniform token info:id = "UsdUVTexture" float4 inputs:default = (0, 0, 0, 1) float2 inputs:st.connect = </rootPrim/Materials/StingrayPBS_7/Primvar.outputs:result> token inputs:wrapS = "repeat" token inputs:wrapT = "repeat" float3 outputs:rgb } ``` The USD importer still creates Image Texture nodes for these shaders, but with empty file paths, hence the missing texture color. I'm not sure why the waning color goes away after disconnecting and reconnecting those nodes. Again, thank you for testing, and I always welcome your feedback! Incidentally, as I mentioned before, I'm working on some additional bug fixes and improvements to the UsdPreviewSurface translation code. For example, the code currently creates redundant UV Map nodes, instead of sharing a single UV Map instance, and the texture inputs aren't always handled correctly (e.g., the code fails to create Separate RGB nodes to split out the channels). These improvements are coming soon.

In #81257#1177262, @makowalski wrote:
I looked at that USD and it turns out that some of the UsdUVTexture shaders don't have file inputs specified.

Does that mean the Playdate USD itself contains errors (so it's not a Blender import error)? And why does this only show up when using Cycles? The original file displays just fine in EVEE.

I'm not sure why the waning color goes away after disconnecting and reconnecting those nodes.

I didn't reconnect the nodes. I just disconnected the Emission nodes and it looked fine. I don't even understand what the Emission nodes would add. That would mean all those materials should emit light, right?

> In #81257#1177262, @makowalski wrote: > I looked at that USD and it turns out that some of the UsdUVTexture shaders don't have file inputs specified. Does that mean the Playdate USD itself contains errors (so it's not a Blender import error)? And why does this only show up when using Cycles? The original file displays just fine in EVEE. > I'm not sure why the waning color goes away after disconnecting and reconnecting those nodes. I didn't reconnect the nodes. I just disconnected the Emission nodes and it looked fine. I don't even understand what the Emission nodes would add. That would mean all those materials should emit light, right?

@Zandman Hi Leon. The emissive_map and normal_map UsdUVTexture shaders are definitely in the USD and these shaders are connected to the emmissiveColor and normal inputs of the UsdPreviewSurface shader, respectively. But the emissive_map and normal_map shaders are missing the file inputs, so they are not well formed, in that sense.

I'm not sure why Evee doesn't generate the same error, but I don't think this is a bug in the USD importer. I think one could argue that the missing inputs should be handled differently in the importer, and this is open to discussion. But please let me know if I'm missing something. Thanks!

@Zandman Hi Leon. The `emissive_map` and `normal_map` `UsdUVTexture` shaders are definitely in the USD and these shaders are connected to the `emmissiveColor` and `normal` inputs of the `UsdPreviewSurface` shader, respectively. But the `emissive_map` and `normal_map` shaders are missing the `file` inputs, so they are not well formed, in that sense. I'm not sure why Evee doesn't generate the same error, but I don't think this is a bug in the USD importer. I think one could argue that the missing inputs should be handled differently in the importer, and this is open to discussion. But please let me know if I'm missing something. Thanks!

Added subscriber: @brecht

In #81257#1177299, @makowalski wrote:
I think one could argue that the missing inputs should be handled differently in the importer, and this is open to discussion. But please let me know if I'm missing something.

Unfortunately I have nothing to add to this as I don't know anything about this. I just regularly have the need for importing USD(Z)s and your project came along at the right time :-) I just find it strange that the EVEE and Cycles output differ that much. But maybe that's perfectly logical. Maybe rendering engine guru @brecht knows why this is.

> In #81257#1177299, @makowalski wrote: > I think one could argue that the missing inputs should be handled differently in the importer, and this is open to discussion. But please let me know if I'm missing something. Unfortunately I have nothing to add to this as I don't know anything about this. I just regularly have the need for importing USD(Z)s and your project came along at the right time :-) I just find it strange that the EVEE and Cycles output differ that much. But maybe that's perfectly logical. Maybe rendering engine guru @brecht knows why this is.

Added subscriber: @aplus

Changed status from 'Confirmed' to: 'Resolved'

Since the initial USD importer has been added to Blender, I suggest to close his task and create further tasks based on the list at https://developer.blender.org/tag/usd/.

I was going to check the status of this to see whether this is now part of the latest 3.0 releases - Since I could not leave a comment on the usd task page I adding one here just in case
so I just checked the https://developer.blender.org/tag/usd/ page,
it is not clear what the status is on the import of usd files with UDIM textures (did not see import of Udims it listed in tasks)
As far as I can tell the feature isn't working yet in the blender 3.0 version I downloaded blender-3.0.0-alpha+master.53af51ad50ec-linux.x86_64-release/blender
Blender 3.0.0 Alpha
build date: 2021-10-12
build time: 23:43:06
build commit date: 2021-10-12
build commit time: 22:43

I was going to check the status of this to see whether this is now part of the latest 3.0 releases - Since I could not leave a comment on the usd task page I adding one here just in case so I just checked the https://developer.blender.org/tag/usd/ page, it is not clear what the status is on the import of usd files with UDIM textures (did not see import of Udims it listed in tasks) As far as I can tell the feature isn't working yet in the blender 3.0 version I downloaded blender-3.0.0-alpha+master.53af51ad50ec-linux.x86_64-release/blender Blender 3.0.0 Alpha build date: 2021-10-12 build time: 23:43:06 build commit date: 2021-10-12 build commit time: 22:43

In #81257#1248777, @aplus wrote:
I was going to check the status of this to see whether this is now part of the latest 3.0 releases - Since I could not leave a comment on the usd task page I adding one here just in case
so I just checked the https://developer.blender.org/tag/usd/ page,
it is not clear what the status is on the import of usd files with UDIM textures (did not see import of Udims it listed in tasks)
As far as I can tell the feature isn't working yet in the blender 3.0 version I downloaded blender-3.0.0-alpha+master.53af51ad50ec-linux.x86_64-release/blender
Blender 3.0.0 Alpha
build date: 2021-10-12
build time: 23:43:06
build commit date: 2021-10-12
build commit time: 22:43

Hi Alain. I have a fix for this issue but have not yet created a patch for the changes. I'll follow up to get this done.

> In #81257#1248777, @aplus wrote: > I was going to check the status of this to see whether this is now part of the latest 3.0 releases - Since I could not leave a comment on the usd task page I adding one here just in case > so I just checked the https://developer.blender.org/tag/usd/ page, > it is not clear what the status is on the import of usd files with UDIM textures (did not see import of Udims it listed in tasks) > As far as I can tell the feature isn't working yet in the blender 3.0 version I downloaded blender-3.0.0-alpha+master.53af51ad50ec-linux.x86_64-release/blender > Blender 3.0.0 Alpha > build date: 2021-10-12 > build time: 23:43:06 > build commit date: 2021-10-12 > build commit time: 22:43 Hi Alain. I have a fix for this issue but have not yet created a patch for the changes. I'll follow up to get this done.

Added subscriber: @brurpo

Hi! Thanks a lot for the work!
When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb.
Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space.
Is there a workaround for this, or is this planned?
Thanks!

Hi! Thanks a lot for the work! When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb. Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space. Is there a workaround for this, or is this planned? Thanks!

In #81257#1268742, @brurpo wrote:
Hi! Thanks a lot for the work!
When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb.
Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space.
Is there a workaround for this, or is this planned?
Thanks!

Hi @brurpo . Thanks for reporting this! The importer does have logic for setting the color space on the textures, so I'd like to see what is failing. If it's not too much trouble, could you provide me with an example asset (USD/textures) that reproduces the issue? I'd very much like to debug and fix the problem. Thanks!

> In #81257#1268742, @brurpo wrote: > Hi! Thanks a lot for the work! > When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb. > Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space. > Is there a workaround for this, or is this planned? > Thanks! Hi @brurpo . Thanks for reporting this! The importer does have logic for setting the color space on the textures, so I'd like to see what is failing. If it's not too much trouble, could you provide me with an example asset (USD/textures) that reproduces the issue? I'd very much like to debug and fix the problem. Thanks!

In #81257#1268743, @makowalski wrote:

In #81257#1268742, @brurpo wrote:
Hi! Thanks a lot for the work!
When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb.
Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space.
Is there a workaround for this, or is this planned?
Thanks!

Hi @brurpo . Thanks for reporting this! The importer does have logic for setting the color space on the textures, so I'd like to see what is failing. If it's not too much trouble, could you provide me with an example asset (USD/textures) that reproduces the issue? I'd very much like to debug and fix the problem. Thanks!

Hi @makowalski !! Absolutelly! Would you like the usd to be binary or ASCII?

> In #81257#1268743, @makowalski wrote: >> In #81257#1268742, @brurpo wrote: >> Hi! Thanks a lot for the work! >> When exporting USD from maya to blender none of the textures comes with the correct color space, they are all srgb. >> Importing on maya again, on a clean scene, does not have this issue, all textures are loaded with the correct color space. >> Is there a workaround for this, or is this planned? >> Thanks! > > Hi @brurpo . Thanks for reporting this! The importer does have logic for setting the color space on the textures, so I'd like to see what is failing. If it's not too much trouble, could you provide me with an example asset (USD/textures) that reproduces the issue? I'd very much like to debug and fix the problem. Thanks! Hi @makowalski !! Absolutelly! Would you like the usd to be binary or ASCII?

Hey @makowalski ! Here is a drive link
https://drive.google.com/file/d/1_A0ToOwqLMqVslG374xWoaNFr_LrFSB-/view?usp=sharing

Ive included both usd versions and the textures. If you are on windows, you can extract it to the root of c: and all files will be on the correct path.

If you want the maya file, let me know, but it does not export correctly the materials and textures by default, Ive made a tool to do this. If you want, I can send you both the maya file and the tool.

Cheers!

Hey @makowalski ! Here is a drive link https://drive.google.com/file/d/1_A0ToOwqLMqVslG374xWoaNFr_LrFSB-/view?usp=sharing Ive included both usd versions and the textures. If you are on windows, you can extract it to the root of c: and all files will be on the correct path. If you want the maya file, let me know, but it does not export correctly the materials and textures by default, Ive made a tool to do this. If you want, I can send you both the maya file and the tool. Cheers!

Please do not use this as a general discussion board. New messages will go to everybody who's subscribed to this task.

My apologies, Sybren. For anyone interested, since this requires following up as a possible bug or feature request for the USD importer, I created a new task for this, which I've assigned to myself:

https://developer.blender.org/T93904

and we can continue the discussion there.

My apologies, Sybren. For anyone interested, since this requires following up as a possible bug or feature request for the USD importer, I created a new task for this, which I've assigned to myself: https://developer.blender.org/T93904 and we can continue the discussion there.

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Initial version of USD Importer #81257

Without instancing

With instancing