Houdini 20.5 Nodes Geometry nodes

Attribute From Pieces geometry node

Assigns an attribute to points specifying which of a set of models should be copied/instanced to that point, randomly or based on various rules.

On this page
Since 18.5

Overview

Houdini’s workflow for automatically creating large numbers of objects in a scene (such as trees in a forest, rocks and pebbles in a desert, or buildings in a city) is as follows:

  1. Build the surface you want to scatter the objects across.

  2. Use the Scatter and Align node to scatter points across the surface.

    Scatter and Align has many high-level controls for how to distribute the points, avoid certain areas, add variety in size and orientation, and so on.

  3. Build the set of models you want to copy onto the points. For example, a set of different types and shapes of trees to make a forest.

  4. Use the Copy to Points node to copy the objects onto the points.

    Copy to Points has a Piece Attribute parameter that chooses which of the set of models to copy onto each point based on the value of an attribute on the point.

This node is a powerful and flexible way to create the “piece” attribute used by Copy to Points to decide which model to copy onto each point. It lets you assign the pieces randomly, or according to various rules. For example, you could make deciduous trees more likely at lower elevations and conifer trees more likely at higher elevations on a mountain.

Visualizing the results

The best way to use this node is to set up the network to create the pieces, scatter the points, assign an attribute specifying which piece to copy onto each point, and using a Copy to Points node to copy the pieces onto the points (making sure you set the piece attribute on the Copy to Points node). Then you can select the Attribute From Pieces node and tweak the parameters based on how they affect the copies/instances.

Even if you don’t have the finished models for the pieces, it is helpful to create simple proxies (for example, different simple shapes or shapes with different colors) for the pieces so you can visualize how the distribution changes as you edit the parameters.

Understanding pieces

Houdini SOP geometry is conceptually just a bunch of unstructured primitives (polygon faces). It does not have an inherent concept of separate “objects” or hierarchy of primitives. Instead, the way nodes can tell that a set of faces are part of the same thing is that they all have the same value in a certain attribute. For example, assuming the node is using a piece attribute named piece, all polygons where the point attribute piece equals 2 are part of the same conceptual object.

The piece attribute may be an integer or string attribute. This attribute is often called piece, class, name, or path.

You can create a piece attribute on geometry using the Connectivity node to automatically create a piece attribute. This is usually all you need. If you need more fine-grained control (if individual objects have disconnected parts), you can use a series of upstream Attribute Create nodes to “manually” assign value to the piece attribute for each separate set of faces.

Attribute From Pieces works by creating an attribute on the points that the pieces will be copied onto in the scattering workflow. For each point, the value of this attribute specifies that the Copy to Points node should copy the piece with the same attribute value from the source geometry onto this point.

Attribute From Pieces does not copy the pieces onto the points; it just creates the attribute that Copy to Points uses to do the copy. However, you need to connect the geometry containing the pieces to Attribute From Pieces' second input (and specify the name of the piece attribute) so that it can see the pieces that are available. This means that before using this node, you must have geometry with a piece attribute set up.

Modeling the pieces

Houdini’s copying/instancing workflows are based on using the pscale (point scale) attribute to control the size of each instance. Since this is a scale, it works best if you model the objects to copy/instance at 1 unit scale, at least along the axis you don’t want to overlap when scattering.

For example, if you are scattering trees, it is best to model each tree so the “radius” of the tree (the maximum distance from the center of the trunk to the end of the longest branch) is one world unit. Then the copy node can scale the tree smaller or larger using pscale.

If you have a model created at a different scale, you can make it 1 unit scale with the Match Size node.

Tips and notes

  • The “Pieces” parameters (Shuffle Pieces and Offset) are not available when Mode is VEXpression.

Inputs

Points

The points to create the name attribute on.

Geometry Library

The different pieces that can be assigned to the points.

Parameters

Piece Attribute

The name of the point attribute that specifies which primitives in the second input are parts of the same thing.

Piece Filter

If you only want the node to use a few of the available pieces from the second input, type a space-separated list of the attribute values here. If this is blank, the node uses all available pieces in the second input.

Mode

The method to assign pieces to points.

Cycle

Go through the points in order, cycling through the available pieces (essentially, assign the piece using “point number modulo number of pieces”).

Note that if the points were created by Scatter or Scatter and Align, the point numbers have no relationship to their position, so the distribution of pieces will look random.

Patches

