BMPRegion Command

An advanced feature of both NairnMPM and NairnFEA is that you can digitize objects directly from images or data in a text file.

Introduction

An alternative method for creating meshes in NairnFEA or material points in NairnMPM to to create them from an image file and data in a text file. An image file can be one you draw in a CAD program or can be a photo of object. The later options lets you create realistic numerical models of complex objects in a single command. A text file is typically created in other software such as a simple python script. In 2D or axisymmetric calculations, the file data fills in an FEA mesh or adds material points to the grid. in 3D MPM simulations, each file represents one slice of the object in the x-y plane at a fixed value of z. By combining a stack of slices, the file data can create all material points for a complex 3D object.

BMPRegion Commands

The command to digitize images or use text data is the same for both FEA and MPM input files. In scripted files, an image is converted into material points using:

BMPRegion (bmpFilePath),(width),<(height)>,<(scheme)>,<(anglesPath)>,<(property),(value)>...
  Origin (xO),(yO),<(zO>,<(flip)>
  Intensity (matID),(grayMin),(grayMax),<(prop),(value)>,...
    . . .
  Intensity "angles",(gray1),(gray2),(angle1),(angle2)
  (optional rotation command - MPM only)
EndRegion

In XML files, the command block is (must be within the single <MaterialPoints> element for MPM input files):

<BMP name="(bmpFilePath)" width="(width)" height="(height)" anglesZ="(anglesPath)" anglesY="(anglesPath)" anglesX="(anglesPath)">
  <Origin x="(xO)" y="(yO)" z="(zO)" flipped="(flip)"/>
  <MatlPtsPerElement>(totalNumber)</MatlPtsPerElement>
  <Intensity mat="(matID)" imin="(gramMin)" imax="(grayMax)">
     (property command options)
  </Intensity>
    . . .
  <Intensity imin="(gray1)" imax="(gray2)" minAngle="(angle1)" maxAngle="(angle2)"/>
  (optional rotation commands - MPM only)
</BMP>

where

• (bmpFilePath) is the full or relative path name to either a BMP file (with extension .bmp) or a plain text file containing tab-delimited or comma-separated values (with extension .txt). Most BMP styles are allowed and the file data are converted to 256 levels of gray (or intensity for RGB files) from 0 to 255. A text file's rows and columns translate to locations as if they were pixels in an image file. Floating point numbers are allowed but all numbers should be in the range of 0 to 255 and only integral values matter.
• (width) and (height) specify the physical width and height for the image (not number of pixels), but there are several ways to specify them.
• (scheme) specifies are rotation scheme if BMP (or text) files are provided to determine those angles. The scheme must by "Z" for 2D simulations (all rotations are about the z axis) or can be any one axis (X, Y, or Z), any pair of axes (e.g., "XY"), or any three axis scheme beginning in Z (e.g., "ZYZ"). The (scheme) must be followed by one (anglesPath) for each axis in the scheme. Because 2D simulations must always be "Z", the (scheme) can be omitted and replaced with the one (anglesPath).
• (anglesPath),... are 1 to 3 (one for each axis defined in (scheme)) optional full or relative path names to BMP or text files whose intensities or values determine a material angle for rotation about the corresponding axis in (scheme) (or "Z" axis if (scheme) is omitted). The angles can set Euler angles to orient the material axes at the start of simulations with anisotropic materials. The file data must be exactly the same size (horizontal and vertical pixels or rows and columns of text) as the image file in (filePath). The gray scale or text values are mapped to angles by using Intensity commands. The relation of axes to Euler angles determines the initial rotation matrix for each particle.
• (totalNumber) is to optionally set the number of material points in each element of the background grid for this region to differ from the default setting.¹ (it must be square or cube of points per side in 2D or 3D, respectively). This option is for XML files only. Use the "res" option below to pick points per element in scripted file.

Note that XML files do not use the (scheme) argument. Instead, the optional angle files are set with anglesZ, anglesY, and anglesX attributes. These attributes can set 1 to 3 files in 3D, but can only set anglesZ in 2D. The order of the attributes determines the (scheme) (for backward compatibility, the attribute (angles) is equivalent to (anglesZ)).

In scripted files, you can set additional parameters in pairs. The first item in each pair (i.e., (property)) is the name of the property to set and the second item (i.e., (value)) is the value for that property (note: to enter pairs without prior optional parameters, enter a value for (height), set (scheme)="", and skip (anglesPath)). Only one option is available:

• res,(axisNumber) is to optionally set the number of material points along each axis in each element of the background grid for this region to differ from the default setting.¹ The total number of points per element is square (for 2D) or cube (for 3D) of (axisNumber).

Inside BMPRegion blocks, you include various commands to determine how the pixels are converted into material points. The possible subordinate commands are:

• Origin command - used to connected the image coordinates to the MPM grid coordinates.
• Intensity command - used to determine conversion of gray scale values in the images into material points or rotation angles
• (optional rotation commands) - these optional commands provide alternative methods for setting initial material orientation when modeling with anisotropic materials, but are only allowed in MPM input files.

Image Width and Height

The (width) and (height) parameters specify the physical width and height of the image or text data, but they can be specified using different styles. The options are:

1. Give both as positive numbers - if both numbers are provided and are positive, they give width and height of the image or data in length units (or determined by a units attribute in XML files). They need not match the aspect ratio of actual data, but if they differ the image will be rescaled.
2. Use a negative number - if either (width) or (height) is negative, the absolute value is taken as the number of length units per pixel, row, or column (or other units per pixel as determined by a units attribute in XML files). The total width or height is calculated from the number of pixels in the BMP image or rows or columns for text files.
3. Give only one dimension - if only (width) or only (height) are given, the entered parameter gives that dimension of the image or text data in length units, if positive, or length units per pixel (or row or column), if negative (or other units as determined by a units attribute in XML files). The other dimension is calculated from the aspect ratio of the BMP to trxt file data. To specify only (height) in scripted files, the (width) parameter has to be more negative than -1e8. To specify only (width) in scripted files that are using the optional (anglesPath) parameter, the (height) parameter has to be more negative than -1e8.

Origin Command

The Origin command within a BMPRegion block (or <BMP> element in XML files) is used to map the image in the associated file to the background MPM grid or the existing FEA mesh. In scripted files, the command is

Origin (x0),(y0),<(z0)>,<(flip)>

In XML files, the command is:

<Origin x="(xO)" y="(yO)" z="(zO)" flipped="(flip)"/>

where

• (xO), (yO), and (zO) give the (x,y,z) coordinate for the origin of the image when mapped to the grid or mesh in length units (or determined by a units attribute in XML files). The (zO) coordinate is only needed for 3D calculations and is not allowed in FEA input files.
• If the optional (flip) is "yes", the origin will move to the upper-left corner of the image data with y increasing in the downward direction and x increasing to the right. This change will flip the representation in the y direction in the analysis compared to the image graphics or text data. To provide (flip) parameter in scripted FEA files, you have to provide the (zO) parameter for proper argument alignment; it can be any number because it will be ignored.

If a BMPRegion block does not have an Origin command, the origin will be set to (0,0,0).

Intensity Command

The Intensity command within a BMPRegion block (or <BMP> element in XML files) has two uses to map either materials or angles to the grid or elements.

Mapping Material Type

In this form, an Intensity command is used to map levels of gray-scale or text values of the associated file to different types of material points or to different material initial conditions in an MPM analysis. For FEA calculations, it is used to map the data to different types of materials to assign to mesh elements. In scripted files, this use has the format:

Intensity (matID),(grayMin),(grayMax),<(prop),(value)>,…

In XML files, this use has the format:

<Intensity mat="(matID)" imin="(grayMin)" imax="(grayMax)">
    (property command options)
</Intensity>

where

• (matID) is the material ID for a previously defined material.
• (grayMin) to (grayMax) defines a range in gray-scale intensities or text values to map to this material. The numbers must be from 0 (for black) to 255 (for white) and (grayMin) must be less than or equal to (grayMax).

If the image (or text) data are at higher resolution than the MPM grid, the mapping will check all pixels intersecting each material point location. The material will be set to the most common material at that location (i.e., the mode of the data at that location and not the average).

In scripted files, the optional pairs of arguments, <(prop),(value)> are used to specify other initial conditions for the particles in the intensity range In each pair, the first parameter defines the property and the second parameter defines the value. The properties that are valid for both FEA and MPM input files are:

• "thick" for particle or element thickness in planar 2D calculations. The units are length units.
• "angle" for rotation angle of for the material about the z axis, which is only relevant for anisotropic materials. The units are degrees.
• "temp" for particle temperature. The units are degrees K.

The additional property options for MPM input files are:

• "vx" for particle x-direction velocity (R direction is axisymmetric). The units are velocity units.
• "vy" for particle y-direction velocity (Z direction is axisymmetric). The units are velocity units.
• "vz" for particle z-direction velocity in 3D MPM. The units are velocity units.
• "conc" for particle concentration (set as concentration potential from 0 to 1).
• "pp" for particle pore pressure. The units are pressure units.

In XML files, all properties are set by commands that are subordinate to the <Intensity> element. The properties that are valid for both FEA and MPM input files are:

<Thickness>(value)</Thickness>
<Angle>(value)</Angle>
<Temperature>(value)</Temperature>

The additional property options for MPM input files are:

<vel x="(value)" y="(value)" z="(value)"/>
<Concentration>(value)</Concentration>

and pore pressure is also set with <Concentration> element (depending on whether simulation is doing diffusion or poroelasticity calculations). The units for each property (value) are the same as of script files (or determined by a units attribute).

Mapping Angles

When the first argument to the Intensity command is "angles" (or actually any text that is not a material ID), then that command is used to map gray-scale or text values in an associated angles mask file to material angle for elements in an FEA mesh or material points in an MPM model. This use of the Intensity command only makes sense when optional (anglesPath)s are used in the BMPRegion command. Angle mapping for more than one (anglesPath) file in 3D simulations can be done by using more than one Intensity command. Each extra command maps the corresponding (anglePath) file in order provided. If there are fewer Intensity commands then (anglesPath) files, the remaining files will use the map set by the last Intensity command.

In scripted files, the angle mapping form of the command is:

Intensity "angles",(gray1),(gray2),(angle1),(angle2)

In XML files, this form of the command is:

<Intensity imin="(gray1)" imax="(gray2)" minAngle="(angle1)" maxAngle="(angle2)"/>

where ((gray1),(angle1)) and ((gray2),(angle2)) define two points. The angle will be calculated by a linear interpolation of gray scale values to angle (in degrees) using the line that goes through these two points. The resulting angle, θ, for any given gray-scale value, g, will be:

      [math]\displaystyle{ \theta = {(gray2)-g\over (gray2)-(gray1)}(angle1) + {g-(gray1)\over (gray2)-(gray1)}(angle2) }[/math]

This interpolation applies to all gray scale values, including those outside the range (gray1) to (gray2).

Notes

1. If you set the number of material points per element in a BMPRegion that differs from the default setting, the code will no longer check to make sure particles are not overlapping. The user is therefore responsible for using images that do not cause materials points to be defined in the same locations. Note also that this setting can use any valid number per element and is not limited to the values allowed when choosing the default setting.