distribs

Module Name: distribs Author: Alain Bernard Version: 0.1.0 Created: 2025-07-18 Last updated: 2025-09-02

Summary: Distribution functions on curves, surfaces and volumes.

arc_dist

arc_dist(radius=1.0, scale=None, center=(0, 0, 0), arc_center=0.0, arc_angle=PI / 2, use_vonmises=False, count=10, density=None, seed=None)

Distribute points along an arc of a circle.

Parameters:

Name	Type	Description	Default
radius	float	Base radius of the arc.	1.0
scale	float	Standard deviation for Gaussian noise around the radius.	None
center	(array_like, shape(D))	Center of the arc (2D or 3D).	(0, 0, 0)
arc_center	float	Center angle (in radians) of the arc.	0.0
arc_angle	float	Total angle covered by the arc (in radians).	TAU
use_vonmises	bool	Whether to sample angles using a von Mises distribution.	False
count	int	Number of points to generate (ignored if density is given).	10
density	float	If specified, the number of points is sampled from a Poisson distribution of expected arc length × density.	None
seed	int or Generator	Random seed.	None

Returns:

Type	Description
dict	Dictionary with keys: - 'points': coordinates of sampled points - 'normals': normal unit vectors at each point - 'tangents': tangent unit vectors at each point - 'lengths': radius values used for each point - 'angles': angle values (in radians) used for each point

ball_dist

ball_dist(radius=1.0, axis=(0, 0, 1), angle=np.pi, use_vonmises=False, center=(0, 0, 0), count=10, density=None, scale=None, seed=None, **kwargs)

Distribute points inside a spherical volume (ball or cap).

Parameters:

Name	Type	Description	Default
radius	float	Radius of the sphere.	1.0
axis	array-like of shape (3,)	Axis of the spherical cap (default is +Z).	(0, 0, 1)
angle	float	Angular aperture from the axis (0 to π).	pi
use_vonmises	bool	Use Von Mises distribution for angular sampling.	False
center	array-like of shape (3,)	Center of the sphere.	(0, 0, 0)
count	int	Number of points to generate (overridden by density if provided).	10
density	float	Target density (points per unit volume).	None
seed	int or Generator	Random seed.	None

Returns:

Name	Type	Description
dict		{ 'points': (count, 3) array of positions, 'normals': (count, 3) array of radial directions, 'lengths': (count,) distances from center }

circle_dist

circle_dist(radius=1.0, scale=None, center=(0, 0, 0), count=10, density=None, seed=None)

Distribute points along a full circle in the XY plane.

Parameters:

Name	Type	Description	Default
radius	float	Base radius of the circle.	1.0
scale	float	Standard deviation for Gaussian noise around the radius.	None
center	(array_like, shape(D))	Center of the circle (2D or 3D).	(0, 0, 0)
count	int	Number of points to generate (ignored if density is given).	10
density	float	If specified, the number of points is sampled from a Poisson distribution of expected arc length × density.	None
seed	int or Generator	Random seed.	None

Returns:

Type	Description
dict	Dictionary with keys: - 'points': coordinates of sampled points - 'tangents': tangent unit vectors at each point - 'lengths': radius values used for each point - 'angles': angle values (in radians) used for each point

cube_dist

cube_dist(size=1, center=(0, 0, 0), count=10, density=None, seed=None)

Distribute points uniformly inside a cube.

Arguments

• size (float or array-like of 3 floats) : dimensions of the cube along each axis
• center (array-like of 3 floats) : center of the cube
• count (int) : number of points to generate (overridden by density if provided)
• density (float, optional) : number of points per unit volume (overrides count)
• seed (int or np.random.Generator, optional) : random seed

Returns:

Type	Description
- dict : { 'points': (count, 3) array of sampled positions }

curve_dist_LATER

curve_dist_LATER(curve, t0=0.0, t1=1.0, count=10, density=None, seed=None)

Distribute points on a curve.

Arguments

