File: shapes.rst

package info (click to toggle)
python-gsd 2.4.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 904 kB
  • sloc: python: 2,742; ansic: 1,881; makefile: 157; cpp: 109
file content (167 lines) | stat: -rw-r--r-- 5,014 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
.. Copyright (c) 2016-2020 The Regents of the University of Michigan
.. This file is part of the General Simulation Data (GSD) project, released
.. under the BSD 2-Clause License.

.. _shapes:

Shape Visualization
===================

The chunk :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]
    }