Assigns the pieces in random “splotches” (using Worley noise). That is, instead of randomizing each individual point, it randomizes irregularly shaped groups of points.

Noise

Assigns the pieces using noise. This is not the same as randomizing each piece. Instead it assigns a piece based on the quantization of the output of a chosen noise function. This lets you create organic-looking patterns and other effects.

Random

Assigns pieces to points randomly. You can assign weights to each piece to make some pieces more likely than others.

Map Attribute

Assigns pieces to points based on the value of an attribute on the points.

This is very powerful since you can use the wide variety of SOP nodes that create attributes to set up the point attribute. For example, you can paint on values using Attribute Paint, or set the attribute based on distance from another object with Distance From Geometry, or from a certain coordinate with Distance From Target.

Tip

If multiple mappings apply to a point, the node picks one randomly.

VEXpression

Evaluates a series of VEX expressions, and assigns the piece based on which VEX expression returns true.

If you can write VEX, this allows full control over how to select a piece based on an attribute value or a logical combination of values.

Tip

If multiple expressions return true for a point, the node picks one randomly.

Copy Attributes

List of attributes to copy from source pieces. Attributes that match this pattern are aggregated over each piece using Promotion Method before they are transferred to the output points.

Note

Attributes are copied from the same class as Piece Attribute. That is, if the Piece Attribute lives on points, then point attributes will be copied; otherwise, the attributes will come from primitives.

Allow P Attribute

The position attribute (P) will be matched against the Copy Attributes pattern only when this parameter is enabled. Turn this on if you want to transfer piece positions to the output instances.

Promotion Method

Specifies how the attribute values are aggregated over each piece before copying to the output points.

Whenever there is more than one attribute in the original class that matches a single entity in the new class, some method must be used to determine the new value. For example, if converting from point attribute to primitive attribute, there will be many points corresponding to a single polygon.

Maximum

Picks the largest match.

Minimum

Picks the smallest match.

Average

The mean, or the sum of all matches divided by the number of matches.

Mode

The most common match. If there is more than one most common, it will be the minimum of the most common.

Median

The middle of the matches. If there is an even number of elements, it is the higher of the two possible middles.

Sum

All of the matches added together.

Sum of Squares

All of the matches squared, and then added together.

Root Mean Square

The square root of the average of the squares of all the matches.

First Match

The first valid match. For promoting points to primitives, this would be the point of the first vertex in the primitive.

Last Match

The last valid match. For promoting points to primitives, this would be the point of the last vertex in the primitive.

Array of All

Provided the source attribute is a tuple attribute, a new array attribute is created. The array attribute is populated with all the values of the matches.

Pieces

Shuffle

Turn this on to randomly scramble the order of the pieces.

Seed

The seed for the random number generator used to scrable the piece order. The same seed will always produce the same ordering. For example, if you want different orderings in each frame, set the seed to $F (the current frame number).

Offset

Shifts the order of pieces forward a certain number of places, with pieces at the end moving to the front of the order.

Source Points

Override Ptnum

Turn on the checkbox next to ID Attribute to use the value of a custom attribute on each point to cycle through the pieces instead of the inherent point number.

ID Attribute

Turn the checkbox on and specify the name of an integer attribute on the points to use the attribute’s value to cycle through the pieces instead of the inherent point number.

Location Attribute

When Mode is Patches or Noise, the attribute to use as the point’s position in the noise field. The default is the point position P. However, you might want to use a different attribute, for example you could use rest if the point positions are animated but you want the noise to follow the points.

Patches

These parameters are visible when Mode is Patches.

Patch Size

Controls the average size of the patches.

Scale

Allows you to control the average height, width, and depth of the patches separately.

Patch Offset

Moves the noise field relative to the points.

Distortion

These parameters can optionally add distortion on top of the base noise pattern.

Strength

The strength of distortion to add.

Size

The size of the distortion.

Roughness

The roughness of the distortion.

Offset

An offset added to the center of the distortion map.

Noise

These parameters are visible when Mode is Noise.

Noise Type

The function to use to generate the noise field. The node uses the point positions as the seed for the random number generator.

Element Size

Controls the size of the noise features.

Element Scale

Allows you to control the height, width, and depth of the noise features separately.

Offset

Moves the noise field relative to the points.

Max Octaves

The number of combined noise layers.

Roughness

The influence falloff for each successive noise layer.

Distortion

These parameters can optionally add distortion on top of the base noise pattern.

Lattice Warp

