Verlet Particle-Spring Network

Math essence

Verlet: x_{t+1} = 2*x_t - x_{t-1} + a*dt^2. Constraint: for each edge (i, j), diff = p_j - p_i, d = |diff|, delta = rest - d, offset = 0.5 * delta * spring_k * diff/d. Move p_i by +offset, p_j by -offset unless one endpoint is anchored. Repeat N rounds per step.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/toxi_openframeworks/ParticleSpring2D/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


class ParticleSpring2D:
    """Verlet-integrated particle-spring network with 4 corner anchors.

    A set of free particles is connected to its k-nearest neighbours
    by Hooke's-law springs of rest length ``spacing``. Four corner
    particles are pinned (anchored) so the network behaves like a
    deformable mesh. Per step:

        1. Verlet integrate  (x_new = 2*x - x_prev + a*dt^2)
        2. N rounds of constraint relaxation  (Jakobsen 2001)

    This is the canonical mass-spring formulation used in the oF
    community — `ofxMSAPhysics` (Memo Akten), `ofxBox2d`, and
    Karsten Schmidt's `toxiclibs.physics` all rely on it. The version
    here is a pure-numpy port of `toxiclibs.physics.VerletPhysics`
    with explicit corners.
    """

    family: ClassVar[str] = "toxi_openframeworks"
    sketch: ClassVar[str] = "particlespring2d"

    def __init__(
        self,
        dim: int = 500,
        num_particles: int = 80,
        spacing: float = 40.0,
        spring_k: float = 0.05,
        damping: float = 0.985,
        gravity: float = 60.0,
        constraint_iterations: int = 6,
        anchor_corners: bool = True,
        anchor_bottom: bool = False,
        anchor_top: bool = False,
        trail_decay: float = 1.0,
        node_radius: int = 2,
        line_alpha: float = 0.85,
        bg_color: tuple[int, int, int] = (245, 240, 230),
        link_color: tuple[int, int, int] = (60, 70, 90),
        node_color: tuple[int, int, int] = (200, 70, 60),
        seed: int | None = None,
    ) -> None:
        self.dim = dim
        self.num_particles = num_particles
        self.spacing = spacing
        self.spring_k = spring_k
        self.damping = damping
        self.gravity = gravity
        self.constraint_iterations = constraint_iterations
        self._anchor_corners = anchor_corners
        self._anchor_bottom = anchor_bottom
        self._anchor_top = anchor_top
        self.trail_decay = trail_decay
        self.node_radius = node_radius