dirty-pixels

name	dirty-pixels
description	把任意图片重画成黑底像素粒子画：笔触尘沿图像自身的结构方向真实流动，长短笔触混搭、 子段错位出"脏"质感，动效按画面的物理规律分区规划（下坠/上升/旋转/外抛）， 输出静态 PNG 与无缝循环 GIF/MP4。触发：/dirty-pixels、「dirty pixels」「粒子流动效果」 「把这张图重绘成笔触」「yudho 那种风格」。风格致敬 pointillistic-noise 像素绘画美学 （参考艺术家 Satrio Yudho），实现为独立的确定性算法，不复制任何原作。
license	PolyForm-Noncommercial-1.0.0

Dirty Pixels v5

把一张图重画成黑底像素粒子画。核心脚本 scripts/dirty_pixels.py，确定性（同参数 同 seed 逐字节相同），全部美学决定都是参数。给用户交付时必须报出完整命令——那就是版本号。

v5 与旧版的关系（先读这段，别走回头路）

v4 的「实心网点 mass 层 + 规划蒙版」画法在实践中被否决：蒙版是画出来的几何形状， 边界永远贴不住图像；对连续光影塑形的图，mass 层会把层次压成色块。 v5 的正典是纯粒子：不给 --plan，不开 mass 层，每一笔的落点由原图亮度和梯度采样， 边界天然贴合。虚空靠 --floor 从亮度上切，不靠蒙版圈。 （v4 的 --plan/--mass 仍可用，仅当输入是平实大色块、真需要静止锚定层时才考虑。）

正典配方（与用户逐轮审定的终版）

python3 scripts/dirty_pixels.py in.png -o out \
  --preset detail --simplify 1 --size 1400 --seed 305 \
  --sparsity 1.8 --gamma 2.4 --edge 0.7 --density 1.5 --floor 0.035 \
  --stroke 20 --curve 0.03 --jitter 0.02 --coherence 45 \
  --length-mix 3 --aniso-len 1.5 --fray 1.4 --gap 0.22 \
  --flow 5 --boil 0.35 --trail 1 --conserve 1.5 \
  --burst-at X,Y,0.55 --rain 0.4 --rain-angle 92 --rain-speed 2 \
  <按物理规划的方向参数，见下> \
  --seconds 1.6 --fps 12 --mp4

--floor 是唯一必须按图调的：极暗原图（平均亮度 <0.05）用 0.03–0.05； 正常亮度原图从 0.2 起试。虚空不够往上提，主体开始碎往下降。

笔触质感的四根支柱（每根都是用户实测选定的）

1. 长短混搭 --length-mix 3：幂律长度分布——大多数是斑点，少数抽成长线。 短的负责图像信息，长的负责运动感。均匀分布（=1）会满屏中长线，画面发"土"。
2. 内容决定长度 --aniso-len 1.5：方向性强的地方（手臂、浪面、光柱）才允许长线， 各向同性的细节区只出斑点。清晰度靠内容恢复，不靠全局调短。
3. 错位 --fray 1.4 --gap 0.22：每根笔拆成随机长度的子段，逐段横向偏移、随机丢弃、 亮度不一。一根"线"其实是几截没对齐的短段——这是"脏"/数据错误感的来源。 干净的连续线（fray 0）一眼就是机器画的。
4. 几乎直 --curve 0.03 --jitter 0.02：curve 高了长笔会卷成逗号钩；0 又太机械。

流动：三条铁律

① --stroke 长度、方向场、真实位移缺一不可。 flow<2 是原地闪烁（虫子爬）， 正典 flow=5：一个循环净位移约 40 输出像素，肉眼能读出"划过"。 --trail 1 让笔触沿运动方向拖尾（自带运动模糊）。

② 集体同向靠 --coherence。 它决定方向场跟多大尺度的结构：2.5 = 每个像素各走各的 （错），45 = 一整块（整条手臂、整片浪面）同向流动（正典）。要跟到手指级细节降到 20–30。

③ 方向的"往哪头"必须按物理规划，见下节。 结构张量给的是无符号线场， 只回答"沿哪条线"，不回答"往哪头"——后者是内容决策，不是数学。

动效规划：先读图，再定方向（核心方法论）

流程：列出画面元素 → 逐个问"这东西在物理上往哪走" → 一个元素一条参数。 一个全局角度必然在某处是错的（光柱下坠 vs 余烬上升不可能同一个方向）。

