Particle Wave

An image-to-particle-cloud pipeline with a real-time physics renderer. The same engine draws the corona on this site's home page.

Placeholder Particle Wave hero capture /media/projects/particle-wave/hero.webp

Live capture of the engine responding to the cursor.

Particle Wave · live demo running

0 pts · 0 fps

Starting engine…

Compare with original

Source

Spin0.00 rad/s

Spin Max Degree360 °

Drift8 px

Mouse strength60

Cursor radius120 px

Burst strength350

Burst radius2.40 × cursor

Wave strength140

Wave speed360 px/s

Meteor Tail Length0 steps

Trail Thickness1.00

Trail Fade Speed0.65

Spring2.60

Damping4.20

Particle size2.00 px

Cursor

Particle Shape

Left Click Action

Right Click Action

Color Mode

Spin Axis

Move the cursor to push the field, then click to fire the action bound to that button. A wave is a travelling front. It leaves the click point, kicks each particle once on the way past, and keeps going, so what you see is a ring crossing the cloud. A burst does not travel: it is a standing radial field that holds everything within its radius for as long as the button is down, hardest at the centre, so what you see is the cloud opening or gathering and then relaxing on release. An uploaded image goes to the ParticleWave service, which extracts the point cloud in Python and sends it back. If that service is unreachable, the image is traced in this tab instead, at lower quality. Nothing is stored either way. The cloud comes back in the response and the upload is discarded.

Placeholder write-up. Replace this body with the real account; the frontmatter above already carries the fields the layout renders.

The problem

A still image on a landing page is inert. A canvas of particles that responds to the cursor is not, but hand-authoring one per image does not scale.

The approach

Split the work in two. A Python pipeline turns any image into a sampled point cloud: grayscale, multi-scale edge extraction, then Poisson-disc sampling so points land where the detail is. The runtime knows nothing about images. It loads a cloud, spawns particles at rest positions, and simulates.

Because the two halves only share a serialisation contract, either can be replaced. The demo below proves it in both directions. Uploads go to the Python service and come back as a cloud the renderer accepts unchanged, and when that service is down a much simpler JavaScript tracer stands in without the renderer noticing. The corona on this site’s home page is not traced from an image at all. It is generated parametrically and loaded by the same runtime.

What I would do differently

To be written.

Run it here

The published package, installed from PyPI into this tab and executed by a real CPython build. Nothing runs on a server, and the first run downloads the interpreter.

Environment

Not started

The image-to-point-cloud extractor from PyPI, running in the tab. The same package the site’s demo backend imports, at the same version.

download: ~32 MB extra on first run
packages: numpy · scipy · pillow · pyyaml · typer · click · rich · particle-wave

Source

import numpy as np
from PIL import Image
from particle_wave.tool.pipeline import Pipeline, PipelineConfig

# A synthetic target: concentric rings, so there is real edge structure
# to find rather than noise.
size = 320
y, x = np.mgrid[0:size, 0:size]
radius = np.hypot(x - size / 2, y - size / 2)
rings = (np.sin(radius / 6.0) * 0.5 + 0.5) * 255
image = Image.fromarray(rings.astype(np.uint8)).convert("RGB")

cfg = PipelineConfig()
cfg.sampling.target_points = 4000
cfg.preprocess.max_resolution = 320

cloud = Pipeline(cfg).build(image, source_name="rings.png")

for key in sorted(cloud["meta"]):
    print(f"meta.{key}: {cloud['meta'][key]}")

# The document stores points as one flat array with a stride, not as a list of
# objects. That is the whole reason a .pwcloud is small enough to ship: 4,000
# points as JSON objects is roughly six times the bytes.
fields, stride, data = cloud["fields"], cloud["stride"], cloud["data"]
print(f"\nencoding: {cloud['encoding']}, fields {fields}, stride {stride}")
print(f"{len(data):,} values = {len(data) // stride:,} points")

for i in range(3):
    row = data[i * stride:(i + 1) * stride]
    print("  ", dict(zip(fields, row)))

preview = cloud["preview"]
print(f"\npreview: {preview['mime']} {preview['width']}x{preview['height']}, "
      f"{len(preview['data']):,} base64 chars")

import numpy as np
from PIL import Image
from particle_wave.tool.pipeline import Pipeline, PipelineConfig

# A synthetic target: concentric rings, so there is real edge structure
# to find rather than noise.
size = 320
y, x = np.mgrid[0:size, 0:size]
radius = np.hypot(x - size / 2, y - size / 2)
rings = (np.sin(radius / 6.0) * 0.5 + 0.5) * 255
image = Image.fromarray(rings.astype(np.uint8)).convert("RGB")

cfg = PipelineConfig()
cfg.sampling.target_points = 4000
cfg.preprocess.max_resolution = 320

cloud = Pipeline(cfg).build(image, source_name="rings.png")

for key in sorted(cloud["meta"]):
    print(f"meta.{key}: {cloud['meta'][key]}")

# The document stores points as one flat array with a stride, not as a list of
# objects. That is the whole reason a .pwcloud is small enough to ship: 4,000
# points as JSON objects is roughly six times the bytes.
fields, stride, data = cloud["fields"], cloud["stride"], cloud["data"]
print(f"\nencoding: {cloud['encoding']}, fields {fields}, stride {stride}")
print(f"{len(data):,} values = {len(data) // stride:,} points")

for i in range(3):
    row = data[i * stride:(i + 1) * stride]
    print("  ", dict(zip(fields, row)))

preview = cloud["preview"]
print(f"\npreview: {preview['mime']} {preview['width']}x{preview['height']}, "
      f"{len(preview['data']):,} base64 chars")

Builds an image in memory, runs the full four-stage pipeline, and prints what came out.

stdin

Ctrl Enter to run · Tab indents the selection

Output

follow

Nothing yet. Run the sample above.

Gallery

Placeholder Image → point cloud pipeline /media/projects/particle-wave/01.webp

Edge extraction and density-aware sampling turn a source image into a cloud.
Placeholder Wave propagation /media/projects/particle-wave/02.webp

A click spawns a wave packet that propagates outward and decays.