Particle Text Core

Live Demo · 在线预览： https://kokoro-ele.github.io/PixelWeave/

EN · Canvas particle text effects — decompose images into colored particles that assemble into interactive typography.
中文 · Canvas 粒子文字特效库 — 将图片拆解为彩色粒子，汇聚成可交互文字动效。

English | 中文

中文

安装

npm install particle-text-core

快速上手

<canvas id="canvas" width="800" height="500"></canvas>
<script type="module">
  import { ParticleTextEffect } from 'particle-text-core';

  const canvas = document.getElementById('canvas');
  const effect = new ParticleTextEffect(canvas, {
    gap: 4,
    fontSize: 120,
    renderMode: 'live-stream', // 'interactive' | 'stream-print' | 'live-stream'
  });

  const img = new Image();
  img.onload = () => effect.start('HELLO WORLD', img);
  img.src = '/your-photo.jpg';
</script>

渲染模式

| 模式 | 值 | 说明 | |------|-----|------| | 交互散射 | interactive | 粒子从图片采样，鼠标靠近产生排斥 | | 流式印刷 | stream-print | 左侧完整照片，粒子逐粒飞出组成右侧文字 | | 实时流式 | live-stream | 每输入一个字，对应粒子立即飞出（支持中文 IME） |

API

| 类 / 方法 | 说明 | |-----------|------| | ParticleTextEffect | 高级封装，推荐使用 | | effect.start(text, image?) | 采样并启动动画 | | effect.update(text, image?) | 重置并重新渲染 | | effect.syncToText(text, opts?) | 实时流式：字素级增量同步 | | effect.appendCharacter(char) | 实时流式：追加单字 | | effect.getStats() | 粒子池用量统计 | | effect.setConfig(partial) | 更新配置 | | effect.stop() / effect.destroy() | 停止 / 销毁 | | ParticleGenerator | 底层采样器 | | ParticleRenderer | 底层渲染循环 |

实时流式示例

import { ParticleTextEffect } from 'particle-text-core';

const effect = new ParticleTextEffect(canvas, { renderMode: 'live-stream' });
effect.resetLiveStream(image);

input.addEventListener('input', () => {
  effect.syncToText(input.value);
});

配置项

interface Config {
  gap: number;              // 采样步长，默认 4
  fontSize: number;         // 字号，默认 120
  fontFamily: string;       // 字体
  mouseRadius: number;      // 鼠标排斥半径
  easing: number;           // 缓动系数
  renderMode: RenderMode;   // 渲染模式
  splitRatio: number;       // 左右分栏比例（流式模式）
  streamInterval: number;   // 粒子发射间隔 (ms)
  streamDuration: number;   // 单颗粒飞行时长 (ms)
  letterSpacing: number;    // 字间距
}

English

Install

npm install particle-text-core

Quick Start

<canvas id="canvas" width="800" height="500"></canvas>
<script type="module">
  import { ParticleTextEffect } from 'particle-text-core';

  const canvas = document.getElementById('canvas');
  const effect = new ParticleTextEffect(canvas, {
    gap: 4,
    fontSize: 120,
    renderMode: 'live-stream',
  });

  const img = new Image();
  img.onload = () => effect.start('HELLO WORLD', img);
  img.src = '/your-photo.jpg';
</script>

Render Modes

| Mode | Value | Description | |------|-------|-------------| | Interactive scatter | interactive | Mouse repulsion on image-sampled particles | | Stream print | stream-print | Particles fly from photo to form text | | Live stream | live-stream | Per-keystroke particle release (CJK IME supported) |

API

| Class / Method | Description | |----------------|-------------| | ParticleTextEffect | High-level wrapper | | effect.start(text, image?) | Sample and start animation | | effect.update(text, image?) | Reset and re-render | | effect.syncToText(text, opts?) | Live stream: grapheme-level sync | | effect.appendCharacter(char) | Live stream: append one character | | effect.getStats() | Particle pool usage stats | | effect.setConfig(partial) | Update configuration | | effect.stop() / effect.destroy() | Stop / destroy | | ParticleGenerator | Low-level sampler | | ParticleRenderer | Low-level render loop |

Live Stream Example

import { ParticleTextEffect } from 'particle-text-core';

const effect = new ParticleTextEffect(canvas, { renderMode: 'live-stream' });
effect.resetLiveStream(image);

input.addEventListener('input', () => {
  effect.syncToText(input.value);
});

Configuration

See the Chinese section above for the full Config interface.

License

MIT