画面里的东西	物理	参数
光柱、雨、瀑布、坠落物	下坠	--flow-region X,Y,RX,RY,90
火焰、余烬、烟、气泡	上升	--flow-region ...,-90
破碎浪的浪背	爬升翻出	--flow-region ...,-40 左右
海面/前景水	随破碎方向推	--flow-region ...,0 或 180
爆炸、被光推开的尘	由中心向外	--flow-from-burst
风中的旗、发、草	顺风	风向角度
天然同心结构（发髻、年轮、浪的卷桶、旋涡星系）	旋转	--swirl X,Y,±S,R

三层模块，独立、可局部使用：

• --flow-bias 角度 / --flow-from-burst：全局兜底，只在整图有压倒性方向时单用
• --flow-region X,Y,RX,RY,ANGLE[,S]：默认手段，软椭圆分区，可重复，覆盖全局， 只改"往哪头"不改场的几何
• --swirl X,Y[,S[,R]]：改场的几何造真环流。只给天然同心的结构（参考：原作者的 佛像只在螺发上用漩涡，主体不用）。判据：这块结构本身是不是同心的？强度 0.4–0.5 = 暗示，0.85+ = 整块卷入（会吞掉形体性格）。正负号 = 转向。

渲染后必须逐区验证方向（方向反了在静帧上看不出来）：

from numpy.fft import rfft2, irfft2
def shift(a, b):   # 两帧同位置裁片的整体位移；dy>0 = 向下
    A=a-a.mean(); B=b-b.mean()
    c=irfft2(rfft2(B)*np.conj(rfft2(A)), A.shape)
    p=np.unravel_index(np.argmax(c), c.shape)
    return (p[1]-(a.shape[1] if p[1]>a.shape[1]//2 else 0),
            p[0]-(a.shape[0] if p[0]>a.shape[0]//2 else 0))

吸引子假轮廓与 --conserve（必开）

平滑矢量场推进粒子，粒子会压缩到场的吸引曲线上，形成蚯蚓状的亮线。这些曲线属于 场的拓扑，不属于画面里的任何东西——看起来像轮廓，却勾不出任何形状，是这个算法最典型的 视觉 bug。--conserve 1.5 做密度守恒：每帧对比粒子当前分布与出生分布，哪里挤了 N 倍 就把亮度除回 N 倍，压缩被精确抵消，其余像素不受影响。正典必开。

注意：这种线不饱和也看得见（它是密度聚集不是亮度过曝），所以验收要看画面， 不能只看饱和像素指标。历史上 --declump/--ink/--soften/--contour 都是治标方案， 参数还在但默认关，不要再用它们来治这个问题。

调参必须用动画帧，不能用静帧

--static-only 时 frames=1，粒子完全不推进——凡是涉及 flow/boil/conserve 的调参， 静帧全部一样，必须渲动画看。静帧只能用来审构图和笔触质感。

内存

1400px 方图在 3× 超采样下是 4200×4200，方图别和其他图并行渲染（8GB 容器会 OOM）。 宽图三张并行安全。

自检清单（每次交付前）

• 循环无缝：|末帧−首帧| ≈ 相邻帧差（比值 0.95–1.05）
• 构图稳：相邻帧大尺度密度相关性 > 0.985
• 方向对：逐区 shift() 位移与物理判断一致
• 无蚯蚓线：肉眼查大面积密集区（地面带、浪身）有无意义不明的亮曲线
• 虚空 ≥ 60%（纯粒子画法下典型 80–90%）

常见失败

• 虫子爬（原地抖不流动）：flow 太小或 boil 压过 flow → flow 5 / boil ≤0.5。
• 长线像梳过的头发（太规整）：fray=0 → 开 1.4；还整齐就查 length-mix 是不是 1。
• 长笔卷成逗号钩：curve 太大 → 0.03。
• 蚯蚓状意义不明亮线：conserve 没开 → 1.5（网格细、强度别超 2，2.5 起画面压平）。
• 光柱向上流 / 方向违反物理：用了全局 flow-bias 兜所有区 → 逐元素 --flow-region。
• 满屏中长线发土：length-mix=1 → 3；density 同步降到 1.5 以下。
• 画面太密失去留黑：floor 提高；density 降；sparsity 提到 2。
• GIF 在 macOS 预览不动：正常，拖浏览器看。
• 两次输出不一样：参数或 seed 变了；算法本身确定性。

边界与伦理

细节（五官、文字、小窗）必然消失；平缓明暗过渡会变均匀绒毛。适合"一个大形 + 强对比"。 本 skill 是对该美学的算法化致敬，代码全部原创；风格不受版权保护，但不得以原作者名义 署名或宣传。转换全在本地完成。