# 3D MPM Shape Commands

These shape commands are used in 3D MPM simulations within Region and Hole commands to discretize an object for the calculations.

## Box Command

A scripted Box command defines a region to be filled with material points or to be defined as a hole:

```Box (xmin),(xmax),(ymin),(ymax),(zmin),(zmax)
```

In XML files, the command is:

```<Box xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)'
zmin='(zmin)' zmax='(zmax)'/>
```

where

• (xmin),(xmax),(ymin),(ymax),(zmin), and (zmax) are the x, y, and z extents of the cubical volume. If xmax<xmin, ymax<ymin, or zmax<zmin, they will be automatically switched to define the box. The units are length units (or determined by a units attribute in XML files). In XML files, the coordinates can alternatively be specified relative to the mesh edges.

If the defined cubical volume overlaps regions that already have material points or previously was defined as a hole, those regions will be ignored.

## Sphere Command

A scripted Sphere command defines a region to be filled with material points or to be defined as a hole:

```Sphere (xmin),(xmax),(ymin),(ymax),(zmin),(zmax)
```

In XML files, the command is:

```<Sphere xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)'
zmin='(zmin)' zmax='(zmax)'/>
```

where

• (xmin),(xmax),(ymin),(ymax),(zmin), and (zmax) are the x, y, and z extents of the cubical volume that encloses the spherical volume. If xmax<xmin, ymax<ymin, or zmax<zmin, they will be automatically switched to define the box. The units are length units (or determined by a units attribute in XML files). In XML files, the coordinates can alternatively be specified relative to the mesh edges.

If the defined spherical volume overlaps regions that already have material points or previously was defined as a hole, those regions will be ignored.

## Cylinder Command

A scripted Cylinder command defines a cylindrical or conical region to be filled with material points or to be defined as a hole:

```Cylinder (xmin),(xmax),(ymin),(ymax),(zmin),(zmax),(axis),<(radius)>
```

In XML files, the command is:

```<Cylinder xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)'
```

where

• (xmin),(xmax),(ymin),(ymax),(zmin), and (zmax) are the x, y, and z extents of the cubical volume that encloses the cylindrical or conical volume. If xmax<xmin, ymax<ymin, or zmax<zmin, they will be automatically switched to define the box. The units are length units (or determined by a units attribute in XML files). In XML files, the coordinates can alternatively be specified relative to the mesh edges.
• (axis) is 1, 2, or 3 (or x, y, or z) for the axial direction of the cylinder to be in the x, y, or z direction, respectively. This command can only define cylinders aligned with one of the global axes.
• (radius) is an optional parameter with a value between -1 and 1. This value gives the relative radius of the cylinder at the top (if > 0) or at the bottom of the cylinder (if < 0) while the opposite end will have relative radius of 1. Entering 0 gives a cone with a point on the top (to get a cone with point on the bottom enter a small negative number). The radius of the cylinder varies linearly along its length.

If the defined cylindrical or conical volume overlaps regions that already have material points or previously were defined as a hole, those regions will be ignored.

## Torus Command

A scripted Torus command defines a defines a toroidal volume to be filled with material points or defined as a hole:

```Torus (xmin),(xmax),(ymin),(ymax),(zmin),(zmax),(axis),<(radius)>
```

In XML files, the command is:

```<Torus xmin='(xmin)' xmax='(xmax)' ymin='(ymin)' ymax='(ymax)'
```

where

• (xmin),(xmax),(ymin),(ymax),(zmin), and (zmax) are the x, y, and z extents used to define the torus (see below). If xmax<xmin, ymax<ymin, or zmax<zmin, they will be automatically switched to define the box. The units are length units (or determined by a units attribute in XML files). In XML files, the coordinates can alternatively be specified relative to the mesh edges.
• (axis) is 1, 2, or 3 (or x, y, or z) for the normal direction to the plane of the torus to be in the x, y, or z direction, respectively.
• (radius) is an optional parameter to define the radius of the toroidal ring cross section in the plane of the torus.

The (axis) parameter specifies the normal direction to the plane of the torus. The bounds for the directions in the plane of the torus (e.g., x and y bounds when (axis) is 3) define an ellipsoid (or circle if the bounds have the same range) that runs through the center of the torodial ring. The bounds in the direction of the axis define top and bottom for the cross-section of the torodial ring. The cross section will be a circle with radius given by half the distance between the top and bottom. To have an eliptical cross section, you can specify optional (radius) parameter to define the radius of the cross section in the plane of the torus (while top and bottom give radius of the cross section in the axis direction).

If the defined toroidal volume overlaps regions that already have material points or previously were defined as a hole, those regions will be ignored.

## Shell Command

A scripted Shell command defines a defines a cylindrical shell volume to be filled with material points or defined as a hole:

```Shell (axis),(axmin),(axmax),(radius),(thickness),<(sxo)>,<(syo)>   (not available yet)
```

