PyPI Docs GitHub Open in Colab

blue-sampler

Generate large stealthy point patterns (i.e. blue noise) on the unit torus $[0, 1)^D$. 📐

Stealthy point patterns exhibit vanishing density fluctuations at low frequencies, making them particularly suited for Monte Carlo integration, image stippling, and any application requiring well-distributed, low-discrepancy points.

📦 Installation

pip install blue-sampler

Quick Start

import blue_sampler as blue

# Generate 10,000 2D blue-noise points
x = blue.sample_points(N=10_000, D=2)
blue.plot(x) 

# Structure factor
blue.plot_structure_factor(x) 

# Image stippling
x = blue.im2points("plots/zebra.jpg")

🖼️ Examples

Uniform sampling, Gaussian Blue Noise (3k points)

Example

Image stippling with points (20k points)

Example 1

📋 Available Samplers

Main sampling methods

x = blue.sample_points(N, D, method="rgbn") #(N, D)
Method Description
gaussian original Gaussian-Blue-Noise sampler (high quality, slow), A. G. M. Ahmed, J. Ren, and P. Wonka.
rgbn Recursive Gaussian-Blue-Noise (speed-up GBN with robust approximations)
nufft/nufft+ Non-Uniform FFT (speed-up spectral methods with fast fourier transform)
cstit STIT inspired clustering (clusters replace complex polygon geometry)
latjit fast and simple lattice jittering

All presented samplers, having linear complexity in the number of points, are thus intended to scale up to million points (at least in 2/3D) beyond the minute (GPU) or 20 minutes (CPU). Were their will be a difference will be in supported dimensions (or cardinality constrains on N), spectral quality, speed, gpu support, target support: The recommanded default is:

  • dimension D = 1/2/3: nufft
  • dimension D = 4/5: rgbn or gaussian (depending on N + gpu availability)
  • dimension 6 or more: gaussian If sampling runtime is realy a problem, then cstit is recommended (much faster, but not so good blue noise) . QUality can be checked with the structure factor.

Alternative Samplers

Sobol sequence 📏

x = blue.sobol(N, D) #(N, D)

Low-discrepancy quasi-random sequence.

STIT Tessellations (2D only) 🧩

# Raw STIT tessellation (quadrilaterals)
ts = blue.sample_tessels(N) #(N, 4, D=2)
blue.plot_tessels(ts) 

# Convert to point set
x = blue.tessel2points(ts) #(N, m, D=2)

Pinwheel Tilings (2D only) 𖣘

# Base pinwheel triangle
pw0 = blue.pinwheel_base()  #(3, D=2)

# Triangulation level 4
pw4 = blue.pinwheel_transform(pw0, depth=4) #(4*5**depth, 3, D=2)
blue.plot_polygons(pw4) 

#===============================
# Convert Pinwheel to point set:
#===============================
#sample points from the BASE pinwheel
x0 = blue.tessel2points(pw0) #(m, D=2)
#then replicate the sample on the full triangulation,
#in a fractal way
x4 = blue.pinwheel_transform(x0, depth = 4) #(4*5**depth, m, D=2)

Note on GPU support: Most methods can run on CPU only, but they can benefit from GPU acceleration. To install the optional GPU dependencies for a CUDA 12 environment:

pip install blue-sampler[gpu]

If the CUDA 12 installation fails, you may need to install jax, cupy, and cufinufft manually. Once installed, you can check that GPU support is correctly configured by running:

import blue_sampler
blue_sampler.check_gpu()

Note on adaptative sampling: The sampling methods implemented here support adaptive sampling from a target distribution. This feature is still experimental beyond 2d distributions

Note on structure factor: The estimation of sf assumes that the points domain is the unit hypercube and uses the standard scattering intensity.

Note on tessel2points method: The conversion from geometric objects (polygons or clusters) to point sets is performed using a standard moment matching technique. cluster2points(x, p = 3) and tessel2points(x, p = 3) will sample m points per batch that mimic the statistical {0, 1, ... p-1} moments of the batch.

Supported Dimensions

Dimension Status
2–3D Fast ⚡
4–5D Supported
≥6D Experimental 🧪

Documentation & Links 🔗

📚 References

The algorithms and mathematical tools implemented in blue-sampler are based or inspired from the following works.

  • Gaussian Blue Noise (repulsive interaction kernel)
    A. G. M. Ahmed, J. Ren, and P. Wonka.
    Gaussian Blue Noise.
    ACM Transactions on Graphics (SIGGRAPH Asia), 41(6), 2022.
    DOI: 10.1145/3550454.3555519

  • FReSCo
    A. Shih, M. Casiulis, and S. Martiniani.
    Fast Generation of Spectrally-Shaped Disorder.
    Physical Review E, 110(3):034122, 2024.
    DOI: 10.1103/PhysRevE.110.034122

  • STIT tessellations and moment matching
    L. Lotz and M. A. Klatt.
    Persistence of asymptotic variance under transport: from hyperfluctuation to stealthy hyperuniformity.
    arXiv:2605.22803, 2026.

  • Aperiodic tiling for hyuperuniformity (here pinwheel)
    A. Gabrielli, B. Jancovici, M. Joyce, J. L. Lebowitz, L. Pietronero, and F. Sylos Labini.
    Generation of Primordial Cosmological Perturbations from Statistical Mechanical Models.
    Physical Review D, 67(4):043506, 2003.

  • SquareNet (v1.3.11). 2026.
    Grid data structure for point clouds, codeveloped with RGBN
    for efficient neighbor query and fourier trnasform in Python.

  • Sobol sequences
    Wrapped from scipy.stats.qmc.Sobol (SciPy).

  • Nufft: The non uniform fast fourier transform (nufft) is performed using the finufft library [FIN] A parallel non-uniform fast Fourier transform library based on an “exponential of semicircle”
    kernel. A. H. Barnett, J. F. Magland, and L. af Klinteberg. SIAM J. Sci. Comput. 41(5), C479-C504 (2019).

