Documentation

blue-sampler

Generate large stealthy point patterns on the unit torus [0, 1)^D. Stealthy point patterns have vanishing density fluctuations at low (“blue”) frequencies, making them useful for Monte Carlo integration, image stippling, and any application that needs well-spread, low-discrepancy points. The main blue noise sampler (RGBN) implemented here have linear complexity in the number of points and the dimension, and run in under 15 minutes for 1 million 2D points.

📦 Installation

pip install blue_sampler

🚀 Quick start

import blue_sampler as blue

# 10 000 points in 2D
x = blue.sample_points(N=10_000, D=2)
blue.plot(x, auto_zoom=True)

# structure factor visualization
blue.plot_structure_factor(x)

# higher dimensions
x = blue.sample_points(N=2_000, D=5)

# image stippling
x = blue.im2points(image="zebra.jpg")

🖼️ Example

Zebra points

📊 Supported dimensions

Dimension	Notes
2D	Fast, recommended
3D	~2× slower
4–5D	Works, more iterations needed
≥6D	Experimental (small N recommended)

📚 Links

🌐 Project website: https://for-a-few-dpps-more.github.io/rgbn/
📦 PyPI: https://pypi.org/project/blue-sampler/
🐙 GitHub: https://github.com/For-a-few-DPPs-more/rgbn
📖 Documentation: https://blue-sampler.readthedocs.io

📄 License

MIT

Main API

Stippling

blue_sampler.im2points([image, N])

simple wrapper for image stippling

Sampling

`blue_sampler.sample_points`([N, D, ...])	Generate N stealthy (blue-noise) points in [0, 1)^D.
`blue_sampler.sample_tessels`([N, D, targets, ...])	Recursively split the unit square into N random quadrilaterals.
`blue_sampler.sample_clusters`([N, D, ...])	Recursively partition a point set into N balanced clusters.
`blue_sampler.tile`(x, repeat[, flatoutput])	Tile points on the unit torus to cover [0, 1)^D periodically.
`blue_sampler.from_geometry`(geometry, gtype)	Convert tessels or clusters into low-discrepancy point set.

Analysis

blue_sampler.structure_factor(points[, ...])

Estimate the radial structure factor S(k) via scattering intensity.

Visualization

`blue_sampler.plot`(points[, auto_zoom, ...])	Scatter plot of a 2-D or 3-D point set.
`blue_sampler.plot_structure_factor`(points[, ...])	Log-log plot of the radial structure factor S(k).
`blue_sampler.plot_tessels`(tessels[, return_fig])	Display a tessellation across up to 12 recursion steps.
`blue_sampler.plot_clusters`(clusters[, ...])	Display a cluster partition across up to 12 recursion steps.

Datasets

blue_sampler.generate_dataset([size, ...])