In XML files, the command is:

```<Shell axis='3' zmin='(axmin)' zmax='(axmax)' radius='(radius)' thickness='(thickness)
xmin='(sxo)' ymin='(syo)'/>
```

where

• (axis) is 1, 2, or 3 (or x, y, or z) for the height direction of the shell to be in the x, y, or z direction, respectively.
• (axmin) and (axmax) define the range of coordinates along the axis of the shell (or along the direction specified by (axis)). In XML files, enter (axmin) and (axmax) using attributes for minimum and maximum of the axis direction (e.g., use zmin and zmax to enter (axmin) and (axmax) when (axis) is z). The units are length units (or determined by a units attribute in XML files).
• (radius) is a user defined function of position along the axis (using variable "h") that gives the inner radius of the shell. The units for "h" and the result are length units (or determined by a units attribute in XML files).
• (thickness) is a user defined function of position along the axis (using variable "h") that gives the thickness of the shell. The units for "h" and the results are length units (or determined by a units attribute in XML files).
• (sxo), and (syo) give the origin for the shell along the two axes other than the one specified by (axis). The default is (0,0). In XML files, give the origin using the minimum values for the other two axis (e.g., use (xmin) and (ymin) when (axis) is z). The units are length units (or determined by a units attribute in XML files).

This shape will be shell formed by rotating around a line in the (axis) direction that passes through (sxo,syo) in the plane perpendicular to the (axis) direction. The shell wall inner radius is given the the (radius) function. The shell wall outer radius is sum of the (radius) and (thickness) functions.

If the defined shell volume overlaps regions that already have material points or previously were defined as a hole, those regions will be ignored.

## Line Command

A scripted Line command defines a region to be filled with material points or to be defined as a hole:

```Line (x1),(x2),(y1),(y2),(z1),(z2),<(tolerance)>
```

In XML files, the command is:

```<Line x1='(x1)' x2='(x2)' y1='(y1)' y2='(y2)'
z1='(y1)' z2='(y2)'tolerance='(tol)'/>
```

where the line is from `(x1,y1,z1)` to `(x2,y2,z2)`. The region will include points within `(tolerance)` of the line. The region will be a cylinder with ends normal to the line and radius of `(tolerance)`.

Note that xmin, xmax, ymin, ymax, zmin, zmax can be used in place of x1, x2, y1, y2, z1, and z2.

## Polyhedron

These commands fill or empty a 3D polyhedron specified by a collection of points connected in various styles. In scripted files, polyhedra are defined with a series of PolyPt commands:

```PolyPt (x1),(y1),(z1)
PolyPt (x1),(y1),(z1)
...
PolyPt (xn),(yn),(zn)
PolyPt (style),(details)
```

The required, final PolyPt command defines how the points are connected to create the shape (see below). In XML files, the shape is specified by a Polyhedron command. A faces command subordinate to the Polyhedron command specifies the points and defines how the points connect to a shape:

```<Polyhedron>
<faces style='(style)'>
(x1) (y1) (z1)
(x1) (y1) (z1)
...
(xn) (yn) (zn)
</faces>
</Polyhedron>
```

In the above, ((x1),(y1),(z1)) to ((xn),(yn),(zn)) define n 3D coordinates. In scripted files, each PolyPt command defines one coordinate. In XML files, the text in the faces command should have 3n numbers entered as free format text. The only requirements are the the correct number of valid numeric data points for the chosen style are provided and that the points are delimited by white space, commas, colons, and/or semicolons. The number of points per line does not matter and multiple delimiters between numbers can be used if desired. The number of coordinates entered depends on the style option being used. The currently available styles are:

• style="pyramid": define a pyramid shape for which the first point is the apex of the pyramid and the remaining 3 or 4 points define the base. With 3 base points (4 total points), the shape is a tetrahedron; with 4 base points (5 total points), the shape is a pyramid with a quadrilaterial base. If the 4 base points are not coplanar, the base will have two face triangles connected by a line between the 1st and 3rd points.
• style="tripts" or style="trivectors": define a triclinic shape, which is an eight-corned box for which opposite faces are parallel, but the corners need not meet at right angles. For this style, you specify 4 points (or 12 coordinates). For `tripts`, the 4 points are the points labeled in the figure below. For trivectors, the first point is point 1 (the origin) and the remaining three points are vectors between the shape's origin that point.
• style="15482637" (entered as (style)="box" and (details)="15482637" in scripted files): define an arbitrarily shaped 8-corner box. The provided numbers map the order of the provided 8 points (or 24 coordinates) to the standard order shown in the figure below.

## Nested Commands

You can nest shapes in other shapes to create a wide variety of new shapes.

## Using a Stack of Images

You can convert pixels in a stack 2D images, such output from X-Ray computed tomography, into material points using BMRegion commands.