- Qt 6.9
- Qt Quick 3D
- QML Types
- QtQuick3D.Helpers
- RandomInstancing
- Qt Quick 3D | Commercial or GPLv3

# RandomInstancing QML Type

Generates a random instancing table. More...

Import Statement: | `import QtQuick3D.Helpers`
Since: | Qt 6.2
Inherits: | Instancing

- List of all members, including inherited members

## Properties

- color : InstanceRange
- colorModel : enumeration
- customData : InstanceRange
- gridSpacing : vector3d `(since 6.9)`
- instanceCount : int
- position : InstanceRange
- randomSeed : int
- rotation : InstanceRange
- scale : InstanceRange

## Detailed Description

The RandomInstancing type provides an easy way to generate a large number of random instances within defined bounds. The number of instances is defined by the instanceCount property. The bounds are defined by the properties position, scale, rotation, color, and customData.

See also InstanceList.

## Property Documentation

color : InstanceRange

The color property defines the color variation range for the generated instances. The type is color. The default value is empty, causing the color to be white.

Setting the colorModel property makes it possible to select only saturated colors, for example.

See also position, rotation, scale, and customData.

colorModel : enumeration

This property controls how the color range is interpreted.

The instance colors are generated component by component within the range determined by the from and to colors. The color model determines how those components are defined.

Constant | Description
--- | ---
`RandomInstancing.RGB` | The components are red, green, blue, and alpha, according to the RGB color model.
`RandomInstancing.HSV` | The components are hue, saturation, value, and alpha, according to the HSV Color Model.
`RandomInstancing.HSL` | The components are hue, saturation, lightness, and alpha,, according to the HSL Color Model.

As an example, the following color range

     color: InstanceRange {
         from: Qt.hsva(0, 0.1, 0.8, 1)
         to: Qt.hsva(1, 0.3, 1, 1)
     }

will generate a full range of pastel colors when using the `HSV` color model, but only shades of pink when using the `RGB` color model.

The default value is `RandomInstancing.RGB`

See also RandomInstancing::color.

customData : InstanceRange

The customData property defines the custom data variation range for the generated instances. The type is vector4d. The default value is empty, causing causing the generated data to be `[0, 0, 0, 0]`.

See also position, color, rotation, scale, and customData.

gridSpacing : vector3d `[since 6.9]`

The gridSpacing property defines the minimum spacing between instances, ensuring they do not overlap. Each position will be separated by at least the value specified in `gridSpacing`.

If the specified `gridSpacing` cannot accommodate the requested number of instances, the `instanceCount` property will be reduced to the number of instances that can be placed without overlap.

Note: The gridSpacing property affects only the position of instances. Rotation and scaling applied to instances are not considered in the spacing algorithm.

The default value is `[0, 0, 0]`, which imposes no restriction on overlapping instances.

This property was introduced in Qt 6.9.

See also position.

instanceCount : int

The instanceCount property specifies the number of instances to generate. Changing this value will regenerate the whole table.

See also randomSeed.

position : InstanceRange

The position property defines the geometrical bounds of the generated instances. The default value is empty, causing a generated position of `[0, 0, 0]`.

See also color, rotation, scale, and customData.

randomSeed : int

This property defines the seed for the random number generator. Setting this to a value different from -1 guarantees that the instance table will have the same content each time it is generated. Note that adding or changing attributes may cause a completely different table to be generated.

The default value is -1, causing the table to get a new random value each time it is generated.

rotation : InstanceRange

The rotation property defines the rotation range for the generated instances. The type is vector3d, corresponding to a Euler rotation vector `[xRotation, yRotation, zRotation]`. The default value is empty, causing no rotation to be applied.

See also position, color, scale, and customData.

scale : InstanceRange

The scale property defines the scaling limits for the generated instances. The type is vector3d. Set InstanceRange.proportional to `true` for uniform scaling. The default value is empty, causing no scaling to be applied.

See also position, color, rotation, scale, and customData.