random_spheres

random_spheres(shape: List | None = None, im: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, r: int = 5, clearance: int = 0, protrusion: int = 0, maxiter: int = 100000, phi: float = 1.0, edges: Literal['contained', 'extended'] = 'contained', smooth: bool = True, seed: int | None = None, value: int = True)

Generates a sphere or disk packing using random sequential addition as described by Torquato [1].

Parameters:

• shape (list) – The shape of the image to create. This is equivalent to passing an array of False values of the desired size to im.

• im (ndarray) – Image with False indicating the voxels where spheres should be inserted. This can be used to insert spheres into an image that already has some features (e.g. half filled with larger spheres, or a cylindrical plug).

• r (int) – The radius of the disk or sphere to insert. The default is 5.

• phi (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 the volume_fraction until the specified limit is reached. Note that if n_max is reached first, then volume_fraction will not be achieved. Also, volume_fraction is not counted correctly if the mode 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 forground. If set to 0 (the default) then all spheres will be fully inside the region marked False in the input image.

• maxiter (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 phi. If None is given, then no limit is used.

• edges (string (default is 'contained')) –

  Controls how the edges of the image are handled. Options are:

  Edge Mode	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.

• 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 normal numpy.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 way numba requires. The default is None, which means each call will produce a new realization.

• value (scalar) – The value to set the inserted spheres to. Using value > 1 is a handy way to repeatedly insert different sphere sizes into the same image while making them easy to identify.

Returns:

image – An image with spheres of specified radius added to the background.

Return type:

ndarray

See also

pseudo_gravity_packing, pseudo_electrostatic_packing

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 the function.

References

[1]

Random Heterogeneous Materials, S. Torquato (2001)

Examples

Click here to view online example.