Component Builder

Overview ¶

USD defines a hierarchy of model kinds. “Component” models are roughly equivalent to Geometry Objects in Houdini. A component represents a single “thing”, like a lamp or a kitchen table, which can be referenced or instanced. (The other kinds, “group” and “assembly”, represent higher-level groupings of components. The component kind is the “leaf” type, and is not allowed to have other model kinds inside it.)

If you're coming from a traditional Houdini background, a component is like an Object-level HDA which contains geometry, as well as its own material network. You can re-use it, and also customize a particular instance without changing the original.

The Component Builder tool automates or enforces various best practices (this is especially useful for artists and studios new to USD):

Sets up the geometry as a payload so the artist can easily unload it, and still see a bounding box in the viewport.
Organizes the files on disk in a directory structure.
Makes it easy to add variants (alternative shapes and/or material looks for the model).
Sets up composition arcs on the prims so the model inherits from a class primitive. This makes it easier to apply shot-level customizations to the component.
Each component keeps its geometry and materials in separate files (layers). This adds flexibility, for example to replace a file without having to regenerate, or reference in just the component’s geometry without its materials.

Often, you will have a single small .hip file just to generate and write out the USD for a component, or possibly one large .hip file that has multiple component builders to generate different components all from the same file. Then in a separate .hip or USD file for a scene, you would reference in the generated component layer file for each component.

See using the component output for more information on writing the result to disk and how to use the component.

Nodes ¶

The tool creates a network snippet with the following nodes:

	Component Geometry	Contains a SOP network you use to define the model’s geometry. Double-click this node to dive inside to the SOP network.
	Material Library	Contains a material network you use to define materials specific to this model. Double-click this node to dive inside to the material network.
	Component Material	Assigns materials from the material network onto specific faces/surfaces of the component geometry. You can assign materials defined in the model-specific node above.
	Component Output	Puts together the other parts (geometry, material, metadata) and creates a final USD prim for the model.

There is an extra node you can add to the network to create model variants, that is not created by default:

Component Geometry Variants

Lets you merge multiple Component Geometry nodes as variants of the component. See how to create variants below.

How to ¶

To... Do this

To...	Do this
Set up and use the component builder network	In a LOP network, press `⇥ Tab`, type `Component Builder` and press `Enter` to put down the four-node component builder network snippet. Set the display flag on the Component Output node at the bottom of the snippet. Double-click the Component Geometry node to dive into its contained SOP network. Set up the model’s geometry. Connect it to the green (`default`) output node. You can also generate simplified proxy geometry and connect it to the yellow `proxy` output. This geometry can be used for display in an OpenGL viewer. You can also generate simplified collision geometry and connect it to the pink `simproxy` output. This geometry is used for computing collisions in a simulation. See proxy outputs in the Component Geometry help for more information, including tips on making efficient display proxy geometry. You can load external geometry in the SOP network using standard nodes such as the File SOP or Object Merge SOP and then modify the geometry using additional SOP nodes. The PolyReduce SOP is useful for quickly creating a low-res display proxy. The Convex Decomposition SOP is useful for creating a low-res convex collision proxy. Press `U` to go back up to the parent LOP network. To create variants of the model, see “build variants of the component” below. Double-click the Material Library node to dive into its contained VOP network. Create a USD Preview Surface VOP. Use the node’s parameters to set up the material look. (There are many different ways to create materials in USD with various levels of support in different renderers. The USD Preview Surface is simple but it should work in all USD-aware renderers.) Press `U` to go back up to the parent LOP network. The model now has the preview material you created. This is because the Component Material node has a default assignment which assigns the last-modified material prim created in the material library to the last-modified model prim created by the Component Geometry node. To assign different materials to subsets of the model, and/or reference in existing materials from a shared library, see Materials below. Select the Component Output node. By default, the name of the model prim is automatically set to the name of this node (`/$OS` in the node’s Root Prim parameter). To set the name manually, set the Root prim to a meaningful name (at the root level), for example `/donut`. Component builder is set up with the idea that you will render the component out to its own self-contained USD file, and then reference that component file into other Solaris network or USD files to use the component. This is why the component output creates the prim at the root level (models in their own files should be defined by a prim at the root level).

Set up and use the component builder network

In a LOP network, press ⇥ Tab, type Component Builder and press Enter to put down the four-node component builder network snippet.
Set the display flag on the Component Output node at the bottom of the snippet.
Double-click the Component Geometry node to dive into its contained SOP network.
Set up the model’s geometry. Connect it to the green (default) output node.

