Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Shape Visualization

The chunk `particles/type_shapes` stores information about shapes corresponding to particle types. Shape definitions are stored for each type as a UTF-8 encoded JSON string containing key-value pairs. The class of a shape is defined by the `type` key. All other keys define properties of that shape. Keys without a default value are required for a valid shape specification.

## Empty (Undefined) Shape

An empty dictionary can be used for undefined shapes. A visualization application may choose how to interpret this, e.g. by drawing nothing or drawing spheres.

Example:

    {}

## Spheres

Type: `Sphere`

Spheres’ dimensionality (2D circles or 3D spheres) can be inferred from the system box dimensionality.

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
diameter | Sphere diameter | float | 1x1 |  | length

Example:

    {
        "type": "Sphere",
        "diameter": 2.0
    }

## Ellipsoids

Type: `Ellipsoid`

The ellipsoid class has principal axes a, b, c corresponding to its radii in the x, y, and z directions.

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
a | Radius in x direction | float | 1x1 |  | length
b | Radius in y direction | float | 1x1 |  | length
c | Radius in z direction | float | 1x1 |  | length

Example:

    {
        "type": "Ellipsoid",
        "a": 7.0,
        "b": 5.0,
        "c": 3.0
    }

## Polygons

Type: `Polygon`

A simple polygon with its vertices specified in a counterclockwise order. Spheropolygons can be represented using this shape type, through the `rounding_radius` key.

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
rounding_radius | Rounding radius | float | 1x1 | 0.0 | length
vertices | Shape vertices | float | Nx2 |  | length

Example:

    {
        "type": "Polygon",
        "rounding_radius": 0.1,
        "vertices": [[-0.5, -0.5], [0.5, -0.5], [0.5, 0.5]]
    }

## Convex Polyhedra

Type: `ConvexPolyhedron`

A convex polyhedron with vertices specifying the convex hull of the shape. Spheropolyhedra can be represented using this shape type, through the `rounding_radius` key.

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
rounding_radius | Rounding radius | float | 1x1 | 0.0 | length
vertices | Shape vertices | float | Nx3 |  | length

Example:

    {
        "type": "ConvexPolyhedron",
        "rounding_radius": 0.1,
        "vertices": [[0.5, 0.5, 0.5], [0.5, -0.5, -0.5], [-0.5, 0.5, -0.5], [-0.5, -0.5, 0.5]]
    }

## General 3D Meshes

Type: `Mesh`

A list of lists of indices are used to specify faces. Faces must contain 3 or more vertex indices. The vertex indices must be zero-based. Faces must be defined with a counterclockwise winding order (to produce an “outward” normal).

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
vertices | Shape vertices | float | Nx3 |  | length
indices | Vertices indices | uint32 |  |  | number

Example:

    {
        "type": "Mesh",
        "vertices": [[0.5, 0.5, 0.5], [0.5, -0.5, -0.5], [-0.5, 0.5, -0.5], [-0.5, -0.5, 0.5]],
        "indices": [[0, 1, 2], [0, 3, 1], [0, 2, 3], [1, 3, 2]]
    }

## Sphere Unions

Type: `SphereUnion`

A collection of spheres, defined by their diameters and centers.

Key | Description | Type | Size | Default | Units
--- | --- | --- | --- | --- | ---
diameters | Sphere diameters | float | Nx1 |  | length
centers | Sphere centers | float | Nx3 |  | length

Example:

    {
        "type": "SphereUnion",
        "centers": [[0, 0, 1.0], [0, 1.0, 0], [1.0, 0, 0]],
        "diameters": [0.5, 0.5, 0.5]
    }