Positioning and scope

One can find extensive Blue-noise and hyperuniform sampling methods in the literature, all involving different trade-offs between spectral quality, computational cost, dimensionality, hardware requirements, implementation complexity, and support for adaptive sampling. To briefly cite some of them: Perturbed lattices are simple and fast; Poisson-disk is a mature and popular tool; Void-and-Cluster masks offer instant execution but are restricted to regular grids; Relaxation methods (such as Lloyd or CCVT) are classic but slow to converge and prone to structural artifacts; Optimal Transport (BNOT) provides natural adaptive sampling but is computationally heavy; Gaussian blue noise (GBN) achieves ultra-high spatial quality but has quadratic complexity; and Fast reciprocal space Correlator (FReSCo) combines ultra-high quality with near-linear complexity, though it requires installing heavy external dependencies or familiarity with docker containers.

blue-sampler is not intended as a universal replacement for these methods. It is a lightweight Python framework for experiments on blue noise and hyperuniformity, targeting simple installation (native Python code) and device flexibility (CPU/GPU), high spectral quality (achieving the commonly accepted "stealthy" criterions $S(k) \lesssim 10^{-3} - 10^{-4}$), adaptive sampling, and support for 3D and higher dimensions.

License

MIT

Project links

Data verified by PyPI on Sep 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for adecacqu from gravatar.com adecacqu

License

MIT

Requires

Python >=3.9

Provides Extra

gpu

Tags

GBN NuFFT Pinwheel STIT blue noise point process sampling stealthy stipling structure factor

Report project as malware

Metadata

Project links

Data verified by PyPI on Sep 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for adecacqu from gravatar.com adecacqu

License

MIT

Requires

Python >=3.9

Provides Extra

gpu

Tags

GBN NuFFT Pinwheel STIT blue noise point process sampling stealthy stipling structure factor

Report project as malware

Release files for blue-sampler 2.1.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blue-sampler 2.1.7
File Size Uploaded
blue_sampler-2.1.7.tar.gz 50.1 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for blue-sampler 2.1.7
File Interpreter ABI Platform
blue_sampler-2.1.7-py3-none-any.whl 60.2 kB Python 3 none any Details

Total release size: 110.3 kB

Release files / blue_sampler-2.1.7.tar.gz

Download URL blue_sampler-2.1.7.tar.gz
Size 50.1 kB
Tags Source
SHA-256 checksum
How to use checksums 		3b2bc53e8fb3218fa243e9bdda06b4bfe3952bdd067f84ac801538a0751efb3b
BLAKE2b-256 checksum
How to use checksums 		0ab4e8edb9cf73afbc9089da67382108babed77c18c8aa438fea6b92f3e75e7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / blue_sampler-2.1.7-py3-none-any.whl

Download URL blue_sampler-2.1.7-py3-none-any.whl
Size 60.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums 		2a4fa2677b8d109679ef42096588fb972149ff92ad00c79bbfbc78ca9e0269f2
BLAKE2b-256 checksum
How to use checksums 		a4c5e520a42a9110f98feb06bf96dab1659c3b934d6920760cdc84d0d4a56d72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.14.4

Release history Release notifications | RSS feed

3.1.3

2 release files

3.1.2

2 release files

3.1.1

2 release files

3.1.0

2 release files

3.0.5

2 release files

3.0.4

2 release files

3.0.3

2 release files

3.0.2

2 release files

3.0.1

2 release files

3.0.0

2 release files

2.1.8

2 release files

This release

2.1.7 This release

2 release files

2.1.6

2 release files

2.1.5

2 release files

2.1.4

2 release files

2.1.3

2 release files

2.1.2

2 release files

2.1.1

2 release files

2.1.0

2 release files

2.0.0

2 release files

1.3.16

2 release files

1.3.15

2 release files

1.3.14

2 release files

1.3.13

2 release files

1.3.12

2 release files

1.3.11

2 release files

1.3.10

2 release files

1.3.9

2 release files

1.3.8

2 release files

1.3.7

2 release files

1.3.6

2 release files

1.3.5

2 release files

1.3.4

2 release files

1.3.3

2 release files

1.3.2

2 release files

1.3.1

2 release files

1.3.0

2 release files

1.2.7

2 release files

1.2.6

2 release files

1.2.5

2 release files

1.2.4

2 release files

1.2.3

2 release files

1.2.2

2 release files

1.2.1

2 release files

1.2.0

2 release files

1.1.0

2 release files

1.0.0

2 release files

0.1.18

2 release files

0.1.17

2 release files

0.1.16

2 release files

0.1.15

2 release files

0.1.14

2 release files

0.1.13

2 release files

0.1.12

2 release files

0.1.11

2 release files

0.1.10

2 release files

0.1.9

2 release files

0.1.8

2 release files

0.1.7

2 release files

0.1.6

2 release files

0.1.5

2 release files

0.1.4

2 release files

0.1.3

2 release files

0.1.2

2 release files

0.1.1

2 release files

0.1.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page