You can also generate simplified proxy geometry and connect it to the yellow proxy output. This geometry can be used for display in an OpenGL viewer.

You can also generate simplified collision geometry and connect it to the pink simproxy output. This geometry is used for computing collisions in a simulation.

See proxy outputs in the Component Geometry help for more information, including tips on making efficient display proxy geometry.
- You can load external geometry in the SOP network using standard nodes such as the File SOP or Object Merge SOP and then modify the geometry using additional SOP nodes.
- The PolyReduce SOP is useful for quickly creating a low-res display proxy.
- The Convex Decomposition SOP is useful for creating a low-res convex collision proxy.
Press U to go back up to the parent LOP network.
To create variants of the model, see “build variants of the component” below.
Double-click the Material Library node to dive into its contained VOP network.
Create a USD Preview Surface VOP. Use the node’s parameters to set up the material look.

(There are many different ways to create materials in USD with various levels of support in different renderers. The USD Preview Surface is simple but it should work in all USD-aware renderers.)
Press U to go back up to the parent LOP network.

The model now has the preview material you created. This is because the Component Material node has a default assignment which assigns the last-modified material prim created in the material library to the last-modified model prim created by the Component Geometry node.

To assign different materials to subsets of the model, and/or reference in existing materials from a shared library, see Materials below.
Select the Component Output node. By default, the name of the model prim is automatically set to the name of this node (/$OS in the node’s Root Prim parameter). To set the name manually, set the Root prim to a meaningful name (at the root level), for example /donut.

Component builder is set up with the idea that you will render the component out to its own self-contained USD file, and then reference that component file into other Solaris network or USD files to use the component. This is why the component output creates the prim at the root level (models in their own files should be defined by a prim at the root level).

Materials ¶

To... Do this

To...	Do this
Assign materials to groups (face sets)	Inside the Component Material node’s contained VOP network, create new materials to assign to different parts of the model. Inside the Component Geometry’s contained SOP network, use the Group SOP to create named groups of faces. Go back up to the LOP network. In the Component Geometry node’s parameters, in the Attributes section, enter the group names as a space-separated list in the Subset Groups parameter (you can use the drop-down menu to the right of the text box to choose from existing primitive groups in the geometry). This creates USD subsets corresponding to the SOP groups. Each subset appears as a `GeomSubset` prim under the component’s `Mesh` geometry prim. In the Component Material node’s parameters, create multi-parm instances for each subset. To bind each subset to a material, do the following: `⌃ Ctrl`-click the Reselect button next to the Primitives parameter. In the Select Primitives dialog, find and select the GeomSubset prim you want to bind (`/ASSET/geo/shape/subset name`), the click OK. Click the Reselect button next to the Material Path parameter. In the Select Primitives dialog, find and select the Material prim you want to bind (`/ASSET/mtl/material name`), then click OK.
Import a material from a shared library	Create a Reference LOP. In the Reference node’s parameters, do the following: Set the Primitive Path to `/ASSET/mtl/material name` to attach the file’s contents where the component builder system expects materials to be. Set the Reference File parm to the path to the file containing the material(s) you want to use. Wire the output of the Reference node to the Input of the Material Library node. (If you will only use materials referenced from an external file, and don’t want to define any “local” materials, you could wire the Reference directly into the Component Material node’s second input and delete the Material Library node.) In the Component Material node, you can edit a binding to use a material you just referenced in. Click the Reselect button next to the Material Path parameter for the binding you want to change. In the Select Primitives dialog, find and select the Material prim you want to bind (`/ASSET/mtl/.../material name`), then click OK.

Assign materials to groups (face sets)

Inside the Component Material node’s contained VOP network, create new materials to assign to different parts of the model.
Inside the Component Geometry’s contained SOP network, use the Group SOP to create named groups of faces.
Go back up to the LOP network.
In the Component Geometry node’s parameters, in the Attributes section, enter the group names as a space-separated list in the Subset Groups parameter (you can use the drop-down menu to the right of the text box to choose from existing primitive groups in the geometry).

This creates USD subsets corresponding to the SOP groups. Each subset appears as a GeomSubset prim under the component’s Mesh geometry prim.
In the Component Material node’s parameters, create multi-parm instances for each subset.
To bind each subset to a material, do the following:
- ⌃ Ctrl-click the Reselect button next to the Primitives parameter. In the Select Primitives dialog, find and select the GeomSubset prim you want to bind (/ASSET/geo/shape/subset name), the click OK.
- Click the Reselect button next to the Material Path parameter. In the Select Primitives dialog, find and select the Material prim you want to bind (/ASSET/mtl/material name), then click OK.

