Share

USDExporter : ExporterPlugin

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

Important:

To use this exporter plug-in with options, use the class method USDExporter.exportFile() (described below), not the built-in MAXScript exportFile().

Interface: USDExport

Example

MAXScript:

-- USD Exporter Example

-- create an assortment of teapots
a = [-100, -100, -100]
b = [100, 100, 100]

teapots = #()
for i = 1 to 10 do (
    t = teapot pos: (random a b) radius: (random 10 50)
    if (random 1 2) == 2 then ( append teapots t    )

)

-- make an export options object
export_path = pathConfig.appendPath (getDir #export) "/some_teapots.usda"
log_path =  pathConfig.appendPath (getDir #temp) "/teapot_log.txt"

export_options = USDExporter.createOptions()
export_options.Meshes = true
export_options.Lights = false
export_options.Cameras = false
export_options.Materials = false
export_options.FileFormat = #ascii
export_options.UpAxis = #y
export_options.LogLevel = #info
export_options.LogPath = log_path
export_options.PreserveEdgeOrientation = true
export_options.Normals = #none
export_options.TimeMode = #current

-- update the UI to match these settings:
USDexporter.UIOptions = export_options

-- export only the teapots in our list:
USDExporter.ExportFile export_path exportOptions:export_options contentSource:#nodeList nodeList:teapots

Python:

# USD Exporter Example

from pymxs import runtime as mxs
import random

# create an assortment of teapots
a = mxs.point3(-100, -100, -100)
b = mxs.point3(100, 100, 100)

teapots = []
for i in range(10):
    t = mxs.teapot(pos=mxs.random(a, b), radius= random.randint(10, 50))
    if random.randrange(2) == 1:
        teapots.append(t)

# make an export options object
export_path = os.path.join(mxs.getDir(mxs.name('export')), "some_teapots.usda")
log_path =  os.path.join(mxs.getDir(mxs.name('temp')), "teapot_log.txt")
export_options = mxs.USDExporter.createOptions()

export_options.Meshes = True
export_options.Lights = False
export_options.Cameras = False
export_options.Materials = False
export_options.FileFormat = mxs.name('ascii')
export_options.UpAxis = mxs.name('y')
export_options.LogLevel = mxs.name('info')
export_options.LogPath = log_path
export_options.PreserveEdgeOrientation = True
export_options.Normals = mxs.name('none')
export_options.TimeMode = mxs.name('current')

# update the UI to match these settings:
mxs.USDexporter.UIOptions = export_options

# export only the teapots in our list:
result = mxs.USDExporter.ExportFile(export_path, exportOptions=export_options, contentSource=mxs.name('nodeList'), nodeList=teapots)
if result:
    print('export succeeded')
else:
    print('export failed')

Properties:

    .UIOptions : Interface : Read|Write

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

Methods:

    <integer>ExportFile <string>filePath exportOptions:<Interface> contentSource:<enum> nodeList:<&node array>
       ExportFile - no automatic redraw after invoked
       exportOptions default value: undefined
       contentSource enums: {#all|#selected|#nodeList}
       contentSource default value: #all
       nodeList default value: #()
       nodeList is In and Out parameter

Exports the file specified by filePath using the optional settings specified by the IUSDExportOptions object specified by the exportOptions keyword. The optional contentSource specifies which nodes are exported.

Note:

If the filename part of filePath has the .usdz extension, the file will be saved in the USDZ format.

If exportOptions is not passed, the default options are used.

The contentSource enum can be one of:

  • #all : export all nodes (starting from the scene root node). This is the default if contentSource is not specified.
  • #selected : export selected scene nodes
  • #nodeList : export the array of nodes provided in the nodeList parameter.
    <Interface>CreateOptions()
       CreateOptions - no automatic redraw after invoked

Creates an IUSDExportOptions object that contains export settings that can be passed to the ExportFile() function.

    <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: IUSDExportOptions

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

Properties:

    .Meshes : boolean : Read|Write

Gets/sets whether to export meshes.

    .Shapes : boolean : Read|Write

Gets/sets whether to export shapes.

    .Lights : boolean : Read|Write

Gets/sets whether to export lights.

    .Cameras : boolean : Read|Write

Gets/sets whether to export cameras.

    .Skin : boolean : Read|Write

Gets/sets whether to export skin and skeletons as USDSkel.

    .Morpher : boolean : Read|Write

Gets/sets whether to export morph targets as USD blend shapes.

    .Materials : boolean : Read|Write

Gets/sets whether to export materials.

    .ShadingMode : string : Read|Write

Gets/sets the shading schema (mode) to use for material export. Current supported values are:

  • "none": Export no shading data to the USD file.
  • "useRegistry": Export shading data. This uses the shader writer registry to define a set of ShaderWriters to export the 3ds Max materials to equivalent UsdShade networks.

The default is "useRegistry".

Note:

Third party plug-ins may expose additional shading modes.

    .AllMaterialTargets : string array : Read|Write

Gets/sets how to convert materials on export. The default value "UsdPreviewSurface" exports to a UsdPreviewSurface shading network. More conversions can be registered by plug-ins.

    .UsdStagesAsReferences : boolean : Read|Write

If true, USD stage objects that are found in the 3ds Max scene are exported as USD references to whatever the root layer of that stage object is. The USD references do not reflect the current stage mask, nor does it contain the animation options for the stage.

Note:

warnings are generated if:

  • The referenced layer has no default prim, in this case the first found prim is used as reference target.
  • The referenced layer has multiple root prims, in this case, the result might not match expectations, as only a single prim can bet targeted in the reference.
  • The layer has in-memory changes (is dirty), those edits will not be saved, and the result may not reflect the current viewport representation.
    .HiddenObjects : boolean : Read|Write

Gets/sets whether to export hidden objects.

    .UseUSDVisibility : boolean : Read|Write

Gets/sets whether hidden objects will be marked as USD invisible on export. Note: visibility discrepancies can occur with this selection (hidden ascendant nodes with visible descendent nodes resulting in hidden due to the USD inheritance schema).

    .AllowNestedGprims : boolean : Read|Write

Gets/sets whether to allow nested geometric prims (Gprims). This can maintain the existing hierarchy and help performance by reducing prim counts, but is not strictly valid in USD and will result in usdchecker warnings.

    .FileFormat : enum : Read|Write
       FileFormat enums: {#ascii|#binary}

Gets/sets the file format to export to, where:

  • #ascii - ASCII text format
  • #binary - binary format
    .Normals : enum : Read|Write
       Normals enums: {#none|#asAttribute|#asPrimvar}

Gets/sets how normals are exported, where:

  • #none - normals are not exported
  • #asAttribute - normals are exported as attributes
  • #asPrimvar - normals are exported as primvars
    .MeshFormat : enum : Read|Write
       MeshFormat enums: {#fromScene|#polyMesh|#triMesh}

Gets/sets the exported mesh format, where:

  • #fromScene - uses the mesh format of the objects in the scene
  • #polyMesh - exports all meshes as polygonal meshes
  • #triMesh - exports all meshes as triangular meshes
    .TimeMode : enum : Read|Write
       TimeMode enums: {#current|#explicit|#animationRange|#frameRange}

Specifies a time mode for export, where:

  • #current exports from the current frame
  • #explicit exports from the time frame specified by .StartFrame.
  • #animationRange exports the current scene animation range
  • #frameRange exports the range specified by .StartFrame and .EndFrame

If a non-default (non zero) value is set for .StartFrame or .EndFrame, and #current is used, a warning is written to the log.

    .StartFrame : double : Read|Write

Specifies the start frame for animation export when .TimeMode is #frameRange or the frame to export when .TimeMode is #explicit.

    .EndFrame : double : Read|Write

Specifies the end frame for animation export when .TimeMode is #frameRange.

    .SamplesPerFrame : double : Read|Write

Gets/sets the number of samples per frame exported.

    .UpAxis : enum : Read|Write
       UpAxis enums: {#y|#z}

Gets/sets which axis to export as the "up" axis. Note that 3ds Max uses the z-axis as up by default.

    .BakeObjectOffsetTransform : boolean : Read|Write

Gets/sets whether to bake object offset from the pivot into the geometry.

    .PreserveEdgeOrientation : boolean : Read|Write

Gets/sets whether to preserve edge orientation on export. When true, curved faces in the scene are split into a collection of planar faces. This guarantees that the output mesh looks like the original, whatever the final triangulation used for display.

    .RootPrimPath : string : Read|Write

Specifies a root scope for export. The default is "/".

    .BonesPrimName : string : Read|Write

When exporting skin data from 3ds Max, the string in bonePrimName will be used as the prim name created for the Usd Skeleton data. This new prim will be located at /{rootPrim}/{bonePrimName} in the exported stage.

    .AnimationsPrimName : string : Read|Write

When exporting animation data from 3ds Max, the string in AnimationsPrimName will be used as the prim name for USD animation data. This new prim will be located at /{rootPrim}/{animationsPrimName} in the exported stage.

    .LogPath : string : Read|Write

Gets/sets the path and filename for the export operation log. If undefined (the default), the log is written to the 3ds Max temp directory (#temp).

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

Gets/sets the logging level, where:

  • #info - all messages are logged.
  • #warn - Only warnings and errors are logged.
  • #error - Only errors are logged.
  • #off - Logging disabled.
.OpenInUsdview : boolean : Read|Write

Specifies whether to open the exported object or scene in the USD View utility when export is complete.

    .ChaserNames : string array : Read|Write

Gets/sets a list of chasers to execute as part of the export process. Chasers are customizations that modify the exported data in some way, such as adding attributes. Chasers can be created using the 3ds Max USD SDK.

    .AllChaserArgs : value : Read|Write

Specifies the arguments to pass to the chasers listed in .ChaserNames. Each argument should be an array in the form: (<chaser name>, <argument name>, <argument value>), or a MAXScript dictionary (see example below).

For example (Python):

export_options = mxs.USDExporter.CreateOptions()
export_options.FileFormat = mxs.Name("ascii")
export_options.RootPrimPath = "/"
export_options.ChaserNames = mxs.Array("first")
export_options.AllChaserArgs = mxs.Dictionary(mxs.Name('string'), mxs.Array('first', (mxs.Dictionary(mxs.Name('string'), mxs.Array("bar", "ometer"), mxs.Array("foo", "tball")))))

Another example passing two chaser names and the the arguments as a flat list:

export_options.AllChaserArgs = mxs.Array("first", "bar", "baric", "second", "bar", "ometer", "first", "foo", "tlocker", "second", "foo", "tball")
export_options.ChaserNames = mxs.Array("first", "second")
    .ContextNames : string array : Read|Write

A list of contexts to apply on export. A "context" is a customization created using the 3ds Max USD SDK that sets export options, including specifying chasers and chaser arguments. In the UI available contexts appear under "Plugin Configuration".

Methods:

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

Resets the IUSDExportOptions object to the default settings.

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

Sets the data channel mapping for primvars back to the default.

    <void>SetChannelPrimvarMapping <integer>channel <value>targetPrimvar type:<enum> autoExpandType:<boolean>
       SetChannelPrimvarMapping - no automatic redraw after invoked
       type enums: {#texCoord2fArray|#texCoord3fArray|#floatArray|#float2Array|#float3Array|#color3fArray}
       type default value: #float3Array
       autoExpandType default value: true

Set the target primvar name and type per channel. When autoExpandType is true, type will expand depending on input values. For example, if type is #textCoord2fArray and the texture coordinate channel has non-zero values in W, then the type will expand to #textCoord3fArray. If targetPrimvar is set to undefined, the specified channel is not exported.

    <enum>GetChannelPrimvarType <integer>channel
       GetChannelPrimvarType enums: {#texCoord2fArray|#texCoord3fArray|#floatArray|#float2Array|#float3Array|#color3fArray
       GetChannelPrimvarType - no automatic redraw after invoked

Returns primvar type for the specified channel.

    <string>GetChannelPrimvarName <integer>channel
       GetChannelPrimvarName - no automatic redraw after invoked

Returns the primvar name for the specified channel.

    <boolean>GetChannelPrimvarAutoExpandType <integer>channel
       GetChannelPrimvarAutoExpandType - no automatic redraw after invoked

Returns the primvar autoExpandType flag for the specified channel.

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

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

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

  • stageId is the export 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
  • export_options are the options specified at export time
    <void>UnregisterCallbacks id:<value> event:<enum>
       UnregisterCallbacks - no automatic redraw after invoked
       id default value: undefined
       event enums: {#onExportComplete}
       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:

fn exportcallback stageId conversionInfo = (format "import succeeded stage:% conversionInfo:% " stageId conversionInfo)
opts.registerCallback exportcallback #exportcallback #onExportComplete
print(opts.GetCallbacks())
--> (DataPair key:#OnExportComplete value:Dictionary #name exportcallback:exportcallback() )
    <string array>AvailableMaterialTargets()
       AvailableMaterialTargets - no automatic redraw after invoked

Returns a list of available material conversion types from the ShadingModeRegistry. This contains all the registered USD Material types that can be converted to.

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

Returns a list of the names of all available export chasers from the ExportChaserRegistry. Chasers are customizations that modify the exported data in some way, such as adding attributes. Chasers can be created using the 3ds Max USD SDK.

Was this information helpful?