# Non-spherical particle shapes

Ellipsoidal particles

User-defined particle shapes

OVITO provides built-in support for various particle shapes beyond the default spherical shape:

> - Spheres

> - Ellipsoids

> - Superquadrics

> - Cubes and boxes

> - Cylinders

> - Spherocylinders (capsules)

> - Circles and squares (billboards that follow the view direction)

> - User-defined polygonal meshes

You can set the particle display shape for the entire system in the settings of the Particles visual element or on a per-type basis using the Edit types modifier.

## Controlling size and orientation of particles

By assigning values to the following particle properties in OVITO, you can control the orientation and dimensions of individual particles:

> - `Radius` (scalar)

> - `Aspherical Shape` (X, Y, Z)

> - `Orientation` (X, Y, Z, W)

> - `Superquadric Roundness` (Phi, Theta)

These properties can be assigned during data import by mapping corresponding file columns to the appropriate target properties in OVITO. You can also modify them later by inserting the Compute property modifier into the data pipeline.

The orientation of non-spherical particles is controlled by the `Orientation` property, which consists of four components:

\[\mathbf{q} = (x, y, z, w)\]

This represents a quaternion, a mathematical construct used for three-dimensional rotations. Quaternions offer a more compact and numerically stable alternative to rotation matrices.

OVITO follows the quaternion notation established by Ken Shoemake. This notation may differ from other conventions found in literature, such as the Wikipedia format, where quaternion components are often written as:

\[(q_r, q_i, q_j, q_k) = (w', x', y', z')\]

Thus, when importing quaternion data into OVITO, ensure the correct mapping of input components.

The `Orientation` and `Aspherical Shape` properties are typically derived from simulation outputs. For example, in LAMMPS, the following script commands dump and export per-particle orientation and size information:

    compute orient all property/atom quatw quati quatj quatk
    compute diameter all property/atom shapex shapey shapez
    dump 1 all custom 100 ellipsoid.dump id type x y z &
                                         c_orient[1] c_orient[2] c_orient[3] c_orient[4] &
                                         c_diameter[1] c_diameter[2] c_diameter[3]

When importing the dump file into OVITO, ensure that the `quati`, `quatj`, `quatk`, and `quatw` attributes are correctly mapped to the `Orientation.X`, `Orientation.Y`, `Orientation.Z`, and `Orientation.W` particle properties (in this exact order).

OVITO can automatically establish this mapping if the column names in the LAMMPS dump file are properly assigned:

    dump_modify 1 colname c_orient[1] quatw colname c_orient[2] quati colname c_orient[3] quatj colname c_orient[4] quatk
    dump_modify 1 colname c_diameter[1] shapex colname c_diameter[2] shapey colname c_diameter[3] shapez

Similarly, the `shapex`, `shapey`, and `shapez` columns will be mapped to `Aspherical Shape.X`, `Aspherical Shape.Y`, and `Aspherical Shape.Z`, which define the principal semi-axes of non-spherical particles as described below.

Note

OVITO can automatically set up the correct mapping only if dump file column names are assigned as described here. Otherwise, you may need to adjust the mapping manually in the Edit column mapping dialog, accessible from the File import panel.

## Spheres

The sphere particle shape is defined by the mathematical equation

> \({\displaystyle {\frac {x^2 + y^2 + z^2}{r^2}} = 1}\).

The sphere radius \(r\) is controlled by the per-particle property `Radius`. If not present, the radius is determined by the particle type or, globally, by the Particles visual element.

The `Position` particle property specifies an additional translation of the spherical equation above away from the coordinate system origin.

## Ellipsoids

The ellipsoid particle shape is defined by the equation

> \({\displaystyle {\frac {x^2}{a^2}}+{\frac {y^2}{b^2}}+{\frac {z^2}{c^2}} = 1}\).

The lengths of the principal semi-axes \(a\), \(b\), \(c\) of the ellipsoid are controlled by the per-particle property `Aspherical Shape`, which has three components X, Y, and Z (all positive). If all three components of the property are zero for a particle, OVITO falls back to \(a=b=c=r\), with \(r\) being the spherical radius of the particle as defined above.

## Superquadrics

The shape of superquadric particles is defined by the equation

> \({\displaystyle \left( {\left| \frac{x}{a} \right| ^{(2/\phi)}} + {\left| \frac{y}{b} \right| ^{(2/\phi)}} \right) ^{(\phi/\theta)} + {\left| \frac{z}{c} \right| ^{(2/\theta)}} = 1}\).

Like ellipsoidal particles, the superquadric shape has three semi-axes \(a\), \(b\), \(c\), which are specified by the `Aspherical Shape` particle property. The two parameters \(\phi\) and \(\theta\) are called east-west and north-south exponents and determine the blockiness/roundness of the superquadric ellipsoid. Both must be strictly positive. The normal sphere (or ellipsoid) is reproduced by setting \(\phi = \theta = 1\). In OVITO, the values of \(\phi\) and \(\theta\) are specified by the `Superquadric Roundness` property, which is a vector particle property having two components.

## Boxes

The size of box-shaped particles is given by the semi-axes \(a\), \(b\), \(c\), which are multiplied by a factor of two to yield the edge lengths of the box along the Cartesian coordinate axes. In OVITO, the semi-axes are determined by the particle property `Aspherical Shape`, which has three components. If not present, or if the components of `Aspherical Shape` are zero for a particle, OVITO falls back to using the `Radius` particle property and renders a cube.

## Cylinders

The cylindrical shape is given by the radius \(r\) and the height \(h\) (in the local coordinate system of the cylinder). The natural orientation of the cylinder is along the positive z-axis, with an optional rotation specified by the `Orientation` particle property. \(r\) and \(h\) are determined by the particle property components `Aspherical Shape.X` and `Aspherical Shape.Z`. The second vector component (Y) is ignored. If `Aspherical Shape` is not defined, OVITO will fall back to \(h = 2 r\), with \(r\) taken from the `Radius` property instead.

## Spherocylinders (capsules)

The size of spherocylindrical particles is controlled in the same way as cylindrical particles. OVITO additionally renders two hemispheres at each end of the cylinder, extending its height.

## Circles and squares

Circles and squares are two-dimensional, i.e., flat, shapes, whose size is controlled by the `Radius` particle property. The orientation of each particle in three-dimensional space is determined automatically such that it exactly faces the viewer. Thus, their orientations are view-dependent, and the `Orientation` particle property, if present, is ignored. In other words, you don’t have the possibility to control their orientations explicitly (use a mesh-based shape instead if you need control).

Note

Rendering of flat circles and squares is only possible with the OpenGL renderer of OVITO. The Tachyon and OSPRay rendering engines do not support this kind of particle shape.

## User-defined shapes

On the level of individual particle types, you can assign custom particle shapes imported from external geometry files. OVITO supports loading general polyhedral meshes, which can serve as user-defined particle shapes, from various file input formats such as STL, OBJ, or VTK/VTP.

Some simulation formats such as HOOMD/GSD can embed information on particle shapes directly in the simulation output file, which will be picked up by OVITO automatically. In most cases, however, you’ll have to load the user-defined particle shape by hand for each particle type in the Particle types panel. Set the particle type’s Shape to Mesh/User-defined and import the shape geometry from a file that you have prepared outside of OVITO.

The vertex coordinates of the loaded polyhedral mesh get scaled by the value of the `Radius` property of each particle (if present) and rotated by the quaternion stored in the `Orientation` property (if present). Alternatively, you can set the Display radius parameter of the type to scale all particles of that type or adjust the Radius scaling factor in the Particles visual element to scale all particles uniformly.