@machinal/mcp 0.0.0-stage → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +366 -2
- package/bin/machinal-mcp.mjs +19 -0
- package/bin/machinal-stdio.mjs +14 -0
- package/package.json +47 -4
- package/skills/machinal-cinema/SKILL.md +18 -0
- package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
- package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
- package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
- package/skills/machinal-cinema/references/film-library/README.md +13 -0
- package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
- package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
- package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
- package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
- package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
- package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
- package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
- package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
- package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
- package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
- package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
- package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
- package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
- package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
- package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
- package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
- package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
- package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
- package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
- package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
- package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
- package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
- package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
- package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
- package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
- package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
- package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
- package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
- package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
- package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
- package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
- package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
- package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
- package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
- package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
- package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
- package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
- package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
- package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
- package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
- package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
- package/skills/machinal-cinema/references/film-styles.json +1322 -0
- package/skills/machinal-cinema/references/film-techniques.json +107 -0
- package/skills/machinal-cinema/references/workflow.md +58 -0
- package/skills/machinal-credits/SKILL.md +24 -0
- package/skills/machinal-editing/SKILL.md +43 -0
- package/skills/machinal-editing/references/brief.md +98 -0
- package/skills/machinal-editing/references/effects.md +58 -0
- package/skills/machinal-editing/references/looks-motion.md +37 -0
- package/skills/machinal-editing/references/styles.json +15 -0
- package/skills/machinal-editing/references/styles.md +16 -0
- package/skills/machinal-editing/references/transitions.md +46 -0
- package/skills/machinal-editing/references/workflow.md +43 -0
- package/skills/machinal-media/SKILL.md +23 -0
- package/skills/machinal-media/references/workflow.md +160 -0
- package/skills/machinal-recipes/SKILL.md +32 -0
- package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
- package/skills/machinal-recipes/references/commands.md +45 -0
- package/skills/machinal-recipes/references/example.edit.yaml +26 -0
- package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
- package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
- package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
- package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
- package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
- package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
- package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
- package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
- package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
- package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
- package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
- package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
- package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
- package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
- package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
- package/skills/machinal-recipes/references/examples.md +28 -0
- package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
- package/skills/machinal-recipes/references/text-audio.md +118 -0
- package/skills/machinal-recipes/references/yaml.md +72 -0
- package/skills/machinal-review/SKILL.md +18 -0
- package/skills/machinal-review/references/production.md +146 -0
- package/skills/machinal-scenes/SKILL.md +44 -0
- package/skills/machinal-scenes/references/authoring.md +97 -0
- package/skills/machinal-scenes/references/runtime.md +136 -0
- package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
- package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
- package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
- package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
- package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
- package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
- package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
- package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
- package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
- package/skills/machinal-scenes/references/scene-templates.json +178 -0
- package/skills/machinal-scenes/references/scene-templates.md +50 -0
- package/skills/machinal-scenes/references/workflow.md +206 -0
- package/skills/machinal-support/SKILL.md +42 -0
- package/src/bridge.mjs +287 -0
- package/src/cli.mjs +157 -0
- package/src/configuration.mjs +148 -0
- package/src/connection.mjs +187 -0
- package/src/credential-store.mjs +61 -0
- package/src/credits.mjs +86 -0
- package/src/docker.mjs +93 -0
- package/src/download.mjs +90 -0
- package/src/endpoints.mjs +3 -0
- package/src/errors.mjs +9 -0
- package/src/formats.mjs +140 -0
- package/src/keys.mjs +127 -0
- package/src/launch.mjs +29 -0
- package/src/local-setup.mjs +109 -0
- package/src/opencode-auth.mjs +246 -0
- package/src/opencode-checkpoints.mjs +90 -0
- package/src/opencode-configuration.mjs +53 -0
- package/src/opencode-media.mjs +139 -0
- package/src/opencode-plugin/index.mjs +7 -0
- package/src/opencode-plugin/package.json +5 -0
- package/src/opencode-recipes.mjs +130 -0
- package/src/opencode-routing.mjs +154 -0
- package/src/opencode-tools.mjs +30 -0
- package/src/opencode-workflow.mjs +32 -0
- package/src/presentation.mjs +31 -0
- package/src/prompts.mjs +32 -0
- package/src/reference-files.json +127 -0
- package/src/runtime.mjs +51 -0
- package/src/setup-options.mjs +69 -0
- package/src/setup-stdio.mjs +116 -0
- package/src/setup.mjs +173 -0
- package/src/skills.mjs +68 -0
- package/src/transfer-http.mjs +109 -0
- package/src/version.mjs +3 -0
- package/src/windows-key-prompt.mjs +37 -0
- package/src/windows-key-prompt.ps1 +77 -0
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Chinese Ink Wash — Style Prompt
|
|
2
|
+
|
|
3
|
+
> Xieyi ink painting on rice paper, animated: blank paper is space, one brushstroke is a mountain, a wave, a gesture or a cut.
|
|
4
|
+
> References (grammar only): Shanghai Animation Film Studio's *Feelings of Mountains and Water* (1988) (blank-paper space, ink bloom, guqin pacing, figures in a few strokes); the bamboo-forest fight of *Crouching Tiger, Hidden Dragon* (weightlessness, stillness before action). Copy none of their characters, compositions or music.
|
|
5
|
+
|
|
6
|
+
## 1. Essence, and what it is not
|
|
7
|
+
|
|
8
|
+
An ink painting (水墨) painted and unrolled before you: black ink on warm rice paper in five tones, plus **one** red, the vermilion seal. No Western outlines: forms are made by **loaded brushstrokes** whose dark edge *is* the contour (没骨, "boneless" painting), by **wet washes** that bleed into the paper, and by **dry, fast strokes** where the paper shows through the bristle tracks (飞白, "flying white").
|
|
9
|
+
|
|
10
|
+
Most of the frame is **empty paper** (留白): water, sky, mist, silence. Things are *painted into existence*, not cut to.
|
|
11
|
+
|
|
12
|
+
Not watercolour (no colour washes), not vector art with a brush texture (no flat fills or closed outlines), not a calligraphy title sequence.
|
|
13
|
+
|
|
14
|
+
## 2. Materials & rendering
|
|
15
|
+
|
|
16
|
+
- **Paper** is procedural, in the compositor, never a texture file: warm rice paper (around `#F2ECDE`), cloud mottling, long fibres, pulp flecks, grain that fades when zoomed out (or it shimmers), a light vignette; anchored to the world.
|
|
17
|
+
- **Ink** is stroke opacity multiplied onto paper (never an overlay), in five tones (墨分五色):
|
|
18
|
+
|
|
19
|
+
| Tone | Opacity | Use |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| 焦 jiao (burnt) | ~.96 | calligraphy, the sharpest lines, moss dots |
|
|
22
|
+
| 浓 nong (thick) | ~.82 | contours, dark edge of loaded strokes |
|
|
23
|
+
| 重 zhong (heavy) | ~.60 | secondary lines, folds |
|
|
24
|
+
| 淡 dan (light) | ~.34 | mountain bodies, robe and body washes |
|
|
25
|
+
| 清 qing (clear) | ~.16 | far mountains, faces, mist |
|
|
26
|
+
|
|
27
|
+
- **Brushstroke model**: centreline × pressure profile × width noise, plus 4–60 **bristles** whose ink load drops along the stroke and breaks on long-scale noise. `dry` runs from a solid wet stroke to flying white (dry strokes are bristle tracks only).
|
|
28
|
+
- **Loaded stroke**: bristles darker on one side, so the stroke carries its own contour: this makes bodies, rocks and waves read as ink, not vectors.
|
|
29
|
+
- **Two layers**: the wet one bleeds in the compositor (noisy blur, **edge pigment accumulation**, granulation); the dry one only gets fibre jitter and paper tooth.
|
|
30
|
+
- **Masses**: soft polygons, jittered edges, a gradient; never flat fills.
|
|
31
|
+
- **Landscape**: mountains dissolve downward into mist bands, with 披麻皴 texture and 苔点 moss dots on near ranges only; rocks are outline → axe-cut texture → shadow wash → dots.
|
|
32
|
+
- **Water is blank paper**, moved by faint dry streaks and open ink rings. Solid water: Song-dynasty **parallel wave lines** (dense near the edge) or a pale body with a few huge loaded strokes along its face.
|
|
33
|
+
- **Figures are xieyi**: one pale body mass plus two loaded strokes, burnt-ink lines for limbs; features, if ever shown, in 3–5 strokes.
|
|
34
|
+
- **Calligraphy**: an OFL brush font is only a **skeleton**: trace centrelines in stroke order, pressure from glyph thickness, hidden-tip entry (藏锋), tapered exits.
|
|
35
|
+
|
|
36
|
+
## 3. Colour logic
|
|
37
|
+
|
|
38
|
+
- Ink only, from cool grey at low density to warm black at full density. No other hue in the world.
|
|
39
|
+
- **One vermilion** (around `#B02E22`), for the seal and at most one tiny accent in the story (an object the protagonist carries). The accent finds the protagonist in wide shots and can rhyme with the seal. Never a red wash, never red type.
|
|
40
|
+
- Values carry depth: far = pale and soft, near = dark and textured. If a frame gets busy, remove ink rather than add tone.
|
|
41
|
+
|
|
42
|
+
## 4. Type & subtitles
|
|
43
|
+
|
|
44
|
+
- Subtitles are **inscriptions (题跋)**: a classical italic serif (Cormorant Garamond italic), ink-coloured, no box, ≤ 2 lines, placed in each shot's empty paper. A small vermilion square marks the start of each line. They appear wet and dry in a fraction of a second. Hold ≥ max(1.8 s, speech + 0.6 s).
|
|
45
|
+
- Titles are written on the painting itself, in vertical columns in its empty space, with a vermilion 白文 seal drawn by code (lines knocked out of a slightly irregular red square, with ink-paste speckles). They move with the world.
|
|
46
|
+
- Screen-space overlays reset the camera transform.
|
|
47
|
+
|
|
48
|
+
## 5. Motion quality
|
|
49
|
+
|
|
50
|
+
- **Figures step at 12 fps** (on twos); their position, the camera, blooms, ripples and splatter move on ones at 24 fps.
|
|
51
|
+
- **Stable strokes on twos**: seed every stroke by its index and compute bristle breaks along *normalized* arc length × a fixed reference length, so flying-white gaps don't crawl every drawing. Allow only a small "boil" on the width noise.
|
|
52
|
+
- **Painted into existence**: strokes appear in drawing order.
|
|
53
|
+
- **Stillness before action** (when a decisive stroke is the event): hold, with at most a slow push-in, then let the stroke cross the frame in a few frames. Consequences start only after the stroke has finished.
|
|
54
|
+
- Nothing is tweened like a vector shape: things are painted, bloom or dissolve into mist.
|
|
55
|
+
|
|
56
|
+
## 6. Camera grammar
|
|
57
|
+
|
|
58
|
+
A vocabulary, not a route. Opening and ending come from the topic.
|
|
59
|
+
|
|
60
|
+
| Move | Expresses | Can serve |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| Locked frame on the paper | The page is the stage; things are painted in | a thing forming; a line being read; a still decision |
|
|
63
|
+
| Right-to-left pan (handscroll) | Time and distance as one painting | a journey; a history; a process |
|
|
64
|
+
| Vertical tilt (hanging scroll) | Height, stages stacked | seasons; a climb; generations |
|
|
65
|
+
| Lateral tracking, lead room, slow far parallax | Motion through a world | travel; a chase; a commute |
|
|
66
|
+
| High wide, a tiny figure in blank paper | Smallness, solitude | loneliness; nature's scale; one life among many |
|
|
67
|
+
| Low angle, dark mass towering, slow push-in with shake | Weight, threat | an obstacle; a storm; pressure |
|
|
68
|
+
| Hard cut to an extreme close-up | A break in the flow (the style's only hard cuts) | a decision; a shock; a memory |
|
|
69
|
+
| Push into an ink bloom or mist | Passing between states | memory; dream; a season turning |
|
|
70
|
+
| Pull back until a mark joins the whole | The part was inside something larger | a summing-up; irony of scale |
|
|
71
|
+
| Return to an earlier framing | The rhyme shows what changed | aftermath; growth; before/after |
|
|
72
|
+
|
|
73
|
+
Framing: 60–80 % empty paper; dark foreground may pass along the frame bottom. Transitions are ink blooms, pans along the scroll or mist; never a generic dissolve or a wipe.
|
|
74
|
+
|
|
75
|
+
## 7. Sound palette
|
|
76
|
+
|
|
77
|
+
- **Guqin-led, not piano and strings**: guqin (`core/audio/pluck.py` `guqin`: open and stopped strings, slides, vibrato, glassy harmonics, sweeps), a low breathy xiao, big drum and timpani for mass, frame drum for steps, a small gong for a seal. Chinese pentatonic modes.
|
|
78
|
+
- **Cue to the picture, never loop**: unmetred plucks suit emptiness, a pulse suits movement, rolls suit mass; painted strokes can each land on a pluck.
|
|
79
|
+
- **Silence is literal**: zero the whole bus (music, ambience, reverb tails) with short fades. At most one sound inside it (a drip, one ring). Place it where the story holds its breath.
|
|
80
|
+
- **Foley follows the material**: ink drop (short "tink" + soft wet thud), brush air (band-passed noise with bristle grains, never a metal whoosh), steps on water (small splash), splatter (wet ticks), seal (wooden thump + paper crackle).
|
|
81
|
+
- **Voice**: calm, few lines, like colophons that don't explain the picture. Duck music ~8 dB and ambience too; verify each line with whisper on the final mix.
|
|
82
|
+
|
|
83
|
+
## 8. Native moves
|
|
84
|
+
|
|
85
|
+
A menu: use the ones your story needs.
|
|
86
|
+
|
|
87
|
+
- **One stroke is everything.** *Fits content like:* a product born from one line; a city growing from a single street; a day beginning with one bird.
|
|
88
|
+
- **Emptiness is matter.** Removing ink reveals paper white. *Fits content like:* a door opening in a wall; a crowd parting; an absence in a family portrait.
|
|
89
|
+
- **Brush = gesture = action.** Stroke order becomes choreography. *Fits content like:* a dancer's phrase that spells a word; a signature; a chef's knife work.
|
|
90
|
+
- **Flying white (飞白).** One fast dry stroke across the frame, strongest out of a silence. *Fits content like:* a sprint finish; a decision; a comet.
|
|
91
|
+
- **Ink bloom transition.** The next scene grows inside a spreading drop with a dark tide-line (noisy radial mask; world-anchored for elements, in the compositor for scenes). *Fits content like:* memories; seasons; one era giving way to the next.
|
|
92
|
+
- **The handscroll.** One long painting panned right to left, seen whole at last. *Fits content like:* a history; a supply chain from field to hand; a day in a street.
|
|
93
|
+
- **Splitting a mass.** Halves clipped either side of the cut; one rises and fades, one slumps; splatter stays. *Fits content like:* breaking a record; a barrier falling; an idea splitting in two.
|
|
94
|
+
|
|
95
|
+
## 9. Pitfalls of the medium
|
|
96
|
+
|
|
97
|
+
- Dry brush looks like dashed lines → breaks from long-scale noise and an ink load that drops along the stroke.
|
|
98
|
+
- Parallel semi-transparent strokes make bodies look like organ pipes → one base mass + two loaded strokes.
|
|
99
|
+
- Big side-brush strokes look like a hairbrush → a gradient mass + a few low-dryness strokes. Gradients in vertical bands leave seams → a cached per-pixel layer.
|
|
100
|
+
- A stroke body split between wet and dry layers loses density → full body in the dry layer plus a wet halo.
|
|
101
|
+
- Clipping calligraphy with the font outline notches the junctions → font as skeleton only.
|
|
102
|
+
- Uniform hatching inside a wave turns it into a wire mesh → loaded strokes along the face.
|
|
103
|
+
|
|
104
|
+
## 10. Engine
|
|
105
|
+
|
|
106
|
+
In `demo/`: `ink.js` (brush engine: strokes, bristles, loaded strokes, masses, blots), `comp.js` (WebGL rice-paper compositor: bleed, edge pigment, paper, bloom), `land.js` (mountains, cun, cliffs, pine, reeds, ripples), `wave.js` (gestural wave), `glyph.js` (skeleton-traced calligraphy), `seal.js` (vermilion seal), `hero.js` (xieyi figure rig), `subs.js` (inscription subtitles), `music/score.py` (guqin writing with `core/audio/pluck.py`); `?test=sheet|pose|frame` pages draw model sheets from the real engine.
|
|
107
|
+
|
|
108
|
+
## 11. Variation space
|
|
109
|
+
|
|
110
|
+
You decide the structure, the characters (or none), the landscape, the opening, the ending, the camera path, the pacing and where the red goes. All far from our demo:
|
|
111
|
+
|
|
112
|
+
- Structures: **one character, stroke by stroke** (no figure; each stroke of one large character opens into a vignette of the topic); **a hanging scroll** (a tilt from sky to ground through four stages, tone deepening); **two brushes in dialogue** (alternating strokes answer each other until they meet in one bloom).
|
|
113
|
+
- Openings: **in motion** (a figure already painted and moving; the world washes in around it); **ink first** (a fully inked frame; ink is lifted where light or a road appears); **the bristles** (a wet stroke fills the frame; only when it lifts do we see what it drew).
|
|
114
|
+
- Endings: **one small mark** (close on a footprint or a leaf while the ink around it dries; no pull-back); **evaporation** (the painting un-paints in reverse stroke order); **mid-gesture** (the brush stops before the last stroke lands).
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Isometric Infographic — Style Prompt
|
|
2
|
+
|
|
3
|
+
> A system diagram comes alive: an isometric diorama of flat three-tone blocks, thin ink labels and Isotype numbers, where things open up to show their insides and the numbers are drawn, not stated.
|
|
4
|
+
> References (grammar only): *Monument Valley* (true-isometric architecture, flat colour blocks, three fixed tones per face, a camera that pans and zooms but never breaks the projection); *SimCity 2000*-style cutaway dioramas (a floating board with soil strata, the whole system visible at once); Kurzgesagt (a question, a steady push forward, one clear visual metaphor per step, a change of scale when a number is too big to feel); Isotype, Otto Neurath / Gerd Arntz (repeated identical icons stand for quantity); *Powers of Ten* (a continuous dive through nested scales). Use none of their characters, buildings, icons, palettes or music.
|
|
5
|
+
|
|
6
|
+
## 1. Essence, and what it is not
|
|
7
|
+
|
|
8
|
+
- **Flat, true isometric.** No perspective, no outlines on solids; shapes are separated only by the three tones of each face. The projection never rotates or tilts.
|
|
9
|
+
- **Infographic furniture is part of the picture**: leader lines, label pins, dashed cut lines, hatched section faces, tracking rings, a legend, a route line all live in the world.
|
|
10
|
+
- **Numbers are built from icons** (Isotype), and they add up.
|
|
11
|
+
- **A diorama**: the system sits on a floating board or plinth with a visible cross-section at its edges, on a pale ground.
|
|
12
|
+
|
|
13
|
+
Not low-poly 3D (no perspective, no lighting beyond three face tones), not a flat 2D explainer (everything has isometric depth), not a blueprint (colour blocks, not line drawings on blue).
|
|
14
|
+
|
|
15
|
+
## 2. Materials & rendering
|
|
16
|
+
|
|
17
|
+
- **Projection**: axes at 30°. `sx = (x − y)·cos30°·k`, `sy = ((x + y)·½ − z)·k`; x runs down-right, y down-left, z up; painter depth = x + y + z. Everything is queued and depth-sorted, then flushed.
|
|
18
|
+
- **Three tones per face** chosen from its normal: top light, left (+y) mid, right (+x) dark. Derive tones from one base colour: mix toward warm white ~20 % for the top and toward a cool dark (e.g. `#231A2C`) ~22 % for the dark side, so shadows are slightly cool.
|
|
19
|
+
- **Ink lines** (2 px) only for infographic elements: leaders, pins, cut lines, rings, routes, labels.
|
|
20
|
+
- **The board**: floats on a pale background with a faint isometric dot lattice and a soft blurred shadow; its front faces show strata (soil, water column, floors, pipes) where the section meets the edge.
|
|
21
|
+
- **Composites** (a terraced hill with shrubs, a crane over a ship) are drawn as one ordered item or given a depth bias; generic painter sorting fails on them.
|
|
22
|
+
- **People**: minimal billboards (round head, tapered two-tone body, a thick arm stroke, a hat or hair shape for identity, no faces), stepping at 12 fps.
|
|
23
|
+
- **Close-ups** of hands or objects: flat faceted shapes in three tones, same logic as the blocks.
|
|
24
|
+
- **Level of detail by zoom**: skip small world detail at high zoom, fade tall objects in by zoom so a pull-out never sweeps a giant shape through the frame.
|
|
25
|
+
|
|
26
|
+
## 3. Colour logic
|
|
27
|
+
|
|
28
|
+
- **A pale neutral ground** (cream, paper grey or pale blue) and **5–7 flat hues**, each with its three tones; one ink colour.
|
|
29
|
+
- **Colour codes meaning**, the way a legend does: one hue per material or role (water is always the same blue, the subject always its hue). Never reuse a hue for two meanings.
|
|
30
|
+
- **The subject's hue is reserved**: when the story needs "this one", everything else desaturates toward warm grey and only the subject keeps its colour (focus + context).
|
|
31
|
+
- Stations that must be found in a wide shot get a pale plate with a dashed ink outline plus one accent hue.
|
|
32
|
+
- Examples: a recycling chain — bottle green, kraft brown, can silver-blue, compost umber, mustard on cream; a hospital — teal, coral, lavender, steel grey on pale grey; a data centre — electric blue, amber, graphite, mint on off-white.
|
|
33
|
+
|
|
34
|
+
## 4. Type & subtitles
|
|
35
|
+
|
|
36
|
+
- One geometric sans (e.g. Jost): titles 600 all caps with ~0.12 em tracking, numbers 400 large (~44 px), units at half size. All text has a ~7 px halo in the ground colour so it reads over any block.
|
|
37
|
+
- **Label pins**: dot (ink ring, pale fill) → vertical leader → horizontal rule → text. Pins point up or down, left or right, chosen per station so labels never cover the subject.
|
|
38
|
+
- **Titles** can be isometric type on a world plane, extruded as blocks.
|
|
39
|
+
- **The subtitle is a map label**: a pale card with a small radius and an ink border, a tiny iso cube as legend chip, sans ~42 px, bottom-centre; border draws first, text wipes in. Keep the bottom ~170 px clear for it. Hold ≥ max(1.8 s, speech + 0.6 s); lines never overlap titles or other lines.
|
|
40
|
+
- **An end frame can be the legend**: title, totals, the Isotype key, credits, "NOT TO SCALE".
|
|
41
|
+
|
|
42
|
+
## 5. Motion quality
|
|
43
|
+
|
|
44
|
+
- **Nothing moves without a line leading it**: a route line is drawn slightly ahead, a leader grows before an inset opens, a cut line draws before a skin slides away.
|
|
45
|
+
- **Cutaway**: cut line (~0.3 s) → the near skin slides out along its normal and fades (~0.35 s, ease-out) → hatched section rims fade in over the last part.
|
|
46
|
+
- **Isotype fill**: icons pop with a back-ease (overshoot), one per subdivision of the beat; count-up numbers run over the same span.
|
|
47
|
+
- **Accumulation = acceleration**: arrivals on quarter notes, then eighths, then waves; the eye feels the system taking over. Solids arrive by motion, never by alpha (semi-transparent blocks look like ghosts).
|
|
48
|
+
- **Objects perform**: squash on landing (~18 %) and small bounces; colour changes that show a process (raw → cooked, empty → full).
|
|
49
|
+
- **Vehicles** follow polylines with ease-in-out and face their tangent.
|
|
50
|
+
|
|
51
|
+
## 6. Camera grammar
|
|
52
|
+
|
|
53
|
+
A vocabulary, not a route. The camera is a world centre plus a **log-interpolated zoom** k (px per unit); the projection never changes. Opening and ending come from the topic.
|
|
54
|
+
|
|
55
|
+
| Move | What it expresses | Can serve |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| Follow along a route | process; cause → effect | a supply chain; a journey; a signal |
|
|
58
|
+
| Hold wide + circular inset | the system and the individual together | one worker in a factory; one cell in an organ |
|
|
59
|
+
| Push through nested cutaways | a fall into scale; finding one thing among millions | a needle in a haystack; inside a machine |
|
|
60
|
+
| Fast log pull-out | release; the big picture after a detail | scale reveal; a statistic made physical |
|
|
61
|
+
| Locked frame while things accumulate | a system filling up; overload | a queue; traffic; data growing |
|
|
62
|
+
| Lateral follow over emptiness | a breath; distance | an ocean; a wait; a quiet phase |
|
|
63
|
+
| Top-to-bottom tilt through strata | layers; depth; history | geology; a city's underground; a software stack |
|
|
64
|
+
| Switch boards (a second diorama) | before/after; here vs there | two cities; two eras; two designs |
|
|
65
|
+
|
|
66
|
+
Framing: the subject ≥ 1/3 of frame height at key moments; labels never cover it; the subtitle zone stays clear. One continuous take is one option; a cut to a new board or an inset is another.
|
|
67
|
+
|
|
68
|
+
## 7. Sound palette
|
|
69
|
+
|
|
70
|
+
- **Music**: acoustic and light: kalimba, marimba, nylon guitar, pizzicato, woodblock and hand percussion (shaker, bongo, cajon), upright or synth bass, glockenspiel, toy piano, or a clean electronic pulse for technical systems. A short motif can mark the subject each time it appears.
|
|
71
|
+
- **Techniques (options)**: one sound per icon as numbers fill; instruments dropping out and a low-pass closing as the camera dives; J-cuts (the next station's sound 0.5 s before it appears); one note per station during a final pull-back.
|
|
72
|
+
- **Ambience beds per station**, crossfaded (wind and birds, harbour, sea, city hum, machine room, crowd murmur).
|
|
73
|
+
- **Foley by material**: fibre snap, fleshy thud, grains pouring, granular rattles, inharmonic steel partials for containers, paper tear, ceramic plink, liquid pour with rising pitch, servo whine, keyboard clicks.
|
|
74
|
+
- **Silence**: digital zero or one faint sound; the first sound after it should be one of the most important in the film.
|
|
75
|
+
- **Mix**: music ducked ~8 dB under voice, ambience ~7 dB; keep high-band beds (2.5–7 kHz) very low under speech or whisper mishears words. Final −14 LUFS.
|
|
76
|
+
- **Voice**: clear, friendly explainer; short lines.
|
|
77
|
+
|
|
78
|
+
## 8. Native moves
|
|
79
|
+
|
|
80
|
+
A menu: use the ones your story needs.
|
|
81
|
+
|
|
82
|
+
- **Cutaway.** Cut line, skin slides away, hatched rims remain. *Fits content like:* a heart's chambers; a server rack; a beehive.
|
|
83
|
+
- **Isotype number.** Identical icons in a new arrangement each time (a calendar, a bar, a silhouette formed by the icons themselves). *Fits content like:* votes in an election; litres of water per product; users of an app.
|
|
84
|
+
- **Focus + context.** Everything greys except the subject. *Fits content like:* one patient in a hospital; one packet in a network; one tree in a forest.
|
|
85
|
+
- **Frame within the frame.** A leader grows into a circular inset with a close-up. *Fits content like:* a chip on a circuit board; a worker's hands; a crack in a bridge.
|
|
86
|
+
- **Scale reveal.** Pull back until every label is on screen and the last frame is a finished infographic. *Fits content like:* how a city is powered; a school's day; a festival site.
|
|
87
|
+
- **Tracked subject.** One object followed with a "you are here" ring. *Fits content like:* a letter through the post; a drop through a water plant; a vaccine dose.
|
|
88
|
+
- **Strata cross-section.** The board's edge becomes the story (layers added or removed). *Fits content like:* a mine; an archaeological dig; a building's floors.
|
|
89
|
+
|
|
90
|
+
## 9. Pitfalls of the medium
|
|
91
|
+
|
|
92
|
+
- Newell normals depend on vertex order: faces get culled as back faces → give every face an outward hint and flip the normal to match before culling.
|
|
93
|
+
- Painter sorting breaks on composites → draw them as one ordered item; add depth bias for overhangs.
|
|
94
|
+
- Semi-transparent moving solids look like ghosts → motion only, no alpha.
|
|
95
|
+
- A hull or wheel touching the wrong surface reads as an accident → leave visible clearance.
|
|
96
|
+
- World geometry behind a close-up becomes giant discs → skip detail above a zoom threshold, paint a flat backdrop behind hero layers.
|
|
97
|
+
- A pull-out through a tall object gives one ugly frame → fade tall objects in by zoom.
|
|
98
|
+
- Hidden jumps (a time or place change during a dive) must be drawn in screen space anchored on the tracked subject, so the frame doesn't reveal the jump.
|
|
99
|
+
- An object drawn with the wrong silhouette reads as something else (a white box with a red roof is a house) → give machines their tell-tale parts.
|
|
100
|
+
|
|
101
|
+
## 10. Engine
|
|
102
|
+
|
|
103
|
+
`demo/engine.js` is dependency-free Canvas 2D: `Iso` (projection, camera, depth-sorted queue: `box`, `prism`, `cyl`, `cone`, `roof`, `sphere`, `flat`, `line3`, `bill`, `text3`, `push/pop` local frames, `desat` + `keep` one-colour hook), `tri()` three-tone generator, `pin`, `inset`, `cutLine`, `hatch`, `ring`, `ICON.*` + `iconGrid`, `person`, and `shape()` which turns any 2D outline into a shaded isometric solid. API table and a minimal example (a shape the demo never uses): [DEMO.md](DEMO.md) "Engine reference".
|
|
104
|
+
|
|
105
|
+
## 11. Variation space
|
|
106
|
+
|
|
107
|
+
You decide the system, the board (or several), whether there is a tracked subject, the numbers, the camera path, the opening and the ending. All far from our demo:
|
|
108
|
+
|
|
109
|
+
- Structures: **one building, floor by floor** (a tilt down through a cutaway tower, each floor a step); **two boards compared** (the same system in two places or eras, alternating, then side by side); **a cycle** (a loop route that returns to its start with one number changed each lap).
|
|
110
|
+
- Openings: **the finished infographic**, which then comes apart into its moving parts; **one icon** that multiplies until it becomes the landscape; **a question written as an isometric title** on an empty board.
|
|
111
|
+
- Endings: **an unanswered station** (the route stops at an empty plate with a question mark); **the legend alone**, the board faded out; **a close-up of a single icon**, the whole number behind it out of focus.
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Isometric Picture Book — Style Prompt
|
|
2
|
+
|
|
3
|
+
> A calm explainer of an everyday rule, set in one real place drawn in true isometric with flat colour: small faceless people seen from behind do the thing in order, while serif type lands on the ground, character by character, as if painted there. Whatever hides the action (a roof, a wall) is cut away or lifts off like a paper flap. The order of movement is the explanation.
|
|
4
|
+
> References (grammar only): isometric explainers about public manners (queues, platforms, crossings) and picture-book cutaways where a roof or a wall is lifted away to show the inside. Take the calm pacing, people as the diagram and type on the floor; never copy their characters, layouts, typefaces or music.
|
|
5
|
+
|
|
6
|
+
## 1. Essence, and what it is not
|
|
7
|
+
|
|
8
|
+
- **One real place, full bleed.** A platform, a gate, a cabin, a crossing, a counter: the ground runs off every edge of the frame. No floating board, no frame line, no vignette. A topic that travels (a parcel, a route, a production line) can still be one place: one continuous ground at one scale, with the stops along it (see §11); what breaks the look is a separate board, a map view or a change of scale for each stop.
|
|
9
|
+
- **People are the diagram.** Slim figures seen from behind, no faces and no hands, move only when the rule says so. Who moves first, who waits, who sits is the information.
|
|
10
|
+
- **Type lies on the ground.** Each idea is one key word or number painted on the floor, big and small sizes, one accent character, landing one character at a time.
|
|
11
|
+
- **The cut-away.** Whatever stands between the camera and the action (a roof, a canopy, the top of a wall, a glass façade) is cut low or lifts off like a paper flap, so the camera always looks into the place from above.
|
|
12
|
+
- **Clean, always.** One place, one action, one phrase per beat. Large calm areas of ground around the type, people in tidy lines and rows, few props, every object instantly recognisable. A frame that needs a second look to find its subject is wrong.
|
|
13
|
+
|
|
14
|
+
Not **Isometric Infographic**: that style builds a model on a floating board over a dot lattice and labels it with sans-serif pins, icon statistics and inset bubbles to trace a process; here there is no board edge, no pins and no icons: the place is real and full bleed, the labels are serif words lying on its floor, and the explanation is people obeying a rule. Not **Low-poly Isometric Island**: no lighting, no faceted terrain, no shadows or glow; solids are flat three-tone paper colours and the ground is a printed plane. Not a cartoon (no expressions, no gags), not a slide (no headers, no centred titles, no cards).
|
|
15
|
+
|
|
16
|
+
## 2. Materials & rendering
|
|
17
|
+
|
|
18
|
+
- True isometric (axes at 30°), Canvas 2D, painter's sort. Every solid and every person is sorted by its **floor footprint** (x + y at floor level), never by the centre of its box: a seat back sorted by its centre height ends up drawn over the passenger sitting behind it.
|
|
19
|
+
- Solids are flat-shaded in **three tones per colour**: top lifted toward warm paper, +y face the base colour, +x face dropped toward a warm umber. Curved bodies (a fuselage, a column) are faceted and quantised to the same tones plus one in-between, so they read as round without gradients. No outlines on solids, no shadows, no textures, no highlight spots (a round tree crown or a ball is a flat disc or a faceted solid in the same tones, never a glint).
|
|
20
|
+
- **New objects** (vehicles, machines, buildings, trees) follow the same model: built from boxes, prisms and faceted solids at real size in metres, three tones from the kit's `tri()`, recognisable from their silhouette at a glance, simpler than the people. Vehicles read from the body (cab, cargo box, a band of the subject hue); wheels are small, low and mostly under the body in one dark tone, never thick drums or tyre-and-hub detail.
|
|
21
|
+
- Ground surfaces carry only their functional markings (painted lanes, chevrons, lead-in lines, stop bars, seat squares) and a faint tile or slab grid.
|
|
22
|
+
- **Cut-aways** are part of the model: the near wall is cut low and the far wall keeps its windows; a lid is its own solid with a paper-coloured underside, hinged on the far edge so it opens away from the camera; glass is a pale tint with thin mullions and is cut to a parapet whenever it would stand between the camera and type or people.
|
|
23
|
+
- **People** are billboards anchored at their feet, about 1.6–1.8 m tall: a round hair-dark head with a sliver of skin at the ear, a two-tone torso, separate trouser legs, dark shoes, optional long hair or skirt, a rolling case. Seated people show only shoulders and the back of the head above a low seat back. Walking scissors the legs along the screen; arms counter-swing.
|
|
24
|
+
- Bodies obey space: people never pass through seats, walls or each other; a queue keeps about 0.75 m between feet; someone sitting down first steps back into the row's legroom, walks sideways to the seat and sits (never sinking into or floating above it); a lifted case travels up over the open bin and is lowered in, never into a wall or a seat.
|
|
25
|
+
- Everything is a function of time. A crowd that queues is simulated once at load (deterministic) and **sampled with interpolation**, so replaying it slowed down still moves every frame.
|
|
26
|
+
|
|
27
|
+
## 3. Colour logic
|
|
28
|
+
|
|
29
|
+
- A warm paper neutral for every ground (outdoor concrete a touch cooler, indoor carpet a touch warmer), one dark ink, **one accent reserved for the rule** (the key character, the "stand here" outline, arrows, a lit sign, the winning number, a stretch of floor that matters), one **subject hue** carried by the place itself (seats, livery bands, chairs in a paler tint, sign trim), one marking colour (lead-in lines, a tug, a baggage tractor). People wear four muted tops, so a filled room reads as an even four-colour weave.
|
|
30
|
+
- The accent never decorates; it appears only where the rule is. It stays small because its rarity is what makes the eye go to it: many frames carry none at all. A path in the accent marks the stretch being explained now (it grows ahead of the walker or the vehicle and fades behind it), not a trail left across the whole film.
|
|
31
|
+
- The subject hue and the marking colour must be clearly apart, in hue and in value, from the four tops: people have to stand out from the place they move through (a blue-green place swallows fog-blue people).
|
|
32
|
+
- Shade toward warm umber and paper, never toward grey or violet: dirty shadows are the fastest way to lose this look.
|
|
33
|
+
- Example palette: paper #F1E8D8, concrete #EAE2D3, carpet #F2E5CE, ink #2A2E29, accent persimmon #D0573A, subject green #3D6B59 / #A7C2B2, marking ginger #E2AE3A; tops ochre, fog blue, grey violet, oat.
|
|
34
|
+
|
|
35
|
+
## 4. Type & subtitles
|
|
36
|
+
|
|
37
|
+
- Chinese: a serif (Noto Serif SC, 700 for keywords, 500 for particles); Latin and numerals: a book serif (Newsreader). Open-licence fonts only, subset to the characters used.
|
|
38
|
+
- **Floor type**: big ≈ 1.5 m on the ground, small ≈ 0.8 m; read along the up-right axis (coordinates in §10). One phrase per beat; one line where the frame is tight. One accent character or number per phrase, never a single thin stroke (一 in the accent reads as a line, not a character). Characters land ≈ 0.14 s apart: fade and scale 1.22 → 1, pale ghost → ink. A painted title or a pair of numbers may scale up to ×1.6.
|
|
39
|
+
- Type sits on clear ground: nothing stands on it, nothing raised stands in front of it (see §9), at least 5 % from every frame edge, and clear of the subtitle bar.
|
|
40
|
+
- Signs in the world (gate signs, group signs, screens) face the camera side of the room at the iso angle, never a flat card facing the lens.
|
|
41
|
+
- Reading time: every piece of world text stays fully in frame ≥ CJK/4.5 + Latin/15 + 1.5 s.
|
|
42
|
+
|
|
43
|
+
### Narration & subtitles
|
|
44
|
+
|
|
45
|
+
When the film tells something, a narrator says it and the picture shows it at the same moment: one line per action or shot, each line starting as its action starts. A calm, quick reader in the film's language; the floor carries only that line's key word or number, never the sentence. Subtitles: one cue per narration line on a pale bar in the lower safe area, one Chinese line above (≈ 34 px) and one English line below (≈ 25 px, a translation of the whole sentence), switched hard, never two cues on screen. Numbers the viewer must remember: at most three, each said with what it compares to, and held on screen ≥ 2.5 s.
|
|
46
|
+
|
|
47
|
+
## 5. Motion quality
|
|
48
|
+
|
|
49
|
+
- **30 fps, on ones** (pass `--fps 30` to the render and to `mux.sh`): crowds and walks are judged frame by frame (§9), and the check assumes this rate.
|
|
50
|
+
- People move only when the rule says so, in order; the order is the point. Walk ≈ 1.5 m/s; nobody moves faster than about 3 m/s on screen, even in a time-lapse: when a process must be compressed, show it as places filling (people settling into their seats) rather than people zipping past.
|
|
51
|
+
- Everything eases; nothing pops. A beat = one floor phrase + one diagram mark (an outline traced, an arrow grown ahead of the walkers, a light run along a path) + one action.
|
|
52
|
+
- A rewind runs the same motion backwards, faster, with a counter running down.
|
|
53
|
+
|
|
54
|
+
## 6. Camera grammar
|
|
55
|
+
|
|
56
|
+
| Move | What it expresses | Can serve |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| slow drift and push (≈ 6–8 % zoom) | calm attention on one rule | a call, a waiting room, a hold to read |
|
|
59
|
+
| follow the head of a line | the order of things | a corridor, a boarding, a procession |
|
|
60
|
+
| travel along the ground at the subject's pace | one place after another on the same road | a delivery, a parade route, a line of workshops |
|
|
61
|
+
| rise to wide while a lid opens | revealing a space whole | an interior, a capacity, a grid of places |
|
|
62
|
+
| locked frame | judging, reading | a verdict, a comparison, the last frame |
|
|
63
|
+
| step back to frame one whole incident | cause and effect in one view | one person blocking, one door jamming |
|
|
64
|
+
| tilt down from outside to the people | arrival, cause → people | an opening, a change of place |
|
|
65
|
+
| scale jump (room → building → site) | the result in context | a verdict, an ending |
|
|
66
|
+
|
|
67
|
+
The angle never changes (iso is fixed); camera moves are translation and zoom. Every move is motivated by the action, and text and subject stay inside the frame at both ends of it. Transitions: a continuous move, a lid opening, a run back along the same path, or a cut on the beat at the same angle. No page turns, wipes, black or blank frames; a pull-out shows its next subject (a mark being drawn) within half a second. A lid is a reveal only while it is seen: it finishes turning, paper side up, inside the frame before it glides off away from the camera.
|
|
68
|
+
|
|
69
|
+
## 7. Sound palette
|
|
70
|
+
|
|
71
|
+
Soft upright piano and vibraphone; a vibraphone note per landing character (keywords louder, the accent doubled on glockenspiel); pizzicato and shaker when people walk. Repeated actions become rhythm: a stuck queue is broken pizzicato stabs, an orderly one is one chord per group. Quiet place beds (hall air, cabin air, distant engines) and a sustained low string root overlap every cut so no scene change drops out; functional sounds of the place (a home-made chime, wheels on carpet and on metal, bin lids, a tug). A rewind plays the last second of music backwards. With narration, the music ducks about 16 dB under the voice and lifts between lines; mix ≈ −16 LUFS before mux, true peak under −1.5 dBFS.
|
|
72
|
+
|
|
73
|
+
## 8. Native moves
|
|
74
|
+
|
|
75
|
+
- **Floor type.** The key word lands on the ground beside the action. *Fits content like:* a hospital triage rule; a polling-station step; a library's quiet zone.
|
|
76
|
+
- **Domino stand-up.** The group called sits together and rises one by one from the near end into a painted lane. *Fits content like:* an exam hall emptying by row; a ferry deck released lane by lane; a classroom drill.
|
|
77
|
+
- **Lid off.** A roof flips open on its far hinge, paper side up, and glides away; the camera rises to see the whole inside. *Fits content like:* a bus at a depot; a lecture hall; a container being packed.
|
|
78
|
+
- **Order lighting.** Places light up one by one in the order they will be used, before anyone moves. *Fits content like:* seat assignments; a parking plan; a vaccination queue by number.
|
|
79
|
+
- **Order arrows.** A flat accent arrow grows ahead of the walkers and branches where each one turns. *Fits content like:* escalator lanes; recycling bins by type; a one-way museum route.
|
|
80
|
+
- **Weave fill.** Places fill in a pattern (every other, window first) so the room becomes a woven grid in four colours. *Fits content like:* a stadium by sections; a cinema with assigned seats; a car park by level.
|
|
81
|
+
- **Bars on the ground.** Two quantities painted as strips on the floor in proportion, the difference marked by a dashed bracket after a still hold. *Fits content like:* two queue times; two routes' lengths; before and after a change.
|
|
82
|
+
- **People as the sample.** The people of a study stand on the ground in the shape of the thing they tested. *Fits content like:* a 72-person boarding test; a class of 30 in their desk plan; a jury in their box.
|
|
83
|
+
- **Stand here.** An accent outline or a lit stretch of floor marks the spot that matters. *Fits content like:* where to wait for a lift; the jammed stretch of an aisle; the right queue at a counter.
|
|
84
|
+
|
|
85
|
+
## 9. Pitfalls of the medium
|
|
86
|
+
|
|
87
|
+
- Anything raised by H metres hides what lies behind it (toward −x behind a face that looks +x, toward −y behind a face that looks +y): floor up to H metres back from a long edge, and a person standing there loses everything below the edge's top, vanishing completely within H − 1.7 m. It holds for low objects too: a 0.8 m belt or counter covers floor type 0.8 m behind it, a 3.2 m truck side hides people's legs up to 3.2 m behind it and whole people within 1.5 m, a glass wall or a wing hides type metres away. Keep type and the people who matter on the camera side of tall objects, or cut those objects down; check every frame in which a vehicle passes.
|
|
88
|
+
- A path that zigzags (turning at every vehicle or doorway) reads as noise; routes run along the world axes with few right-angle turns, and the walker or vehicle on them heads away from the camera (see the back-view pitfall below).
|
|
89
|
+
- A crowd folded into a serpentine reads as a solid block; one straight line reads as order. Numbers on the floor beside each person need spacing wide enough for the label (about 1 m).
|
|
90
|
+
- People walking toward the camera show a back view that looks wrong; route walks up-left, up-right or across.
|
|
91
|
+
- Seated people disappear behind high seat backs: keep backs low enough that shoulders show.
|
|
92
|
+
- Sorting boxes by their centre and people by their feet puts furniture over people (see §2).
|
|
93
|
+
- Colours passed to the engine as a bare hex string are shaded by `engine.js`'s own `tri()`, which darkens toward violet; always pass `kit.js`'s `tri(colour)` (warm umber). `iso.sphere` adds a white glint unless given `{ hi: false }`.
|
|
94
|
+
- A simulated crowd sampled by rounding to frames steps on and off when replayed slowly; interpolate. Compressing a long process by moving people faster than ~6 m/s (0.2 m per frame) reads as teleporting.
|
|
95
|
+
- A camera move can drag a sign or a word across the frame edge, and background details (a far sign, a row of labels) can appear half-cut at the edge of another shot: anything meant to be read needs both ends of the move checked, and background text belongs only to its own shot.
|
|
96
|
+
- Check a crowd film frame by frame, not by eye: `demo/tools/motion_check.mjs` renders every frame at 30 fps and lists jumps, stop-start stepping and people standing closer than a body width, from positions the film reports through a one-line hook (documented in the tool); copying it is in §10.
|
|
97
|
+
|
|
98
|
+
## 10. Engine
|
|
99
|
+
|
|
100
|
+
**Copy as they are** into the project folder (they hold no demo content): `demo/engine.js`, `demo/kit.js` and `demo/tools/motion_check.mjs`. `kit.js` re-exports what you need from `engine.js`, so a film imports from `kit.js`. `main.js` and `index.html` are a short page shell (fonts loaded, then `window.DUR`, `SHOTS`, `TEXTS`, `render`, `READY`, as `core/README.md` describes) to rewrite with your own fonts and characters.
|
|
101
|
+
|
|
102
|
+
**Demo-only, read for technique, don't reuse as props:** `plane.js` (a lofted fuselage, a cut-away cabin, a hinged flap `lid` / `lidMap`), `places.js` (apron markings, a glass wall that drops to a parapet, painted lanes, signs, chairs), `film.js` (a timeline built from narration line lengths, a deterministic queue simulation sampled with interpolation, sitting and stowing, `texts()` for readcheck).
|
|
103
|
+
|
|
104
|
+
**What the kit gives:**
|
|
105
|
+
- World: metres; x runs down-right on screen, y down-left, z up; depth toward the viewer is x + y + z. `kit.js` exports one shared `iso`: set `iso.g = g` and `iso.cam = { x, y, z, k }` each frame (k = pixels per metre; the camera only translates and zooms).
|
|
106
|
+
- Solids: queued `iso.box(x, y, z, w, d, h, tri(c), o)`, `prism(footprint, z, h, …)`, `cyl(…, { axis })`, `cone`, `roof`, drawn by `iso.flush()`; `*Now` versions draw at once (inside a cut-away, between back and front walls). `o.bias` corrects the sort: the queue sorts by the box's centre, people by their feet, so a solid that should sort by its footprint gets `bias = −(z + h/2 − floor height)`. `o.faceColor`, `o.decal` for a lit face or markings on it.
|
|
107
|
+
- `facet(g, pts3, tri, { out })`: any flat polygon in metres, toned by its normal (`out` points outward), for curved bodies and lids.
|
|
108
|
+
- `onPlane(g, x, y, z, plane, fn)`: draw in metres on a plane: `'xy'` floor (u = −y, v = +x), `'yz'` wall facing +x (u = −y, v = −z), `'xz'` wall facing +y (u = +x, v = −z). Markings, signs, windows and screens go through it.
|
|
109
|
+
- Floor type: `phraseLayout(P)` with `P = { x, y, z, t0, t1, step, scale, lines: [[[text, kind], …], …] }` (kinds: `B` big ink, `A` big accent, `s` small, `n` / `na` / `ns` numerals, `e` / `en` Latin), then `floorType(g, t, P, L)` every frame. The first line's baseline lies along x = P.x and reads from y = P.y toward −y (up-right); its glyphs fill x ∈ [P.x − size, P.x], and later lines step toward +x. `phraseWorld(P, L)` returns the floor rectangle (keep it clear, §4 and §9), `phraseBox(P, L)` the screen box for `texts()`.
|
|
110
|
+
- People: `iso.bill(x, y, floor z, gg => drawPerson(gg, p, pose))` with `p = { h, top, legs, skirt?, hairLong?, bagc? }` (tops and legs from `TOPS` / `LEGS`) and `pose = { walking, phase, bag, lift }` (walk, rolling case, case raised overhead); `drawSeated(gg, p)` for shoulders and head above a seat back. Push `globalThis.__POS?.push({ i, k: 'w' | 's', x, y, a })` where each person is drawn, for the motion check.
|
|
111
|
+
- `subtitles(g, t, cues)` (two lines, hard switch) and `subtitleBox()` for the margin check; `tri()`, `C`, `mix`, easing (`ss`, `eo`, `eio`, `seg`).
|
|
112
|
+
|
|
113
|
+
**What a new topic builds itself:** the place (its ground, markings, cut-away buildings), its vehicles and machines (§2), and any pose beyond walking, carrying a case and sitting. A pose is made like `drawPerson`: a billboard in metres, back view, no face or hands, parts as flat shapes in the top's three tones (a rider, for example, is the seated torso raised to the saddle with two leg quads that swap with the pedal phase). A lid on any building is a `facet` roof turned about its far edge, as `lidMap` does.
|
|
114
|
+
|
|
115
|
+
**Motion check:** in the copy of `motion_check.mjs`, point the `page.mjs` import at the library's `core/render/page.mjs` (from `films/<name>/tools/` that is `../../../core/render/page.mjs`; outside a clone, an absolute path), then `node <project>/tools/motion_check.mjs <project> --fps 30` from the library root.
|
|
116
|
+
|
|
117
|
+
Minimal example, not in the demo: a lift lobby with two painted lanes, `floorType()` with 先下后上 on the floor, people billboards stepping out of a box car before the waiting line steps in.
|
|
118
|
+
|
|
119
|
+
## 11. Variation space
|
|
120
|
+
|
|
121
|
+
The agent decides the place, its cut-aways, the cast size, the rules and their order, the narration, the camera path, the pacing and the palette within the colour logic.
|
|
122
|
+
|
|
123
|
+
- Structures: one rule shown right once; the same group doing it two ways and compared (rewind between); a day in one place as five small rules; one thing travelling through several stops, one small rule each.
|
|
124
|
+
- A travelling topic is one way among others to stage, not a required form. One option: lay the stops along one continuous street, yard or hall, each a cut-away building or a marked stretch of the same ground, and join them with the travelling move, a run back along the path, or a cut on the beat at the same angle; keep each stop to one action and one floor phrase.
|
|
125
|
+
- Openings: the place empty, then people arrive; the title painted on the ground as the first person walks over it; a tilt down from the building to the room.
|
|
126
|
+
- Endings: the place empty again with the rule left on the floor; a scale jump out to the building; the last person stepping onto the outlined spot.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
How our demo was made (story, shots, narration, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Constructivist Montage — Style Prompt
|
|
2
|
+
|
|
3
|
+
> Real archive footage, photographs and documents, printed as one ink-and-paper poster with a single red, and cut on a machine beat. Diagonal bands carry the type; windows cut along the axis hold the film; people are scissored out of photographs and stacked into structures; numbers count, documents are marked in red, and two images collide to make a third idea.
|
|
4
|
+
> References (grammar only): Soviet montage cinema of the 1920s (city symphonies with split screens, counting and machine rhythm; "intellectual" montage where A + B yields a concept), constructivist posters and photomontage (red / black / paper, steep diagonals, photo cut-outs with geometric blocks, type as structure). Never copy their shots, layouts, slogans or lettering, and never name them in the film.
|
|
5
|
+
|
|
6
|
+
## 1. Essence, and what it is not
|
|
7
|
+
|
|
8
|
+
1. **Evidence, recut.** Every picture is real material (archive film, photographs, documents) about the actual subject. The film's argument comes from how they are cut and set, not from illustration.
|
|
9
|
+
2. **One printed sheet.** All material is converted to the same two-tone print (warm ink → paper); red is the only colour and is laid on top as a printed element.
|
|
10
|
+
3. **The beat is the editor.** Cuts, slams, wipes and counts sit on a 120 BPM grid (or the score's tempo); sections accelerate by halving shot length.
|
|
11
|
+
4. **Type is structure.** Words and numbers are beams: on a −18° band, as solid blocks, stacked vertically. Never floating captions.
|
|
12
|
+
5. **The collective over the individual.** Crowds, hands, machines and many small figures; a single face is never the protagonist.
|
|
13
|
+
|
|
14
|
+
Not **Data Storytelling** or a keynote: no centred headline with bullets, no slide transitions, no header bars; data appears as marked documents, counters and measured bars inside the composition. Not **Swiss Motion Graphics**: asymmetric, diagonal, no grid of white space, no thin rules as decoration. Not **Art Deco** or **60s Spy Titles**: no gold, no fine lines, no jazz. Not a museum slideshow: archive material is never shown "as is" in a neutral frame; it is cut, windowed, stacked and counted.
|
|
15
|
+
|
|
16
|
+
## 2. Materials & rendering
|
|
17
|
+
|
|
18
|
+
- **Four kinds of element only**: **bands** (red or ink, along the axis), **windows** (rectangles or parallelograms holding film or photographs), **cut-outs** (people scissored from photographs with a paper-white border), **type blocks**. Plus one paper-fibre texture over everything.
|
|
19
|
+
- **The print grade** (one function for film, photos and documents): luminance → percentile stretch (film: one pair of percentiles per clip, so it never pumps; 0.7 / 99.5; photos 0.8 / 99.4) → S-curve `x + s·(x−0.5)·(1−|2x−1|)·2`, s = 0.32 (documents 0.18, they keep their paper) → map to ink→paper: `rgb = INK + (PAPER − INK)·g`. Archive film keeps a ±2.5 % per-frame flicker inside its window (`hash(frame)`), photographs and documents do not.
|
|
20
|
+
- **Cut-outs**: a person-segmentation model (u2net_human_seg via onnxruntime) → threshold 0.5 → median filter → largest component → 7 px paper border dilated outside the mask. The border is the medium's own look and hides the model's edge errors. Group photos rarely segment cleanly: use them whole in windows.
|
|
21
|
+
- **Documents**: scans at full resolution, never retyped. They are marked: a red highlighter bar in `multiply` over the exact sentence, a hand-drawn red ellipse round a heading, a red circle on a map. Drawings on a document (a chart, a map) may be lifted off the page and reused, keyed from their paper (`alpha = (205 − luminance) / 90`).
|
|
22
|
+
- **Resolution ceiling**: archive film ≤ 2.5× its source pixels on screen, modern footage ≤ 1.5×, photos ≥ 1 source px per screen px where possible. Prepare clips with `hqdn3d → lanczos → light unsharp` before grading; add grain only in the mux. A 720-line film transfer can fill a 1,700 px window, not a full 1080p frame: frame it (a window, a split strip, an iris) instead of stretching it.
|
|
23
|
+
- **Paper fibre**: a fixed seeded noise canvas multiplied over the frame at α 0.5; film grain 4 added by `mux.sh`.
|
|
24
|
+
|
|
25
|
+
## 3. Colour logic
|
|
26
|
+
|
|
27
|
+
| Role | Value | Use |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| Red | `#D52B1E` | bands, wedges, blocks, the key number, marker bars, circles and leaders, the one winner in a comparison |
|
|
30
|
+
| Ink | `#141210` | type, beams under each floor, window borders, dark grounds |
|
|
31
|
+
| Paper | `#EDE4D0` | ground, reversed type, cut-out borders |
|
|
32
|
+
|
|
33
|
+
- Everything photographic is ink-on-paper; nothing else has colour. Red is never laid on red: a red block on a red ground becomes ink.
|
|
34
|
+
- Alternate grounds to make cuts land: paper scene → ink scene → paper. In an acceleration the background itself alternates red / ink per cut.
|
|
35
|
+
|
|
36
|
+
## 4. Type & subtitles
|
|
37
|
+
|
|
38
|
+
| Use | Face | Size (1080p) |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| Chinese display, slogans | Noto Sans SC 900 (subset) | 110–210 px; stacked vertically 170 px per character |
|
|
41
|
+
| Numbers, English display | Oswald 600–700 | numbers 230–440 px; English lines 30–62 px, letter-spacing 2–10 px, capitals |
|
|
42
|
+
| Source and footage tags | Space Mono Bold (CJK falls back to Noto) | 17–18 px on an ink or red tab, padding 6 |
|
|
43
|
+
| Subtitles | Noto Sans SC 700 40 px over Oswald 500 28 px | bottom left, ink bar at 90 %, a 10 px red tick |
|
|
44
|
+
|
|
45
|
+
- **Bilingual pairs**: Chinese block, then one English line in Oswald directly under it (or on the neighbouring band). Each language one line, measured.
|
|
46
|
+
- **Placement**: along the −18° axis on a band, or as an ink / red block; never centred on the frame, never a header. Numbers can be bigger than the words that explain them.
|
|
47
|
+
- **Tags**: every archive window carries its footage tag (`FILM · <TITLE> · <PLACE> <YEAR>`, `PHOTO · <AUTHOR> <YEAR>`), every fact a source tag (`来源 · <PUBLISHER> <YEAR>`). If the footage is not of the subject itself, the tag says what it really is.
|
|
48
|
+
- **Subtitles** stay bottom-left in a 960–1056 px strip; key type keeps above y 930 while narration runs. Subtitles hold ≥ max(1.8 s, speech + 0.6 s). On-screen text follows `readcheck.mjs` (CJK ÷ 4.5 + other ÷ 15 + 1.5 s, fully in frame); a comparison holds every item ≥ 2.5 s before its verdict.
|
|
49
|
+
|
|
50
|
+
## 5. Edit grammar
|
|
51
|
+
|
|
52
|
+
- **Grid**: one tempo for picture and score (120 BPM: beat 0.5 s, bar 2 s). Every cut, slam, wipe and count lands on a beat, half-beat or sixteenth. The page exports these times as `window.EV`; the mix reads the same list.
|
|
53
|
+
- **Shot length**: 0.5–2 s for footage; one idea per shot. A section may accelerate by halving: 0.5 → 0.25 → 0.125 s (never shorter than 3 frames). Holds are reserved for reading: a text block, a freeze, a comparison.
|
|
54
|
+
- **Cut rule**: adjacent shots conflict in at least one of direction (left slam / right slam), value (paper / ink ground), or geometry (diagonal band / upright window). Never two paper documents in a row.
|
|
55
|
+
- **Nothing static for more than a second**: inside a hold something moves (film in its window, a counter, a slow push, a frame-within-the-frame). Planned exceptions only: the comparison hold, one silence beat, the end card.
|
|
56
|
+
- **Transitions inside the medium** (pick per cut, don't fade):
|
|
57
|
+
- *red wipe*: a 260 px red band at 72° (perpendicular to the axis) sweeps the frame in 0.25 s, the next scene revealed behind it; it lands on the downbeat;
|
|
58
|
+
- *iris*: a red marker circle drawn on a map or photo becomes an aperture and opens onto footage;
|
|
59
|
+
- *slam*: the next element arrives from outside along the axis in 0.08–0.2 s, ease-out, hard stop, frame shake (amplitude 3–18 px, `exp(−14·Δt)`);
|
|
60
|
+
- *flash cut*: one frame of 50–80 % paper over a window at a cut or freeze;
|
|
61
|
+
- *hard cut on the beat* between grounds of opposite value;
|
|
62
|
+
- *jump-in*: inside a freeze, a cut to a 1.2× crop of the same frame, the annotation scaling with it.
|
|
63
|
+
- **Two silences**: one where the orchestra stops and only an original recording remains, and one true half-bar of nothing (ink frame, one red dot) before the heaviest hit.
|
|
64
|
+
|
|
65
|
+
## 6. Formats (each is a function in `demo/index.html`)
|
|
66
|
+
|
|
67
|
+
| Format | How it looks | How it is built |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| **Title package** | a red band slams along the axis; a window cut to the band's edge runs footage; digits stamp one per eighth, the CJK unit in red | `S1`: window clipped to the band's top edge (`onBar`), digits measured and slammed individually, `reg()` registers the group for readcheck |
|
|
70
|
+
| **Lower third** | a red bar from the left edge with Chinese, an ink tab with the English | 92 px bar at y ≈ 760–850, slams in 0.14 s, slides off with the next transition |
|
|
71
|
+
| **Map + iris** | a document map pushes in, a red circle is drawn round the place, the circle opens onto the site | `mapXf()` (scale / focus / angle over time), `mapToScreen()` keeps the circle on the map point; aperture = `arc` clip whose radius grows to the frame |
|
|
72
|
+
| **Vertical title** | CJK characters stacked top to bottom beside a tall window, English rotated 90° | per-character slams 1/16 apart |
|
|
73
|
+
| **Date on a girder** | the date in paper on a red band crossing the footage | text placed on the band's centre line (point + normal offset), rotated by the axis |
|
|
74
|
+
| **Grid** | 3 × 3 windows light one per sixteenth in a spiral, the centre counts 1…9 and lights last in red | cells `back()`-scale in, each a different clip at 1.4–1.8× speed, ping-pong |
|
|
75
|
+
| **Split strips** | the frame rotated to the axis, three strips of two panels each; one panel changes per beat; strips drift in opposite directions | panels ≤ 1,160 px wide so the film stays ≤ 2.5×; red seam on the middle strip |
|
|
76
|
+
| **Freeze + annotation** | flash, freeze, push; a red ellipse drawn on the object, a leader to a red block with the number; a jump-in; the film keeps running in a small red-framed inset | the circle is computed from the zoom focus so it follows the jump; inset = same clip, live |
|
|
77
|
+
| **Document close-up** | a tilted page slams in, a red marker bar crosses the exact sentence, a red block repeats the number huge | marker in `multiply` over the scan's own line coordinates; a tall slot beside it runs footage fast to show speed |
|
|
78
|
+
| **Process staircase** | three windows rising along a diagonal, red triangles between them, a counter climbing to the claim | each window 0.75 s apart; the counter is graphic, only its end value is a fact |
|
|
79
|
+
| **The question** | a document heading on an ink ground, circled in red; a huge red "?" | heading cropped tight so only the words that matter show |
|
|
80
|
+
| **Acceleration + count** | full-frame windows tilted ±4–6°, ground alternating red / ink, a four-digit counter jumping per cut | cut list with shrinking durations; the original sound plays alone |
|
|
81
|
+
| **Multiple exposure** | top-down footage, a second clip in `screen` at 45 %, cut-outs in `multiply`, the answer in a block | exposure window ≤ 1,700 px on a red ground |
|
|
82
|
+
| **Chart from the document** | the page turns 90°, its drawings lift off and stand on one ground line to scale, red dimension lines, numbers, names; held; then the verdict block | outlines keyed from the scan, scaled so tip-to-ground = value × px per unit; the winner tinted red (`source-in`) |
|
|
83
|
+
| **Photomontage tower** (signature) | floors of footage strips slam in from alternate sides every sixteenth, an ink beam under each, a cut-out worker lands on every other; the camera climbs; a crown and a figure on top | `FLOORS` list, camera `y` follows the eased count of built floors; the floor counter runs to the dated anchor, **rests there while its caption is up**, then runs on to the end value |
|
|
84
|
+
| **Silence beat** | ink frame, one red rivet | half a bar; the score and foley are gated to zero |
|
|
85
|
+
| **Result composition** | huge numbers left, a tall slanted window with the finished subject (camera tilts up it), a tilted photo, a red wedge | numbers slam, the last line restamps the key number on red |
|
|
86
|
+
|
|
87
|
+
## 7. Sound palette
|
|
88
|
+
|
|
89
|
+
- **Score**: an original machine ostinato (eighths, minor, e.g. D–D–F–D–A–D–E–F) in spiccato cellos + staccato bassoon, staccato tuba / trombone on the beat, snare sixteenth taps, xylophone for counts (one rising note per lit cell or built floor), horn / trumpet stabs and a short brass motif, timpani rolls into section changes, gran cassa + gong on the heaviest hit. Sampled CC0 libraries (VSCO 2 CE, VCSL). No piano-and-strings bed.
|
|
90
|
+
- **Original sound alternates with music**: in one section the orchestra stops and a real recording (a rivet gun, a machine, a crowd) carries the cut alone, each burst trimmed to its shot. Bring it in a beat early (J-cut).
|
|
91
|
+
- **Foley for every printed action**: slam = low thump + steel clank; stamp = thump + clack; wipe and iris = whoosh; marker = filtered noise scrub; paper = band-passed rustle; floors and cells = pitched clanks.
|
|
92
|
+
- **Layers**: ambience (a real site / street recording, about 20 dB under the voice, out for the silence), foley ducked 35 % under speech, music ducked 70 % under speech (≈ 10 dB under the voice), narration compressed and levelled by RMS. Master to −14 LUFS with the peaks limited to −1.8 dBFS before `mux.sh`, and a 25 ms fade at sample 0 (an AAC encode overshoots on a hit at the first sample).
|
|
93
|
+
- **Narration** (when the film has one): short declarative lines, newsreel cadence, never more than one sentence over a format; numbers spelled out for TTS, digits in subtitles.
|
|
94
|
+
|
|
95
|
+
## 8. Native moves
|
|
96
|
+
|
|
97
|
+
1. **The document is marked, not quoted**: the actual sentence on the scan gets a red bar; the number then becomes a red block.
|
|
98
|
+
2. **The document becomes the chart**: drawings printed on a page are lifted off, turned and stood on a ground line to scale.
|
|
99
|
+
3. **A + B → idea**: two kinds of image alternate faster and faster (the machine / the hands; a heading / the people it leaves out) until a card or a number states what the collision meant.
|
|
100
|
+
4. **Count the many**: a counter driven by the cuts, a grid that fills cell by cell, a tower floor by floor.
|
|
101
|
+
5. **People build the structure**: cut-out figures stacked into the thing they made (photomontage).
|
|
102
|
+
6. **Silence, then the heaviest hit** into the result.
|
|
103
|
+
|
|
104
|
+
## 9. Footage
|
|
105
|
+
|
|
106
|
+
1. **Ask first.** Before searching, ask the user for their own material: film, video, photographs, scans of documents (reports, brochures, letters, minutes), data. What they give leads; archives fill gaps.
|
|
107
|
+
2. **Where to look, and how to judge the licence** (`demo/tools/footage.py` searches, downloads and records licence, author and source page into `SOURCES.jsonl`; `footage.py md` writes `SOURCES.md`):
|
|
108
|
+
- **Internet Archive**: read each item's `licenseurl` and description. Public Domain Mark / CC0 / CC BY are usable; *no licence field* is not. For a pre-1978 US film, check the title and end cards for a copyright notice: published 1930 or earlier = public domain in the US by date; published without notice before 1978 = public domain; with a notice, check renewal. Corroborate date and producer elsewhere (a library catalogue, an archive exhibit). Avoid YouTube mirrors, re-uploads with no provenance, colourised or "restored" versions.
|
|
109
|
+
- **Wikimedia Commons**: read the file page's licence and its source institution. Public domain, CC0, CC BY (credit in full) are usable; CC BY-SA is not used in library demos.
|
|
110
|
+
- **US National Archives (NARA)**, **Library of Congress**, **NASA**, other US federal agencies: federal works are public domain; check each item's rights statement. "No known restrictions" (LOC, Flickr Commons) is **not** clear enough: name it to the user or find the same image elsewhere with a clear statement.
|
|
111
|
+
- **Museums with open access** (Met, Rijksmuseum, Smithsonian): CC0 where the object page says so; check that the item is still marked open access.
|
|
112
|
+
- **University and city libraries** (e.g. Columbia's digitised ephemera on the Internet Archive): use their rights statement; "copyright status undetermined" is not usable.
|
|
113
|
+
3. **Tell the user before downloading**: what (title, years), from where (URL), under which licence and why. Keep `raw/` under about 1.5 GB; download serially (Commons rate-limits).
|
|
114
|
+
4. Record every asset with the seconds used (`footage.py used <name> "<source s> → film s"`), list it in `demo/CREDITS`, and keep the trail for anything judged "no notice".
|
|
115
|
+
5. Footage that is not of the subject itself (another city, another year) may stand in only with a tag that says exactly what it is.
|
|
116
|
+
|
|
117
|
+
## 10. Facts
|
|
118
|
+
|
|
119
|
+
Every number, date and claim on screen or in the voice comes from an official or primary source (a contemporary report, an official brochure, a government record), kept in `demo/FACTS.md` with the URL and the quoted wording. Counters are graphics: only their end values and dated anchors are facts. Where two primary sources disagree (a film's intertitle vs. the official brochure), use one and record the conflict.
|
|
120
|
+
|
|
121
|
+
## 11. Engine
|
|
122
|
+
|
|
123
|
+
- `demo/index.html`: one Canvas 2D page, stateless `render(t)`; scene functions draw a full frame; wipes draw the old scene, clip, draw the new one, then the band. `txt()` draws and registers rotated text boxes for `readcheck.mjs`; `reg()` registers a group drawn in pieces; `slam()`, `flash()`, `flicker()`, `shake()`, `slant()` (parallelogram windows), `cover()` (focus-point cover fit), `clipImg()` (forward / reverse / ping-pong / speed).
|
|
124
|
+
- `demo/tools/prep.py`: the print grade, clip extraction to 24 fps JPEG sequences (one percentile set per clip), stills, document pages and outline keying, cut-outs. `demo/tools/fonts.py`: fetch the OFL fonts and subset Noto Sans SC to the characters used. `demo/tools/cues.mjs`: subtitle cues from the page's own table, measured one line per language. `demo/audio/mix.py`: score, foley, narration, ambience, master.
|
|
125
|
+
- Checks: `readcheck.mjs`, `asr_check.py` per line, `tools/final_asr.py` on the final mix, `tools/rhythm_report.py` (flat windows, cut points, hit-to-onset alignment), `mux.sh` loudness.
|
|
126
|
+
|
|
127
|
+
## 12. Pitfalls of the medium
|
|
128
|
+
|
|
129
|
+
- **Upscaled archive film** turns to mush on a 1080p full frame: window it; split strips into panels; keep zooms inside the 2.5× ceiling.
|
|
130
|
+
- **Per-frame grading pumps**: one percentile pair per clip.
|
|
131
|
+
- **Type on a band running off frame**: place it from the band's centre line (point + normal), not by eye.
|
|
132
|
+
- **Red on red**: a red answer block on a red exposure ground disappears; switch it to ink.
|
|
133
|
+
- **A face as hero**: ordinary identifiable workers appear in groups, at work, in quick cuts; no slow motion or close-up protagonist.
|
|
134
|
+
- **Counters read as facts**: label only the end value and dated anchors; a caption beside a counter must match the number shown at every frame (stop the count on the caption's value while it is up).
|
|
135
|
+
- **A number without a unit**: every counter carries its unit in the same layout as elsewhere (小时 / 层 / 人 MEN).
|
|
136
|
+
- **Ink type over a window**: a line that runs past a photo's edge disappears into dark film; give it a paper tab or keep it clear of the window.
|
|
137
|
+
- **The verdict covering what was compared**: place it where no item is, after the hold.
|
|
138
|
+
- **Too many documents**: one marked sentence per document shot; a page with three highlights is a slide.
|
|
139
|
+
- **Short labels in an acceleration** fail reading time by design: keep text out of the 1/8-beat cuts; put the result in a held block after.
|
|
140
|
+
- **A hit at sample 0** overshoots in the AAC encode: fade the first 25 ms.
|
|
141
|
+
|
|
142
|
+
## 13. Variation space
|
|
143
|
+
|
|
144
|
+
The agent decides per film: structure, which archive and documents, which formats (not all of them in one film), the axis angle (−15° to −30°), the red's exact hue, tempo (100–140 BPM), whether there is narration (intertitles only is valid), the signature build (a tower, a bridge span, a crowd forming a word, a map filling in).
|
|
145
|
+
|
|
146
|
+
- **Three structures:** a calendar machine (one counter runs the whole film and stops at milestones); a document that asks and footage that answers (the turn at the middle); one object's journey through a process, then the scale of the whole.
|
|
147
|
+
- Subjects that fit: construction and engineering histories, industrial anniversaries, mass events, labour and collective effort, infrastructure openings, any "many people, one machine rhythm" story with archive film and documents behind it.
|
|
148
|
+
|
|
149
|
+
Our demo: [DEMO.md](DEMO.md).
|