Point Trail

Point Trail is deliberately discrete and stable, like professional trail systems. It does not resample the past every frame; instead it keeps a per-node ring buffer of committed echoes (up to 600 stored snapshots):

1. Each frame the node reads the live cloud (the "head") and tracks its centroid, accumulating the total path length the centroid has travelled.
2. A new echo — a full snapshot of the head cloud — is committed only when the trail's own clock says so:

• Time mode: at least Delay seconds since the last commit.
• Distance mode: the centroid has travelled at least Spacing units since the last commit — giving evenly spaced echoes regardless of how fast the source moves.
• The very first non-empty frame always commits, so the trail starts immediately.

1. The output is assembled newest → oldest: echo 0 is the most recent commit, echo 1 the one before it, and so on, up to Count echoes. Skip shifts the window back by N commits, cutting the newest echoes off and detaching the visible trail from the live head. If Taper is set, each older echo is scaled toward its own centroid by s = 1 − Taper × (i / (Count − 1)), producing a comet-style shrink with age.

Between commits the output is byte-for-byte identical. This is the node's defining property: consumers like Plexus see the exact same point array frame after frame, so their connection orderings never reshuffle — no flicker, no crawling lines. At a commit, exactly one new echo enters at the head and the oldest visible one falls off the tail.

Other lifecycle details:

• The trail grows in: until enough commits exist, fewer than Count echoes are emitted.
• If the input cloud becomes empty (source disabled, tracking lost), the buffer stops updating but keeps emitting the frozen trail — history is not thrown away.
• The buffer is volatile per-node state: it resets when the project reloads, then refills at its own pace.
• Safety caps: at most 500 echoes, 600 stored commits, and 50 000 output points (echo count × points per echo — a 200-point shape with Count 50 already outputs 10 000 points).

• Points (Structure) — the live head cloud. Works with a single moving point (Mouse position, one landmark) just as well as a full shape — a lone {x, y} becomes a one-point cloud and the trail becomes its path.
• Count (Int, default 10, clamped 1…500) — how many echoes are emitted. With a one-point head this is the number of dots in the path; with an N-point shape the output is up to Count × N points.
• Mode (Int, default 0) — commit trigger: Time (0) commits every Delay seconds, giving echoes evenly spaced in time (fast motion stretches the trail, slow motion bunches it); Distance (1) commits every Spacing units of centroid travel, giving echoes evenly spaced along the path regardless of speed — and no new echoes at all while the source is still.
• Delay (Float, default 0.1, floor 0.001) — seconds between commits in Time mode (hidden in Distance mode). Total trail duration ≈ Count × Delay: 10 echoes at 0.1 s is a one-second memory.
• Spacing (Float, default 0.1, floor 0.0001) — centroid travel distance (Grafit units) between commits in Distance mode (hidden in Time mode). Total trail length ≈ Count × Spacing along the motion path.
• Skip (Int, default 0, minimum 0) — cuts N echoes from the head end. The visible trail then starts N commits behind the live cloud — a detached ghost that follows at a delay of Skip × Delay seconds (or Skip × Spacing units). Note the stored history must be deep enough: Count + Skip ≤ 600.
• Taper (Float, default 0, clamped 0…1) — shrinks older echoes toward their own centroid. 0 keeps every echo full size; 1 collapses the oldest visible echo to a point. Each echo scales about its own center, so a tapered shape-trail reads as the shape "evaporating" in place rather than sliding toward a point.

Outputs: Points (all echoes concatenated newest → oldest) and Count (total emitted points — useful for keeping an eye on the Count × cloud-size product).

• Cursor comet — Mouse → Point Trail (Count 30, Time mode, Delay 0.03, Taper 0.8) → Points Visualize (additive dots) → Canvas. A classic glowing comet following the pointer.
• Motion ribbon — Mouse → Point Trail (Distance mode, Spacing 0.05) → Point Density (Smooth, Amount 2) → Plexus → Canvas. Distance mode lays evenly spaced beads along the gesture; Smooth and Plexus turn them into a continuous ribbon of light.
• Onion-skin dancer — Vision Tracking → Landmarks to Points → Point Trail (Count 6, Delay 0.15, Taper 0.4) → Plexus → Canvas. Ghost skeletons trail the performer, each older pose smaller and fainter in structure.
• Shape echo choreography — Geometry to Points (Triangle, Edges) → Point Transform (Position from LFO) → Point Trail (Count 12, Distance mode) → Points Visualize → Canvas. The gliding triangle prints a stroboscopic path of copies across the screen.
• Detached follower — Geometry to Points (Circle) → Point Transform (Position from Mouse) → Point Trail (Count 1, Skip 8) → Plexus → Canvas. With Count 1 and Skip, the output is a single ghost shape following the live one at a fixed delay — a follower without any visible trail.
• Beat-frozen afterimages — Audio Beat Detection → (drive motion upstream) → Point Trail (Time mode, Delay tuned near the beat interval) → Points Visualize → Canvas. Echoes land in rhythm with the track, snapshotting the cloud once per beat.

• Choose the mode by what should control spacing: Time for rhythm-driven looks and speed-sensitive stretching, Distance for calligraphic, even-spaced paths (and note a stationary source stops producing new echoes in Distance mode — the trail simply waits).
• Output size multiplies fast: Count × points-per-echo, hard-capped at 50 000. For long trails of a dense shape, thin the head first with Point Density (negative Amount) rather than losing the tail to the cap.
• The output is intentionally frozen between commits — don't add Point Animation before this node expecting per-frame wiggle in the echoes (each echo snapshots whatever the head looked like at commit time). Put Point Animation after Point Trail to animate the whole trail continuously.
• Taper scales each echo around its own centroid, so single-point trails are unaffected by Taper (a point has no size) — use Points Visualize's Size Mode / variance options, or a Gradient with Plexus Color Mode, to fade a dot trail instead.
• Distance tracking uses the cloud's centroid, so a shape that spins in place without translating won't commit in Distance mode; switch to Time mode for purely rotational motion.
• The echo buffer survives input dropouts (frozen trail) but not project reloads — after loading, expect the trail to grow back in over Count commits.