feat: support for 'image' shape in spawner (#16)

Author: cazala

README.md

@@ -11,7 +11,7 @@ A high-performance particle physics simulation system with interactive playgroun
 - **Playground Sessions**: Save/load/share sessions (module settings, oscillators, and optional particles/joints)
 - **Real-time Oscillators**: Animate any module parameter with configurable frequency and bounds
 - **Interactive Playground**: React-based interface with undo/redo, hotkeys, and live parameter adjustment
-- **Text Spawner**: Spawn particles from text in the core spawner and INIT UI
+- **Text/Image Spawner**: Spawn particles from text or images in the core spawner and INIT UI
 
 ## Documentation
 

docs/playground-user-guide.md

@@ -158,6 +158,7 @@ The INIT panel controls how particles are spawned when using the Restart button
 - **Donut**: Particles arranged in a ring (inner + outer radius)
 - **Square**: Particles arranged in a square
 - **Text**: Particles spawn to form the typed text
+- **Image**: Particles spawn to form an image from a URL or upload
 
 ### Particle Properties
 
@@ -182,6 +183,7 @@ The INIT panel controls how particles are spawned when using the Restart button
 - **Square size**: Square Size slider (Square)
 - **Square corner radius**: Corner Radius slider (Square)
 - **Text fields**: Text, Text Size, and Font (Sans Serif / Serif / Monospace)
+- **Image fields**: Image URL or upload (URL disabled when upload is used), plus Image Size (max dimension). Transparent pixels are ignored and particle colors come from the image.
 
 ## Physics Modules
 

docs/user-guide.md

@@ -158,7 +158,7 @@ Notes
 
 ### Spawner utility
 
-The `Spawner` helper generates `IParticle[]` for common shapes, including text.
+The `Spawner` helper generates `IParticle[]` for common shapes, including text and images.
 
 ```ts
 import { Spawner } from "@cazala/party";
@@ -187,6 +187,28 @@ Notes:
 - `position` + `align` define the anchor point for the text bounds.
 - Supported fonts in the playground UI: `sans-serif`, `serif`, `monospace`.
 
+Image example:
+
+```ts
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+const particles = spawner.initParticles({
+  count: 12000,
+  shape: "image",
+  center: { x: 0, y: 0 },
+  position: { x: 0, y: 0 },
+  align: { horizontal: "center", vertical: "center" },
+  imageData,
+  imageSize: 400, // scales to this max dimension
+  size: 3,
+  mass: 1,
+});
+```
+
+Notes:
+
+- `imageData` is required and must be provided synchronously.
+- Fully transparent pixels are ignored; particle colors come from the image pixels.
+
 #### Engine methods and lifecycles
 
 - `initialize()`

packages/core/README.md

@@ -12,7 +12,7 @@ A high-performance TypeScript particle physics engine with dual runtime support
 - **Advanced Rendering**: Trails, particle instancing, line rendering with multiple color modes
 - **Export/Import Presets**: Export/import module settings (inputs + enabled state)
 - **Cross-platform**: Works in all modern browsers with automatic feature detection
-- **Spawner Utility**: Generate particle shapes, including text
+- **Spawner Utility**: Generate particle shapes, including text and images
 
 ## Installation
 
@@ -192,7 +192,7 @@ engine.unpinAll();
 
 ### Spawner
 
-Generate particle arrays from common shapes (including text) using `Spawner`:
+Generate particle arrays from common shapes (including text and images) using `Spawner`:
 
 ```typescript
 import { Spawner } from "@cazala/party";
@@ -220,6 +220,28 @@ Notes:
 - `size` controls particle radius; `textSize` is the font size used to rasterize text.
 - Playground font options: `sans-serif`, `serif`, `monospace`.
 
+Image example:
+
+```typescript
+const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+const imageParticles = spawner.initParticles({
+  count: 12000,
+  shape: "image",
+  center: { x: 0, y: 0 },
+  position: { x: 0, y: 0 },
+  align: { horizontal: "center", vertical: "center" },
+  imageData,
+  imageSize: 400, // scales to this max dimension
+  size: 3,
+  mass: 1,
+});
+```
+
+Notes:
+
+- `imageData` must be provided synchronously (no URL fetching inside the spawner).
+- Fully transparent pixels are skipped; particle colors come from image pixels.
+
 ### Modules
 
 Modules are pluggable components that contribute to simulation or rendering:

packages/core/src/spawner.ts

@@ -28,7 +28,8 @@ export type SpawnShape =
   | "circle"
   | "donut"
   | "square"
-  | "text";
+  | "text"
+  | "image";
 
 export type TextHorizontalAlign = "left" | "center" | "right";
 export type TextVerticalAlign = "top" | "center" | "bottom";
@@ -56,6 +57,9 @@ export interface SpawnOptions {
   textSize?: number;
   position?: { x: number; y: number };
   align?: { horizontal: TextHorizontalAlign; vertical: TextVerticalAlign };
+  // image
+  imageData?: ImageData | null;
+  imageSize?: number;
 }
 
 function calculateVelocity(
@@ -125,6 +129,8 @@ export class Spawner {
       textSize = 64,
       position,
       align,
+      imageData,
+      imageSize,
     } = options;
 
     const particles: IParticle[] = [];
@@ -258,6 +264,119 @@ export class Spawner {
       return particles;
     }
 
+    if (shape === "image") {
+      if (!imageData) return particles;
+      const width = Math.floor(imageData.width);
+      const height = Math.floor(imageData.height);
+      if (
+        !Number.isFinite(width) ||
+        !Number.isFinite(height) ||
+        width <= 0 ||
+        height <= 0
+      )
+        return particles;
+
+      const data = imageData.data;
+      const sampleStepTarget = Math.max(1, Math.round(size));
+      const targetSize =
+        typeof imageSize === "number" && Number.isFinite(imageSize) && imageSize > 0
+          ? imageSize
+          : Math.max(width, height);
+      const scale = Math.max(0.0001, targetSize / Math.max(width, height));
+      const sampleStepSource = Math.max(1, Math.round(sampleStepTarget / scale));
+      const points: {
+        x: number;
+        y: number;
+        color: { r: number; g: number; b: number; a: number };
+      }[] = [];
+
+      for (let y = 0; y < height; y += sampleStepSource) {
+        for (let x = 0; x < width; x += sampleStepSource) {
+          const idx = (y * width + x) * 4;
+          const alpha = data[idx + 3];
+          if (alpha === 0) continue;
+          points.push({
+            x: x * scale,
+            y: y * scale,
+            color: {
+              r: data[idx] / 255,
+              g: data[idx + 1] / 255,
+              b: data[idx + 2] / 255,
+              a: alpha / 255,
+            },
+          });
+        }
+      }
+
+      const maxCount = Math.max(0, Math.floor(count));
+      if (maxCount <= 0 || points.length === 0) return particles;
+
+      const imagePosition = position ?? center;
+      const horizontal = align?.horizontal ?? "center";
+      const vertical = align?.vertical ?? "center";
+      const scaledWidth = width * scale;
+      const scaledHeight = height * scale;
+      const originX =
+        horizontal === "left"
+          ? imagePosition.x
+          : horizontal === "right"
+          ? imagePosition.x - scaledWidth
+          : imagePosition.x - scaledWidth / 2;
+      const originY =
+        vertical === "top"
+          ? imagePosition.y
+          : vertical === "bottom"
+          ? imagePosition.y - scaledHeight
+          : imagePosition.y - scaledHeight / 2;
+
+      const baseCount = Math.min(maxCount, points.length);
+      const stride = points.length / baseCount;
+      for (let i = 0; i < baseCount; i++) {
+        const idx = Math.floor(i * stride);
+        const point = points[idx];
+        if (!point) continue;
+        const x = originX + point.x;
+        const y = originY + point.y;
+        const { vx, vy } = calculateVelocity(
+          { x, y },
+          imagePosition,
+          velocity
+        );
+        particles.push({
+          position: { x, y },
+          velocity: { x: vx, y: vy },
+          size,
+          mass,
+          color: point.color,
+        });
+      }
+
+      const extraCount = maxCount - baseCount;
+      if (extraCount > 0) {
+        const jitter = sampleStepTarget * 0.4;
+        for (let i = 0; i < extraCount; i++) {
+          const point = points[Math.floor(Math.random() * points.length)];
+          if (!point) continue;
+          const x = originX + point.x + (Math.random() - 0.5) * jitter;
+          const y = originY + point.y + (Math.random() - 0.5) * jitter;
+          const { vx, vy } = calculateVelocity(
+            { x, y },
+            imagePosition,
+            velocity
+          );
+          particles.push({
+            position: { x, y },
+            velocity: { x: vx, y: vy },
+            size,
+            mass,
+            color: point.color,
+          });
+        }
+      }
+
+      return particles;
+    }
+
     if (shape === "grid") {
       const cols = Math.ceil(Math.sqrt(count));
       const rows = Math.ceil(count / cols);

packages/playground/README.md

@@ -12,7 +12,7 @@ Interactive web application for experimenting with particle physics simulations.
 - **Sophisticated Undo/Redo**: Command pattern with transaction support and action grouping
 - **Parameter Oscillators**: Animate any module parameter with configurable frequency and bounds
 - **Comprehensive Hotkeys**: Efficient keyboard-driven workflow
-- **Text Shape Spawn**: Type text to spawn particles in the INIT panel
+- **Text/Image Shape Spawn**: Type text or provide an image to spawn particles in the INIT panel
 
 ### Physics Modules
 - **Environment**: Gravity, inertia, friction, damping with directional/radial options

packages/playground/src/components/InitControls.tsx

@@ -16,6 +16,7 @@ import { useAppDispatch } from "../hooks/useAppDispatch";
 import { lockSpawnTemporarily } from "../slices/init";
 import { buildPlayPath } from "../utils/playUrl";
 import { consumeSharedSessionFromUrlOnce } from "../utils/urlSharedSession";
+import { InitImageInput } from "./InitImageInput";
 import "./InitControls.css";
 
 export function InitControls() {
@@ -45,6 +46,10 @@ export function InitControls() {
     text,
     textFont,
     textSize,
+    imageData,
+    imageSize,
+    imageSource,
+    imageUrl,
     hasInitialSpawned,
     isSpawnLocked,
     setNumParticles,
@@ -62,6 +67,10 @@ export function InitControls() {
     setText,
     setTextFont,
     setTextSize,
+    setImageData,
+    setImageSize,
+    setImageSource,
+    setImageUrl,
     markInitialSpawned,
     initState,
   } = useInit();
@@ -269,6 +278,8 @@ export function InitControls() {
       text,
       textFont,
       textSize,
+      imageData,
+      imageSize,
     });
   }, [
     // NOTE: spawnParticles is intentionally NOT in this dependency array
@@ -291,6 +302,8 @@ export function InitControls() {
     text,
     textFont,
     textSize,
+    imageData,
+    imageSize,
     barsVisible, // Include to detect when component remounts due to UI changes
   ]);
 
@@ -316,6 +329,8 @@ export function InitControls() {
     text,
     textFont,
     textSize,
+    imageData,
+    imageSize,
   ]);
 
   // Create grid joints after particles are spawned
@@ -380,7 +395,14 @@ export function InitControls() {
   const handleSpawnChange = (
     options: {
       newNumParticles?: number;
-      newShape?: "grid" | "random" | "circle" | "donut" | "square" | "text";
+      newShape?:
+        | "grid"
+        | "random"
+        | "circle"
+        | "donut"
+        | "square"
+        | "text"
+        | "image";
       newSpacing?: number;
       newParticleSize?: number;
       newRadius?: number;
@@ -462,7 +484,8 @@ export function InitControls() {
               | "circle"
               | "donut"
               | "square"
-              | "text",
+              | "text"
+              | "image",
           })
         }
         options={[
@@ -471,6 +494,7 @@ export function InitControls() {
           { value: "donut", label: "Donut" },
           { value: "square", label: "Square" },
           { value: "text", label: "Text" },
+          { value: "image", label: "Image" },
           { value: "random", label: "Random" },
         ]}
       />
@@ -575,6 +599,26 @@ export function InitControls() {
           />
         </>
       )}
+      {shape === "image" && (
+        <>
+          <InitImageInput
+            imageUrl={imageUrl}
+            imageSource={imageSource}
+            imageData={imageData}
+            onImageUrlChange={setImageUrl}
+            onImageSourceChange={setImageSource}
+            onImageDataChange={setImageData}
+          />
+          <Slider
+            label="Image Size"
+            value={imageSize}
+            min={20}
+            max={2048}
+            step={1}
+            onChange={(value) => setImageSize(value)}
+          />
+        </>
+      )}
       <MultiColorPicker colors={colors} onColorsChange={handleColorsChange} />
       <Slider
         label="Velocity Speed"