random_spheres#
- random_spheres(im_or_shape: array, r: int, volume_fraction: int = 1, clearance: int = 0, protrusion: int = 0, n_max: int = 100000, edges: str = 'contained', return_spheres: bool = False, smooth: bool = True, seed: Optional[int] = None)[source]#
Generates a sphere or disk packing using Random Sequential Addition
- Parameters:
im_or_shape (ndarray or list) – To provide flexibility, this argument accepts either an image into which the spheres are inserted, or a shape which is used to create an empty image. In both cases the spheres are added as
True
values to the background. SinceTrue
is considered the pore space, then the added spheres represent holes.r (int) – The radius of the disk or sphere to insert.
volume_fraction (scalar (default is 1.0)) – The fraction of the image that should be filled with spheres. The spheres are added as
True
’s, so each sphere addition increases thevolume_fraction
until the specified limit is reached. Note that ifn_max
is reached first, thenvolume_fraction
will not be achieved. Also,volume_fraction
is not counted correctly if themode
is'extended'
.clearance (int (optional, default = 0)) – The amount of space to put between each sphere. Negative values are acceptable to create overlaps, so long as
abs(clearance) < r
.protrusion (int (optional, default = 0)) – The amount by which inserted spheres are allowed to protrude outside of the given background. If set to 0 (the default) then all spheres will be fully inside the region marked
False
in the input image. If > 0, then spheres will extend into the region markedTrue
in the input image.n_max (int (default is 100,000)) – The maximum number of spheres to add. Using a low value may halt the addition process prior to reaching the specified
volume_fraction
. IfNone
is given, then no limit is used.edges (string (default is 'contained')) –
Controls how the edges of the image are handled. Options are:
edges
description
’contained’
Spheres are all completely within the image
’extended’
Spheres are allowed to extend beyond the edge of the image. In this mode the volume fraction will be less than requested since some spheres extend beyond the image, but their entire volume is counted as added for computational efficiency.
return_spheres (bool) – If
True
then an image containing only the spheres is returned rather than the input image with the spheres added, which is the default behavior.smooth (bool) – Indicates whether balls should have smooth faces (
True
) or should include the bumps on the extremities (False
).seed (int) – The seed to supply to the random number generators. Because this function uses
numba
for speed, calling the normalnumpy.random.seed(<seed>)
has no effect. To get a repeatable image, the seed must be passed to the function so it can be initialized the waynumba
requires. The default isNone
, which means each call will produce a new realization.
- Returns:
image – An image with spheres of specified radius added to the background.
- Return type:
ndarray
Notes
This algorithm ensures that spheres do not overlap but does not guarantee they are tightly packed.
This function adds spheres to the background of the received
im
, which allows iteratively adding spheres of different radii to the unfilled space by repeatedly passing in the result of previous calls to RSA.References
[1] Random Heterogeneous Materials, S. Torquato (2001)
Examples
Click here to view online example.