concave_decomposition command

Purpose

This command decomposes a particle into convex blocks.

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

concave_decomposition keyword value ...

  • zero or more keyword/value pairs may be appended

  • keyword = mesh_file or output_file or output_folder or overwrite or resolution or reduction_threshold or write_vtm_decomposition

mesh_file arg = stlfile [mandatory keyword]
  stlfile = path to a .stl file for the particle shape
output_file arg = output-filename [mandatory keyword]
  output-filename = filename for the generated include file
output_folder arg = output-folder
  output-folder = folder to which the decomposition and include file should be written
overwrite arg = yes or no
  yes = existing decomposition will be overwritten
  no = existing decomposition will only be recreated if arguments or mesh file changed
resolution arg = low or medium or high
  low = low resolution
  medium = medium resolution
  high = high resolution
reduction_threshold arg = value
  value = maximum volume error to accept reduced block
write_vtm_decomposition arg = yes or no
  yes = write decomposition to a .vtm file
  no = don't write .vtm file

Examples

concave_decomposition mesh_file myParticleShape.stl output_file decomp.asx
concave_decomposition mesh_file myParticleShape.stl output_file decomp.asx output_folder decomp_coarse/ overwrite no resolution low reduction_threshold 0.2

concave_decomposition mesh_file myParticleShape.stl output_file decomp.asx output_folder decomp_fine/ overwrite no resolution high reduction_threshold 0.001 overwrite yes
# usage of previous output with particle_template
particle_template id myTemplate material stone shape concave convex_bodies_file decomp_fine/decomp.asx

Description

This command takes a particle shape which is represented by an stl mesh and creates a decomposition into convex blocks for further use with the particle_template command for concave particles. The output of the command are an include file and a set of convex blocks represented as .stl files. The name of the include file is set via output_file, and the include file as well as the .stl files produced by the command are placed in output_folder (default value: data).

To use the decomposed object in your particle_template command use the convex_bodies_file keyword as shown in the examples above and give it the path to the output_file as value, i.e. output_folder/output_file (Linux) or output_folder\output_file (Windows).

Note

output_file must end with .asx and can not contain any file system separators (/ or \, depending on your operating system). The workflow will place include file and generated .stl files in the same folder.

By default, Aspherix® detects whether a decomposition already exists at the destination, and only calculates a new decomposition if either the mesh file or the settings of the concave_decomposition command in the input script changed. If overwrite is set to yes, Aspherix® always recomputes the decomposition and overwrites files present at the destination.

The details of the decomposition can be controlled by the user via the resolution and reduction_threshold keywords. resolution can be set to low, medium or high and controls the resolution of the splitting process. A low resolution will speed up the computation of the decomposition and in general produce fewer convex blocks, which will also lead to faster simulation. However, it might also alter or eradicate small geometric features such as holes in the particle geometry. A high resolution will produce a more accurate representation of the particle shape, using more blocks with more triangles, but decomposition generation will take longer and subsequent simulations will be slower due to more and more complex particles being used. reduction_threshold controls a reduction mechanism after the particle shape is split into convex blocks. The mesh size of the block is reduced, and the relative volume error between original and reduced block is computed. If the relative volume error is below the value given for reduction_threshold, the reduced block is accepted. If not, the unreduced block is used.

The decomposition can be written to a .vtm file for viewing in ParaView by setting write_vtm_decomposition to yes. The output file will be placed in output_folder, and the file name will be the same as output_file, with extension .vtm (decomp.asx will result in decomp.vtm being written). The resulting file contains two VTK blocks: the original .stl mesh, and another one containing the decomposition as sub-blocks. Use ParaView’s “Extract blocks” filter to view either one in more detail.

In case the input mesh is already convex, this command will not throw an error and instead create the same output files but with just one block. This can then be used in the particle_template command with shape concave.