Hobbs Spirograph (Tyler Hobbs — Petal Loops / Elektroanima)

Math essence

Each point i has its own angle theta_i that is advanced by dtheta each step. The whole ring's anchor also rotates by dtheta around (cx, cy). The pen position of point i at step t is (cx + r1*cos(dtheta*t) + r2*cos(theta_i + dtheta*t), cy + r1*sin(dtheta*t) + r2*sin(theta_i + dtheta*t)). A closed polyline is drawn through the M points, then the polyline is repeated at the next step. After N steps the canvas is the union of N rotated copies of the M-gon — a continuous ribbon whose outline is a hypotrochoid envelope.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/hobbs_cherniak_penne_deep/HobbsSpirograph/reference.py

"""HobbsSpirograph — Tyler Hobbs rotating-circular-arc trails (hypotrochoids).

A composition in the spirit of Tyler Hobbs's
*Elektroanima* / *Petal Loops* / *Cranes* family of works
(2019-2020), where a small rotating system of points traces
hypotrochoid curves across the canvas as the whole system
spins.  Hobbs calls this "looping taken to an excessive level"
(he posted about Petal Loops on Facebook as a prime example).

The kernel we implement:

    1. Place a small ring of M points (default 8) on a circle of
       radius r1 around an anchor (cx, cy).  Each point also
       carries its own local orbital radius r2 (so the trace is a
       hypotrochoid, not a plain circle).
    2. Each step, advance every point's orbital angle by dtheta
       (the small rotation), AND advance the whole ring's anchor
       angle by Dtheta (the large rotation).  This is the classic
       spirograph / hypotrochoid update.
    3. Draw a thin coloured polyline through the M points every
       K steps.  The polyline's vertices rotate rigidly, so the
       closed shape morphs each frame.
    4. After N iterations, the canvas is a beautiful rotating
       hypotrochoid ribbon — a single connected curve drawn many
       times in slightly different positions.

A real spirograph produces a *closed* curve when the ratio
r1 / r2 is rational.  When the ratio is irrational, the curve
is dense in an annular region.  We use the rational case (a
small integer ratio) so the trace closes and reads as a
rotating ribbon; the apparent rotation comes from the slow
anchor spin.

Reference:
- https://www.tylerxhobbs.com/works/petal-loops
- https://www.tylerxhobbs.com/works/elektroanima
- Spirograph / hypotrochoid math: a hypotrochoid is the
  parametric curve
    x(t) = (R - r) * cos(t) + d * cos((R - r)/r * t)
    y(t) = (R - r) * sin(t) - d * sin((R - r)/r * t)
  where R is the radius of the outer fixed circle, r is the
  radius of the inner rolling circle, d is the distance of the
  pen from the centre of the rolling circle.
"""
from __future__ import annotations

from typing import ClassVar

import numpy as np


# ---------------------------------------------------------------------------
class HobbsSpirograph:
    """Hobbs-style rotating-circular-arc trails (hypotrochoid family).

    Parameters
    ----------
    dim : int
        Square canvas side length (px).
    num_points : int