# Particle sand-fill bars

Bar charts don't grow tall — they "rain into being": square particles fall one by one and pile up into bars, then solidify.

- Category: data · Tags: shotcraft, remotion, data, effects
- Spec: 1920×1080 @ 30 fps · 5.38s (16:9)
- License: Apache-2.0 · Tier: free
- JSON: https://gimgs.net/motion/particle-sand-fill.json
- Kind: remotion
- Source (TSX): https://gimgs.net/motion/particle-sand-fill/template.html
- Repo: https://github.com/Vincentwei1021/video-shotcraft
- Credits: video-shotcraft (Vincent Wei) — https://github.com/Vincentwei1021/video-shotcraft
- Page: https://gimgs.net/motion/particle-sand-fill.html

## Params

_No params._

Default params (base64url for `?p=`): `e30`

## Prompt

## When to use

Bar chart / magnitude-comparison entrance; data sections about "accumulation/convergence" semantics

## Intention

Swaps the bar-chart entrance from a "growing taller" animation to "falling accumulation": a rain of square particles falls above each bar, falling one by one under gravity acceleration, stopping and bouncing back 15% the instant they hit the pile, layering up until the target height is reached, then the particle surface fades out and is replaced by a solid bar with the value label popping up top. The data's "quantity" becomes something you can see "being piled up one grain at a time" — division of labor with unit-dot-swarm-regroup (the same batch of dots changing formation): that one is dots reshaping in a plane, this is falling material building up a shape.

## Duration & energy

- Duration: 4–5s
- Energy: Medium-high (a constructive-feeling entrance)

## Shot recipe (original Chinese — timing, easing, parameter table, known pitfalls)

## 意图
把柱状图入场从"长高动画"换成"落体堆积"：每根柱上方下一场方块雨，
粒子逐颗坠落（重力加速）、触堆积面即停+15% 回弹，一层压一层堆到目标
高度后粒子面淡出换实体柱、顶部数值标签弹出。数据的"量"变成看得见的
"一颗一颗攒出来"——与 unit-dot-swarm-regroup（点群平面迁徙聚形）
分工：那是同一批点改队形，这是落体材料筑成图形。

## 参数表
| 参数 | 典型值 | 调节手感 |
|------|--------|----------|
| 粒径 | 14px 方点 | 词汇原案 4px 不可感，QA 中加码 3.5 倍 |
| 每柱粒子数 | ~50 颗 | 太少堆积感稀疏，太多单颗不可辨 |
| 坠落 | 重力加速，落地帧闭式预解析 | 堆积高度=已落数×粒径，禁真碰撞模拟 |
| 回弹 | 触面 15% 单次回弹 | 无回弹读作贴图；多次回弹拖节奏 |
| 柱间错峰 | 6f 逐柱启动 | 齐落读作机械；错峰有"雨势推移"感 |
| 收束 | 堆满→粒子面淡出→实体柱+标签 back-out 弹出 | 粒子态直接定格显脏，必须凝成实体 |

## 已知坑
- demo 在灰阶/占位素材上调校通过——参数是调校起点非实战定稿，
  首次实战须以真实素材回验
- 落地帧全部闭式预解析（每颗粒子的落点/落帧编译期可算），
  帧确定性是渲染正确的前提——禁逐帧状态累积
- 只适合 3–5 根柱的量级对比；十几根柱的密集图表用常规入场
  （雨帘太多读作噪声）
- 与"碎块解体"否决判例的界限：这是构筑（从无到有堆出图形），
  不是破坏（把完整图形打碎）——方向语义相反，别做反向播放变体
- 声音：细密颗粒落地声铺底，每柱堆满一声轻"叩"，标签弹出一声 tick

## 参考实现
demos/data/particle-sand-fill/
（ParticleSandFill.tsx）

## Reference implementation (Remotion)

- demos/data/particle-sand-fill/ParticleSandFill.tsx — https://raw.githubusercontent.com/Vincentwei1021/video-shotcraft/main/demos/data/particle-sand-fill/ParticleSandFill.tsx

The component imports shared fixtures from `demos/_fixtures` and helpers from `assets/lib` in the repo; SKILL.md there documents the render workflow.


## Flow

1. **Read the recipe**
   Prompt = when to use, intention, parameter table with typical values and how each one feels, known pitfalls. Treat values as calibrated starting points.
2. **Get the code** — tool: git
   `git clone https://github.com/Vincentwei1021/video-shotcraft && cd video-shotcraft && npm install`
3. **Register + render** — tool: remotion
   `npx remotion render <CompositionId> out.mp4   # component: demos/data/particle-sand-fill/ParticleSandFill.tsx`
4. **Or re-implement**
   Port the timing/easing from the recipe to HTML + WAAPI (gimgs motion contract) or any engine; keep the same segment windows and easing.

## Render

Clone https://github.com/Vincentwei1021/video-shotcraft (npm install). The component lives under demos/{category}/{name}/ and imports shared fixtures from demos/_fixtures and helpers from assets/lib. Copy it (with those imports) into a Remotion project, register a <Composition> with the template's width/height/fps/duration in Root.tsx, then `npx remotion render <CompositionId> out.mp4`. SKILL.md in the repo documents the full Claude Code / Codex workflow. The prompt below is the shot recipe (timing, easing, parameter table, pitfalls) — enough to re-implement the shot in HTML/WAAPI or another engine if you prefer.

## Contract

React/Remotion composition (TSX) from the open-source video-shotcraft library (Apache-2.0). It is not a browser-playable template: clone the repo, register the component in a Remotion project and render with `npx remotion render`. The recipe (prompt) describes timing, easing and parameters so you can also re-implement the shot in any engine.