Adds “stringiness” or “wiriness” to standard noise.

Freq

The frequency of the Lattice Warp.

Gradient Warp

Widens the peaks or valleys of the noise output.

Remap Noise

A ramp used to remap noise values.

Random

These parameters are visible when Mode is Random.

Weight Method

The way of specifying the weight that each piece is given.

Uniform Distribution

Each piece is equally likely.

Piece Weights

Give each piece a weighting using a multiparm, allowing you to make some pieces more likely than others.

If you choose this option, click the Autofill Pieces button to automatically set up the multiparm based on the pieces in the second input.

Weight Attribute

Use a primitive float attribute on the piece geometry that sets the piece’s random weighting. The weighting for a piece is the average of this attribute’s values across the primitives of the piece.

Seed

When Weight Method is not Uniform, this is the seed value for the random number generator that chooses between weighted alternatives.

Autofill Pieces

When Weight Method is Piece Weights, click this button to automatically set up the multiparm based on the pieces in the second input.

A button that will automatically fill out the Number of Assets and Piece parameters such that each unique piece in the geometry is included in the list.

Number of Pieces

The number of pieces to specify weights for in the multiparm.

Piece

The attribute value for this piece.

Weight

A value representing how likely this piece is to appear in the chain, relative to other pieces. The weights of all pieces are normalized to add up to 1.0 and then used as probabilities. For example, if three pieces have weights of 1, 1, and 2, the last piece is likely to appear 50% of the time, while the other two are each likely to appear 25% of the time.

Weight Attribute

When Mode is Weight Attribute, the name of a primitive float attribute on the piece geometry that sets the piece’s random weighting. The weighting for a piece is the average of this attribute’s values across the primitives of the piece.

Map Attribute

These parameters are visible when Mode is Map Attribute.

Tip

If multiple mappings apply to a point, the node picks one randomly.

Attribute

The name of an attribute on the points to use to choose the piece for each point.

Attribute Type

The type of attribute.

Numeric

The attribute is either a float or an integer. This lets you matching pieces to ranges of numbers.

String

The attribute is a string. This lets you match against exact values or string patterns.

Map Pieces From

When Attribute Type is Numeric, choose whether to map values to pieces automatically or manually.

Automatic Ranges

Automatically creates a mapping between equal-sized ranges of values in the attribute and the available pieces in the second input.

Explicit Ranges

Lets you manually map between ranges and pieces using a multiparm.

Autofill Pieces

When Attribute Type is String or Map Pieces From is Explicit Ranges, click this button to automatically set up the multiparm with an initial set of mappings based on the pieces in the second input.

Number of Maps/ranges

When Attribute Type is String or Map Pieces From is Explicit Ranges, this is the number of mappings in the multiparm.

Enable Piece

Use the checkbox next to each range to control whether it is used or not.

Piece

The name of the piece to assign to points where the value matches this pattern. If you enter a space-separated list of piece names, the node will choose one randomly.

Map From

The string value or pattern to match against.

Min

The minimum value for this range.

Max

The maximum value for this range.

VEXpression

These parameters are visible when Mode is VEXpression.

Tip

If multiple expressions return true for a point, the node picks one randomly.

Autofill Pieces

Click this button to set up the multiparm with expressions for each piece in the second input.

Number of VEXpressions

The number of VEX expressions to test.

Enable piece

Use the checkbox next to each expression to control whether it is used or not.

Piece

The name of the piece to assign to points where the expression returns true. If you enter a space-separated list of piece names, the node will choose one randomly.

VEXpression

The VEX expression to run for each point. If the expression evaluates to a non-zero value, it “matches” the point and the corresponding piece will be assigned to the point.

Unmatched Piece

When none of the rules in the multiparm match, use this piece. If you enter a space-separated list of piece names, the node will choose one randomly.

Use Unmatched Group

Turn on the checkbox next to Unmatched group to create a group in the output containing any unmatched points.

Unmatched Group

Turn on the checkbox and enter a group name to create a group in the output containing any unmatched points.

Seed

The seed value for the random number generator for when the node chooses between alternatives.

Examples

AttributeFromPiecesForest Example for Attribute From Pieces geometry node

This example shows how to use the Attribute from Pieces SOP to assign pieces with an attribute indicating size.

AttributeFromPiecesModes Example for Attribute From Pieces geometry node

This example demonstrates the behaviour of the different Mode options in the Attribute from Pieces SOP.

See also

Geometry nodes