• curve (Curve) : the curve
• t0 (float = 0.) : start parameter
• t1 (float = 1.) : end parameter
• count (int = 10) : number of points to generate (overriden by density if not None)
• density (float = None) : density of points (overrides count if not None)
• seed (int = None) : random seed

Returns:

Type	Description
- dict : 'points', 'tangents'

cylinder_dist

cylinder_dist(radius=1.0, scale=None, height=1.0, center=(0, 0, 0), arc_center=0.0, arc_angle=TAU, use_vonmises=False, count=10, density=None, seed=None)

Distribute points on the lateral surface of a cylinder.

Points are placed on an arc of the circular base and uniformly along height.

Parameters:

Name	Type	Description	Default
radius	float	Cylinder radius.	1.0
scale	float	Radial noise (used inside arc_dist).	None
height	float	Height of the cylinder (Z direction).	1.0
center	(array_like, shape(3))	Center of the cylinder.	(0, 0, 0)
arc_center	float	Center angle (in radians) for arc distribution.	0.0
arc_angle	float	Angular extent of the arc to sample.	TAU
use_vonmises	bool	Whether to use Von Mises distribution for angular sampling.	False
count	int	Number of points to sample (overridden by density).	10
density	float	Surface density of points per unit area (overrides count).	None
seed	int or Generator	Random seed or NumPy generator.	None

Returns:

Type	Description
dict	Dictionary with: - 'points' : (count, 3) sampled positions - 'tangents' : (count, 3) tangent vectors along arc - 'normals' : (count, 3) surface normals (radial) - 'lengths' : (count,) radial distances - 'angles' : (count,) angular positions (radians)

disk_dist

disk_dist(radius=1, outer_radius=None, center=None, normal=None, count=10, density=None, seed=None)

Distribute points uniformly on a 2D disk or annulus in the XY plane.

Parameters:

Name	Type	Description	Default
radius	float	Radius of the disk (or inner radius if outer_radius is provided).	1
outer_radius	float	Outer radius of the disk. If given, points are sampled in an annular ring [radius, outer_radius].	None
center	(array_like, shape(2) or (3,))	Center of the disk if difference from (0, 0, 0)	None
normal	normal	Normal if different from Z	None
count	int	Number of points to generate (overridden by density if given).	10
density	float	Point density per unit area. Overrides count if provided.	None
seed	int or Generator	Random seed or NumPy random generator.	None

Returns:

Type	Description
dict	Dictionary with keys: - 'points' : (count, D) point positions - 'tangents' : (count, 3) unit tangent vectors in-plane - 'normals' : (count, 3) normal vectors (Z-up) - 'lengths' : (count,) radial distances from center - 'angles' : (count,) polar angles in radians

dome_dist

dome_dist(radius=1.0, scale=None, axis=(0, 0, 1), angle=np.pi / 2, use_vonmises=False, center=(0, 0, 0), count=10, density=None, seed=None)

Distribute points on a spherical cap (dome).

Parameters:

Name	Type	Description	Default
radius	float	Radius of the sphere.	1.0
scale	float	Standard deviation of radial noise.	None
axis	(array_like, shape(3))	Direction of the dome (default is +Z).	(0, 0, 1)
angle	float	Aperture angle of the dome (in radians), from center axis.	π/2
use_vonmises	bool	Whether to use Von Mises angular distribution.	False
center	(array_like, shape(3))	Center of the sphere.	(0, 0, 0)
count	int	Number of points to generate (overridden by density if provided).	10
density	float	Surface density of points per unit area.	None
seed	int or Generator	Random seed or generator.	None

Returns:

Name	Type	Description
dict		{ 'points' : (count, 3) array of sampled positions, 'normals' : (count, 3) unit vectors from center to points, 'lengths' : (count,) sampled distances from center }

line_dist

line_dist(point0=(-1, -1, -1), point1=(1, 1, 1), count=10, density=None, seed=None)

Distribute points randomly along a segment [point0, point1].

Parameters:

