Trait System

The trait system is how Natsura decides which library asset goes where on a tree. A trait is an attribute that lives on both sides of a workflow: on the tree's geometry where assets will be placed, and on each asset in the library. At placement time, the consumer node matches assets to spawn points by comparing trait values.

Visual pending.

The trait system underpins the Assembly Decoration (the default tool for foliage placement) and the Classify node (the standalone classification step). It replaces the older pattern of building switch trees upstream to route different library sub-sets to different decoration instances.

The matching mechanism

At placement time, every spawn point on the tree has some set of trait attributes attached: height, angle, age, and any other traits the project has defined. Every asset in the library carries the same trait attributes with its own values. The decoration matches assets to spawn points by comparing trait values; the asset whose traits are closest to the spawn point's traits wins the placement.

The simplest case: if both the tree and an asset carry a height attribute, the asset spawns at the heights on the tree that match its trait value. An asset tagged with height = 0.9 ends up near the top of the tree; an asset tagged with height = 0.1 ends up near the base.

Adding more traits extends the matching to multiple dimensions. With both height and angle, an asset tagged with (height = 0.9, angle = 0.0) spawns on horizontal branches near the top; an asset tagged with (height = 0.1, angle = 1.0) spawns on upward-pointing branches near the base.

Selection is encoded in the asset's trait values, not in upstream graph topology. The same library can be reused across trees by retargeting the trait values, rather than rebuilding switch trees per project.

What can be a trait

Traits are not limited to geometric attributes. Any attribute can be a trait:

• Geometric. height, angle, width, distance_to_trunk.
• Biological. age, health, vigour.
• Project-specific. season, species, gameplay_zone, anything the project needs.

As many traits as the project requires can be defined. Each adds a dimension to the matching space.

How traits get assigned

Trait values can be assigned through any attribute-assignment workflow inside Houdini. For interactive trait assignment with immediate visual feedback, two surfaces are provided:

The classify gizmo (embedded)

The classify gizmo is the interactive viewport tool embedded in the Assembly Decoration. Press Enter on the decoration while the tree is displayed to enter the classification state. The viewport shows a graph (2D for two traits, higher-dimensional for more) where each asset in the library appears as a draggable point.

Dragging an asset toward a higher value on a trait axis causes it to spawn more on the parts of the tree where that trait is high. Dragging a leaf cluster toward height = high makes that cluster appear more on the top of the tree; dragging it toward angle = high makes it appear on more upward-facing parts. Updates are close to real time, so the tree visibly redistributes as assets are dragged.

The Classify node (standalone)

The Classify node exposes the same gizmo as a standalone network step. Use the standalone form when:

• A large library needs splitting into sub-libraries that feed different assembly decorations.
• Different parts of a tree need different trait assignments.
• The classification step should be reusable across multiple downstream placements.

Notes

• Categorical-trait semantics. Numeric traits (continuous values like height and angle) use distance-based matching. Non-numeric attributes (a species trait, a season trait) need different matching semantics: exact match, set membership, or something else. The current trait system handles numeric traits well; the rules for categorical traits are still being worked out.
• No-clean-fit fallbacks. If the tree's spawn point has trait values that no library asset matches across all dimensions, the current behaviour is closest-match. Configurable fallbacks (default asset, leave the spawn point empty, etc.) are an option for the future.
• Grouping in the classify gizmo. Dragging multiple library entries as a group on the trait graph is planned.
• Fuzzy thresholds. Limiting selection to assets within a defined attribute range, rather than always picking the closest match, is planned.
• Higher-dimensional gizmo visualisation. The 2D graph is the current interactive surface. How the gizmo presents three or more traits at once is an open question.

Related

• Assembly Decoration. The decoration that uses the trait system for foliage placement.
• Classify. The standalone classification node.
• Assembly Resource. Prepares the library that gets classified.
• Assemblies (workflow overview).
• Mapping. The parameter-driven graph system used for the mappable parameters on nodes that consume traits.
• From the Cluster Decoration to the Assembly Decoration (article). The design history that led to the trait system replacing switch-tree selection.