Share

USDImporter : ImporterPlugin

The USDImporter plug-in exposes a single interface, USDImport, that provides access to the plug-in's functionality.

Important:

To use this importer plug-in with options, use the class method USDImporter.importFile() (described below), not the built-in MAXScript importFile().

Interface: USDImport

Example

MAXScript:

-- USD import example

myfile = @"D:\downloads\Kitchen_set\Kitchen_set.usd"

-- set up the import options
opts = USDImporter.CreateOptions()

-- we can reset the options to ensure defaults are set
opts.reset()

opts.LogPath = @"D:\downloads\Kitchen_set\import.log"
opts.LogLevel = #warn

-- unregister any callbacks:
opts.UnregisterCallbacks id:#importcallback

-- register a callback for successful import:
fn importcallback stageId conversionInfo filename options = (format "import succeeded stage:% conversionInfo:% " stageId conversionInfo)

opts.RegisterCallback importcallback #importcallback #onImportComplete

USDImporter.importFile myfile importOptions:opts

-- unregister the callback:
opts.UnregisterCallbacks id:#importcallback

Python:

# USD import example
from pymxs import runtime as mxs

myfile = "D:/downloads/Kitchen_set/Kitchen_set.usd"

# set up the import options
opts = mxs.USDImporter.CreateOptions()

opts.LogPath = "D:/downloads/Kitchen_set/import.log"
opts.LogLevel = mxs.name('warn')

#unregister any callbacks:
opts.UnregisterCallbacks( id=mxs.name('importcallback'))

# register a callback for successful import:
#fn importcallback stageId conversionInfo filename options = (format "import succeeded stage:% conversionInfo:% " stageId conversionInfo)

def importcallback(stageId, conversionInfo, filename, options):
    mxs.format("import succeeded stage:% conversionInfo:% ", stageId, conversionInfo)
    
opts.RegisterCallback( importcallback, mxs.name('importcallback'), mxs.name('onImportComplete'))

mxs.USDImporter.importFile( myfile, importOptions=opts)

#unregister the callback:
opts.UnregisterCallbacks( id=mxs.name('importcallback'))

Properties

    .UIOptions : Interface : Read|Write

The options currently set in the UI. This property is a IUSDImportOptions object - see the description of IUSDImportOptions later in this topic.

Methods

    <integer>ImportFile <string>filePath importOptions:<Interface>
       ImportFile - no automatic redraw after invoked
       importOptions default value: undefined

Imports the file specified by filePath using the optional settings specified by the IUSDImportOptions object specified by the importOptions keyword.

    <integer>ImportFromCache <integer>stageCacheId importOptions:<Interface>
       ImportFromCache - no automatic redraw after invoked
       importOptions default value: undefined

Imports a USD scene from the cache, using the IUSDImportOptions object specified by the importOptions keyword.

For example:

MAXScript:

pyUsd = python.import("pxr.Usd")
pyUsdUtils = python.import("pxr.UsdUtils")
local stage = pyUsd.Stage.Open(@"C:\Kitchen_set.usd")
local stageCache = pyUsdUtils.StageCache.Get()
stageCache.Insert(stage)
local stageId = (stageCache.GetId(stage)).ToLongInt()
local importOptions = USDImporter.CreateOptions()
USDImporter.ImportFromCache stageId importOptions:importOptions

Python:

from pxr import Usd, UsdUtils
from pymxs import runtime as mxs
stage = Usd.Stage.Open(r"C:\Kitchen_set.usd")
stageCache = UsdUtils.StageCache.Get()
stageCache.Insert(stage)
stageId = stageCache.GetId(stage).ToLongInt()
option = mxs.USDImporter.CreateOptions()
mxs.USDImporter.ImportFromCache(stageId, importOptions=option)
    <mesh>ConvertUsdMesh <integer>stageCacheId <string>path options:<Interface>
       ConvertUsdMesh - no automatic redraw after invoked
       options default value: undefined