Import a material from a shared library

Create a Reference LOP.
In the Reference node’s parameters, do the following:
- Set the Primitive Path to /ASSET/mtl/material name to attach the file’s contents where the component builder system expects materials to be.
- Set the Reference File parm to the path to the file containing the material(s) you want to use.
Wire the output of the Reference node to the Input of the Material Library node.

(If you will only use materials referenced from an external file, and don’t want to define any “local” materials, you could wire the Reference directly into the Component Material node’s second input and delete the Material Library node.)
In the Component Material node, you can edit a binding to use a material you just referenced in. Click the Reselect button next to the Material Path parameter for the binding you want to change. In the Select Primitives dialog, find and select the Material prim you want to bind (/ASSET/mtl/.../material name), then click OK.

Variants ¶

To...	Do this
Build geometry variants	USD lets you switch a model between multiple variants. For example, one tree component can contain multiple different tree models for different species (elm, spruce, larch, and so on). In the LOP network, add a Component Geometry Variants node between the Component Geometry node and the Component Material node. Wire additional Component Geometry nodes into the Component Geometry Variants node’s multi-input. You should have one Component Geometry node for each variant. Go inside each Component Geometry node and create the model geometry for that variant. Go back up to the LOP network level. By default, the name of each variant is automatically set to the name of the corresponding Component Geometry node. To set a variant name manually, edit the Advanced ▸ Geo Variant Name parameter on the Component Geometry node. The default name for the geometry variant set is `geo`. You can change the Variant Set parameter on the Component Geometry Variants node to change the variant set name.
Use materials specific to a geometry variant	If a material is specific to a geometry variant, you can assign it using a Component Material node (with a Material Library or Reference node connected to its second input) wired in between a variant’s Compontent Geometry node and the Component Geometry Variants node.
Build material variants	Inside the Material Library network, define more materials. In the LOP network, below the default Component Material node that was created by the tool, add extra Component Material nodes. You should have one Component Material node for each material variant. In each Component Material node, assign the material(s) you want for that variant, and set the Variant Name parameter. The default name for the material variant set is `mtl`. You can change the Material Variant Set parameter on each Component Material node to change the variant set name (or to set up multiple material variant sets).
Set the default variant(s)	You can set the default geometry and material varaints (the ones used when someone references the component without explicitly specifying a variant they want). In the LOP network, select the Component Output node. In the parameters, turn on and expand the Component Options ▸ Set Default Variants section. Enter the name of the default geometry and/or material variants.

Extras ¶

You can double-click the Component Output node to dive into a contained LOP network. You can wire additional LOP nodes (starting from the Input Stage pseudo-node) into this network to further modify the prims created by the component nodes under /ASSET. Any modifications you do in this network are separated into an extras.usdc layer in the file output that overrides the weaker opinions authored by the component nodes.

This might be useful, for exmaple, for lighting, or some keep-alive animation cycles.

Tips and notes ¶

You can insert other LOPs between the Component Material and Component Output node. Just set them up to edit the “temp” asset prims (under /ASSET) created by the Component Geometry and Component Material nodes.
If the geometry you want to use for the component already exists on disk or in an existing SOP network, you can swtich the Component Geometry node’s Source parameter from Internal SOP network to File or External SOP.
If the geometry you want to use has already been imported into LOPs earlier in the LOP network, you can switch the Component Output node’s Source parameter from Upstream Component Geometry to Scene Import (to process an existing prim that was generated by the Scene Import LOP) or Input Primitives (to use an existing prim with geometry and materials under it).
Currently the component builder network does not allow multiple or nested geometry variant sets.

Prim output ¶

The output scene tree looks like the following, where <component> is the name of the root prim (see about the class prim for information about the extra prim under __class__).

/<component>     (xform) ← Component Kind
    /geo         (scope) ← Display Purpose: default
    /mtl         (scope)

/__class__       (class)
    /<component> (class) ← Inherited by /<component>

If you use the extra outputs inside the Component Geometry node to define display and/or simulation proxy geometry, the geo prim will have extra branches under it:

/<component>     (xform) ← Component Kind
    /geo         (scope)
        /proxy   (scope) ← Display Purpose: proxy
        /render  (scope) ← Display Purpose: render

Managing purpose on a parent primitive can help Hydra avoid update issues and crashes, and it also makes it clear to artists what geometry to expect at that location in the scene.