Name	Type	Description	Default
point0	(array_like, shape(D))	First endpoint of the segment.	(-1, -1, -1)
point1	(array_like, shape(D))	Second endpoint of the segment.	(1, 1, 1)
count	int	Number of points to generate (ignored if density is specified).	10
density	bfloat	If specified, determines point count via a Poisson distribution with mean = density * segment_length.	None
seed	int or Generator	Random seed.	None

Returns:

Type	Description
dict with:	'points': ndarray of shape (count, D) 'tangents': ndarray of shape (count, D)

mesh_dist

mesh_dist(mesh, selection=None, count=10, density=None, seed=None)

Distribute points on a mesh surface.

Arguments

• mesh (Mesh) : mesh object
• selection (array of bools = None) : face selection mask
• count (int = 10) : number of points to generate (overridden by density if not None)
• density (float = None) : density of points (overrides count if not None)
• seed (int = None) : random seed

Returns:

Type	Description
- dict : { 'points': (count, 3), 'normals': (count, 3) }

normal_dist

normal_dist(shape, scale, dim=3, seed=None)

Generate normally distributed points in random directions.

Points are distributed isotropically around the origin, with a normal distribution of distances (mean 0, std = scale).

Arguments

• shape (int or tuple) : shape of the returned array
• scale (int) : standard deviation
• dim (int in (1, 2, 3)) : dimension
• seed (int or Generator) : random seed

Returns:

Type	Description
- array of values in dim dimensions

pie_dist

pie_dist(radius=1, outer_radius=None, center=None, normal=None, pie_center=0.0, pie_angle=PI / 2, use_vonmises=False, count=10, density=None, seed=None)

Distribute points uniformly inside a circular sector ("pie") in the XY plane.

Parameters:

Name	Type	Description	Default
radius	float	Disk radius (or inner radius if outer_radius is specified).	1
outer_radius	float	Outer radius. If provided, defines a ring sector from radius to outer_radius.	None
center	(array_like, shape(2) or (3,))	Center of the pie if different from (0, 0, 0).	None
normal	normal	Normal if different from Z	None
pie_center	float	Central angle of the pie (radians).	0.
pie_angle	float	Total angular span of the pie (radians).	TAU
use_vonmises	bool	Whether to use a Von Mises distribution for angle sampling.	False
count	int	Number of points to generate (overridden by density if provided).	10
density	float	Point density per unit area. Overrides count if given.	None
seed	int or Generator	Random seed or NumPy Generator.	None

Returns:

Type	Description
dict	'points' : (count, D) array of points (D=2 or 3) 'tangents' : (count, 3) array of direction vectors (XY tangent) 'normals' : (count, 3) array of Z-up normals 'lengths' : (count,) array of radial distances 'angles' : (count,) array of polar angles (radians)

rect_dist

rect_dist(a=1, b=1, center=(0, 0, 0), count=10, density=None, seed=None)

Distribute points uniformly on a rectangle in the XY plane.

Parameters:

Name	Type	Description	Default
a	float	Length of the rectangle along the X axis.	1
b	float	Length of the rectangle along the Y axis.	1
center	(array_like, shape(2) or (3,))	Center of the rectangle.	(0, 0, 0)
count	int	Number of points to generate (overridden by density if specified).	10
density	float	Point density per unit area. Overrides count if provided.	None
seed	int or Generator	Random seed or generator.	None

Returns:

Type	Description
dict	Dictionary with: - 'points': (count, D) array of sampled points (D=2 or 3) - 'normals': (count, 3) array of normals (Z-up)

shake_points

shake_points(points, scale=None, seed=None)

Slightly displace points using isotropic normal noise.

Each point is moved randomly in all directions according to a normal (Gaussian) distribution centered at its original position. If scale is None, the points are returned unchanged.

Parameters:

Name	Type	Description	Default
points	(array_like, shape(..., D))	Input array of points (D is typically 2 or 3).	required
scale	bfloat or None	Standard deviation of the displacement. If None, no displacement is applied.	None
seed	int or Generator	Random seed or NumPy random Generator for reproducibility.	None