Converts the target USD mesh specified by the stageCacheId and path, using the specified import options into a MAXScript trimesh object.

For example:

MAXScript:

pyUsd = python.import("pxr.Usd")
pyUsdUtils = python.import("pxr.UsdUtils")

-- Create a box, and export it to USD.
my_box = box()
my_box.name = "box"

convertToPoly my_box
polyop.defaultMapFaces my_box 1

exportPath = "convert_usd_mesh.usd"

opts = USDExporter.CreateOptions()
opts.FileFormat = #ascii
USDExporter.ExportFile exportPath exportOptions:opts

-- Open the exported layer, and place it into the cache.
stage = pyUsd.Stage.Open(exportPath)
stageCache = pyUsdUtils.StageCache.Get()
stageCache.Insert(stage)
stageId = (stageCache.GetId(stage)).ToLongInt()

-- Convert the UsdMesh of the box to a Max mesh.
meshData = USDImporter.ConvertUsdMesh stageId "/box" 
boxMesh = meshData.mesh
    
format "number of verts: %" boxMesh.numVerts 
format "number of faces: %" boxMesh.numFaces 

bindMaterial = meshData.usdGeomSubsetsBindMaterial

-- A box has 6 material Ids, so on export we generated 6 usdGeomSubsets. When we convert it to 
-- 3dsMax data, we should therefor get a multi-material with 6 slots.
format "material: %" (GetNumSubMtls bindMaterial) 
format "material slot1: %" (getSubMtlSlotName bindMaterial 1) 
    <void>SetMaterialParamByName <material>material <string>paramName <value>value
       SetMaterialParamByName - no automatic redraw after invoked

Sets the material parameter with the specified paramName to the specified value. This function provides a faster way to set paramblock values, and is used internally by the 3ds Max USD component. For example, these two calls do the same thing, but the first is more performant:

USDImporter.SetMaterialParamByName material "base_color_map" map
material.base_color_map = map.
    <void>SetTexmapParamByName <texturemap>texmap <string>paramName <value>value
       SetTexmapParamByName - no automatic redraw after invoked

Sets the texture map parameter with the specified paramName to the specified value. This function provides a faster way to set paramblock values, and is used internally by the 3ds Max USD component.

    <Interface>CreateOptions()
       CreateOptions - no automatic redraw after invoked