Use the component output ¶

The end goal of a component builder network is usually to write out the component to its own self-contained USD file, which can then by referenced by other USD files (or Houdini Solaris scenes) that need to use the component. This hierarchy of files referencing files referencing files one of the main organization principles of USD.

Within the LOP network you set up to generate the component, the output of the node is a stage with the component in a prim at the root level. This prim is ready to be written to a USD file (it conforms to the requirement that files to be referenced in have a single prim at the file’s root level). The information is not actually written to disk until you use the controls on the Component Output node to write out disk files.

Tip

The component builder network is set up to output files to disk, but you can reference the output component prim from elsewhere in the same network if needed (see below).

When writing to disk, the component builder always outputs a directory of related files (see directory structure below for more information). This is a best-practice. It groups together related files (layer files, a thumbnail image of the model), it makes it easy to add more files related to the component (for example, a read_me.txt file), and it only requires the directory name to be unique (the files inside can have generic names).

To...	Do this
Write the component out into a directory of USD layer files	Select the Component Output node. In the parameters, open the Caching section. The Component Output node has several parameters for controlling the naming of the directory and component layer file. By default they have expressions that use the prim name, which is itself based on the name of the Component Ouput node. You can choose to set the name of the Component Output node to something meaningful (for example, `campfire`), or you can overwrite the default expressions in the Name, File Name, and/or Location fields. Name is base name used by the default expressions in the other two parameters. The default expression computes this by taking the value of the Root Prim and strips off the leading `/`. (Note that the default value of the Root Prim parameter is itself an expression (`/$OS`) that just puts a `/` in front of the Component Output node’s name.) Filename is the file name of the “main” layer file. The default expression computes this by adding `.usd` to the value of the Name parameter above. Location is the file path of the “main” layer file (the nodes writes other output files in the same directory, next to this file). The default expression computes a path relative to the current scene file, in `usd/assets/Name/Filename`. The Location parameter (the file path of the “main” layer file) is the parameter that “really” controls where the output files go. The Name and Filename fields are conveniences. For example, you could edit the expression in Name or Filename to change how they are computed, but leave the Location using the new computed values. Or, you could edit the Location but still include the `chs(“name”)` and `chs(“filename”)` expressions to use the computed name/filename. Click Save to Disk or Save to Disk in Background. See below for information about the directory structure and USD composition arcs the node writes out.
Reference a component file in another scene	Reference the model with a Reference or Asset Reference node. Add the model to the asset gallery database, so you can use it with a Layout node brush.
Reference the component within the same network	You can reference the component into a separate scene tree in the same network without having to write it out to disk. Create a Reference node elsewhere in the network. In the parameters, set the node to Reference from multi-input. Connect the Component Builder output to the Reference node’s multi-input.
Generate an automatic thumbnail image	The Component Output node has options for creating a thumbnail image for the component. You can use this thumbnail image in Houdini’s asset gallery or an asset management system. Select the Component Output node. In the parameters, open the Caching ▸ Thumbnail section. Turn on View Thumbnail Camera. This adds a thumbnail preview camera to the scene and looks through it. You can move/rotate the camera (for example, by locking the view to the camera and panning/dollying in the viwer) to make sure it frames the component how you want. Turn off View Thumbnail Camera to hide the preview camera. Set the Mode to how you want to generate the thumbnail. Viewport uses whatever renderer the viewer is using. Houdingi GL is the fastest method but lowest quality method. Render lets you choose to render the thumbnail using a Hydra delegate (such as Karma). This gives the highest quality but can be very slow. If you already have a thumbnail image you want to use, set the Mode to File and set Source File to the file path of the image. This switches the node to use copy the existing image when writing out files, rather than generating it. Click Generate Thumbnail to write out the thumbnail file. This creates a `thumbnail.png` or `thumbnail.jpg` file in the output directory specified in the Caching ▸ Location parameter. If you set Mode to Render or Houdini GL , you can turn on Auto-generate on export to always regenerate the thumbnail when you write out the USD files. Tip If Houdini finds a `Thumbnail.usda` file on the Houdini path (for example, in your user prefs directory `$HOUDINI_USER_PREF_DIR`), it will sublayer it into the stage when generating the thumbnail. You can use this to automatically add extra “stuff” to the the thumbnail such as custom backgrounds, lighting rigs, size comparisons, and so on.
Generate a thumbnail image with custom camera and lights	The Component Output node has a second input, which can be used to setup a camera, lights, and other objects for an asset’s thumbnail. Select the Component Output node. In the parameters, open the Caching ▸ Thumbnail section. Set Camera and Scene to Second Input. Click Thumbnail Scene Quickstart. This adds an Insertion Point, and a camera based on your current view. You can add other items via this second input, such as lights, objects for scale, and a backdrop. Click Generate Thumbnail to write out the thumbnail file. This creates a `thumbnail.png` or `thumbnail.jpg` file in the output directory specified in the Caching ▸ Location parameter. Tip You can turn on Save Thumbnail Scene to Disk, which will create a `Thumbnail.usda` file in your asset directory, that can be used to re-generate the thumbnail renders using husk.
Add the component to an asset gallery database	The Component Output node has a button to automatically add the files written to disk to the USD asset gallery (as used by the Layout node). This requires that you have already written the files to disk. It simply uses the file paths of the output files to add an entry to the layout database. Note that the default output path for files puts the files in a directory relative to the current `.hip` file. This might be fine if the `.hip` file you use to generate components is in a shared/centralized directory. If not, you might want to duplicate the Component Output node and change its file output parameters to write to a more centralized location (like a shared asset directory), write the files there, and then add those files to the asset gallery. Select the Component Output node. In the parameters, open the Caching section. Check the Location parameter. This is where the asset gallery will load the files from, so you might want it to be a centralized/shared directory. Click Save to Disk to generate the files. The files must already exist on disk before you can add the component to the asset gallery. Click Add to Asset Gallery. The node creates a new entry in the gallery database, pointing to the files on disk. Tip To view the asset gallery in a floating window, in the main menus choose Windows ▸ New Floating Panel. Then right-click the pane tab in the floating panel and choose Solaris ▸ Layout Asset Gallery.