Returns:

Name	Type	Description
displaced	(ndarray, shape(..., D))	Array of displaced points.

shake_vectors

shake_vectors(vectors, scale=None, length_only=False, lengths=None, seed=None)

Slightly perturb a set of vectors.

The noise is proportional to the original vector norms. This can affect either only the magnitudes (length_only=True) or both directions and magnitudes.

Parameters:

Name	Type	Description	Default
vectors	(array_like, shape(..., D))	Input vectors to perturb.	required
scale	bfloat or None	Relative noise scale (as a fraction of the vector norm). If None, no perturbation is applied.	None
length_only	bool	If True, only the magnitudes are modified (direction remains unchanged).	False
lengths	array_like	Precomputed norms of the input vectors. Required only if length_only=False.	None
seed	int or Generator	Seed or NumPy random Generator for reproducibility.	None

Returns:

Name	Type	Description
perturbed_vectors	(ndarray, shape(..., D))	The perturbed vectors.

speed_dist

speed_dist(direction, speed, scale=None, mu=None, seed=None)

Generate velocity vectors distributed around a given direction.

This uses a Von Mises-Fisher-like sampling in 2D or 3D, centered on the input direction, with angular dispersion controlled by mu.

Parameters:

Name	Type	Description	Default
direction	(N, D) array or (D,) array	Target directions (2D or 3D), normalized or not.	required
speed	float	Base speed (magnitude of output vectors).	required
scale	float	Std deviation for speed variation (in modulus).	None
mu	float	Concentration parameter for angular dispersion (Von Mises). Higher = more concentrated.	None
seed	int or Generator	Random seed.	None

Returns:

Name	Type	Description
speeds	(N, D) array	Velocity vectors.

sphere_dist

sphere_dist(radius=1.0, scale=None, center=(0, 0, 0), count=10, density=None, seed=None)

Distribute points on the surface of a sphere.

Parameters:

Name	Type	Description	Default
radius	float	Radius of the sphere.	1.0
scale	float	Standard deviation of radial noise.	None
center	(array_like, shape(3))	Center of the sphere.	(0, 0, 0)
count	int	Number of points to generate (overridden if density is provided).	10
density	float	Surface density of points per unit area (overrides count).	None
seed	int or Generator	Random seed or NumPy Generator.	None

Returns:

Name	Type	Description
dict		{ 'points' : (count, 3) array of sampled positions, 'normals' : (count, 3) unit vectors from center to points, 'lengths' : (count,) sampled distances from center, 'thetas' : (count,) azimuthal angles ∈ [0, 2π), 'phis' : (count,) polar angles ∈ [–π/2, π/2] }

surface_dist

surface_dist(surface, count=10, density=None, seed=None)

Distribute points on a triangulated surface.

The surface is passed as a dictionary with the following keys: - 'triangles' : (n_faces, 3, 3) float array of triangle vertices - 'areas' : (n_faces,) float array of face areas - 'normals' : (n_faces, 3) float array of face normals

Parameters:

Name	Type	Description	Default
surface	dict	Surface description with triangles, areas, and normals.	required
count	int	Number of points to generate (overridden by density).	10
density	float	Point density per unit area (overrides count).	None
seed	int	Random seed.	None

Returns:

Name	Type	Description
dict		{ 'points' : (count, 3) sampled points on the surface, 'normals' : (count, 3) normals at each sampled point }

triangle_dist

triangle_dist(corners, count, rng=None)

Distribute points uniformly on a triangle.

Parameters:

Name	Type	Description	Default
corners	(array_like, shape(3, 3))	Coordinates of the three triangle corners.	required
count	int	Number of points to generate.	required
rng	Generator	Numpy random generator. Created if not provided.	None

Returns:

Name	Type	Description
points	(ndarray, shape(count, 3))	Points uniformly distributed on the triangle.