| On this page | |
| Since | 22.0 |
Overview ¶
USD supports two types of instancing: instanceable primitives (where multiple copies of the same branch are aliases to shared storage) and point instancing (where USD stores points and prototypes to copy onto the points, but only draws the copies at render time). See USD instancing for more information.
This node specializes in point instancing. It uses an internal SOP network (or an external SOP) as the source of the per-instance data, and authors that data onto one or more USD PointInstancer prims. The node can either create a new point instancer or edit an existing one (or any combination of both in a single cook).
The thing or things you want to create multiples of are called the prototypes. The node assumes the prototypes already exist, connected to the first or second input (or already present on an existing point instancer in the first input).
The points you want to instance onto are called the targets. The targets are SOP points (from the internal SOP network or an external SOP). Each point becomes one instance. A target point can be assigned to a specific instancer prim by setting a path string attribute on it; points without that attribute fall back to the Primitive Path on this node.
Compared to Copy to Points LOP, this node is focused exclusively on the point instancer workflow but offers finer control over multi-instancer authoring, sparse updates, ids, primvars, time sampling, and animated prototype extents.
Editing an Existing PointInstancer ¶
The internal SOP network usually contains a USD PointInstancer Import SOP feeding into an output node. That import SOP reads instances out of the existing point instancer(s) listed in Primitives, exposes them as points, and lets you modify them with standard SOPs. When this node cooks, the modified points are written back as USD time samples on the source instancer prim.
The Create Import Node button on the Existing PointInstancers tab creates such an import SOP inside this node and pre-wires it to the parameters on this LOP. The Edit PointInstancer shelf tool is a one-click equivalent for setting up an existing PointInstancer for in-place editing – it drops this node configured for the Edit workflow and wires the internal import SOP automatically.
The internal SOP network also contains an output SOP (with its display flag set) that defines which points feed back into the LOP. The Edit PointInstancer shelf tool wires the import SOP into this output automatically; in a create workflow, route your own SOPs into the output SOP to make the network’s intent explicit.
In Sparse edit mode, only the points whose ids changed are re-authored; instances absent from the SOP geometry are governed by the Missing Points Policy. In Overwrite mode the entire instancer data is replaced on each cook.
Special SOP attributes ¶
The following attributes on the target points have special meaning:
-
path(string) – The scene graph path of the point instancer prim that this point should become an instance of. **When set, this attribute takes precedence over the Primitive Path parameter for this point. Points without this attribute fall back to Primitive Path. -
id(int) – The USD instance id for the point. Required for sparse edits of existing instancers. Points without anidattribute, or withid == -1, are assigned the next available id automatically. -
delete(string) – A value ofdeleteremoves the point from the output entirely. The corresponding instance is dropped regardless of Edit Mode or Missing Points Policy – this is a hard delete, distinct from a “missing” id. -
usdvisibility(string) – A value ofinvisibleadds the point’s id to the instancer’sinvisibleIds. The defaultinheritremoves it. -
usdxform(matrix4d) – A per-point matrix4 attribute recording the world transform of the source instancer when the points were imported with Transform into World Space on theUSD PointInstancer Import SOP. This LOP reads the first point’s value and authors the matching world transform on the destination instancer prim. The LOP emits a warning if the per-point values disagree for points targeting the same destination.
The standard SOP instancing attributes – P, orient (or N/up), scale/pscale, v, accel, w, and id – map directly to the USD positions, orientations, scales, velocities, accelerations, angularVelocities, and ids attributes when the corresponding Set Properties From Data toggle is on. Any other point attribute can be carried through as a primvar via Point Attributes to Copy.
Parameters ¶
Frame Sampling ¶
Sampling Behavior
Cooking this node can generate many USD time samples, rather than just a single time sample at the current time. This can be equivalent to having a Cache LOP following this node, but it will evaluate much faster, and does not cache data from any other nodes. This allows animated data to be authored to USD without introducing a node time dependency which would then cause all following nodes to also be time dependent. This can vastly improve playback performance of some LOP Networks.
In all sampling modes, if a parameter on this node does not vary with time, and does not rely on other time sampled data from the stage, only a single default value will be generated in USD for the corresponding attribute. USD time samples are only generated for parameters that may vary over time.
Sample Current Frame
A single time sample will be generated for the current time.
Sample Frame Range If Input Is Not Time Dependent
If the input to this node is time dependent, this node behaves as if it is in Sample Current Frame mode. Otherwise it behaves as if it is in Sample Frame Range mode.
Sample Frame Range
The Start/End/Inc parameter is used to generate multiple times at which this node’s parameters are evaluated, and a USD time sample is created for each attribute at each one of these times.
Start/End/Inc
When the Sampling behavior is Sample Frame Range, this parameter controls the number and spacing of base time samples to be generated by this node. The default values of this parameter are @fstart, @fend, and @finc. These values correspond to the start, end, and step size of the global Houdini animation settings when interacting with Houdini. When using a ROP node to generate a range of frames, these values correspond to the start, end, and increment values specified on the ROP node being executed. This default ensures that a USD file written to disk will contain time samples for exactly the frame range requested by the ROP (regardless of the Houdini animation settings).
Subframe Sampling
For each primary sample generated by this node, these parameters can cause additional samples to be generated around that primary sample time. This is most often used to ensure that accurate data exists at exactly the camera shutter open and close times, as well as at the primary sample time.
Shutter
Controls the method used to specify the shutter open and close times relative to the primary sample times.
Specify Manually
The Shutter Open/Close parameter values provide exact offset values relative to the primary sample time.
Use Camera Prim
The Camera Prim parameter provides the scene graph path of a camera primitive from which the shutter open and close times are extracted to provide the offset values relative to the primary time sample.
Shutter Open/Close
When Shutter is set to Specify Manually, these two offset values are added to the primary sample time to indicate the shutter open and close times. The open time should be less than or equal to zero, and the close time should be greater than or equal to zero.
Camera Prim
When Shutter is set to Use Camera Prim, this is the scene graph path of a camera prim on the input node’s stage. The shutter open and close attribute values are read from this primitive.
Samples
The number of subframe samples to create for each primary sample. These samples are evenly distributed between the shutter open and close times. Note that such an even distribution may or may not create a sample at exactly the primary sample time.
Always Include Frame Sample
When turned on, forces a sample to be created at exactly the primary sample time. If the Samples value, together with the shutter open and close times, already place a sample at the primary sample time, turning on this option has no effect. Otherwise, this option causes an addition sample to be added. This means that the actual number of samples per primary sample may in fact be one more than the number specified in the Samples parameter.
PointInstancer ¶
Primitive Path
The scene graph path of the point instancer prim to create or edit. If the prim doesn’t exist, this node creates it as a PointInstancer. If the prim exists but isn’t a PointInstancer, the node errors.
Note
This parameter applies only to source points that do not have a path attribute set. Points whose path attribute names a different scene graph path are routed there instead, and Primitive Path is ignored for those points.
Create Empty PointInstancer
When on (the default), the node authors a PointInstancer prim at Primitive Path even when the source SOP geometry has no points (or no points whose path attribute resolves to Primitive Path). Turn this off when you only want to edit existing instancers and don’t want a stray empty one to be created at Primitive Path.
The tab-menu Edit PointInstancer tool turns this off automatically so editing flows never accidentally author empty instancers.
These parameters apply to point instancer prims that this node creates. They are ignored when an instancer already exists at the target path.
Primitive Kind
The kind to set on any newly created instancer prim. Leave blank to author no kind.
Primitive Specifier
The specifier (def, over, or class) used when creating new instancer prims. The default is def.
Parent Primitive Type
The type used when this node has to create any intermediate ancestor prims along Primitive Path. The default is Xform.
These parameters apply to point instancer prims that already exist on the stage.
Primitives
The scene graph path(s) of existing point instancer prims to edit. You can use pattern syntax to select multiple instancers.
Each target point’s path attribute selects which of these instancers it belongs to. Points whose path doesn’t match any listed instancer fall back to Primitive Path.
Edit Mode
Controls how the data on existing instancer prims is replaced.
Sparse
Only re-author the instance entries (rows of the protoIndices, positions, orientations, etc. arrays) whose id is present in the SOP geometry. Ids absent from the SOP geometry are handled according to the Missing Points Policy. This is the recommended mode for partial edits.
Overwrite
Replace the full per-instance arrays with whatever the SOP geometry provides. Ids in the source data are honoured, and missing ids are dropped entirely.
Prototypes Relationship Mode
Controls how this node combines its prototype list with the existing prototypes relationship on the target instancer prim.
Preserve
Keep the existing prototypes relationship targets exactly as they are. The cooked protoIndices values must reference indices in the preserved list. Prototype-related parameters on this node are disabled for existing instancers in this mode.
Overwrite
Replace the prototypes relationship with the targets specified by this node. Existing protoIndices values are invalidated; supply new index assignments via the Prototype Assignment ▸ Existing PointInstancers controls.
Append
Append this node’s prototypes to the existing prototypes relationship. Existing instance entries continue to point at the original prototypes; new entries can address the appended ones via the Existing PointInstancers assignment controls.
Create Import Node
Click to add a USD PointInstancer Import SOP inside this node’s internal SOP network, named
existing_pointinstancers, with its key parameters wired to the parameters above. Use this as the starting point for an edit-existing-instancer setup.
Prototype Source
Whether the prim(s) you want to reference/instance onto the points is/are in the first input or the second input.
Use Entire Stage as Prototype
If Prototype Source is Second Input and this is on, the node copies everything from the second input’s scene graph tree under a new prim and uses that as the prototype. This lets you build a node chain that builds the prototype and connect it to the second input, and not have to specify which prim in the second input to use.
Using this option implies that there is only one prototype, because this node has no multi-input. If you have several full stages you want to use as prototypes, combine them with a Graft Stages LOP first, and feed the result into the second input, but with this option turned off.
Prototype Primitives
The scene graph path(s) of the primitive(s) you want to use as prototype(s). You can use pattern syntax to select multiple primitives.
Handle Missing Prototypes
If a point specifies a prototype that doesn’t exist, this parameter controls whether the node will present a warning, enter an error state or create the missing primitives. The default is to enter an error state, which can be useful to catch accidental use of missing prototypes. The warning mode is useful for scenarios where prototypes may be added to the instancer later in the LOP network or through USD composition. The create mode will create placeholder prims in the scene to use as prototypes.
Create Prototypes Area
If Prototype Source is First Input, this toggle controls whether to create a “Prototypes” scope under the specified Primitive Path or not.
If enabled, the primitive will be populated with references (see Prototype Reference Type below) to the original source primitives, and these references will be used for the instances. If disabled, the instances will be directly connected to the original source primitives. It is standard practice, but not required, to have this enabled when the Method is set to PointInstancer.
Make Prototype Source Primitives Invisible
If Prototype Source is First Input and Create Prototypes Area is enabled and this is on, the node sets the visibility of the prims used as primitives to “hidden” in the output. The default is on.
Root Prim
The scene graph path to the root prim for the prototype area. This prim will be created if it doesn’t already exist.
This parm has access to the following local variables
@primpath
The currently targeted prim path.
Root Prim Kind
When Use Entire Stage is on, this sets the kind of the prim the node creates as a parent for root prims from the second input. The default is None.
Name
The name for the prototype prims to be created under the prototype destination root prim.
This parm has access to the following local variables
@primpath
The currently targeted prim path.
@protoprimpath
The source primpath for the current prototype.
@protoprimname
The name of the source prototype prim.
@protoindex
The index for the current prototype.
Only Copy Specified Prototype Prims
If Prototype Source is Second Input and Use Entire Stage as Prototype is off, this controls whether to only copy the prototype primitives specified by Prototype Primitives, or the entire stage. The default is on.
Using this option can result in a smaller stage, but requires that the prototype sources are fully self-contained (for example they cannot refer to materials that sit elsewhere in the prim hierarchy).
Prototype Reference Type
If Prototype Source is First Input and Create Prototypes Area is enabled, this parameter controls the composition type to use when creating references to the source primitives from within the Prototypes folder in the scene graph. This parameter can be Reference, Inherit, or Specialize. See inherits and specializes for more information about how these choices differ from a simple reference.
Target Points ¶
SOP Source
Where to find the SOP geometry that drives the per-instance data.
Internal SOP
Use this node’s internal SOP network. The display SOP of that subnet provides the points.
External SOP
Use the output of a SOP elsewhere in the Houdini node hierarchy. Specify it in SOP Path.
SOP Path
When SOP Source is External SOP, the node path of the SOP that generates the target points. Defaults to ..
Show LOP Stage in SOPs
Points to a LOP node whose stage is rendered into the Scene Viewer along with the SOP geometry when you dive inside this node’s internal SOP network. Any USD cameras and lights will also become available to look through in the viewport’s camera menu. Specifying a LOP Network instead of a LOP node path fetches the stage of the display-flagged LOP node within the target LOP Network.
This is only used when SOP Source is Internal SOP. The default expression looks at this node’s first input.
Point Group
Restrict the imported points to this named point group on the SOP geometry.
Missing Points Policy
When Edit Mode is Sparse, controls what happens to instance ids on existing point instancers when those ids are absent from the SOP geometry (either because the upstream SOPs dropped them, or because the Point Group filter excluded them). Points marked with the delete SOP attribute are not handled here – they are removed unconditionally, see Special SOP attributes.
Do Nothing
Leave the existing instance entries untouched. The instance keeps its previous transform and visibility.
Remove Instances
Delete the missing ids from the instancer. The corresponding instance entries are erased from protoIndices, positions, etc.
Make Instances Invisible
Add the missing ids to the instancer’s invisibleIds. The data for those instances is preserved so the instance can be re-shown later by re-adding its id.
Ids
Author the USD ids attribute from the SOP id point attribute. Required when Edit Mode is Sparse (a warning notes that ids are handled automatically in sparse mode regardless of this toggle).
InvisibleIds
Author the USD invisibleIds attribute. Any point whose usdvisibility string attribute is invisible has its id added to invisibleIds. Requires the SOP id attribute (or an automatically assigned one).
Positions
Author the USD positions attribute from the SOP point position P.
Orientations
Author the USD orientations (or orientationsf) attribute from the SOP orient quaternion (or the standard N/up combination if orient isn’t present).
Scales
Author the USD scales attribute from the SOP scale and/or pscale attributes.
Accelerations
Author the USD accelerations attribute from the SOP accel point attribute.
Velocities
Author the USD velocities attribute from the SOP v point attribute.
Angular Velocities
Author the USD angularVelocities attribute from the SOP w point attribute.
Point Attributes to Copy
A pattern matching point attribute names to copy onto the instancer prim as array primvars. Each listed attribute becomes one entry per instance. The default excludes the standard instancing attributes (which are handled by the toggles above), USD bookkeeping attributes, and the path attribute.
Missing Primvars Policy
When Edit Mode is Sparse, controls how mismatched primvar sets between the SOP geometry and an existing instancer prim are handled. Ignored when Edit Mode is Overwrite (the existing instancer’s primvars are replaced wholesale in that mode).
Do Nothing
If the SOP geometry lacks an attribute that exists as a primvar on the instancer, leave the primvar values for the affected ids unchanged.
Create
Create any missing primvar on the instancer, using zero-valued entries for ids absent from the SOP geometry.
Common Primvars
A whitespace-separated list of primvar names that should be authored on every PointInstancer affected by this node. This is a finer-grained alternative to setting Missing Primvars Policy to Create (which authors every SOP primvar on every affected instancer) – list only the primvars you want broadcast, and leave the rest to follow the per-instancer import set.
The USD PointInstancer Import SOP writes this list to the geometry’s
importedprimvars detail attribute, and this LOP reads it to drive sparse primvar resampling.
Indexed Primvars
A space-separated list of primvar names or patterns specifying which primvars are authored as indexed (a deduplicated value array plus an index array) rather than flat per-instance arrays.
type:string
Matches against any SOP string primvars.
Indexed primvars are a useful optimization when a small number of unique values is repeated across a large number of instances. Preparing an indexed primvar can be expensive for attribute types other than integers or strings, so use this where the storage savings are clearly worth it.
Prototype Assignment ¶
These controls assign a protoIndices value to each instance on newly created instancer prims.
Prototype Index
How the prototype index for each instance is determined.
None
Don’t author protoIndices from this node. Useful when another node downstream supplies the values.
Random
Pick a prototype at random for each instance, using Seed as the seed.
Integer Attribute
Use the value of an integer point attribute as the index into the prototype list.
String Attribute
Use the value of a string point attribute. The value is matched against each prototype’s prim name (or the path’s basename); a match sets the corresponding protoIndices entry.
Seed
When Prototype Index is Random, the seed for the random number generator.
Integer Attribute
When Prototype Index is Integer Attribute, the name of the integer point attribute to read. Defaults to protoindex.
String Attribute
When Prototype Index is String Attribute, the name of the string point attribute to read. Defaults to protoname.
These controls assign prototype indices for instances on existing instancer prims. They are disabled when Prototypes Relationship Mode is Preserve (because the existing prototype list and indices are kept intact).
Prototype Index
Same as New PointInstancers ▸ Prototype Index, applied to existing instancers. The default is None – existing instances keep their authored protoIndices values.
Seed
When Prototype Index is Random, the seed for the random number generator.
Integer Attribute
When Prototype Index is Integer Attribute, the name of the integer point attribute to read.
String Attribute
When Prototype Index is String Attribute, the name of the string point attribute to read.
Warn on Skipped Instances
When a per-instance attribute lookup fails (an integer index out of range, or a string with no matching prototype name), emit a warning naming the first such instance. Visible only when one of the Prototype Index menus is set to Integer Attribute or String Attribute.
| See also |