pseudo_gravity_packing#

pseudo_gravity_packing(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, axis: int = 0, edges: Literal['contained', 'extended'] = 'contained', maxiter: int = 1000, phi: float = 1.0, seed: int | None = None, smooth: bool = True, value: int = 1) → ndarray[source]#

Iteratively inserts spheres at the lowest accessible point in an image, mimicking a gravity packing.

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 spheres to be added

  • clearance (int (default is 0)) – The amount space to add between neighboring spheres. The value can be negative for overlapping spheres, but abs(clearance) > r.

  • protrusion (int (optional, default=0)) – The amount that spheres are allowed to protrude beyond the active phase. A negative number will create clearance between spheres and the background.

  • axis (int (default is 0)) – The axis along which gravity acts, directed from the end (-1) towards the start (0).

  • phi (float (default is 1.0)) – The “solid volume fraction” of spheres to add (considering spheres as solid). This is used to calculate the discrete number of spheres, N, required based on the total volume of the image. If N is less than maxiter then maxiter will be set to N. Note that this number is not quite accurate when the edges=’extended’ since it’s not possible to know how much of the sphere will be cutoff by the edge.

  • maxiter (int (default is 1000)) – The maximum number of spheres to add. This places a hard limit on the number of spheres even if phi is specified.

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

    Controls how spheres at 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 that requested since some spheres extend beyond the image, but their entire volume is counted as added for computational efficiency.

  • seed (int, optional, default = None) – The seed to supply to the random number generator. 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.

  • smooth (bool, default = True) – Controls whether or not the spheres have the small pip each face.

  • value (int, default = 1) – The value of insert for the spheres. The default is 1, which puts holes into the background. Values other than 1 make it easy to add spheres repeatedly and identify which were added on each step.

Returns:

spheres – An image the same size as im with spheres indicated by value. The spheres are only inserted at locations that are accessible from the top of the image.

Return type:

ndarray

Examples

Click here to view online example.