simPoissonSystem: Poisson germ-grain process
In unfoldr: Stereological Unfolding for Spheroidal Particles

Description Usage Arguments Details Value Author(s) References Examples

Simulation of Poisson germ-grain processes with either spheres, spheroids or spherocylinders as grains

simPoissonSystem(
  theta,
  lam,
  size = "const",
  shape = "const",
  orientation = "rbetaiso",
  type = c("prolate", "oblate", "spheres", "cylinders"),
  rjoint = NULL,
  box = list(c(0, 1)),
  mu = c(0, 0, 1),
  dz = 0,
  n = c(0, 1, 0),
  intersect = c("original", "full", "only", "digi"),
  delta = 0.01,
  intern = FALSE,
  perfect = FALSE,
  pl = 0,
  label = "N"
)

`theta`	list of simulation parameters which must consist of elements: `size`, `shape` and `orientation`
`lam`	mean number of objects per unit volume
`size`	name of the size distribution function
`shape`	name of the shape distribution function
`orientation`	name of direction distribution function
`type`	type of grain, either "`prolate`" or "`oblate`", "`spheres`", "`cylinders`"
`rjoint`	user-defined function, which specifies the (joint) distribution of the size, shape and orientation
`box`	simulation box
`mu`	main orientation axis, `mu=c(0,0,1)` (default)
`dz`	distance of the intersecting plane to the origin
`n`	normal vector defining the intersecting plane
`intersect`	options for type of return values: "`full`" for the simulated system together with section profiles as two lists named `S` and `sp` respectively, choose "`only`" for section profiles only, "`original`" for the 3D system only and "`digi`" for a (binary) integer matrix `W` as a discretized version of section profiles whose resolution depends on the chosen lattice constant `delta`
`delta`	lattice constant for discretization, set to `0.01` (default)
`intern`	logical, `FALSE` (default), whether to return only section profiles with centers inside the simulation window
`perfect`	logical, `FALSE` (default), whether to simulate exactly (also called perfect)
`pl`	integer, print level and return value type, see details
`label`	character, a label set to each generated object, set to '`N`' (default)

The function can simulate a Poisson germ-grain process according to the parameter theta within a predefined (3D) box. The positions of the germs follow a uniform distribution according to a Poisson process with mean intensity parameter lam. The function either randomly generates type="prolate" or type="oblate" spheroids, spheres or spherocylinders. The argument size sets the name of the distribution function for the size/length of the objects, i.e. the major semi-axis lengths in case of spheroids, radii for spheres or the lengths of the main axis of rotation for spherocylinders including the end caps.

The following direction (orientation) distributions of the spheroids' major-axis, respectively, cylinders' main axis are available: a uniform distribution ("runifdir"), distribution ("rbetaiso") and the "von Mises-Fisher" ("rvMisesFisher") distribution. The two last ones depend on the concentration parameter kappa which is set as part of the parameter list theta, see examples below. The direction distributions generate random spherical coordinates (\vartheta, φ) w.r.t. a fixed main orientation axis mu with polar angle \vartheta\in[0,π/2) and azimuthal angle φ\in[0,2π). The simulations are always performed within a bounding 3D box which consists of a list specifying the ranges of each dimension corresponding to the lower and upper limits of the box in each direction. If the argument box contains only a single range, i.e. box=list(c(0,1)), this limit isassumed for the remaining dimensions which is then simply replicated. The optional argument rjoint defines a (joint) distribution function which can be any function provided by the user in order to generate the required distributional parameters for the spheroids or spherocylinders. For an in-depth example of usage please see the workflow in 'simSpheroids.R' and 'simCylinders.R'.

In addition, the function supports an exact simulation type [2] of the grains. In case of spheroids and spherocylinders setting size="rbinorm" declares a bivariate size-shape distribution for which the exact simulation is available. More specifically, for a bivariate normal random vector [X,Y] with correlation parameter ρ, the length of the major semi-axis of a spheroid is given by a=exp(x) with a (logit-transformed) shape parameter as s=1/(1+exp(-y)) and thus a scaled minor semi-axis length c=a*s. The modification leads to a log-normally distributed length of the major semi-axis. Consequently, in case of spherocylinders, the log-normally distributed length is len=h+2*r where h is the height and r=len/2*s the radius. The main direction u of a spheroid or spherocylinder is determined by the major axis independent of size and shape. Further, the following univariate distributions of the major semi-axis a, respectively, length len and shape s are available: 'rbeta', 'rgamma', 'rlnorm' and 'runif'. One can also use 'const' for simulations with constant lengths or shapes. Note that only simulations with size distributions 'rbinorm' or 'rlnorm' can use the exact type of simulation.

For spheres any distribution of the radii can be specified as a name of a user-defined function in the argument size as long as the formal named function parameters match the actual names of the parameters exactly as defined in theta. Besides this, all other distributions given above are also available. Using 'const' simulates spheres of constant radii.

The argument pl>=0 denotes both the print level of intermediate output and by the same time the type of the return value. If pl=10, then an abbreviated list of spheroids or spheres is returned to speed up computation. Note that, the current implementation does not include routines for unfolding the joint size-shape-orientation distribution of spherocylinders so far.

list of 3D objects depending on the chosen return type defined by the argument intersect

M. Baaske

Ohser, J. and Schladitz, K. 3D images of materials structures Wiley-VCH, 2009
C. Lantu\acute{\textrm{e}}joul. Geostatistical simulation. Models and algorithms. Springer, Berlin, 2002. Zbl 0990.86007

 # intensity parameter
 lam <- 100

 # simulation bounding box
 box <- list("xrange"=c(0,5),"yrange"=c(0,5),"zrange"=c(0,5))

 # log normal size distribution with a constant shape factor and
 # concentration parameter (\code{kappa=1}) for the orientation, see reference [1] 
 theta <- list("size"=list("meanlog"=-2.5,"sdlog"=0.5),
               "shape"=list("s"=0.5),
               "orientation"=list("kappa"=1))

 S <- simPoissonSystem(theta,lam,size="rlnorm",box=box,type="oblate",pl=1) 
 length(S)