Creates a new IUSDImportOptions object, set to the default settings. See IUSDImportOptions below.

    <void>Log <enum>logLevel <string>message
       Log - no automatic redraw after invoked
       logLevel enums: {#info|#warn|#error}

Writes the specified message string to the log, with the specified log level. If a log path and file has not been set, the message is written to the default log in the 3ds Max temp directory.

Interface: IUSDImportOptions

This interface exposes options for importing USD scene files. Note that not all of these options are available on the USD Import dialog.

Properties:

    .StageMask : string array : Read|Write

An array of strings to use as stage mask paths.

    .MetaData : enum array : Read|Write
       MetaData enums: {#kind|#purpose|#hidden}

Specifies what USD metadata to import. Standard USD metadata fields are added as custom attributes in the 3ds Max scene. These custom attributes are:

  • usd_hidden for #hidden
  • usd_kind for #kind
  • usd_purpose for #purpose
    .TimeCode : enum : Read|Write
       TimeCode enums: {#startTime|#endTime|#explicit}

Gets or sets the time code type. The default is #startTime, if this is not specified. If set to #explicit, the TimeCodeValue parameter is used.

    .TimeCodeValue : value : Read|Write

Gets or sets the time code value used when the TimeCode parameter is #expclicit.

    .InitialLoadSet : enum : Read|Write
       InitialLoadSet enums: {#loadAll|#loadNone}

Gets or sets the initial load set.

    .LogPath : string : Read|Write

Gets or sets the full path and filename for the log file.

    .LogLevel : enum : Read|Write
       LogLevel enums: {#off|#info|#warn|#error}

Gets or sets the log level.

    .ImportUnmappedPrimvars : boolean : Read|Write

Specifies whether to import primvars with an explicit mapping. Note: this option is not exposed on the USD Import UI.

If false, only primvars with an explicit mapping are imported.

If true: Channel 1 (main UV) is filled with a primvar of type (prioritized in this order):

  1. TexCoord2fArray
  2. TexCoord2dArray
  3. TexCoord2hArray
  4. TexCoord3fArray
  5. TexCoord3dArray
  6. TexCoord3hArray
  7. Float2Array
  8. Double2Array
  9. Half2Array

Channel 0 (VertexColor) if filled with a primvar of type (in this order):

  1. Color3fArray
  2. Color3dArray
  3. Color3hArray

All other unmapped (and still unused) primvars of dimension 3 or more are imported to unused channels 2+. For example, if channels 2, 4, 6 are already used by explicit mappings, unmapped primvars that are not the main UV or VertexColor are imported to 3,5,7, etc. TexCoord types are imported to lower channels.

    .Materials : boolean : Read|Write

Specifies whether to import materials.

Methods:

<void>Reset()
       Reset - no automatic redraw after invoked

Resets the IUSDImportOptions to the default settings.

<void>SetPrimvarChannelMappingDefaults()
       SetPrimvarChannelMappingDefaults - no automatic redraw after invoked

Sets defaults primvar to channels mappings.

<void>SetPrimvarChannelMapping <string>primvar <value>targetChannel
       SetPrimvarChannelMapping - no automatic redraw after invoked

Sets a specified primvar to be imported to a specified targetChannel.

    <value>GetPrimvarChannel <string>primvar
       GetPrimvarChannel - no automatic redraw after invoked

Gets the target channel for the specified primvar.

    <boolean>IsMappedPrimvar <string>primvar
       IsMappedPrimvar - no automatic redraw after invoked

Returns true if the specified primvar is currently mapped to a channel, false otherwise.

    <string array>GetMappedPrimvars()
       GetMappedPrimvars - no automatic redraw after invoked

Returns an array of all currently mapped primvars, as an array of strings.

    <void>ClearMappedPrimvars()
       ClearMappedPrimvars - no automatic redraw after invoked

Clears the mapping for all currently mapped primvars.

    <void>RegisterCallback <value>callback <value>id <enum>event
       RegisterCallback - no automatic redraw after invoked
       event enums: {#onImportComplete}

Registers a callback to execute when an import operation completes successfully. The callback takes this form, with four parameters:

func myCallback <int>stageId <struct>conversionInfo <string>usd_filename <options>import_options

Where:

  • stageId is the import stage
  • the conversionInfo struct is in the form:
    struct conversionInfo(
    <dictionary> primsToNodes (
        #('prim/Path':<INode>)
        ...
    )
)
  • usd_filename is the name of the USD file being imported
  • import_options are the options specified at import time

See the example above for an example of how to create and register a callback.

    <void>UnregisterCallbacks id:<value> event:<enum>
       UnregisterCallbacks - no automatic redraw after invoked
       id default value: undefined
       event enums: {#onImportComplete}
       event default value: 0

Unregisters the callback or callbacks specified by id and event.

    <void>GetCallbacks()
       GetCallbacks - no automatic redraw after invoked

Returns a dictionary to access all the registered callbacks, where the dictionary key is the callback type (either #onImportComplete or #onExportComplete, and the value is another dictionary of callback IDs (Name type) to registered callback functions.

For example:

-- register a callback for successful import:
fn importcallback stageId conversionInfo filename options = (format "import succeeded stage:% conversionInfo:% " stageId conversionInfo)

opts.RegisterCallback importcallback #importcallback #onImportComplete

print(opts.GetCallbacks())
--> (DataPair key:#onImportComplete value:Dictionary #name importcallback:importcallback() )

USDImporter.importFile myfile importOptions:opts

-- unregister the callback:
opts.UnregisterCallbacks id:#importcallback

Was this information helpful?