# Soil Materials Extension

The Soil Materials Extension lets you define which soil presets the simulation uses as the soil material in the scene. It also has settings to limit the number of soil particles during a simulation, or remove particles if they stop moving for a specified amount of time. This extension applies to Earthwork projects.

Note: Mass loss can occur if the particle limit is too low. You can only add and one Soil Materials Extension to each scene.

## Configuring the Soil Material

When you insert the first Earthwork Zone in the scene, the Soil Materials extension appears under the Earthwork Systems folder by default. You can also add the extension manually.

1. In your scene or mechanism, select Earthwork Systems in the Toolbox.
2. Double-click Soil Materials to add the extension.
3. Select the extension in the Explorer panel and configure its parameters, described below.

Configuring the soil materials can be confusing at first. It is often better to logically group the parameters and set them in the following order:

1. Select a soil type:
• Parameter: Soil Material Preset
2. Specify a soil particle limit:
• Parameter: Enable Soil Particle Limit
• Parameter: Soil Particle Limit
3. Configure the removal (culling) of soil particles which come to rest:
• Parameter: Enable Soil Particle Culling
• Parameter: Soil Particle Culling Min Age
• Parameter: Soil Particle Culling Max Linear Velocity
• Parameter: Soil Particle Culling Max Angular Velocity

The Soil Materials parameters are:

• Culled Soil Mass (output): This is the amount of mass culled as part of the "soil particle culling" feature. It is useful to keep track of soil which gets spilled outside of dig zones.
• Soil Material Preset: Select a soil type from this drop-down menu. The selected soil type defines the type of soil simulated in the entire scene (all Earthwork Zones, soil bins, soil layers, soil emitters).
Presets from previous releases of Vortex® Studio come with a version number indicating the version with which they have been released. If you load a scene from a previous version, it will default to the current soil preset; with this, you can downgrade to an older version if need be.
The soil presets are defined in Vortex Resource files (.vxr), which are stored under the Resources folder in the Vortex installation location (for example, C:\CM Labs\Vortex Studio [current version]\resources\EarthworkSystems\SoilMaterialPresets\Gravel.vxr).
Note
You can only select one soil type for a scene. For example, you cannot select both gravel and sand.
• Enable Soil Particle Limit: Selecting this box puts a hard limit (defined in Soil Particle Limit) on the number of particles simulated. This is useful if computational performance is more important than accuracy.
Note
If the particle limit is reached during a dig operation, no more particles will be generated. The dig tool will continue to remove mass from the soil grid (Earthwork Zone or soil bin), which will invalidate the conservation of mass.
• Soil Particle Limit: This sets a maximum number of particles simulated for the soil. It is only taken into account if the Enable Soil Particle Limit checkbox is active.
• Enable Soil Particle Culling: Selecting this box will remove particles based on their age and/or velocity, even though they would otherwise be simulated. This allows removal of particles at rest which are no longer actively contributing to the simulation and are outside of any Earthwork Zone, soil bin or bucket. This helps to keep the particle count within a reasonable range to ensure good computational performance.
• Soil Particle Culling Min Age: Sets a maximum lifespan for the particles simulated for the soil. Age is specified in number of simulation frames. It is only taken into account if the Enable Soil Particle Culling checkbox is active.
• Soil Particle Culling Max Linear Velocity and Soil Particle Culling Max Angular Velocity: These values define the linear and angular velocity thresholds used for the soil particle culling feature.
Particles which have sufficiently high age (see Soil Particle Culling Min Age), and are not moving faster than indicated by these parameters (i.e., they are considered at rest), will be removed from the simulation (culled). This is only taken into account if the Enable Soil Particle Culling checkbox is active.