About the class prim ¶

The component builder sets up the component so it inherits from a prim at /__class__/prim_name (for example, if the root prim is /campfire, that prim inherits from /__class__/campfire).

Inherits are a very powerful and useful feature of USD. Basically, every time the component is referenced into a scene tree, USD checks whether in that tree a prim exists at the path it wants to inherit from. If the inherit-from prim exists, its attributes override those on the component. This lets you customize prims based on the context in which they appear.

In Houdini, when you reference in a prim with an “inherits” composition arc on it, you can right-click the prim in the Scene Graph Tree and choose Edit Primitive ▸ New Node to Edit Inherit inherited path. This will automatically create a new Edit Properties node in the LOP network that lets you override properties on the inherited prim (and so customize the inheriting prim in this scene only).

(Future versions of Houdini may add tools to make inherits easier to set up, visualize, and edit.)

Directory structure ¶

The directory output of a component builder network (without variants) look like this:

/campfire
    campfire.usd    ← Main file, points to payload
    payload.usdc    ← References shape and material layers
    geo.usdc        ← Shape data
    mtl.usdc        ← Materials
    thumbnail.jpg

The directory may contain other files, such as texture maps. If you added extra nodes inside the Component Output’s contained network, the directory will include an extra.usdc file with the changes created by that network.

Tip

You can change the names of the “sidecar” layer files (payload.usdc, geo.usdc, mtl.usdc, and extra.usdc) in the Component Output node’s parameters under Caching ▸ Export Options.

This diagram shows how the “main” asset file references the other files:

(The payload layer uses references, rather than a sublayering, to ensure that the opinions of each layer can override the preceding, weaker layer, even when using variants.)

Variant files ¶

If the component builder network sets up variants, the Component Output node generates a sub-directory called variants. Inside the subdirectory, for each variant there is a thumbnail and a simple layer file that references in the component with the given variant set as current. This makes it easy to treat variants as individual assets, for example in the Solaris asset gallery.

/campfire
    campfire.usd
    payload.usdc
    geo.usdc
    /maps
        wood_diffuse.exr
        wood_normal.exr
    mtl.usdc
    thumbnail.jpg
    /variants
        campfire_blazing.usd
        campfire_blazing_thumbnail.jpg
        campfire_calm.usd
        campfire_calm_thumbnail.jpg
        campfire_smoldering.usd
        campfire_smoldering_thumbnail.jpg

Component Builder

Overview ¶

Nodes ¶

How to ¶

Materials ¶

Variants ¶

Extras ¶

Tips and notes ¶

Prim output ¶

Use the component output ¶

About the class prim ¶

Directory structure ¶

Variant files ¶

Solaris

USD ¶

Geometry ¶

Layout ¶

Look Development ¶

Karma rendering ¶

Tutorials ¶