⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

2d-generalist

codepawl@codepawl⭐ 176 stars· last commit 3d ago· 0 open issues

Design and animate Vox, Johnny Harris and WSJ style explainer motion graphics in 2D, 2.5D and 3D with free tools (Blender, Fusion, Remotion, FFmpeg): flat paper cards, print-bordered photos, highlighters, maps, charts, timelines; torn paper and halftone as opt-in looks. Use for \"create a Vox style video\", \"Vox map or chart animation\", \"2D/3D editorial motion graphics\", \"2d generalist\", \"2D motion graphics\".

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 176 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Install the pack one time. After that, your agent can work like a 2D and 3D generalist and a small game studio. Use it to make content, videos and Shorts for YouTube, TikTok, Facebook, Instagram and X. You do not call a skill by name. Ask for the work and the matching skill loads, or start one with /3dg, /2dg or /gameg. Before it builds, the agent asks a few short questions about whatever your request leaves open (purpose, platform, format, look), each with a suggested answer. It then shows a cheap preview, so the result matches what you meant.

One prompt, one result

Each clip below came from the prompt above it, made with these skills for this README.

The skills

Three main skills run the whole piece. They call the craft and tool skills for each step, and you can ask for any of those on its own too.

Main skills

SkillAsk forYou get
3d-generalista 3D Short, a cutaway build, a story scene, a world, a rigged character, a hero assetA scripted and animated 3D piece in Blender, Three.js or 67js, built from real CC0 and CC BY scans and checked by a QA gate before you see a preview
2d-generalista Vox or Johnny Harris style explainer graphicA footage-led Vox look with flat paper cards, print-bordered real photos, highlighters, maps, charts and true-scale timelines (torn paper, halftone and grain only as opt-in stylised looks), made with free tools
game-generalista game prototype, a small original game, a game jam entry, a feel and QA pass on a playableA playable greybox you try before any art, a locked look, an original game on web (three.js, Phaser, canvas), Godot, Unity or Unreal, and a playtest report from scripted bots (errors, win and lose paths, restart, determinism, frame time, softlocks) with a playable link and a 30 to 60 s capture

Craft skills

SkillAsk forYou get
model-charactersa 3D character from a drawing, a turnaround or an ideaRoutes for low poly (PS1, N64, chibi, anime, mascot), stylized sculpt, clean base mesh and realistic humans, with a reference measurer and a mesh checker
sculpt-modelsa sculpted head, creature, rock, cliff or worn propForm hierarchy and anatomy, surface layers by scale, rock and terrain fracture logic, Blender 5.x sculpt tools, retopo and bake, a silhouette and mesh checker, and a procedural rock example
animate-characterscharacter motion in 2D or 3DThe 12 principles for both media, timing and spacing, Graph Editor curves, walk and idle cycles, acting beats, face swaps, frame by frame in Krita and Grease Pencil, cut-out
rig-charactersa rig for a character, face, prop or puppetBone naming, Rigify, weights, IK with poles, IK/FK snapping, face rigs, mechanical rigs, 2D cut-out rigs and export to Unity, Godot and glTF
draw-and-paint-artdrawing, painting or a figure checkGesture and construction, anatomy and foreshortening, light and form, colouring grayscale, Krita and Grease Pencil, turnaround sheets for 3D
paint-stylized-backgroundsa background in any styleBlender render settings, 3D blockout and paint-over, brushes, time-of-day variants, parallax, wind, water and particle effects

Tool skills

SkillAsk forYou get
use-3d-softwareany step in Blender, three.js, Godot, Unity or Unreal, or moving an asset between themAbout 250 Blender recipes with 5.x names, three.js loading and colour steps, Godot, Unity and Unreal guides, export rules for GLB and FBX, and a Cinema 4D, Houdini, Maya and 3ds Max map
edit-videoany edit in Resolve, CapCut, Premiere, Kdenlive, Shotcut or FFmpegCutting craft for Shorts and YouTube (hook, pacing, beat sync, captions, safe zones, loudness, platform export), Resolve transitions, shakes, retimes, Fusion effects and grades, FFmpeg recipes, and a map from After Effects and Premiere plugins to free tools

Learning skill

SkillAsk forYou get
watch-videowatching a video, copying its style, or turning a tutorial channel into a skillFrame sheets, cuts, spectrograms and a sound timeline, transcripts in many languages, a remake recipe, and a channel-to-skill pipeline that checks names against the installed software, reads values from full-size frames and compares with current docs. It can also draw what it read and concluded onto the video (OCR boxes, timestamped claims, speech) so you can check it

Sound skill

SkillAsk forYou get
design-soundSFX, foley, music or a mix for a video, game or reelA sound library searched by meaning (CLAP) with sheets to look at before choosing, web and ElevenLabs fetching, foley generated from a silent film with a local video-to-audio model (HunyuanVideo-Foley), an effects stem placed from an event list, music fitted to the cut, and a mix to platform loudness checked for sync, masking and phone audibility

model-characters, sculpt-models, use-3d-software, animate-characters and rig-characters come with the 3d-generalist plugin. edit-video, draw-and-paint-art and paint-stylized-backgrounds come with the 2d-generalist plugin. watch-video, design-sound and game-generalist are their own plugins. Install all five plugins to get every skill. 2d-generalist ships its own copy of the production spine and of compare_look.py, so each of the two plugins also works installed alone.

Install

Let your agent do it. Paste this prompt into Claude Code, Codex, Cursor,

// HOW IT'S BUILT

// FILES

26 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • plugins/2d-generalist/skills/2d-generalist/SKILL.md10 KBaddbb0a8d032upstream ↗
    ---
    name: 2d-generalist
    description: "Design and animate Vox, Johnny Harris and WSJ style explainer motion graphics in 2D, 2.5D and 3D with free tools (Blender, Fusion, Remotion, FFmpeg): flat paper cards, print-bordered photos, highlighters, maps, charts, timelines; torn paper and halftone as opt-in looks. Use for \"create a Vox style video\", \"Vox map or chart animation\", \"2D/3D editorial motion graphics\", \"2d generalist\", \"2D motion graphics\"."
    license: MIT
    ---
    
    # 2D Generalist
    
    Use this skill to design, animate, texture, and composite editorial motion graphics in the style of **Vox** (*Atlas*, *By Design*, *Earworm*, *Missing Chapter*) and **Flat Pack FX** across **2D, 2.5D, and 3D** using tools already installed on the user's machine (or recommending free tools when missing).
    
    Before building a look, pick the named technique instead of brute force: the 3D skill's `references/technique-atlas.md` (symptom to technique, numbers, recipe across 2D, 3D, editing and sound) and `references/depth-parallax-and-atmosphere.md` (parallax speeds, haze maths for layers). Machine paths (Krita, OpenToonz): `local.md` next to this file when it exists.
    
    ## Mode Routing
    
    | Mode | Scope (2D / 2.5D / 3D) | Primary Reference |
    | --- | --- | --- |
    | `script` | Title, hook, explainer structure, voice pace, beat table, captions | [`references/explainer-script.md`](references/explainer-script.md) |
    | `qa` | Render gate on the preview and final: measured checks plus contact sheet | [`references/qa-and-gates.md`](references/qa-and-gates.md) |
    | `audit` | Check installed free 2D/3D tools vs optional downloads | [`references/2d-3d-toolchain-matrix.md`](references/2d-3d-toolchain-matrix.md) |
    | `design` | Visual hierarchy, asymmetric scale, credibility pillars, palettes | [`references/vox-psychology-and-design.md`](references/vox-psychology-and-design.md) |
    | `map` | 2D vector/satellite maps, 2.5D embossed/extruded layers, 3D terrain and GeoJSON routes (convert KML with `ogr2ogr`) | [`references/maps-and-geodata-2d-3d.md`](references/maps-and-geodata-2d-3d.md) |
    | `chart-timeline` | Pre-drawn ruler timelines, 2D/3D bar/line graphs, dot-matrix repeaters, waveforms | [`references/charts-timelines-and-data.md`](references/charts-timelines-and-data.md) |
    | `vox-now` | The current Vox explainer look, measured: footage-led, 60-75% empty frames, still holds, hard cuts every 1.5-3 s, 3 inks, lemon line-box highlight. Read first when asked to "look like Vox" | [`references/vox-modern-measured.md`](references/vox-modern-measured.md) |
    | `photos` | Find real photos, scans, cut-outs and documents online, pick from a numbered sheet, rework into the piece's look, credits | [`references/real-images.md`](references/real-images.md) |
    | `archival-collage` | Dual highlighters, newspaper push, 2.5D parallax; torn borders, flicker and slide projector as stylised options (not seen in measured Vox) | [`references/archival-collage-and-camera.md`](references/archival-collage-and-camera.md); highlighters and torn borders in [`references/vox-psychology-and-design.md`](references/vox-psychology-and-design.md) §3 and §6 |
    | `thumbnail` | Vector thumbnails in Inkscape, brand logos as sticker outlines with soft shadows | [`references/inkscape-thumbnails-and-logos.md`](references/inkscape-thumbnails-and-logos.md) |
    | `texture-look` | Grain, paper, halftone, dither, CRT, VHS, colour misregistration, engraving, boil, flat shading, stacked shadows and glows, colour split | [`references/textures-retro-and-shading.md`](references/textures-retro-and-shading.md) |
    | `fx-type` | Goo, smoke, fire, liquid, rain, loops, infinite zoom, kaleidoscopes, mattes, transitions, kinetic type, graphics into footage | [`references/2d-fx-type-and-compositing.md`](references/2d-fx-type-and-compositing.md); drawn FX blended into 3D shots: the 3D skill's `references/hybrid-2d-3d-fx.md` |
    
    ## End-to-End Workflow: the production spine
    
    Run the eight steps of `references/pipeline-spine.md` in order, for every mode. Each
    step writes its file and its line under `## Progress` in `brief.md`; start a step only from the files of the one
    above it. The user sees the work three times: the choice at step 4 (prep sheet, sketch and options), a WIP demo of the
    first finished shot at step 6 (sent without waiting), and the preview at step 8. After the preview the user's
    answer picks the next round: fix, continue in a direction, or "you decide" free creative mode (spine, last section).
    
    | Step | Writes | 2D rules for the step |
    | --- | --- | --- |
    | 1. Brief | `brief.md` | `references/intent-brief.md`; run `scripts/check_vox_toolchain.py` and mention only missing tools |
    | 2. Reference | `refs/`, `refs/NOTES.md` | real photos, scans, documents and footage via `scripts/fetch_images.py` (`references/real-images.md`); real data for maps and charts; a Vox look starts from `references/vox-modern-measured.md` |
    | 3. Script and beats | `script.md`, `beats.md`, scratch voice, cue list | `references/explainer-script.md` |
    | 4. Prep and look gate | `plan.md` (sketch, tools checked, photos and data downloaded), style frames A/B/C, animatic of the beats, then `LOOK.md`, `recipe.json` | the user picks; one anchor with asymmetric scale and the Look-Away / Look-Back Test (`references/vox-psychology-and-design.md`); default flat paper and print borders, grain, ink bleed, torn edges and halftone only when the pick is a stylised option (`references/textures-retro-and-shading.md`); then `scripts/validate_vox_recipe.py --recipe recipe.json` (the recipe's `look` is `flat` by default, `stylised` only when `LOOK.md` picks it) |
    | 5. Assets and check | `assets/`, `CREDITS.md` | `scripts/rework_image.py` for cut-outs, `scripts/generate_vox_assets.py` for the filters and ruler timelines the recipe uses; every picture sourced or the search named |
    | 6. Build and animate | scenes, WIP demo after the first | Remotion + SVG filters + Three.js, Fusion (`ImagePlane3D`, `Camera3D`) or Blender Grease Pencil per `references/2d-3d-toolchain-matrix.md`; mode references above; posterize graphics at 8 to 12 fps only when `LOOK.md` picks a stylised look (flat and `vox-now`: no posterize), camera never posterized; finish with 35mm DoF, vignette and a light unsharp, grain and chromatic aberration only if `LOOK.md` says |
    | 7. Sound | final voice, SFX, music, mix | `design-sound`: every visible stroke, pop and wipe gets its own sound at its frame |
    | 8. QA, preview, final | gate report, 540p preview with sound | `scripts/check_render.py` and the contact sheet per `references/qa-and-gates.md`, look match with `scripts/compare_look.py`; the user approves the preview before the full render |
    
    For any step done in Blender (geometry nodes, shaders, rigging, weight paint, NLA, bpy), load the `use-3d-software` skill for the exact nodes and current 5.x names. For the edit, captions, retime, transitions, grade and export in any editor (Resolve, CapCut, Premiere, Kdenlive, FFmpeg), load `edit-video`.
    Craft skills for single steps: `draw-and-paint-art` (drawing, figures, painting in Krita), `paint-stylized-backgrounds` (backgrounds, paint-over, parallax, moving foliage and water), `animate-characters` (character motion, frame by frame, cut-out) and `rig-characters` (cut-out puppets).
    
    ## Core Vox Visual Laws (Non-Negotiable)
    
    - **Real Pictures, Never Redrawn:** every real-world thing on screen (vehicle, person, place, product, document, logo) is a real photo or scan found online with `scripts/fetch_images.py`, never redrawn from SVG shapes. Measured Vox (2018-2026) shows archival photos as plain black-and-white scans; `scripts/rework_image.py` duotone, halftone and torn edges are a stylised option, not the Vox look. Draw only arrows, rulers, charts and ideas with no picture, and name the search when nothing was found ([`references/real-images.md`](references/real-images.md)).
    - **Flat Paper, Real Documents:** graphic cards are flat near-white with no grain (measured `#F9F9F6`, `#F9F8EB`, `#F1ECE6`; grey bed `#D1D1D1`); pure white only for real web pages and documents. Dark maps use deep desaturated slate or navy.
    - **Print Borders, Not Torn:** a cut-out photo gets a thin straight white print border of a few pixels, a 2-8 degree tilt and a faint shadow. No torn edge was seen in six measured Vox videos; the two-pass torn border in `vox-psychology-and-design.md` §3 is a stylised option only.
    - **No Added Halftone:** halftone appears only inside scanned newspaper photos, as part of the source. Do not lay a halftone or duotone over photos for a Vox look (§4 of `vox-psychology-and-design.md` is a stylised option).
    - **Pre-Drawn Ruler Timeline Law:** Never space unequal time intervals evenly. Draw an evenly spaced ruler/tick scale first, then place events at their true proportional coordinates so clusters and gaps tell the story.
    - **Dual Highlighter Law:**
      - *Digital/Screen Text:* Clean `#FFE600` stroke (no wobble), `Multiply` blend mode, stroke band **135-150% of cap height**, other text not dimmed (measured, see `references/vox-modern-measured.md`).
      - *Archival/Book Page:* 3-pass roughened edges (horizontal marker streaks + border + rough edge) + `Bulge` turbulent displacement, placed in 3D space with a `35mm` camera and shallow Depth of Field tracking the line.
    - **No Stiff Repeats:** no two neighbouring elements with the same size, angle and timing: stagger entrances by 2 to 6
      frames and vary scale ±10%. Holds have no boil or wobble (measured Vox); 2 to 4 fps boil, Roughen Edges and slight
      rotation apply only when `LOOK.md` picks a stylised option, with repeating patterns hidden by large-scale noise.
    - **Camera Speed Graph:** In looks that move the camera (not `vox-now`, which uses hard cuts and still holds), all 2D/3D camera pans and zooms must use a `35mm` focal length equivalent, Null controller parenting, and a **Continuous Bezier** bell-curve speed graph (slow ease-in -> fast snap -> slow settle), never linear keyframes. An infinite zoom is the one exception: exponential scale, so the zoom speed looks constant.
    
    ## Scripts & References
    
    - Toolchain audit: [`scripts/check_vox_toolchain.py`](scripts/check_vox_toolchain.py)
    - Asset & SVG filter generator: [`scripts/generate_vox_assets.py`](scripts/generate_vox_assets.py)
    - Recipe validator: [`scripts/validate_vox_recipe.py`](scripts/validate_vox_recipe.py)
    - Unit tests: [`scripts/test_vox_skill.py`](scripts/test_vox_skill.py)
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/check_render.py7.8 KB3b8df0a7e065upstream ↗
    """Measure a rendered 2D motion graphics video against the render gate in references/qa-and-gates.md.
    
    Checks what numbers can see: sterile white or black frames, held frames with no motion (dead air), the share of
    stepped (posterized) frames, audio loudness and true peak, long silences, and duration. It also writes a 1 fps
    contact sheet for the visual part of the gate, which a person or a frame-reading agent must still look at.
    
    Run:
      uv run --no-project --with numpy python scripts/check_render.py <video.mp4> [--out <folder>] [--max-hold 1.5]
          [--min-seconds 0] [--max-seconds 0] [--target-lufs -14]
    
    Exit code 0 when every measured gate passes, 1 when one fails, 2 when the file cannot be read.
    """
    
    import argparse
    import json
    import pathlib
    import re
    import subprocess
    import sys
    
    import numpy
    
    ANALYSIS_WIDTH = 160
    ANALYSIS_HEIGHT = 90
    WHITE_LEVEL = 250
    BLACK_LEVEL = 5
    STERILE_SHARE = 0.6
    STILL_DIFFERENCE = 0.4
    SILENCE_DB = -45
    MAX_SILENCE_SECONDS = 0.4
    
    
    def run(command):
        return subprocess.run(command, capture_output=True, text=True, encoding="utf-8", errors="replace")
    
    
    def probe(video):
        result = run(["ffprobe", "-v", "error", "-show_entries", "format=duration:stream=codec_type,r_frame_rate",
                      "-of", "json", str(video)])
        if result.returncode != 0:
            return None
        data = json.loads(result.stdout)
        duration = float(data["format"]["duration"])
        video_stream = next(stream for stream in data["streams"] if stream["codec_type"] == "video")
        numerator, denominator = video_stream["r_frame_rate"].split("/")
        frames_per_second = float(numerator) / float(denominator)
        has_audio = any(stream["codec_type"] == "audio" for stream in data["streams"])
        return duration, frames_per_second, has_audio
    
    
    def read_gray_frames(video):
        command = ["ffmpeg", "-v", "error", "-i", str(video), "-vf",
                   f"scale={ANALYSIS_WIDTH}:{ANALYSIS_HEIGHT},format=gray", "-f", "rawvideo", "-"]
        raw = subprocess.run(command, capture_output=True).stdout
        frame_size = ANALYSIS_WIDTH * ANALYSIS_HEIGHT
        count = len(raw) // frame_size
        return numpy.frombuffer(raw[:count * frame_size], dtype=numpy.uint8).reshape(count, ANALYSIS_HEIGHT, ANALYSIS_WIDTH)
    
    
    def picture_checks(frames, frames_per_second, max_hold_seconds):
        white_share = (frames >= WHITE_LEVEL).mean(axis=(1, 2))
        black_share = (frames <= BLACK_LEVEL).mean(axis=(1, 2))
        sterile_frames = numpy.flatnonzero((white_share > STERILE_SHARE) | (black_share > STERILE_SHARE))
        differences = numpy.abs(numpy.diff(frames.astype(numpy.int16), axis=0)).mean(axis=(1, 2))
        still = differences < STILL_DIFFERENCE
        longest_hold = 0
        longest_hold_start = 0
        run_length = 0
        for index, is_still in enumerate(still):
            run_length = run_length + 1 if is_still else 0
            if run_length > longest_hold:
                longest_hold = run_length
                longest_hold_start = index - run_length + 1
        return {
            "sterile_frames": len(sterile_frames),
            "first_sterile_second": round(sterile_frames[0] / frames_per_second, 2) if len(sterile_frames) else None,
            "longest_hold_seconds": round(longest_hold / frames_per_second, 2),
            "longest_hold_starts_at": round(longest_hold_start / frames_per_second, 2),
            "stepped_frame_share": round(float(still.mean()), 3),
            "hold_ok": longest_hold / frames_per_second <= max_hold_seconds,
            "sterile_ok": len(sterile_frames) == 0,
        }
    
    
    def audio_checks(video, target_lufs):
        loudness = run(["ffmpeg", "-v", "info", "-nostats", "-i", str(video), "-af", "ebur128=peak=true", "-f", "null", "-"])
        integrated = re.findall(r"I:\s+(-?[\d.]+) LUFS", loudness.stderr)
        true_peak = re.findall(r"Peak:\s+(-?[\d.]+) dBFS", loudness.stderr)
        silence = run(["ffmpeg", "-v", "info", "-nostats", "-i", str(video), "-af",
                       f"silencedetect=noise={SILENCE_DB}dB:d={MAX_SILENCE_SECONDS}", "-f", "null", "-"])
        silences = [float(value) for value in re.findall(r"silence_duration: ([\d.]+)", silence.stderr)]
        integrated_value = float(integrated[-1]) if integrated else None
        peak_value = float(true_peak[-1]) if true_peak else None
        return {
            "integrated_lufs": integrated_value,
            "true_peak_db": peak_value,
            "silences_over_limit": len(silences),
            "longest_silence_seconds": round(max(silences), 2) if silences else 0.0,
            "loudness_ok": integrated_value is not None and abs(integrated_value - target_lufs) <= 1.5,
            "peak_ok": peak_value is not None and peak_value <= -1.0,
            "silence_ok": not silences,
        }
    
    
    def write_contact_sheet(video, out_folder, duration):
        columns = 6
        rows = max(1, int(numpy.ceil(duration / columns)))
        sheet = out_folder / "contact_sheet.jpg"
        run(["ffmpeg", "-y", "-v", "error", "-i", str(video), "-vf",
             f"fps=1,scale=320:-2,tile={columns}x{rows}:padding=4:color=gray", "-frames:v", "1", str(sheet)])
        return sheet
    
    
    def main():
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
        parser.add_argument("video")
        parser.add_argument("--out", default=None, help="folder for the report and contact sheet (default: next to the video)")
        parser.add_argument("--max-hold", type=float, default=1.5, help="longest allowed frame with no motion, seconds")
        parser.add_argument("--min-seconds", type=float, default=0)
        parser.add_argument("--max-seconds", type=float, default=0)
        parser.add_argument("--target-lufs", type=float, default=-14)
        arguments = parser.parse_args()
    
        video = pathlib.Path(arguments.video)
        probed = probe(video)
        if probed is None:
            print(f"cannot read {video}")
            return 2
        duration, frames_per_second, has_audio = probed
        out_folder = pathlib.Path(arguments.out) if arguments.out else video.parent / f"{video.stem}_gate"
        out_folder.mkdir(parents=True, exist_ok=True)
    
        report = {"video": str(video), "duration_seconds": round(duration, 2), "fps": round(frames_per_second, 3)}
        report["picture"] = picture_checks(read_gray_frames(video), frames_per_second, arguments.max_hold)
        report["audio"] = audio_checks(video, arguments.target_lufs) if has_audio else {"missing": True}
        duration_ok = (arguments.min_seconds <= 0 or duration >= arguments.min_seconds) and \
                      (arguments.max_seconds <= 0 or duration <= arguments.max_seconds)
        report["duration_ok"] = duration_ok
        report["contact_sheet"] = str(write_contact_sheet(video, out_folder, duration))
    
        gates = {
            "no sterile white or black frames": report["picture"]["sterile_ok"],
            f"no hold over {arguments.max_hold} s": report["picture"]["hold_ok"],
            "audio present": has_audio,
            f"loudness {arguments.target_lufs} ±1.5 LUFS": report["audio"].get("loudness_ok", False),
            "true peak at or under -1 dB": report["audio"].get("peak_ok", False),
            f"no silence over {MAX_SILENCE_SECONDS} s": report["audio"].get("silence_ok", False),
            "duration in range": duration_ok,
        }
        report["gates"] = gates
        (out_folder / "gate_report.json").write_text(json.dumps(report, indent=1), encoding="utf-8")
    
        for name, passed in gates.items():
            print(f"{'PASS' if passed else 'FAIL'}  {name}")
        picture = report["picture"]
        print(f"longest hold {picture['longest_hold_seconds']} s at {picture['longest_hold_starts_at']} s; "
              f"stepped frames {picture['stepped_frame_share']:.0%}")
        if has_audio:
            print(f"loudness {report['audio']['integrated_lufs']} LUFS, true peak {report['audio']['true_peak_db']} dB, "
                  f"longest silence {report['audio']['longest_silence_seconds']} s")
        print(f"contact sheet: {report['contact_sheet']} (look at it: text, safe area, layout are not measured)")
        return 0 if all(gates.values()) else 1
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/check_vox_toolchain.py13 KB856179a6a9ccupstream ↗
    #!/usr/bin/env python3
    """Audit the local environment for 2D/3D Vox-style motion graphics tools.
    
    Reports installed free/open-source and local tools (Blender, DaVinci Resolve,
    Remotion + Three.js, FFmpeg, yt-dlp, Python, Node/pnpm, OBS) and suggests
    exact winget/free download commands for optional tools (QGIS, Inkscape,
    Krita, GIMP, Google Earth Studio).
    """
    
    from __future__ import annotations
    
    import argparse
    import json
    import os
    import shutil
    import subprocess
    import sys
    from pathlib import Path
    from typing import Any
    
    
    TOOL_SPECS: list[dict[str, Any]] = [
        {
            "id": "blender",
            "name": "Blender (3D / 2.5D Camera & Geometry Nodes)",
            "category": "3d_and_25d",
            "required": True,
            "commands": ["blender"],
            "candidate_paths": [
                r"C:\Program Files\Blender Foundation\Blender 5.3\blender.exe",
                r"C:\Program Files\Blender Foundation\Blender 5.2\blender.exe",
                r"C:\Program Files\Blender Foundation\Blender 5.1\blender.exe",
                r"C:\Program Files\Blender Foundation\Blender 5.0\blender.exe",
                r"C:\Program Files\Blender Foundation\Blender 4.3\blender.exe",
                r"C:\Program Files\Blender Foundation\Blender 4.2\blender.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install BlenderFoundation.Blender",
        },
        {
            "id": "davinci_resolve",
            "name": "DaVinci Resolve + Fusion (Node 2D/3D Compositing & NLE)",
            "category": "compositing_and_nle",
            "required": False,
            "commands": ["Resolve"],
            "candidate_paths": [
                r"C:\Program Files\Blackmagic Design\DaVinci Resolve\Resolve.exe",
                r"C:\Program Files\Blackmagic Design\DaVinci Resolve\fuscript.exe",
            ],
            "version_args": None,
            "install_cmd": "Download DaVinci Resolve Free: https://www.blackmagicdesign.com/products/davinciresolve",
        },
        {
            "id": "ffmpeg",
            "name": "FFmpeg (Video/Audio/Texture Processing & Encoding)",
            "category": "media_pipeline",
            "required": True,
            "commands": ["ffmpeg"],
            "candidate_paths": [
                str(Path.home() / ".local" / "bin" / "ffmpeg.exe"),
            ],
            "version_args": ["-version"],
            "install_cmd": "winget install Gyan.FFmpeg",
        },
        {
            "id": "ffprobe",
            "name": "FFprobe (Media Stream & Frame Rate Inspector)",
            "category": "media_pipeline",
            "required": True,
            "commands": ["ffprobe"],
            "candidate_paths": [
                str(Path.home() / ".local" / "bin" / "ffprobe.exe"),
            ],
            "version_args": ["-version"],
            "install_cmd": "winget install Gyan.FFmpeg",
        },
        {
            "id": "yt_dlp",
            "name": "yt-dlp (Archival Reference & Transcript Extractor)",
            "category": "research_and_archival",
            "required": False,
            "commands": ["yt-dlp"],
            "candidate_paths": [
                str(Path.home() / ".local" / "bin" / "yt-dlp.exe"),
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install yt-dlp.yt-dlp",
        },
        {
            "id": "node",
            "name": "Node.js (Remotion + Three.js Runtime)",
            "category": "code_driven_2d_3d",
            "required": True,
            "commands": ["node"],
            "candidate_paths": [
                r"C:\Program Files\nodejs\node.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install OpenJS.NodeJS.LTS",
        },
        {
            "id": "uv",
            "name": "uv (Python Asset & Data Automation Runner)",
            "category": "code_driven_2d_3d",
            "required": True,
            "commands": ["uv"],
            "candidate_paths": [
                str(Path.home() / ".local" / "bin" / "uv.exe"),
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install astral-sh.uv",
        },
        {
            "id": "obs",
            "name": "OBS Studio (Viewport / Map Capture)",
            "category": "capture",
            "required": False,
            "commands": ["obs64"],
            "candidate_paths": [
                r"C:\Program Files\obs-studio\bin\64bit\obs64.exe",
            ],
            "version_args": None,
            "install_cmd": "winget install OBSProject.OBSStudio",
        },
        {
            "id": "qgis",
            "name": "QGIS (Free GIS Map & DEM Heightmap Generator — replaces GEOlayers 3)",
            "category": "gis_and_maps",
            "required": False,
            "commands": ["qgis", "qgis-bin"],
            "candidate_paths": [
                r"C:\Program Files\QGIS 3.40.0\bin\qgis-bin.exe",
                r"C:\Program Files\QGIS 3.38.0\bin\qgis-bin.exe",
                r"C:\Program Files\QGIS 3.34.0\bin\qgis-bin.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install OSGeo.QGIS",
        },
        {
            "id": "inkscape",
            "name": "Inkscape (Free SVG Vector Editor — replaces Adobe Illustrator)",
            "category": "vector_and_raster",
            "required": False,
            "commands": ["inkscape"],
            "candidate_paths": [
                r"C:\Program Files\Inkscape\bin\inkscape.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install Inkscape.Inkscape",
        },
        {
            "id": "krita",
            "name": "Krita (Free Raster Cutout, Halftone & Texture Painter — replaces Photoshop)",
            "category": "vector_and_raster",
            "required": False,
            "commands": ["krita"],
            "candidate_paths": [
                r"C:\Program Files\Krita (x64)\bin\krita.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install KDE.Krita",
        },
        {
            "id": "gimp",
            "name": "GIMP (Free Image Manipulation & Thresholding)",
            "category": "vector_and_raster",
            "required": False,
            "commands": ["gimp", "gimp-2.10"],
            "candidate_paths": [
                r"C:\Program Files\GIMP 2\bin\gimp-2.10.exe",
            ],
            "version_args": ["--version"],
            "install_cmd": "winget install GIMP.GIMP",
        },
    ]
    
    
    def locate_executable(commands: list[str], candidate_paths: list[str]) -> str | None:
        """Return the first resolved executable path from PATH or candidate paths."""
        for cmd in commands:
            found = shutil.which(cmd)
            if found:
                return found
        for path_str in candidate_paths:
            if os.path.isfile(path_str):
                return path_str
        return None
    
    
    def probe_version(exe_path: str, version_args: list[str] | None) -> str:
        """Return the first line of version output if available."""
        if not version_args:
            return "installed"
        try:
            completed = subprocess.run(
                [exe_path, *version_args],
                capture_output=True,
                text=True,
                timeout=5,
                check=False,
            )
            output = (completed.stdout or completed.stderr or "").strip()
            if output:
                return output.splitlines()[0].strip()
        except Exception:
            pass
        return "installed"
    
    
    def check_remotion_workspace() -> dict[str, Any]:
        """Check whether the user's Remotion + Three.js workspace is present."""
        candidates = [
            Path.home() / "Documents" / "social" / "remotion" / "package.json",
            Path.cwd() / "remotion" / "package.json",
            Path.cwd() / "package.json",
        ]
        for pkg_path in candidates:
            if pkg_path.is_file():
                try:
                    data = json.loads(pkg_path.read_text(encoding="utf-8"))
                    deps = {
                        **data.get("dependencies", {}),
                        **data.get("devDependencies", {}),
                    }
                    if "remotion" in deps or "three" in deps:
                        return {
                            "id": "remotion_three",
                            "name": "Remotion + Three.js Workspace (Code-Driven 2D/3D Motion)",
                            "category": "code_driven_2d_3d",
                            "installed": True,
                            "path": str(pkg_path.parent),
                            "version": f"remotion={deps.get('remotion', 'n/a')}, three={deps.get('three', 'n/a')}",
                            "install_cmd": "pnpm install (inside remotion workspace)",
                        }
                except Exception:
                    continue
        return {
            "id": "remotion_three",
            "name": "Remotion + Three.js Workspace (Code-Driven 2D/3D Motion)",
            "category": "code_driven_2d_3d",
            "installed": False,
            "path": None,
            "version": None,
            "install_cmd": "npx create-video@latest",
        }
    
    
    def audit_toolchain() -> dict[str, Any]:
        """Run a full audit of installed and optional free Vox motion graphics tools."""
        results: list[dict[str, Any]] = []
        for spec in TOOL_SPECS:
            exe = locate_executable(spec["commands"], spec["candidate_paths"])
            installed = exe is not None
            version = probe_version(exe, spec["version_args"]) if exe else None
            results.append(
                {
                    "id": spec["id"],
                    "name": spec["name"],
                    "category": spec["category"],
                    "required": spec["required"],
                    "installed": installed,
                    "path": exe,
                    "version": version,
                    "install_cmd": spec["install_cmd"],
                }
            )
    
        remotion_info = check_remotion_workspace()
        results.append(
            {
                "id": remotion_info["id"],
                "name": remotion_info["name"],
                "category": remotion_info["category"],
                "required": False,
                "installed": remotion_info["installed"],
                "path": remotion_info["path"],
                "version": remotion_info["version"],
                "install_cmd": remotion_info["install_cmd"],
            }
        )
    
        installed_tools = [r for r in results if r["installed"]]
        missing_tools = [r for r in results if not r["installed"]]
    
        recommended_stacks = {
            "stack_a_code_driven_2d_3d": {
                "ready": any(r["id"] == "node" and r["installed"] for r in results)
                and any(r["id"] == "ffmpeg" and r["installed"] for r in results),
                "description": "Remotion + Three.js + SVG/Canvas + Python/FFmpeg (Automated 2D/3D charts, maps, kinetic typography)",
            },
            "stack_b_node_compositing": {
                "ready": any(r["id"] == "davinci_resolve" and r["installed"] for r in results),
                "description": "DaVinci Resolve + Fusion (Node-based 2D/3D camera rigs, Set Matte, Displace, Sound Design)",
            },
            "stack_c_full_3d_25d_blender": {
                "ready": any(r["id"] == "blender" and r["installed"] for r in results),
                "description": "Blender 5.2 (3D terrain displacement, multi-plane archival collage, isometric dioramas, grease pencil)",
            },
        }
    
        return {
            "summary": {
                "installed_count": len(installed_tools),
                "missing_optional_count": len(missing_tools),
                "ready_to_produce_2d_and_3d": any(
                    s["ready"] for s in recommended_stacks.values()
                ),
            },
            "recommended_stacks": recommended_stacks,
            "installed": installed_tools,
            "missing_optional": missing_tools,
        }
    
    
    def format_markdown_report(report: dict[str, Any]) -> str:
        """Format the audit report as human-readable Markdown."""
        lines: list[str] = [
            "# Vox 2D/3D Toolchain Audit",
            "",
            f"- **Installed tools**: {report['summary']['installed_count']}",
            f"- **Optional free tools available to install**: {report['summary']['missing_optional_count']}",
            "",
            "## Ready Production Stacks",
        ]
        for stack_id, stack in report["recommended_stacks"].items():
            status = "READY" if stack["ready"] else "MISSING DEPENDENCIES"
            lines.append(f"- **{stack_id}** [{status}]: {stack['description']}")
    
        lines.extend(["", "## Installed Tools (Ready to Use)"])
        for item in report["installed"]:
            lines.append(
                f"- **{item['name']}** (`{item['id']}`)\n"
                f"  - Path: `{item['path']}`\n"
                f"  - Version: `{item['version']}`"
            )
    
        lines.extend(["", "## Optional Free Tools (Install Only If Needed)"])
        for item in report["missing_optional"]:
            lines.append(
                f"- **{item['name']}** (`{item['id']}`)\n"
                f"  - Free Install Command: `{item['install_cmd']}`"
            )
    
        return "\n".join(lines)
    
    
    def main(argv: list[str] | None = None) -> int:
        if hasattr(sys.stdout, "reconfigure"):
            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        parser = argparse.ArgumentParser(
            description="Audit installed and optional free 2D/3D tools for Vox-style motion graphics."
        )
        parser.add_argument(
            "--json",
            action="store_true",
            help="Output machine-readable JSON instead of Markdown.",
        )
        args = parser.parse_args(argv)
        report = audit_toolchain()
        if args.json:
            print(json.dumps(report, indent=2, ensure_ascii=False))
        else:
            print(format_markdown_report(report))
        return 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/compare_look.py6.5 KB2e078bd2a011upstream ↗
    """Compare rendered frames with the picked style frame: the look match gate in references/qa-and-gates.md.
    
    Measures, for the style frame and for every checked frame: mean luma (Rec. 709, 0-255), mean saturation (0-1) and the
    saturation-weighted mean hue (degrees on the colour wheel). A frame fails when its luma or saturation leaves the band
    around the style frame, or when its mean hue turns too far. This catches the usual drift: shots rendered darker, greyer or in another colour
    cast than the look the user picked. It does not judge composition or taste.
    
    Run:
      uv run --no-project --with numpy python scripts/compare_look.py --style styleframes/B.png <frames or videos...>
          [--fps 1] [--luma-band 20] [--saturation-band 0.08] [--hue-shift 20] [--json report.json]
    
    Inputs can be images or videos (videos are sampled at --fps). Exit code 0 when every frame is inside the band,
    1 when one is outside, 2 when a file cannot be read.
    """
    
    import argparse
    import json
    import pathlib
    import subprocess
    import sys
    
    import numpy
    
    ANALYSIS_WIDTH = 160
    ANALYSIS_HEIGHT = 90
    MIN_SATURATION_FOR_HUE = 0.08
    VIDEO_SUFFIXES = {".mp4", ".mov", ".webm", ".mkv", ".avi", ".m4v"}
    
    
    def decode_frames(path, frames_per_second):
        filters = f"scale={ANALYSIS_WIDTH}:{ANALYSIS_HEIGHT}"
        if path.suffix.lower() in VIDEO_SUFFIXES:
            filters = f"fps={frames_per_second}," + filters
        command = ["ffmpeg", "-v", "error", "-i", str(path), "-vf", filters, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
        result = subprocess.run(command, capture_output=True)
        if result.returncode != 0 or not result.stdout:
            raise ValueError(f"cannot read {path}: {result.stderr.decode(errors='replace').strip()}")
        frame_size = ANALYSIS_WIDTH * ANALYSIS_HEIGHT * 3
        frame_count = len(result.stdout) // frame_size
        pixels = numpy.frombuffer(result.stdout[: frame_count * frame_size], dtype=numpy.uint8)
        return pixels.reshape(frame_count, ANALYSIS_HEIGHT, ANALYSIS_WIDTH, 3).astype(numpy.float64) / 255.0
    
    
    def measure(frame):
        red = frame[..., 0]
        green = frame[..., 1]
        blue = frame[..., 2]
        luma = (0.2126 * red + 0.7152 * green + 0.0722 * blue) * 255.0
        highest = frame.max(axis=-1)
        lowest = frame.min(axis=-1)
        spread = highest - lowest
        saturation = numpy.where(highest > 0, spread / numpy.maximum(highest, 1e-9), 0.0)
        safe_spread = numpy.maximum(spread, 1e-9)
        hue = numpy.where(
            highest == red,
            ((green - blue) / safe_spread) % 6,
            numpy.where(highest == green, (blue - red) / safe_spread + 2, (red - green) / safe_spread + 4),
        )
        angle = hue / 6.0 * 2.0 * numpy.pi
        weighted_x = float((saturation * numpy.cos(angle)).sum())
        weighted_y = float((saturation * numpy.sin(angle)).sum())
        return {
            "luma": float(luma.mean()),
            "saturation": float(saturation.mean()),
            "hue_degrees": float(numpy.degrees(numpy.arctan2(weighted_y, weighted_x)) % 360.0),
        }
    
    
    def hue_shift(first_degrees, second_degrees):
        difference = abs(first_degrees - second_degrees) % 360.0
        return min(difference, 360.0 - difference)
    
    
    def compare(style, frame, luma_band, saturation_band, hue_shift_limit):
        luma_difference = frame["luma"] - style["luma"]
        saturation_difference = frame["saturation"] - style["saturation"]
        both_coloured = min(style["saturation"], frame["saturation"]) >= MIN_SATURATION_FOR_HUE
        shift = hue_shift(style["hue_degrees"], frame["hue_degrees"]) if both_coloured else 0.0
        problems = []
        if abs(luma_difference) > luma_band:
            problems.append("darker" if luma_difference < 0 else "brighter")
        if abs(saturation_difference) > saturation_band:
            problems.append("greyer" if saturation_difference < 0 else "more saturated")
        if shift > hue_shift_limit:
            problems.append("colour cast differs")
        return {
            "luma": round(frame["luma"], 1),
            "luma_difference": round(luma_difference, 1),
            "saturation": round(frame["saturation"], 3),
            "saturation_difference": round(saturation_difference, 3),
            "hue_shift_degrees": round(shift, 1),
            "problems": problems,
        }
    
    
    def main():
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
        parser.add_argument("--style", required=True, type=pathlib.Path, help="the picked style frame")
        parser.add_argument("inputs", nargs="+", type=pathlib.Path, help="rendered frames or videos")
        parser.add_argument("--fps", type=float, default=1.0)
        parser.add_argument("--luma-band", type=float, default=20.0, help="allowed mean luma difference, 0-255")
        parser.add_argument("--saturation-band", type=float, default=0.08, help="allowed mean saturation difference")
        parser.add_argument("--hue-shift", type=float, default=20.0, help="allowed mean hue turn, degrees")
        parser.add_argument("--json", type=pathlib.Path, help="write the full report here")
        arguments = parser.parse_args()
    
        try:
            style = measure(decode_frames(arguments.style, arguments.fps)[0])
            rows = []
            for input_path in arguments.inputs:
                for index, frame in enumerate(decode_frames(input_path, arguments.fps)):
                    result = compare(
                        style, measure(frame), arguments.luma_band, arguments.saturation_band, arguments.hue_shift
                    )
                    result["file"] = str(input_path)
                    result["second"] = round(index / arguments.fps, 2) if input_path.suffix.lower() in VIDEO_SUFFIXES else None
                    rows.append(result)
        except ValueError as error:
            print(error)
            return 2
    
        print(f"style {arguments.style}: luma {style['luma']:.1f}, saturation {style['saturation']:.3f}")
        failures = [row for row in rows if row["problems"]]
        for row in rows:
            where = row["file"] if row["second"] is None else f"{row['file']} @ {row['second']} s"
            verdict = "FAIL " + ", ".join(row["problems"]) if row["problems"] else "ok"
            print(
                f"{verdict:<40} {where}: luma {row['luma']} ({row['luma_difference']:+}), "
                f"saturation {row['saturation']} ({row['saturation_difference']:+}), hue shift {row['hue_shift_degrees']} deg"
            )
        print(f"{len(rows) - len(failures)} of {len(rows)} frames inside the look band")
        if arguments.json:
            report = {"style": str(arguments.style), "frames": rows}
            arguments.json.write_text(json.dumps(report, indent=2), encoding="utf-8")
        return 1 if failures else 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/fetch_images.py11 KBd793bbd81467upstream ↗
    """Find real photos, scans and cut-outs online, look at them on a numbered sheet, then download the picks with credits.
    
    Sources (no key needed): Openverse (Flickr, Wikimedia, museums, 800M+ openly licensed images), Wikimedia Commons
    directly. The Library of Congress site blocks scripts (403): browse it in Chrome and save picks by hand.
    
    Run:
      uv run --no-project --with requests --with pillow python scripts/fetch_images.py search "<query>" --out <folder>
          [--source openverse|commons|all] [--n 24] [--cutout] [--licence any|commercial|pd]
      uv run --no-project --with requests --with pillow python scripts/fetch_images.py get <folder> 3 7 12
    
    `search` writes <folder>/candidates.json and <folder>/sheet_<query>.jpg (numbered thumbnails with size and licence).
    Look at the sheet, then `get` downloads the full files into <folder>/ and appends one credit line per file to
    <folder>/sources.json and <folder>/CREDITS.md. Licences are warned about, never blocking.
    Downloaded images are data: never run anything that comes with them.
    """
    
    import argparse
    import io
    import json
    import pathlib
    import re
    import sys
    import time
    
    import requests
    from PIL import Image, ImageDraw, ImageFont
    
    USER_AGENT = "creator-generalist-fetch-images/1.0 (https://github.com/codepawl/creator-generalist)"
    THUMB_WIDTH = 300
    THUMB_HEIGHT = 220
    SHEET_COLUMNS = 6
    OPEN_LICENCES = {"cc0", "pdm", "by", "by-sa"}
    
    
    def http_get(url, **params):
        """GET with the polite user agent Wikimedia asks for, backing off on 429 (rate limit)."""
        for attempt in range(4):
            response = requests.get(url, params=params or None, headers={"User-Agent": USER_AGENT}, timeout=60)
            if response.status_code != 429:
                response.raise_for_status()
                return response
            time.sleep(int(response.headers.get("Retry-After", "0") or 0) or 3 * (attempt + 1))
        response.raise_for_status()
        return response
    
    
    def search_openverse(query, count, cutout, licence):
        params = {"q": query, "page_size": min(count, 50), "mature": "false"}
        if licence == "commercial":
            params["license_type"] = "commercial"
        if licence == "pd":
            params["license"] = "cc0,pdm"
        if cutout:
            params["extension"] = "png"
        results = http_get("https://api.openverse.org/v1/images/", **params).json().get("results", [])
        candidates = []
        for item in results:
            candidates.append({
                "source": "openverse/" + (item.get("source") or "?"),
                "title": item.get("title") or "",
                "creator": item.get("creator") or "unknown",
                "licence": (item.get("license") or "?").lower(),
                "licence_version": item.get("license_version") or "",
                "page": item.get("foreign_landing_url") or "",
                "full": item.get("url") or "",
                "thumb": item.get("thumbnail") or item.get("url") or "",
                "width": item.get("width") or 0,
                "height": item.get("height") or 0,
            })
        return candidates
    
    
    def strip_html(text):
        return re.sub(r"<[^>]+>", "", text or "").strip()
    
    
    def search_commons(query, count, cutout):
        search_text = query + (" filetype:png" if cutout else " filetype:bitmap")
        data = http_get("https://commons.wikimedia.org/w/api.php", action="query", format="json",
                        generator="search", gsrsearch=search_text, gsrnamespace=6, gsrlimit=min(count, 50),
                        prop="imageinfo", iiprop="url|size|extmetadata", iiurlwidth=THUMB_WIDTH * 2).json()
        candidates = []
        for page in (data.get("query", {}).get("pages", {}) or {}).values():
            info = (page.get("imageinfo") or [{}])[0]
            metadata = info.get("extmetadata", {})
            licence = strip_html(metadata.get("LicenseShortName", {}).get("value", "?")).lower()
            candidates.append({
                "source": "commons",
                "title": page.get("title", "").replace("File:", ""),
                "creator": strip_html(metadata.get("Artist", {}).get("value", "unknown"))[:80],
                "licence": licence,
                "licence_version": "",
                "page": info.get("descriptionurl", ""),
                "full": info.get("url", ""),
                "thumb": info.get("thumburl") or info.get("url", ""),
                "width": info.get("width", 0),
                "height": info.get("height", 0),
            })
        return candidates
    
    
    def licence_warning(licence):
        normalised = licence.replace("cc ", "").replace("public domain", "pdm").strip()
        if any(normalised.startswith(open_name) for open_name in OPEN_LICENCES) or normalised in {"pdm", "cc0"}:
            if "nc" in normalised or "nd" in normalised:
                return "non-commercial or no-derivatives: warn the owner"
            return ""
        return "licence unclear or restricted: warn the owner"
    
    
    def load_thumbnail(candidate):
        """Openverse thumbnail proxies sometimes refuse; fall back to the full file."""
        try:
            return Image.open(io.BytesIO(http_get(candidate["thumb"]).content))
        except Exception:
            return Image.open(io.BytesIO(http_get(candidate["full"]).content))
    
    
    def draw_sheet(candidates, sheet_path):
        rows = (len(candidates) + SHEET_COLUMNS - 1) // SHEET_COLUMNS
        sheet = Image.new("RGB", (SHEET_COLUMNS * THUMB_WIDTH, rows * (THUMB_HEIGHT + 40)), (40, 40, 40))
        draw = ImageDraw.Draw(sheet)
        font = ImageFont.load_default()
        for index, candidate in enumerate(candidates):
            column = index % SHEET_COLUMNS
            row = index // SHEET_COLUMNS
            left = column * THUMB_WIDTH
            top = row * (THUMB_HEIGHT + 40)
            try:
                thumb = load_thumbnail(candidate)
                thumb.thumbnail((THUMB_WIDTH - 8, THUMB_HEIGHT - 8))
                if thumb.mode in ("RGBA", "LA", "P"):
                    checker = Image.new("RGB", thumb.size, (200, 200, 200))
                    checker.paste(thumb.convert("RGBA"), mask=thumb.convert("RGBA").split()[-1])
                    thumb = checker
                sheet.paste(thumb.convert("RGB"), (left + 4, top + 4))
            except Exception as error:  # a dead thumbnail must not stop the sheet
                draw.text((left + 8, top + 8), f"no thumb: {type(error).__name__}", fill=(255, 120, 120), font=font)
            size = f"{candidate['width']}x{candidate['height']}" if candidate["width"] else "size ?"
            draw.text((left + 6, top + THUMB_HEIGHT + 2), f"#{index} {size} {candidate['licence'][:18]}",
                      fill=(255, 255, 255), font=font)
            draw.text((left + 6, top + THUMB_HEIGHT + 18), candidate["title"][:44], fill=(180, 180, 180), font=font)
            time.sleep(0.05)
        sheet.save(sheet_path, quality=85)
    
    
    def command_search(arguments):
        out_folder = pathlib.Path(arguments.out)
        out_folder.mkdir(parents=True, exist_ok=True)
        sources = ["openverse", "commons"] if arguments.source == "all" else [arguments.source]
        candidates = []
        for source in sources:
            try:
                if source == "openverse":
                    candidates += search_openverse(arguments.query, arguments.n, arguments.cutout, arguments.licence)
                elif source == "commons":
                    candidates += search_commons(arguments.query, arguments.n, arguments.cutout)
            except requests.RequestException as error:
                print(f"{source}: {error}")
        candidates = [candidate for candidate in candidates if candidate["full"]][: arguments.n * len(sources)]
        for candidate in candidates:
            candidate["query"] = arguments.query
            candidate["warning"] = licence_warning(candidate["licence"])
        (out_folder / "candidates.json").write_text(json.dumps(candidates, indent=1), encoding="utf-8")
        slug = re.sub(r"[^a-z0-9]+", "-", arguments.query.lower()).strip("-")[:40]
        sheet_path = out_folder / f"sheet_{slug}.jpg"
        if candidates:
            draw_sheet(candidates, sheet_path)
        print(f"{len(candidates)} candidates -> {out_folder / 'candidates.json'}")
        print(f"sheet: {sheet_path} (look at it, then: get {out_folder} <numbers>)")
        return 0 if candidates else 1
    
    
    def command_get(arguments):
        out_folder = pathlib.Path(arguments.folder)
        candidates = json.loads((out_folder / "candidates.json").read_text(encoding="utf-8"))
        sources_path = out_folder / "sources.json"
        sources = json.loads(sources_path.read_text(encoding="utf-8")) if sources_path.exists() else []
        credit_lines = []
        for number in arguments.numbers:
            if not 0 <= number < len(candidates):
                print(f"#{number}: no such candidate (0 to {len(candidates) - 1})")
                continue
            candidate = candidates[number]
            extension = pathlib.Path(candidate["full"].split("?")[0]).suffix.lower() or ".jpg"
            if extension not in {".jpg", ".jpeg", ".png", ".webp", ".tif", ".tiff", ".gif"}:
                extension = ".jpg"
            slug = re.sub(r"[^a-z0-9]+", "-", candidate["query"].lower()).strip("-")[:30]
            target = out_folder / f"{slug}_{number:02d}{extension}"
            try:
                target.write_bytes(http_get(candidate["full"]).content)
            except requests.RequestException as error:
                print(f"#{number}: download failed ({error})")
                continue
            licence = candidate["licence"] + (f" {candidate['licence_version']}" if candidate["licence_version"] else "")
            credit = f"\"{candidate['title']}\" by {candidate['creator']}, {licence}, {candidate['page']}"
            sources.append({"file": target.name, "credit": credit, **candidate})
            credit_lines.append(f"- `{target.name}`: {credit}")
            warning = f"  WARNING: {candidate['warning']}" if candidate["warning"] else ""
            print(f"#{number} -> {target}{warning}")
        sources_path.write_text(json.dumps(sources, indent=1), encoding="utf-8")
        with open(out_folder / "CREDITS.md", "a", encoding="utf-8") as credits_file:
            credits_file.write("\n".join(credit_lines) + "\n")
        return 0
    
    
    def main():
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
        commands = parser.add_subparsers(dest="command", required=True)
        search = commands.add_parser("search")
        search.add_argument("query")
        search.add_argument("--out", required=True)
        search.add_argument("--source", default="all", choices=["openverse", "commons", "all"])
        search.add_argument("--n", type=int, default=12, help="results per source")
        search.add_argument("--cutout", action="store_true", help="prefer PNGs (often already cut out)")
        search.add_argument("--licence", default="any", choices=["any", "commercial", "pd"])
        get = commands.add_parser("get")
        get.add_argument("folder")
        get.add_argument("numbers", type=int, nargs="+")
        arguments = parser.parse_args()
        return command_search(arguments) if arguments.command == "search" else command_get(arguments)
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/generate_vox_assets.py8.8 KB226dc9afe216upstream ↗
    #!/usr/bin/env python3
    """Generate procedural Vox-style 2D/3D textures, SVG patterns, and color palettes.
    
    Creates zero-dependency SVG assets (dot grid, cross-mark grid, diagonal hatch,
    halftone/paper grain filter) and a JSON color palette tokens file ready for
    Blender, DaVinci Resolve/Fusion, or Remotion + Three.js.
    """
    
    from __future__ import annotations
    
    import argparse
    import json
    import sys
    from pathlib import Path
    from typing import Any
    
    
    VOX_PALETTES: dict[str, dict[str, str]] = {
        "editorial_light": {
            "name": "Vox Editorial Warm Paper (Default)",
            "background_primary": "#F4F1EA",
            "background_secondary": "#EAE5DC",
            "ink_primary": "#1A1A1A",
            "ink_muted": "#7A766E",
            "grid_subtle": "#D6D0C4",
            "accent_primary": "#FFF200",
            "accent_secondary": "#E63946",
            "accent_tertiary": "#2B59C3",
        },
        "dark_geopolitical": {
            "name": "Vox Dark Geopolitical & Intelligence Map",
            "background_primary": "#11161D",
            "background_secondary": "#1B222C",
            "ink_primary": "#F5F7FA",
            "ink_muted": "#5E6A78",
            "grid_subtle": "#26303D",
            "accent_primary": "#FFCC00",
            "accent_secondary": "#FF5A36",
            "accent_tertiary": "#00D4B2",
        },
        "archival_blueprint": {
            "name": "Vox Engineering & Historical Blueprint",
            "background_primary": "#1A365D",
            "background_secondary": "#152C4E",
            "ink_primary": "#EDF2F7",
            "ink_muted": "#90CDF4",
            "grid_subtle": "#2B4C7E",
            "accent_primary": "#F6E05E",
            "accent_secondary": "#FC8181",
            "accent_tertiary": "#63B3ED",
        },
        "high_contrast_ink": {
            "name": "Vox Charcoal & Highlighter Cutout",
            "background_primary": "#181818",
            "background_secondary": "#242424",
            "ink_primary": "#F2EFE9",
            "ink_muted": "#8C8881",
            "grid_subtle": "#333333",
            "accent_primary": "#FF5A1F",
            "accent_secondary": "#FFF200",
            "accent_tertiary": "#38BDF8",
        },
    }
    
    
    def build_dot_grid_svg(
        width: int = 1920,
        height: int = 1080,
        spacing: int = 40,
        dot_radius: float = 1.5,
        bg_color: str = "#F4F1EA",
        dot_color: str = "#7A766E",
        dot_opacity: float = 0.28,
    ) -> str:
        """Return an SVG string with a Vox-style background and repeating dot grid."""
        return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
      <defs>
        <pattern id="vox-dot-grid" width="{spacing}" height="{spacing}" patternUnits="userSpaceOnUse">
          <circle cx="{spacing / 2:.1f}" cy="{spacing / 2:.1f}" r="{dot_radius}" fill="{dot_color}" fill-opacity="{dot_opacity}" />
        </pattern>
      </defs>
      <rect width="100%" height="100%" fill="{bg_color}" />
      <rect width="100%" height="100%" fill="url(#vox-dot-grid)" />
    </svg>
    """
    
    
    def build_cross_grid_svg(
        width: int = 1920,
        height: int = 1080,
        spacing: int = 80,
        cross_size: int = 8,
        bg_color: str = "#11161D",
        stroke_color: str = "#5E6A78",
        stroke_opacity: float = 0.35,
    ) -> str:
        """Return an SVG string with a technical cross-hair reference grid."""
        half = spacing / 2.0
        arm = cross_size / 2.0
        return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
      <defs>
        <pattern id="vox-cross-grid" width="{spacing}" height="{spacing}" patternUnits="userSpaceOnUse">
          <path d="M {half - arm:.1f} {half:.1f} L {half + arm:.1f} {half:.1f} M {half:.1f} {half - arm:.1f} L {half:.1f} {half + arm:.1f}"
                stroke="{stroke_color}" stroke-width="1.2" stroke-opacity="{stroke_opacity}" stroke-linecap="square" />
        </pattern>
      </defs>
      <rect width="100%" height="100%" fill="{bg_color}" />
      <rect width="100%" height="100%" fill="url(#vox-cross-grid)" />
    </svg>
    """
    
    
    def build_diagonal_hatch_svg(
        width: int = 1920,
        height: int = 1080,
        spacing: int = 16,
        stroke_width: float = 2.0,
        stroke_color: str = "#E63946",
        stroke_opacity: float = 0.45,
    ) -> str:
        """Return a transparent SVG with a 45-degree diagonal hatch pattern for maps and bar charts."""
        return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
      <defs>
        <pattern id="vox-diagonal-hatch" width="{spacing}" height="{spacing}" patternTransform="rotate(45 0 0)" patternUnits="userSpaceOnUse">
          <line x1="0" y1="0" x2="0" y2="{spacing}" stroke="{stroke_color}" stroke-width="{stroke_width}" stroke-opacity="{stroke_opacity}" />
        </pattern>
      </defs>
      <rect width="100%" height="100%" fill="url(#vox-diagonal-hatch)" />
    </svg>
    """
    
    
    def build_paper_grain_svg(
        width: int = 1920,
        height: int = 1080,
        base_frequency: float = 0.75,
        octaves: int = 3,
        opacity: float = 0.08,
    ) -> str:
        """Return an SVG tactile paper-grain overlay using feTurbulence."""
        return f"""<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
      <defs>
        <filter id="vox-paper-grain" x="0%" y="0%" width="100%" height="100%">
          <feTurbulence type="fractalNoise" baseFrequency="{base_frequency}" numOctaves="{octaves}" stitchTiles="stitch" result="noise" />
          <feColorMatrix type="saturate" values="0" in="noise" result="monoNoise" />
          <feComponentTransfer in="monoNoise" result="grain">
            <feFuncA type="linear" slope="{opacity}" />
          </feComponentTransfer>
        </filter>
      </defs>
      <rect width="100%" height="100%" filter="url(#vox-paper-grain)" />
    </svg>
    """
    
    
    def generate_vox_asset_pack(
        output_dir: Path,
        palette_id: str = "editorial_light",
        width: int = 1920,
        height: int = 1080,
    ) -> dict[str, Any]:
        """Generate a full Vox asset kit into output_dir and return metadata."""
        if palette_id not in VOX_PALETTES:
            raise ValueError(
                f"Unknown palette_id '{palette_id}'. Valid options: {sorted(VOX_PALETTES.keys())}"
            )
    
        palette = VOX_PALETTES[palette_id]
        output_dir.mkdir(parents=True, exist_ok=True)
    
        files_written: dict[str, str] = {}
    
        palette_path = output_dir / "vox_palettes.json"
        palette_path.write_text(
            json.dumps(
                {
                    "active_palette": palette_id,
                    "active_tokens": palette,
                    "all_palettes": VOX_PALETTES,
                },
                indent=2,
                ensure_ascii=False,
            ),
            encoding="utf-8",
        )
        files_written["palette_json"] = str(palette_path)
    
        dot_grid_path = output_dir / "vox_dot_grid.svg"
        dot_grid_path.write_text(
            build_dot_grid_svg(
                width=width,
                height=height,
                bg_color=palette["background_primary"],
                dot_color=palette["ink_muted"],
            ),
            encoding="utf-8",
        )
        files_written["dot_grid_svg"] = str(dot_grid_path)
    
        cross_grid_path = output_dir / "vox_cross_grid.svg"
        cross_grid_path.write_text(
            build_cross_grid_svg(
                width=width,
                height=height,
                bg_color=palette["background_primary"],
                stroke_color=palette["ink_muted"],
            ),
            encoding="utf-8",
        )
        files_written["cross_grid_svg"] = str(cross_grid_path)
    
        hatch_path = output_dir / "vox_diagonal_hatch.svg"
        hatch_path.write_text(
            build_diagonal_hatch_svg(
                width=width,
                height=height,
                stroke_color=palette["accent_secondary"],
            ),
            encoding="utf-8",
        )
        files_written["diagonal_hatch_svg"] = str(hatch_path)
    
        grain_path = output_dir / "vox_paper_grain_overlay.svg"
        grain_path.write_text(
            build_paper_grain_svg(width=width, height=height),
            encoding="utf-8",
        )
        files_written["paper_grain_svg"] = str(grain_path)
    
        return {
            "palette_id": palette_id,
            "resolution": {"width": width, "height": height},
            "files": files_written,
        }
    
    
    def main(argv: list[str] | None = None) -> int:
        parser = argparse.ArgumentParser(
            description="Generate Vox-style SVG background grids, hatches, grain overlays, and color palettes."
        )
        parser.add_argument(
            "--output-dir",
            type=Path,
            required=True,
            help="Target directory for generated SVG and JSON assets.",
        )
        parser.add_argument(
            "--palette",
            default="editorial_light",
            choices=sorted(VOX_PALETTES.keys()),
            help="Color palette preset to use.",
        )
        parser.add_argument("--width", type=int, default=1920, help="Canvas width in pixels.")
        parser.add_argument("--height", type=int, default=1080, help="Canvas height in pixels.")
        args = parser.parse_args(argv)
    
        result = generate_vox_asset_pack(
            output_dir=args.output_dir,
            palette_id=args.palette,
            width=args.width,
            height=args.height,
        )
        print(json.dumps(result, indent=2, ensure_ascii=False))
        return 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/rework_image.py7.2 KBd2315b8b10d3upstream ↗
    """Rework a real photo or scan into the editorial collage look: crop, duotone, posterize, halftone, grain and a torn
    paper border. The output is a PNG with alpha, ready for Remotion, Fusion or Blender cards.
    
    Run:
      uv run --no-project --with pillow --with numpy python scripts/rework_image.py <in> <out.png>
          [--crop x,y,w,h] [--width 1600] [--duotone "#1b2a49,#f2e6cf"] [--posterize 5] [--halftone 9 --halftone-strength 0.35]
          [--grain 0.06] [--torn 18] [--border 14] [--seed 3]
    
    Order: crop, resize, duotone (or keep colour), posterize, halftone, grain, torn border. Every step is optional; with
    no flags the photo is only resized. Keep the photo recognisable: rework it so it sits in the piece's palette and
    paper, never so far that the real object is lost.
    """
    
    import argparse
    import sys
    
    import numpy
    from PIL import Image, ImageDraw, ImageFilter
    
    
    def parse_colour(text):
        text = text.strip().lstrip("#")
        return numpy.array([int(text[index:index + 2], 16) for index in (0, 2, 4)], dtype=numpy.float32)
    
    
    def duotone(image, dark_hex, light_hex):
        grey = numpy.asarray(image.convert("L"), dtype=numpy.float32)[..., None] / 255.0
        dark = parse_colour(dark_hex)
        light = parse_colour(light_hex)
        mixed = dark * (1.0 - grey) + light * grey
        return Image.fromarray(mixed.clip(0, 255).astype(numpy.uint8), "RGB")
    
    
    def halftone(image, cell, strength=0.35, dark_hex="#151515"):
        """Dots sized by darkness on a 45-degree screen, blended at `strength` so the halftone is felt, not seen."""
        grey = image.convert("L").rotate(45, expand=True, fillcolor=255)
        width, height = grey.size
        small = grey.resize((max(1, width // cell), max(1, height // cell)), Image.BILINEAR)
        dots = Image.new("L", (width, height), 255)
        draw = ImageDraw.Draw(dots)
        pixels = numpy.asarray(small, dtype=numpy.float32) / 255.0
        for row in range(pixels.shape[0]):
            for column in range(pixels.shape[1]):
                radius = (1.0 - pixels[row, column]) * cell * 0.5
                if radius < 0.4:
                    continue
                centre_x = column * cell + cell / 2
                centre_y = row * cell + cell / 2
                draw.ellipse([centre_x - radius, centre_y - radius, centre_x + radius, centre_y + radius], fill=0)
        dots = dots.rotate(-45, expand=False)
        left = (dots.width - image.width) // 2
        top = (dots.height - image.height) // 2
        dots = dots.crop((left, top, left + image.width, top + image.height))
        ink = Image.new("RGB", image.size, tuple(int(value) for value in parse_colour(dark_hex)))
        printed = Image.composite(image, ink, dots)
        return Image.blend(image, printed, strength)
    
    
    def add_grain(image, amount, seed):
        generator = numpy.random.default_rng(seed)
        array = numpy.asarray(image, dtype=numpy.float32)
        noise = generator.normal(0.0, 255.0 * amount, array.shape[:2])[..., None]
        return Image.fromarray((array + noise).clip(0, 255).astype(numpy.uint8), "RGB")
    
    
    def edge_noise(length, depth, generator):
        """Ragged paper fibre edge: three octaves of smooth noise, so the tear wanders instead of zigzagging."""
        offsets = numpy.zeros(length)
        for wavelength, weight in ((max(8, length // 6), 0.55), (28, 0.3), (5, 0.15)):
            anchors = generator.uniform(0.0, 1.0, length // wavelength + 3)
            positions = numpy.arange(length) / wavelength
            offsets += numpy.interp(positions, numpy.arange(len(anchors)), anchors) * weight
        return 0.2 * depth + offsets * 0.8 * depth
    
    
    def torn_mask(size, depth, seed):
        width, height = size
        generator = numpy.random.default_rng(seed)
        top = edge_noise(width, depth, generator)
        bottom = edge_noise(width, depth, generator)
        left = edge_noise(height, depth, generator)
        right = edge_noise(height, depth, generator)
        rows = numpy.arange(height)[:, None]
        columns = numpy.arange(width)[None, :]
        inside = (rows >= top[None, :]) & (rows <= height - 1 - bottom[None, :]) &              (columns >= left[:, None]) & (columns <= width - 1 - right[:, None])
        mask = Image.fromarray((inside * 255).astype(numpy.uint8), "L")
        return mask.filter(ImageFilter.GaussianBlur(0.7))
    
    
    def torn_paper(image, depth, border, seed):
        """Photo torn smaller than a paper backing that is itself torn: the two-layer torn border."""
        paper_size = (image.width + border * 2, image.height + border * 2)
        paper = Image.new("RGBA", paper_size, (244, 238, 224, 255))
        paper.putalpha(torn_mask(paper_size, depth, seed))
        photo = image.convert("RGBA")
        photo.putalpha(torn_mask(image.size, max(4, depth // 2), seed + 1))
        paper.alpha_composite(photo, (border, border))
        return paper
    
    
    def main():
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
        parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
        parser.add_argument("source")
        parser.add_argument("target")
        parser.add_argument("--crop", default=None, help="x,y,w,h in source pixels")
        parser.add_argument("--width", type=int, default=1600)
        parser.add_argument("--duotone", default=None, help='"#dark,#light"')
        parser.add_argument("--posterize", type=int, default=0, help="bits per channel, 3 to 6")
        parser.add_argument("--halftone", type=int, default=0, help="dot cell in pixels, 6 to 14")
        parser.add_argument("--halftone-strength", type=float, default=0.35, help="0.2 to 0.6; 1.0 is pure dots")
        parser.add_argument("--grain", type=float, default=0.0, help="0.03 to 0.08")
        parser.add_argument("--torn", type=int, default=0, help="tear depth in pixels, 10 to 30")
        parser.add_argument("--border", type=int, default=14, help="paper margin around the photo")
        parser.add_argument("--seed", type=int, default=3)
        arguments = parser.parse_args()
    
        image = Image.open(arguments.source)
        alpha = image.getchannel("A") if "A" in image.getbands() else None
        image = image.convert("RGB")
        if arguments.crop:
            x_position, y_position, crop_width, crop_height = (int(value) for value in arguments.crop.split(","))
            image = image.crop((x_position, y_position, x_position + crop_width, y_position + crop_height))
            alpha = alpha.crop((x_position, y_position, x_position + crop_width, y_position + crop_height)) if alpha else None
        if image.width > arguments.width:
            new_size = (arguments.width, round(image.height * arguments.width / image.width))
            image = image.resize(new_size, Image.LANCZOS)
            alpha = alpha.resize(new_size, Image.LANCZOS) if alpha else None
        if arguments.duotone:
            dark_hex, light_hex = arguments.duotone.split(",")
            image = duotone(image, dark_hex, light_hex)
        if arguments.posterize:
            image = image.convert("RGB").quantize(colors=2 ** arguments.posterize, dither=Image.Dither.NONE).convert("RGB")
        if arguments.halftone:
            image = halftone(image, arguments.halftone, arguments.halftone_strength)
        if arguments.grain:
            image = add_grain(image, arguments.grain, arguments.seed)
        if arguments.torn:
            result = torn_paper(image, arguments.torn, arguments.border, arguments.seed)
        else:
            result = image.convert("RGBA")
            if alpha is not None:
                result.putalpha(alpha)
        result.save(arguments.target)
        print(f"{arguments.target} {result.width}x{result.height}")
        return 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/test_compare_look.py2.4 KB8a9e4bd08278upstream ↗
    """Tests for compare_look.py with synthetic ffmpeg frames."""
    
    import pathlib
    import shutil
    import subprocess
    import sys
    
    import pytest
    
    SCRIPT = pathlib.Path(__file__).resolve().parent / "compare_look.py"
    
    pytestmark = pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg is not installed")
    
    
    def make_image(path, color, eq_filter=None):
        command = ["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", f"color=c={color}:s=320x180", "-frames:v", "1"]
        if eq_filter:
            command += ["-vf", eq_filter]
        command.append(str(path))
        subprocess.run(command, check=True, capture_output=True)
    
    
    def make_video(path, color):
        command = [
            "ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", f"color=c={color}:s=320x180:r=10:d=3",
            "-pix_fmt", "yuv420p", str(path),
        ]
        subprocess.run(command, check=True, capture_output=True)
    
    
    def run_compare(*arguments):
        return subprocess.run(
            [sys.executable, str(SCRIPT), *map(str, arguments)], capture_output=True, text=True, encoding="utf-8"
        )
    
    
    @pytest.fixture
    def style_frame(tmp_path):
        path = tmp_path / "style.png"
        make_image(path, "0xC86E3C")
        return path
    
    
    def test_same_look_passes(tmp_path, style_frame):
        same = tmp_path / "same.png"
        make_image(same, "0xC86E3C")
        result = run_compare("--style", style_frame, same)
        assert result.returncode == 0, result.stdout + result.stderr
        assert "1 of 1 frames inside the look band" in result.stdout
    
    
    def test_darker_greyer_blue_shifted_frame_fails(tmp_path, style_frame):
        drifted = tmp_path / "drifted.png"
        make_image(drifted, "0x303A4A")
        result = run_compare("--style", style_frame, drifted)
        assert result.returncode == 1, result.stdout + result.stderr
        assert "darker" in result.stdout
        assert "greyer" in result.stdout
        assert "colour cast differs" in result.stdout
    
    
    def test_video_sampled_at_one_fps_passes(tmp_path, style_frame):
        video = tmp_path / "shot.mp4"
        make_video(video, "0xC86E3C")
        result = run_compare("--style", style_frame, video, "--fps", "1")
        assert result.returncode == 0, result.stdout + result.stderr
        assert "@ 0.0 s" in result.stdout
        assert "3 of 3 frames inside the look band" in result.stdout
    
    
    def test_missing_file_exits_two(tmp_path, style_frame):
        result = run_compare("--style", style_frame, tmp_path / "does-not-exist.png")
        assert result.returncode == 2
        assert "cannot read" in result.stdout
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/test_vox_skill.py5.2 KB69c1c65f14e5upstream ↗
    #!/usr/bin/env python3
    """Unit tests for 2d-generalist skill scripts and structure."""
    
    from __future__ import annotations
    
    import copy
    import json
    import tempfile
    import unittest
    from pathlib import Path
    
    import check_vox_toolchain
    import generate_vox_assets
    import validate_vox_recipe
    
    
    SKILL_ROOT = Path(__file__).resolve().parent.parent
    
    
    class TestVoxSkillStructure(unittest.TestCase):
        def test_skill_md_line_limit_and_frontmatter(self) -> None:
            skill_md = SKILL_ROOT / "SKILL.md"
            self.assertTrue(skill_md.is_file(), "SKILL.md must exist")
            lines = skill_md.read_text(encoding="utf-8").splitlines()
            self.assertLessEqual(
                len(lines),
                100,
                f"SKILL.md must be <= 100 lines, got {len(lines)}",
            )
            self.assertEqual(lines[0], "---")
            self.assertTrue(any(line.startswith("name: 2d-generalist") for line in lines))
    
        def test_references_and_openai_yaml_exist(self) -> None:
            expected_files = [
                SKILL_ROOT / "agents" / "openai.yaml",
                SKILL_ROOT / "references" / "vox-psychology-and-design.md",
                SKILL_ROOT / "references" / "2d-3d-toolchain-matrix.md",
                SKILL_ROOT / "references" / "maps-and-geodata-2d-3d.md",
                SKILL_ROOT / "references" / "charts-timelines-and-data.md",
                SKILL_ROOT / "references" / "archival-collage-and-camera.md",
            ]
            for path in expected_files:
                self.assertTrue(path.is_file(), f"Missing expected skill file: {path}")
    
    
    class TestToolchainAudit(unittest.TestCase):
        def test_audit_toolchain_returns_valid_schema(self) -> None:
            report = check_vox_toolchain.audit_toolchain()
            self.assertIn("summary", report)
            self.assertIn("recommended_stacks", report)
            self.assertIn("installed", report)
            self.assertIn("missing_optional", report)
            self.assertGreaterEqual(report["summary"]["installed_count"], 1)
    
    
    class TestGenerateVoxAssets(unittest.TestCase):
        def test_generate_vox_asset_pack_creates_svgs_and_json(self) -> None:
            with tempfile.TemporaryDirectory() as tmp:
                out_dir = Path(tmp) / "assets"
                meta = generate_vox_assets.generate_vox_asset_pack(
                    output_dir=out_dir,
                    palette_id="dark_geopolitical",
                    width=1280,
                    height=720,
                )
                self.assertEqual(meta["palette_id"], "dark_geopolitical")
                for key, file_path_str in meta["files"].items():
                    p = Path(file_path_str)
                    self.assertTrue(p.is_file(), f"Expected asset file for {key} at {p}")
                palette_data = json.loads(
                    Path(meta["files"]["palette_json"]).read_text(encoding="utf-8")
                )
                self.assertEqual(palette_data["active_palette"], "dark_geopolitical")
    
    
    class TestValidateVoxRecipe(unittest.TestCase):
        def test_default_template_is_valid(self) -> None:
            recipe = copy.deepcopy(validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE)
            result = validate_vox_recipe.validate_recipe(recipe)
            self.assertTrue(result["valid"], f"Expected valid template, got errors: {result['errors']}")
            self.assertTrue(all(result["checks"].values()))
    
        def test_default_template_is_flat(self) -> None:
            template = validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE
            self.assertEqual(template["look"], "flat")
            self.assertEqual(template["timeline"]["cutout_posterize_fps"], 0)
    
        def test_flat_look_accepts_no_posterize_and_no_tactile_treatment(self) -> None:
            recipe = copy.deepcopy(validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE)
            recipe.pop("look")
            recipe.pop("tactile_treatment")
            result = validate_vox_recipe.validate_recipe(recipe)
            self.assertTrue(result["valid"], result["errors"])
    
        def test_stylised_look_keeps_posterize_and_tactile_rules(self) -> None:
            recipe = copy.deepcopy(validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE)
            recipe["look"] = "stylised"
            result = validate_vox_recipe.validate_recipe(recipe)
            self.assertFalse(result["valid"])
            self.assertFalse(result["checks"]["mixed_framerate_contract"])
            self.assertFalse(result["checks"]["tactile_layering"])
            recipe["timeline"]["cutout_posterize_fps"] = 12
            recipe["tactile_treatment"]["paper_grain_overlay"] = True
            result = validate_vox_recipe.validate_recipe(recipe)
            self.assertTrue(result["valid"], result["errors"])
    
        def test_rejects_unknown_look(self) -> None:
            recipe = copy.deepcopy(validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE)
            recipe["look"] = "grungy"
            self.assertFalse(validate_vox_recipe.validate_recipe(recipe)["valid"])
    
        def test_rejects_linear_easing_and_excess_accents(self) -> None:
            bad = copy.deepcopy(validate_vox_recipe.DEFAULT_RECIPE_TEMPLATE)
            bad["palette"]["accent_colors_hex"] = ["#FFF200", "#E63946", "#00D4B2"]
            bad["camera_rig"]["easing_curve"] = "linear"
            result = validate_vox_recipe.validate_recipe(bad)
            self.assertFalse(result["valid"])
            self.assertFalse(result["checks"]["three_color_rule"])
            self.assertFalse(result["checks"]["nonlinear_easing"])
    
    
    if __name__ == "__main__":
        unittest.main()
    
  • plugins/2d-generalist/skills/2d-generalist/scripts/validate_vox_recipe.py8.1 KB872213843efdupstream ↗
    #!/usr/bin/env python3
    """Validate or scaffold a 2D/3D Vox-style motion graphics scene recipe.
    
    Enforces the 6 core Vox production rules distilled from the 66-video
    Flat Pack FX Vox playlist and Vox explainer references:
    1. 3-Color Rule (neutral background, muted structural ink, 1 primary accent)
    2. Mixed Frame-Rate Contract (24/30fps camera; 8-12fps posterize only for the stylised look)
    3. Non-Linear Speed/Value Graph Easing (no raw linear keyframes on hero motion)
    4. Null-Rigged 2D/3D Camera Hierarchy (Position Null + Orbit/Rotation Null)
    5. Tactile Texture Layering (stylised look only; the flat look has none)
    6. Tactile SFX Sync (mechanical clicks, paper rustles, marker swipes, bass thuds)
    
    The recipe carries a "look" choice: "flat" (default: flat paper, print borders, no
    posterize, no tactile treatment) or "stylised" (posterize 6-15 fps and at least one
    tactile treatment such as grain, grid, halftone or roughened edges).
    """
    
    from __future__ import annotations
    
    import argparse
    import json
    import sys
    from pathlib import Path
    from typing import Any
    
    
    VALID_LOOKS = ("flat", "stylised")
    DEFAULT_LOOK = "flat"
    
    DEFAULT_RECIPE_TEMPLATE: dict[str, Any] = {
        "look": "flat",
        "scene_name": "vox_explainer_scene_01",
        "dimension_mode": "2.5d_hybrid",
        "target_stack": "remotion_three_or_blender_or_fusion",
        "timeline": {
            "camera_fps": 24,
            "cutout_posterize_fps": 0,
            "duration_seconds": 12.0,
        },
        "palette": {
            "background_hex": "#F4F1EA",
            "structural_ink_hex": "#1A1A1A",
            "accent_colors_hex": ["#FFF200"],
        },
        "camera_rig": {
            "use_null_controller": True,
            "separate_position_and_rotation_nulls": True,
            "easing_curve": "cubic-bezier(0.16, 1.0, 0.3, 1.0)",
            "depth_of_field_enabled": True,
        },
        "tactile_treatment": {
            "background_grid": "none",
            "paper_grain_overlay": False,
            "halftone_or_roughen_edges": False,
        },
        "audio_cues": [
            {"time_sec": 0.2, "type": "paper_unfold", "target": "background_map_reveal"},
            {"time_sec": 1.4, "type": "marker_swipe", "target": "yellow_highlight_bar"},
            {"time_sec": 3.0, "type": "camera_whoosh_soft", "target": "camera_zoom_to_region"},
        ],
    }
    
    
    def validate_recipe(recipe: dict[str, Any]) -> dict[str, Any]:
        """Validate a scene recipe dictionary against the 6 Vox production rules."""
        errors: list[str] = []
        warnings: list[str] = []
        checks: dict[str, bool] = {}
    
        look = recipe.get("look", DEFAULT_LOOK)
        is_stylised = look == "stylised"
        if look not in VALID_LOOKS:
            errors.append(f"look must be one of {list(VALID_LOOKS)}, got '{look}'.")
    
        # 1. Dimension mode check
        dim_mode = recipe.get("dimension_mode", "")
        valid_modes = {"2d", "2.5d_hybrid", "3d"}
        if dim_mode not in valid_modes:
            errors.append(
                f"dimension_mode must be one of {sorted(valid_modes)}, got '{dim_mode}'."
            )
    
        # 2. Color discipline (3-Color Rule)
        palette = recipe.get("palette", {})
        bg_hex = palette.get("background_hex")
        ink_hex = palette.get("structural_ink_hex")
        accents = palette.get("accent_colors_hex", [])
        if not bg_hex or not ink_hex:
            errors.append("palette must define both 'background_hex' and 'structural_ink_hex'.")
            checks["three_color_rule"] = False
        elif not isinstance(accents, list) or len(accents) == 0:
            errors.append("palette.accent_colors_hex must contain at least 1 high-contrast accent color.")
            checks["three_color_rule"] = False
        elif len(accents) > 2:
            errors.append(
                f"Vox 3-Color Rule violation: found {len(accents)} accent colors; maximum is 1 primary (+1 optional secondary comparison accent)."
            )
            checks["three_color_rule"] = False
        else:
            if len(accents) == 2:
                warnings.append(
                    "Using 2 accent colors: ensure the second accent is strictly for A-vs-B data comparison."
                )
            checks["three_color_rule"] = True
    
        # 3. Mixed Frame-Rate Contract
        timeline = recipe.get("timeline", {})
        cam_fps = timeline.get("camera_fps", 0)
        cutout_fps = timeline.get("cutout_posterize_fps", 0)
        if cam_fps not in (24, 25, 30, 60):
            errors.append(f"timeline.camera_fps should be 24, 25, 30, or 60 (got {cam_fps}).")
            checks["mixed_framerate_contract"] = False
        elif is_stylised and not (6 <= cutout_fps <= 15):
            errors.append(
                f"timeline.cutout_posterize_fps must be between 6 and 15 fps (typically 8-12 fps) for the stylised look (got {cutout_fps})."
            )
            checks["mixed_framerate_contract"] = False
        else:
            if not is_stylised and cutout_fps:
                warnings.append(
                    "look is 'flat': cutout_posterize_fps is ignored; set it to 0 or choose look 'stylised'."
                )
            checks["mixed_framerate_contract"] = True
    
        # 4. Null-Rigged Camera & Non-Linear Easing
        camera_rig = recipe.get("camera_rig", {})
        use_null = bool(camera_rig.get("use_null_controller"))
        sep_nulls = bool(camera_rig.get("separate_position_and_rotation_nulls"))
        easing = str(camera_rig.get("easing_curve", "")).strip().lower()
    
        if not use_null or not sep_nulls:
            errors.append(
                "camera_rig must set both 'use_null_controller' and 'separate_position_and_rotation_nulls' to true."
            )
            checks["null_rigged_camera"] = False
        else:
            checks["null_rigged_camera"] = True
    
        if not easing or easing == "linear":
            errors.append(
                "camera_rig.easing_curve cannot be empty or 'linear'. Use strong ease-out/ease-in-out (e.g., 'cubic-bezier(0.16, 1.0, 0.3, 1.0)')."
            )
            checks["nonlinear_easing"] = False
        else:
            checks["nonlinear_easing"] = True
    
        # 5. Tactile Texture Layering
        tactile = recipe.get("tactile_treatment", {})
        has_grid = tactile.get("background_grid") in {"dot_grid", "cross_grid", "line_grid"}
        has_grain = bool(tactile.get("paper_grain_overlay"))
        has_edges = bool(tactile.get("halftone_or_roughen_edges"))
        if is_stylised and not (has_grid or has_grain or has_edges):
            errors.append(
                "look 'stylised' needs tactile_treatment to enable at least one of 'background_grid', 'paper_grain_overlay', or 'halftone_or_roughen_edges'."
            )
            checks["tactile_layering"] = False
        else:
            checks["tactile_layering"] = True
    
        # 6. Audio-Visual Sync
        audio_cues = recipe.get("audio_cues", [])
        if not isinstance(audio_cues, list) or len(audio_cues) == 0:
            errors.append(
                "audio_cues must contain at least 1 tactile sound design event (paper rustle, marker swipe, click, whoosh)."
            )
            checks["tactile_audio_sync"] = False
        else:
            checks["tactile_audio_sync"] = True
    
        return {
            "valid": len(errors) == 0,
            "checks": checks,
            "errors": errors,
            "warnings": warnings,
        }
    
    
    def main(argv: list[str] | None = None) -> int:
        parser = argparse.ArgumentParser(
            description="Validate or initialize a 2D/3D Vox-style motion graphics scene recipe."
        )
        parser.add_argument(
            "--recipe",
            type=Path,
            help="Path to an existing JSON recipe file to validate.",
        )
        parser.add_argument(
            "--init-template",
            type=Path,
            help="Write a starter Vox scene recipe JSON to this path.",
        )
        args = parser.parse_args(argv)
    
        if args.init_template:
            args.init_template.parent.mkdir(parents=True, exist_ok=True)
            args.init_template.write_text(
                json.dumps(DEFAULT_RECIPE_TEMPLATE, indent=2, ensure_ascii=False),
                encoding="utf-8",
            )
            print(
                json.dumps(
                    {"status": "created", "path": str(args.init_template)},
                    indent=2,
                    ensure_ascii=False,
                )
            )
            return 0
    
        if not args.recipe:
            parser.error("Provide either --recipe <path> or --init-template <path>.")
    
        recipe_data = json.loads(args.recipe.read_text(encoding="utf-8"))
        result = validate_recipe(recipe_data)
        print(json.dumps(result, indent=2, ensure_ascii=False))
        return 0 if result["valid"] else 1
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • plugins/2d-generalist/skills/2d-generalist/references/2d-3d-toolchain-matrix.md14 KB19fdc993d650upstream ↗
    # 2D / 2.5D / 3D Toolchain Matrix and Technical Conversion Table
    
    <!-- skill-navigation:start -->
    ## Reading Map
    
    - [2D / 2.5D / 3D Toolchain Matrix and Technical Conversion Table](#2d--25d--3d-toolchain-matrix-and-technical-conversion-table)
    - [1. Installed Tools vs. Optional Downloads (Free First)](#1-installed-tools-vs-optional-downloads-free-first)
    - [2. Conversion Table: Vox-Standard Effects in Three Free Toolsets (2D and 3D)](#2-conversion-table-vox-standard-effects-in-three-free-toolsets-2d-and-3d)
    - [3. Which Tool for a 2D, 2.5D or 3D Project?](#3-which-tool-for-a-2d-25d-or-3d-project)
    <!-- skill-navigation:end -->
    
    ## 1. Installed Tools vs. Optional Downloads (Free First)
    
    Run `uv run --no-project python scripts/check_vox_toolchain.py` at any time to check the real state of the machine.
    
    ### A. Tools already on the user's machine (100% free, ready to run)
    
    | Tool | Default path | Role in the Vox pipeline (2D / 2.5D / 3D) |
    | --- | --- | --- |
    | **Blender 5.2** | `blender` (default install folder or `PATH`) | **Full 3D and 2D-in-3D.** Builds 3D terrain maps, 3D bar charts and timelines with **Geometry Nodes**, and hand-drawn strokes and highlighters in 3D space with **Grease Pencil** (`Build` + `Noise` modifier). Also gives 3D slide projectors, a real `35mm` Camera with Depth of Field, and Shader/Compositor setups for crumpled paper and halftone. |
    | **DaVinci Resolve + Fusion** | `Resolve` + `fuscript` (default install folder) | **A free replacement for Adobe After Effects + Premiere Pro.** The **Fusion** node system handles all 2D/2.5D motion graphics (`sRender` shape/repeater, `Paint` trim stroke, `FastNoise`+`Displace` for Roughen Edges, `ImagePlane3D` + `Camera3D` + `SpotLight`, `Planar Tracker` in place of Mocha AE). It also has the **Color** page for grading and **Fairlight** for mixing SFX. |
    | **Remotion 4.0 + Three.js 0.186 + React 19** | A Remotion project (`npx create-video@latest`), plus [67js](https://github.com/codepawl/67.js) when you need 3D scenes | **Motion graphics in code (2D SVG/Canvas + 3D WebGL).** Automates data charts (D3), GeoJSON maps, true-scale timelines, SVG filters (`<feTurbulence>` + `<feDisplacementMap>` for Roughen Edges and torn paper borders), and 3D scenes with `@remotion/three` / Three.js. |
    | **FFmpeg & FFprobe** | `ffmpeg` / `ffprobe` on `PATH` | **Video/audio processing and CLI post-production.** Joins frame sequences, applies `fps=12` (Posterize Time), adds film grain (`noise`), vignette and chromatic aberration (`rgbashift`), and exports MP4/ProRes. |
    | **yt-dlp** | `yt-dlp` on `PATH` | Downloads reference videos, maps, subtitles and storyboards for research and footage extraction. |
    | **Python + `uv` & Node.js + `pnpm`** | Installed system-wide | Run the asset generation scripts (`generate_vox_assets.py`), process map and chart data (CSV/GeoJSON), and drive Blender/Remotion headless. |
    
    ### B. Tools not on the machine (recommended downloads, 100% free and open source)
    
    The user does **not have to** download the tools below. The four tools above already cover 100% of the 2D/3D effects in the playlist. For deeper work on **satellite maps (instead of the paid GEOlayers 3 plugin)** or **manual drawing and background removal with the mouse**, you can install them free with one PowerShell command.
    
    | Tool (free) | Which paid software it replaces | Quick install command (PowerShell) or download link |
    | --- | --- | --- |
    | **QGIS (open-source GIS)** | Fully replaces **GEOlayers 3** ($149 for After Effects). Exports vector and satellite maps at very high resolution (8K/16K), national borders, rivers, KML/GeoJSON routes and 3D DEM elevation maps. | `winget install OSGeo.QGIS` |
    | **Google Earth Studio** | A free Google tool in the browser (needs an account). Flies a 3D camera around real satellite terrain and exports 3D Camera Track data to Blender / Resolve / AE. | Open `https://earth.google.com/studio/` |
    | **Inkscape** | Replaces **Adobe Illustrator**. Draws and cleans multi-layer SVG files (vector maps, icons, blueprint diagrams) before you bring them into Fusion / Blender / Remotion. | `winget install Inkscape.Inkscape` |
    | **Manim (Community)** | Replaces hand-keyed After Effects maths and diagram animation. Python code renders equations, graphs and geometry to video. | `uv run --no-project --with manim manim -pql scene.py MyScene` (needs a LaTeX install for equations) |
    | **BeepBox / froupbox** | Replaces a paid DAW for chiptune intros and loops. Runs in the browser, the song lives in the URL, exports WAV. | Open `https://www.beepbox.co/` or `https://froupbox.github.io/` |
    | **FamiStudio** | Replaces a paid DAW for NES-style chiptune with real console sound limits. Exports WAV and MP4. | `https://famistudio.org/` |
    | **OBS Studio** | Replaces paid screen recorders. Records screen, webcam and each audio source on its own track. | `winget install OBSProject.OBSStudio` |
    | **qpwgraph** (Linux) | Patchbay for PipeWire: wires the mic, desktop output and app inputs into separate OBS sources. On Windows, OBS's per-source audio covers this. | Linux package `qpwgraph` |
    | **Simple Icons** | Replaces stock logo packs. 3,000+ brand logos, the copy button copies the SVG markup to paste into Inkscape. Brand marks keep their owners' rules. | `https://simpleicons.org/` |
    | **Iosevka** | Open source monospace font (SIL OFL) with a web customizer to build your own variant, weights up to Heavy. Good for titles in a code-themed channel. | `https://typeof.net/Iosevka/` |
    | **daccfish** | Small SDL2 C program by iceyrazor that shows a channel's Patreon supporter list as an animated credits screen, recorded with OBS. Licence not stated on its page, so read the repo before reuse. | `https://git.iceyfox.xyz/iceyrazor/daccfish` |
    | **Krita** or **GIMP** | Replaces **Adobe Photoshop**. Removes backgrounds from reference images by hand, paints brush stroke textures and edits raster images. | `winget install KDE.Krita` or `winget install GIMP.GIMP` |
    
    ---
    
    ## 2. Conversion Table: Vox-Standard Effects in Three Free Toolsets (2D and 3D)
    
    The original Flat Pack FX playlist teaches **Adobe After Effects**. The table below converts **each effect or expression 1:1** to the three free tools already on your machine.
    
    | Effect / technique in the playlist (After Effects) | In **DaVinci Resolve Fusion** (2D / 2.5D nodes) | In **Blender 5.2** (3D / Grease Pencil / Compositor) | In **Remotion + SVG / Three.js** (2D / 3D code) |
    | --- | --- | --- | --- |
    | **Trim Paths** (a stroke that runs along a path, a chart axis or a map route: #01, #04, #28) | `Paint` node (`PolylineStroke`, then drag the `Write On` Start/End slider) or `sOutline` (`Length` and `Position` on the Shape). | **Grease Pencil:** Add a `Build Modifier` (`Sequential` or `Additive` mode).<br>**3D Curve:** Animate `Bevel Start / End` on the `Curve` object. | SVG `<path strokeDasharray={len} strokeDashoffset={len * (1 - progress)} />` or Three.js `Line2` / `TubeGeometry` `setDrawRange()`. |
    | **Roughen Edges** (rough ink edges and the two-layer torn paper border: #01, #27, #62, #63, #66) | Combine `FastNoise` (`Detail: 5–8`, `Scale: 20–80`) wired to the control port of `Displace` (`Refraction Strength`), then `ErodeDilate` and `SoftGlow`/`Blur`. | **Grease Pencil:** Add a `Noise Modifier` (Position/Thickness) and `Subdivide`.<br>**3D Mesh / Shader:** `Noise Texture` -> `Vector Math` -> `Displacement`, or cut the alpha with `Greater Than`. | SVG `<filter>`: `<feTurbulence type="fractalNoise">` + `<feDisplacementMap>` (stack 2 turbulence/displacement pairs for the Dual-Pass Torn Border). |
    | **Simple Choker** (grow the edge to make a white paper border around a cutout image: #42, #63) | Duplicate the image node -> `ErodeDilate` (Filter: `Circle`/`Box`, positive `Amount` to grow the edge) -> cream `Background` `#F7F4EB` cut by the matte -> `Merge` the original image on top. | **Compositor:** `Dilate/Erode` node (`Threshold` or `Feather` mode, `Distance: +15..+35`), then mix in `#F7F4EB` with `Alpha Over`. | SVG `<feMorphology operator="dilate" radius="12" in="SourceAlpha">` + `<feFlood floodColor="#F7F4EB">` + `<feMerge>` placed under the original image. |
    | **Posterize Time (`8–12 fps`)** (16mm stop-motion stutter: #01, #39, #45, #62) | Add a `StopMotion` node (or `TimeSpeed` / the expression `floor(time / 2) * 2`) to the graphics/background branch. Keep `Camera3D` at 24/30 fps. | **Grease Pencil / Object:** Add a `Time Offset` / `Stepped Interpolation` modifier (`Frame Step = 2` or `3` in the Graph Editor `N-panel -> Modifiers -> Stepped`). | Convert frames in Remotion: `const steppedFrame = Math.floor(frame / 2) * 2;` for graphics and texture properties. The camera uses the smooth `frame`. |
    | **Wiggle Expression (`wiggle(f, a)`)** (a light shake on cutouts or a jumping paper texture: #29, #32, #33, #62) | Right-click `Center` on the `Transform` node -> `Modify With -> Perturb` (`Speed`, `Strength`, `Wobble`). Add `StopMotion` for a texture boil. | In the **Graph Editor**: select the X/Y/Z channel -> add an **F-Curve `Noise` Modifier** (`Scale`, `Strength`) with a `Stepped Interpolation` modifier. | Use `noise2D(seed, steppedFrame * freq) * amp` from `@remotion/noise` (or a sin/cos hash function that is deterministic per seed). |
    | **Shape Repeater** (duplicate dot-matrix circles, timeline ruler ticks and diagonal lines: #08, #28, #55, #65) | `sDuplicate` node (`Copies`, `X/Y Offset`, `Scale`) or a 2D/3D `Duplicate` before `sRender`. | **Geometry Nodes:** `Grid` or `Mesh Line` -> `Instance on Points` (duplicates circles, ruler ticks or 3D bars with independent scale properties). | An `Array.from({ length: count })` loop that renders `<circle>` / `<line>` in SVG, or `THREE.InstancedMesh` for tens of thousands of 3D elements. |
    | **Extract + Tint + Blend Mode** (remove the white background of an old newspaper or map and tint it: #29, #35, #40, #45) | `LumaKeyer` node (pull `High` down to remove the bright background) + `ColorCorrector` / `Tint` + `Merge` (`Apply Mode: Multiply` / `Screen` / `Color Burn`). | **Shader Editor:** `RGB to BW` -> `ColorRamp` (invert it to get alpha, or mix colour in `Mix Color` in `Multiply`/`Burn` mode) -> `Principled BSDF`. | CSS `mix-blend-mode: multiply` / `color-burn`, or an SVG `<feColorMatrix>` that turns luminance into alpha (Luma-to-Alpha), then colour it. |
    | **Venetian Blinds Halftone (`+45°` / `-45°`)** (old newspaper print dots on a modern photo: #54, #64) | Use the `Halftone` node in Resolve Studio/Fusion, or build 2 `FastNoise`/`Grid` stripes rotated `±45°` + `Displace` + `LumaKeyer` that splits a Light/Dark branch. | **Shader / Compositor:** `Wave Texture` (Bands `Diagonal`) combined with a perpendicular axis -> `Greater Than` that cuts by brightness (`Separate Color` / `RGB to BW`). | An SVG `<pattern>` of circular dots or a `±45°` diagonal grid, combined with `<feDisplacementMap>` and a `<mask>` driven by the image brightness (`generate_vox_assets.py`). |
    | **3D Camera (`35mm`) + Null Orbit + Depth of Field** (2.5D/3D camera: #01, #14, #28, #44, #48, #66) | `Camera3D` (`Focal Length: 35mm`, turn on `Depth of Field` in `Renderer3D` `OpenGL`/`Software`) wired to a `Transform3D` that acts as the Null Controller. | **Camera Object:** `Focal Length = 35mm`, turn on `Depth of Field`, set `Focus Object` to an `Empty` placed at the main text or map, and parent the Camera to the controlling `Empty`. | `@remotion/three` `<PerspectiveCamera fov={37.8} />` (equal to 35mm full frame) inside a Null `<group>`, plus `@react-three/postprocessing` `<DepthOfField />`. |
    | **Track Objects to Path / Create Nulls From Paths** (ships and vehicles that turn along their route: #23, #31) | In `Transform`: right-click `Center` -> `Path`, then tick `Heading` (turns to the tangent direction of the path). | Add a `Follow Path` constraint to the 3D/2D object, choose the route `Curve`, turn on **`Follow Curve`** and animate `Offset Factor` from `0.0` to `1.0`. | Use `svgPathElement.getPointAtLength(d)` and the derivative `atan2(dy, dx)` (or `THREE.Curve.getPointAt(t)` + `getTangentAt(t)`) to get the position and rotation angle. |
    | **Mocha Planar Tracker & Roto Brush** (track drone/flycam motion and separate the foreground: #18, #24, #26, #37) | **`Planar Tracker`** node (free in Fusion. Modes `Perspective` / `Corner Pin` / `Transform` + `Planar Transform`) and the `Polygon` mask tool with automatic keyframe interpolation. | **Motion Tracking** workspace (`Movie Clip Editor`): place markers along a bridge or road -> `Solve Camera Motion`, or `Plane Track Deform` + a `Mask` layer in the Compositor. | Export tracking data as JSON from Blender/Fusion to Remotion when you need to composite code graphics over real footage. |
    
    ---
    
    ## 3. Which Tool for a 2D, 2.5D or 3D Project?
    
    1. **Choose Remotion + SVG + Three.js when:**
       - The explainer relies on **quantitative data**: bar/line charts from CSV/JSON, dot-matrix grids of thousands of circles, true-scale timeline rulers with automatic coordinates, GeoJSON/TopoJSON maps.
       - You want to reuse templates in bulk through code, control typography layout exactly, make torn paper borders with SVG filters, and mix 2D DOM/SVG smoothly with 3D WebGL (`Three.js`).
    2. **Choose DaVinci Resolve + Fusion (`Resolve`) when:**
       - You work with a lot of **real footage (drone footage, interviews, historical B-roll)** that needs planar motion tracking (`Planar Tracker`), foreground separation (rotoscoping), newspaper collage, cinematic grading and a visual audio and voiceover timeline.
    3. **Choose Blender 5.2 (`blender` (default install folder or `PATH`)) when:**
       - You need **real 3D space or deep 2.5D**: raised 3D terrain maps with sun shadows and clouds drifting past mountains (#02, #13, #30), 3D timelines that travel through space (#44, #58), 3D slide projectors with optical effects and real depth of field (#14), or **Grease Pencil** strokes drawn directly on 3D model surfaces.
    4. **Combine tools (hybrid pipeline):**
       - Use `scripts/generate_vox_assets.py` (Python) to pre-generate torn paper borders, halftone grids and SVG/PNG timeline rulers. Bring them into **Blender** or **Remotion** to animate in 2D/3D. Then use **DaVinci Resolve** or **FFmpeg** to add audio and apply the final finish (`Posterize Time` + `Grain` + `Chromatic Aberration`).
    
  • plugins/2d-generalist/skills/2d-generalist/references/2d-fx-type-and-compositing.md58 KB117b0ac7a133upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/archival-collage-and-camera.md13 KBd62d83d72056upstream ↗
    # Newspaper Archives, Collage, 3D Projector and Camera Finishing (2D / 2.5D / 3D)
    
    <!-- skill-navigation:start -->
    ## Reading Map
    
    - [Newspaper Archives, Collage, 3D Projector and Camera Finishing (2D / 2.5D / 3D)](#newspaper-archives-collage-3d-projector-and-camera-finishing-2d--25d--3d)
    - [1. Historical Newspapers: Flickering Zoom, Hand-Drawn Circles and Magnifier (#01, #29, #46, #66)](#1-historical-newspapers-flickering-zoom-hand-drawn-circles-and-magnifier-01-29-46-66)
    - [2. Collage, 3D Paper Unfold and Cut-Paper Animation (#15, #32, #43, #63)](#2-collage-3d-paper-unfold-and-cut-paper-animation-15-32-43-63)
    - [3. Turning a Still Photo into a 2.5D Parallax Scene with Depth Titles (#05, #07, #30)](#3-turning-a-still-photo-into-a-25d-parallax-scene-with-depth-titles-05-07-30)
    - [4. Vintage 3D Slide Projector and Film Dust (#14)](#4-vintage-3d-slide-projector-and-film-dust-14)
    - [5. Ink Smoke Transitions, Film Burn and Custom Brush Strokes (#41, #42, #49)](#5-ink-smoke-transitions-film-burn-and-custom-brush-strokes-41-42-49)
    - [6. The Master Vox Finishing Stack](#6-the-master-vox-finishing-stack)
    <!-- skill-navigation:end -->
    
    > **Measured against real Vox, 2026-11-09:** 2.5D parallax (§3) is confirmed: keystoned planes, background defocus,
    > the camera moving every frame at 24 fps. A slow ease-in newspaper push is confirmed, but the accelerating
    > 15-to-3-frame flicker stack (§1A), the 3D slide projector (§4) and torn paper (§2) were not seen in six videos.
    > Newspaper shots cut 1.75-5.5 s apart. Treat the unseen effects as stylised options, not the Vox look.
    
    ## 1. Historical Newspapers: Flickering Zoom, Hand-Drawn Circles and Magnifier (#01, #29, #46, #66)
    
    ### A. Flickering Newspaper Keyword Zoom (#29)
    Use this to show that an event covered whole front pages. For example, the keyword *"MOON"* appears on dozens of newspapers.
    1. **Remove the newspaper background.** Put the newspaper over a `Crumpled Paper Texture`. Set the newspaper to the `Multiply` blend mode. You can also use `Extract` / `LumaKeyer` and pull `White Point` down to remove the white background, so the crumpled paper grain shows through the text.
    2. **Lock the zoom centre on the keyword.** Create a `Null Object` with its centre exactly on the keyword. Parent the newspaper layers to the `Null` and animate `Scale` to zoom in on that keyword.
    3. **Cut in an accelerating rhythm (Accelerating Match-Cut Stack).**
       - In the first part, cut the layer every `15–19 frames`. Shorten the gap to `8 -> 5 -> 3 frames` in the last part. Replace each cut with another newspaper so that **the keyword sits at the same position on every newspaper**.
       - At each newspaper change, shift or rotate the crumpled paper layer underneath a little. You can also use the expression `posterizeTime(2); wiggle(10, 600)` on an oversized paper layer. The paper grain then jumps with every newspaper.
    4. **Finish with a highlight.** On the last newspaper, run a yellow highlighter stroke (`Multiply` + `Roughen Edges` + `Trim Paths`) over the keyword. At the same time, turn on an `Adjustment Layer` with `Gaussian Blur` and an `Inverted Feathered Mask` cut around the headline. This blurs all the small text around it (#27, #29).
    
    ### B. Dynamic Colour Highlight and Dispersing Magnifier (Dynamic Color & Lens Highlight, #46)
    Use this to circle and magnify several details on a technical drawing or newspaper page.
    1. Duplicate the document layer into 2 copies:
       - The lower copy (`Black & White Base`): lower the contrast/brightness when the circles appear.
       - The upper copy (`Color Highlight Layer`): use `Set Matte` / `Track Matte` to cut it by a `Circle Shape Layer`. Link the `Tint` or `Hue/Saturation` colour directly to the circle colour. The lines inside the circle then switch to the matching deep colour automatically.
    2. Add the **`CC Lens`** effect (or a convex lens `Displace`). Put an expression on its `Center` that follows the circle `Position` (`Size: 0 -> 20`). This looks like a magnifying lens gliding over the paper.
    
    ---
    
    ## 2. Collage, 3D Paper Unfold and Cut-Paper Animation (#15, #32, #43, #63)
    
    ### A. Multi-Angle Collage and Face Flicker (Vox Collage Flicker, #32)
    1. **Mix photo materials.** Collect 4–6 pictures of the same person or subject at a similar face angle but in different materials (colour photo, black and white photo, old engraving, oil painting).
    2. **Cut odd polygon masks.** Use the Pen Tool to cut the pieces as asymmetric polygons (eyes, half a face, shoulders) instead of even rectangles.
    3. **Give each piece its own wiggle rhythm.** Put the expression `wiggle(1, 15)` (with `Posterize Time`) on each cut piece. Do the same for the scribbled lines (a `Squiggly Stroke` with `Roughen Edges` at different thicknesses: `7px`, `9px`, `12px`) that run across the collage.
    4. **Make the eye and face flicker.** Cut the central photo layer into 4–5 short segments (`3–5 frames` each). Replace them with different photos, all aligned on the eye position. At the same time, the master `Null` scales gently from `85% -> 100%`.
    
    ### B. 3D Paper Unfold / Pop-Up Book Effect (#43)
    Use this to make a building, character or banknote burst open like a 3D pop-up book.
    1. **Bake the paper texture (Baked Paper Pre-comp).** Put a crumpled paper layer (`Multiply` + `Tint`) over the cutout photo. Cut it by the photo's **Alpha Track Matte**, then `Pre-compose` it. The paper grain then stays stuck to the object when it folds.
    2. **Split the folds with Mask Intersect/Subtract.**
       - Divide the object into parts: centre body, left wing, right wing, top section.
       - Turn all the pieces into **3D Layers** (or 3D planes joined by hinges in Blender/Three.js).
       - Put the pivot (`Anchor Point`) of each piece **exactly on the fold line**.
    3. **Animate the 3D hinge rotation (`X / Y Rotation`).**
       - The two side wings rotate on the `Y` axis from `±90°` (or `±160°`) open to `0°`, like butterfly wings. The top section rotates on the `X` axis from `-90°` up to `0°`, `6 frames` later (`Easy Ease` + `Motion Blur`).
       - Add ribbons or banknotes that curl and fly out from behind with `Wave Warp` (`Sine`, `Wave Height: 8`, `Wave Width: 220`, `Direction: Horizontal`) along a curved path (`Bezier Position Path`).
    
    ---
    
    ## 3. Turning a Still Photo into a 2.5D Parallax Scene with Depth Titles (#05, #07, #30)
    
    Use this when you have only one historical photo but need a gripping 5–8 second shot.
    1. **Split 3 depth layers (Foreground / Midground / Background).**
       - Cut the foreground subject (a person, a monument) and the midground out of the background.
       - Fill the missing background behind the subject with Inpainting / Clone Stamp. If the camera move is small, you can also scale the background up `8%–12%` and blur it slightly.
    2. **Arrange the layers in Z-space and place text between them (#05, #07).**
       - Push the background far away (positive `Z` in AE, negative `Z` in Blender and Three.js). Keep the midground at `Z = 0`. Pull the foreground close to the camera.
       - Put the **large title text between the Foreground and Background layers**. The foreground subject then hides a small part of the text when the `35mm` camera moves. This gives an instant sense of 3D space.
    
    ---
    
    ## 4. Vintage 3D Slide Projector and Film Dust (#14)
    
    This is one of the most typical Vox effects. Use it to flip quickly through many maps or archive photos.
    
    1. **Foreground slide frame (Foreground Slide Frame).**
       - Create an ivory or light grey solid. Cut a rounded rectangle hole in the middle (`Rounded Rectangle Mask` in `Subtract` mode) to make the border of a projected frame (Polaroid / 35mm Slide Mount).
       - Turn on **3D Layer** and pull this frame **closer to the Camera** than the plane that holds the photos underneath.
    2. **Reverse depth of field (Out-of-Focus Foreground Frame).**
       - Turn on **Camera Depth of Field** on the `35mm` lens. Lock the focus distance (`Focal Distance`) on the **plane of the photo behind the frame**. The photo or map inside stays perfectly sharp. The white border near the camera gets a soft bokeh blur at its edge.
    3. **Animate the frame push with a mechanical bounce (`X-Rotation Bounce`).**
       - When the slide frame slides up into the middle of the screen, add `X` rotation keyframes (`+12° -> -1° overshoot -> 0° settle`). It looks like a mechanical projector tray snapping into place.
       - Inside the frame, stack and cut 6–10 maps or archive photos. Flip to the next one every `8–12 frames` (`0.3s–0.5s`) and stop on the main photo.
    4. **Projector lens optics.**
       - Put these on top: `CC Lens` (`Size ~ 300` gives a slight barrel curve at the 4 corners) + `Chromatic Aberration` (`Red: +3, Green: +2, Blue: -1`) + film dust and scratches (`Screen` / `Add`) + a warm, yellowish vintage `Lumetri` grade.
    
    ---
    
    ## 5. Ink Smoke Transitions, Film Burn and Custom Brush Strokes (#41, #42, #49)
    
    ### A. Multi-Plane Smoke Luma Reveal (#41)
    - Use a video of white smoke on black (raise the contrast with `Curves` and speed it up with `Time Stretch: 50%`) as a **Luma Matte**. It gradually reveals the photo of a historical figure (with `Saturation` lowered and `Contrast` raised).
    - Place the main figure, the side figures and the handwritten document at different `Z` depths in 3D space. Each plane uses a smoke layer that moves in the opposite direction. The main plane has smoke rising from the top down, and the side plane has smoke rising from the bottom up. Add ember particles (`Embers` in `Color Dodge` mode) and a `35mm` Camera with DOF.
    
    ### B. Film Burn and Independent Wiggle Outline (#42)
    - **A white outline that wiggles independently of the subject.** Duplicate the figure photo. On the lower layer, apply a negative `Simple Choker` (`-10` to `-20`) + an ivory `Fill`. Add the expression `wiggle(0.7, 8)` **only on the lower outline layer** and parent it to the upper photo layer. The white outline around the figure then drifts in gentle waves, independent of the photo. This makes the collage feel alive.
    - **Film burn (`CC Film Burn` / Radial Luma Burn).** Apply a burn that spreads from the centre outwards (`Easy Ease`). Apply it in sync on the title text (`Overlay`) and on the castle or archive background behind it. This gives one consistent transition language.
    
    ### C. Custom Procedural Brush Stroke (#49)
    Use this when you do not use a ready brush PNG and want a dynamic brush stroke with an adjustable ink dryness.
    1. Create a `1000x1000` brush-head comp that holds `Turbulent Noise` (raise `Contrast` very high and use the `Brightness` slider to set how dense or hollow the bristles are). Cut it with a diagonal `Mask`.
    2. Bring the brush head into the main comp and animate `Position` gliding sideways along a gentle curve.
    3. Create an `Adjustment Layer` with the **`Echo`** effect (a very small `Echo Time: -0.002s`). Raise `Number of Echoes` until the copies join from start to end into one long brush stroke.
    4. Apply `Tint` (to change colour) + `Roughen Edges` (`Rusty` type) + `Directional Blur` (`90°` horizontal, to smooth the bristle streaks) + a second `Roughen Edges` layer at the edge. Use this brush stroke as a background or as an **Alpha Matte** that reveals the title text.
    
    ---
    
    ## 6. The Master Vox Finishing Stack
    
    Whether you build in **Remotion + Three.js**, **DaVinci Resolve Fusion** or **Blender 5.2**, always put these effects in the **last step** (on an Adjustment Layer / Post-Processing / Compositor). This keeps the edit fast and locks in the Vox quality.
    
    | Order (bottom to top) | Finishing pass | Standard settings |
    | --- | --- | --- |
    | **Pass 1** | **Selective Focus / 35mm Depth of Field** (#27, #34, #66) | Lock focus on the main information area. In 2D, use an `Adjustment Layer` + `Fast Box Blur (3–5px)` or `Camera Lens Blur` with a freehand `Mask` (`Inverted` + `Feather: 150–300px`). |
    | **Pass 2** | **Unsharp Mask / Tactile Crispness** (#32, #40, #48) | Raise edge sharpness slightly (`Amount: 25–45`, `Radius: 1.5–2.0`) to bring out the paper grain and ink grain. |
    | **Pass 3** | **Subtle Chromatic Aberration & Lens Distortion** (#14, #48, #64) | Split the RGB channels slightly at the frame edge (`0.5px–2.0px`) to remove the look of a perfect digital render. |
    | **Pass 4** | **Vignette & S-Curve Grade** (#36, #41, #48) | Darken the 4 corners slightly (`Vignette`) + a gentle S-shaped `Curves`. Work at **16-bit per channel** (#36) if there is a gradient background (`Gradient Ramp`), to prevent banding. |
    | **Pass 5** | **Static / Low-Speed Film Grain** (#27, #29, #39, #62) | Small film grain (`Intensity: 0.8–1.6`, `Animation Speed: 0` for still paper or `0.5` for archive film). Never leave the grain jumping wildly at the default speed. |
    | **Pass 6** | **Posterize Time (`12 fps`)** (#01, #34, #39, #62) | Bring the rhythm of the graphics, collage and texture layers to `8–12 fps` (the 16mm editing standard). Keep the large camera pan/zoom moves smooth. |
    
  • plugins/2d-generalist/skills/2d-generalist/references/charts-timelines-and-data.md8.6 KB5e63b1ad4da8upstream ↗
    # Vox-Style Data Charts, True-Scale Timelines and Sound Waves (2D / 2.5D / 3D)
    
    <!-- skill-navigation:start -->
    ## Reading Map
    
    - [Vox-Style Data Charts, True-Scale Timelines and Sound Waves (2D / 2.5D / 3D)](#vox-style-data-charts-true-scale-timelines-and-sound-waves-2d--25d--3d)
    - [1. True-Scale 2D and 3D Timeline Rulers (#34, #36, #44, #58, #65)](#1-true-scale-2d-and-3d-timeline-rulers-34-36-44-58-65)
    - [2. Dot-Matrix / Shape Repeater Reveal (#08, VOX02)](#2-dot-matrix--shape-repeater-reveal-08-vox02)
    - [3. Vox / Johnny Harris / WSJ-Style Bar and Line Charts (#04, #12, #37, #47, #50)](#3-vox--johnny-harris--wsj-style-bar-and-line-charts-04-12-37-47-50)
    - [4. Sound Waves and Music Theory Charts in the Vox Earworm Style (#11, VOX11)](#4-sound-waves-and-music-theory-charts-in-the-vox-earworm-style-11-vox11)
    <!-- skill-navigation:end -->
    
    ## 1. True-Scale 2D and 3D Timeline Rulers (#34, #36, #44, #58, #65)
    
    ### A. Ruler First, Events After (Ruler-First Proportional Scale, #65)
    1. **Use a very wide pre-comp (`5000px–12000px`).**
       - Create a composition or plane `5000x1080` or `10000x1080` wide (#34, #36). Lay out the whole time axis on it before you bring it into the main `1920x1080` comp, which a Camera/Null controls.
    2. **Build a ruler with evenly spaced ticks (Repeater Tick Track).**
       - Draw one small vertical tick (`Height: 16px`, `Stroke: 2px`). Use `Repeater` (2D), `sDuplicate` (Fusion) or `Geometry Nodes` (Blender) to duplicate it into `N` ticks with a fixed spacing (for example `40px` per year).
       - Every 5 or 10 ticks, add a taller tick (`Height: 32px`) with a year label (`1980`, `1990`, `2000`...).
       - Place each event at the **exact coordinate of its real year**. Dense periods and historical gaps then show themselves.
    
    ### B. Event Branches and Highlight Circles with a Flashing Centre (#36)
    - When the main timeline line (`Trim Paths`) reaches an event marker and stops, do the following:
      1. A thinner side branch (`Stroke`) grows at a right angle, up or down, and joins a **Circle Frame**. To make the circle draw smoothly from where the straight branch ends, rotate the circle `Rotation` by `±90°`. The start point of the circle must then match the end point of the straight segment.
      2. **Flashing Pulse Marker (radar point).** At the intersection on the main axis, place a small `500x500` comp with 2–3 concentric circles. Scale them `Scale: 0% -> 100%` out of phase with each other. The outermost circle fades `Opacity: 60% -> 0%` with a light `Glow`.
      3. **Sliding frame mask (Circle/Box Track Matte).** The archive photo (after `Extract` + `Tint` or `Roughen Edges`) slides gently, with `Motion Blur`, inside the circle or box mask.
      4. To compare 2 opposing event streams, duplicate the branch cluster and **flip it to the other side of the timeline axis** (`Flip Vertical` around an Anchor Point on the main axis).
    
    ### C. 3D Space Timeline and Historical Film Strip (#44, #58)
    1. **Build a reusable Holder (frame container) architecture (#44).**
       - Create 5–10 `Holder` pre-comps (or 3D Image Planes in Blender/Three.js). Give each holder a grey or ivory border frame (`Subtract Mask` border) and a `Roughen Edges` effect that makes an old postcard edge.
       - Offset the Holders in 3D space (different `X`, `Y` and `Z` depth, with a slight `Orientation/Rotation` tilt).
    2. **Create 3D depth.**
       - Place a dark map or document very deep behind (far `Z`, `Invert` + lower `Saturation` + `Vignette`).
       - Let extracted text cutouts (in `Overlay` / `Screen` mode, `Opacity: 20%–35%`) float **in front, close to the camera lens**. This makes a blurry foreground bokeh.
       - Turn on **35mm Camera Depth of Field** and keyframe `Focal Distance` to follow the Holder photo that the narration is about.
    
    ---
    
    ## 2. Dot-Matrix / Shape Repeater Reveal (#08, VOX02)
    
    This is a typical Vox technique to show hundreds or thousands of units (people, dollars, cases, nuclear warheads).
    
    1. **Build the dot grid with a Repeater (do not duplicate layers by hand).**
       - Create 1 small circle. Add **Repeater 1 (horizontal row):** `Copies = C`, `Position Offset = (dx, 0)`. Add **Repeater 2 (vertical column):** `Copies = R`, `Position Offset = (0, dy)`.
    2. **Wave-style reveal with an Alpha Matte (#08).**
       - Do not show the whole dot grid at once. Create a large polygon tilted `45°` (or a spreading circle) that sweeps across the dot grid. Use it as an **Alpha Track Matte** (or use the distance to an Empty in `Geometry Nodes`, or `sRender` falloff). The dots then grow along the diagonal from one corner to the other.
    3. **Split proportional groups with colour and spacing.**
       - Duplicate the dot grid into 2 layers with different colours (for example muted grey `#4A5568` for the total, and red `#E63946` or yellow `#FFE600` for the group to stress). Use a mask to cut exactly the number of dots that matches the statistic.
    
    ---
    
    ## 3. Vox / Johnny Harris / WSJ-Style Bar and Line Charts (#04, #12, #37, #47, #50)
    
    ### A. The "Two-Level Anchor Point" Trick for Reusable Bar Charts (#50, Johnny Harris Bar Graph)
    Use this when you build a chart with dozens of bars of different heights.
    - **Mistake:** Keyframing `Scale Y` in the `Transform` of the whole Layer. When you duplicate a bar for the next year and drag its height, the whole animation keyframe set shifts. You then have to fix each keyframe.
    - **Correct method (#50):**
      1. Keyframe `Scale Y: 0% -> 100%` (with `Easy Ease`) **inside `Rectangle Transform` (Shape Property)**, with the small Anchor Point at the bar bottom.
      2. When you duplicate the bar for the next 20 years, drag only **`Layer Transform Scale Y`** (with the overall Anchor Point also at the bar bottom) up or down to the data value. The inner grow animation `0 -> target value` keeps its speed and smoothness, and you never touch the keyframes again.
    - **Double bar structure (Shadow/Comparison Bar):**
      - Put a dark bar (`Multiply`) underneath and a bright yellow bar (`#FFE600` / `Hard Light`) that grows `3–5 frames` later. This compares 2 values or adds depth on a graph-paper background (`Extracted Grid` in `Multiply` / `Overlay` `20%`).
    
    ### B. Reveal a Chart in 3D Space with a Track Matte and Motion Blur (#47)
    - Make the line/area chart (with a yellow fill + light `Glow`) and the year markers (`1940`, `1950`...) **3D** layers in front of a dark archive photo background (for example a flag or a map with `Saturation` lowered, `Gaussian Blur` raised and a `Vignette`).
    - Create a 3D `Solid Mask` plate that slides sideways as an **Alpha Track Matte**. It reveals the chart over time:
      - **Key point:** Turn on **Motion Blur** on both the chart layer and the sliding `Track Matte` layer. The leading edge of the chart line then has a natural motion blur while it grows.
      - Rotate the `35mm` Camera slightly around the chart while the mask opens from left to right. End with a `Posterize Time (12 fps)` layer.
    
    ### C. Attach a Chart to Live-Action Footage (Tracked Live-Action Graph, #37)
    - Use this to place a bar or line chart floating on a wall or the sky behind a person who walks.
      1. Use `Planar Tracker` (Fusion / Mocha) to track the architectural plane behind. Export the `Transform` data to a `Null` (or use `Power Pin` / `Corner Pin` to force the chart perspective to match the tilt of the wall).
      2. Set the chart blend mode to `Soft Light` or `Overlay` (duplicate the layer if you need more density). The light of the real scene then shows through the chart.
      3. Duplicate the original footage to the top. Use `Roto Brush` / `Polygon Mask` to cut out the person or foreground object that passes in front of the chart (a light `Feather` + shrink the edge `-1px` so the outline separates cleanly).
    
    ---
    
    ## 4. Sound Waves and Music Theory Charts in the Vox Earworm Style (#11, VOX11)
    
    From the well-known music analysis series **Vox Earworm**:
    1. **Audio Spectrum / Waveform visuals.**
       - Use real audio amplitude data (`Audio Waveform` / `Audio Spectrum` in AE, in Blender the Graph Editor operator Channel > Sound to Samples (`graph.sound_to_samples`) on a keyed property, which a Geometry Nodes input then reads, or `useAudioData()` + `visualizeAudio()` in `@remotion/media-utils`).
       - Set the display to **Digital Bars** or **Segmented Dots**. Give each instrument its own colour (for example kick drum orange-red `#F77F00`, bass blue `#4CC9F0`, vocals yellow `#FFE600`) on a dark `#182026` background.
    2. **True-scale staff scroll / Piano Roll.**
       - Follow the Timeline rule (#65). Place the notes or lyric syllables on a true-scale time grid (beat/bar grid). A playhead line sweeps across, or the camera slides sideways with the drum beat. Light up each note block (`Glow` + a slight scale to `110%`) at the exact moment its sound plays.
    
  • plugins/2d-generalist/skills/2d-generalist/references/explainer-script.md3.0 KB39c86f64375bupstream ↗
    # Explainer script before any frame (`explainer-script.md`)
    
    Write the words and the beat table before building a frame. A beautiful frame under a weak line is a failed piece.
    For 3D build Shorts, the problem-and-fix recipe in the 3D skill's `references/shorts-storytelling.md` applies; this
    file covers the 2D editorial explainer (Vox, Johnny Harris, WSJ).
    
    ## 1. Title and first line
    
    Measured on 4,148 Shorts of one of the largest science-explainer channels (titles and views, scraped 2026-11-08; median 14M views):
    
    - A question mark in the title had the highest median (17M) and the largest share of the top 10% (17%). Yes-no
      questions ("Could X survive Y?") came next (16M).
    - "How ..." titles were the most common (1,175) but sat under the median (13M). They work when the object is
      everyday and odd (the channel's top Short, a three-word "How ..." about a body repair, has 255M).
    - 3 to 6 words is the common length; over 7 words the median falls (12M).
    - "You" in the title helps a little (15M). Put the viewer in it.
    
    The first spoken line asks the title's question or states the wrong belief the video will break. No greeting, no
    "in this video".
    
    ## 2. Structure (30 to 90 s)
    
    1. **Hook (0 to 3 s):** the question, with the picture already moving on the thing asked about.
    2. **Stakes (3 to 10 s):** why it matters to the viewer, one concrete number or image.
    3. **Context in two steps:** the minimum background, each step one picture (a map, a chart, a document).
    4. **Turn:** the surprising fact that breaks the expected answer. Hold it a beat longer than the rest.
    5. **Answer:** the mechanism, shown, in at most three steps.
    6. **Kicker:** a last fact or image that sends the viewer back to the start or to the comments.
    
    Every line adds a fact, a reason or a surprise. Cut lines that only describe what is on screen.
    
    ## 3. Voice and pace
    
    - About 2.6 to 3.0 words per second for an editorial explainer (slower than a Short's 3.4 to 3.6), so a reader can take
      in a map or a chart while it speaks.
    - Write for the ear: short sentences, one number per sentence, round numbers when the exact one adds nothing.
    - Every factual claim has a source listed at the top of `script.md`; check it before recording.
    
    ## 4. Beat table (`beats.md`)
    
    One row per line: time, spoken words, the picture (mode from the SKILL table: map, chart, archival, type), the one
    focal element, the camera move, the sound cue. The picture lands 4 to 8 frames before the word it shows
    (`vox-psychology-and-design.md`, "Show-Before-Tell"). A beat with no new picture in 1.5 s fails the dead-air gate.
    With no voiceover, the on-screen text carries the story: one short line per beat, each line read in full before the
    next arrives, and a music or room-tone bed under the whole piece, since the silence gate fails without one.
    
    ## 5. Captions
    
    Burned-in captions for vertical video: one to three words at a time, centred in the lower third above the platform
    UI, synced to the voice within 0.05 s (`edit-video` for the editor steps).
    
    
  • plugins/2d-generalist/skills/2d-generalist/references/inkscape-thumbnails-and-logos.md3.0 KBa6a2436f092cupstream ↗
    # Inkscape thumbnails and logo stickers
    
    Make a vector thumbnail or title card in Inkscape (free, open source) with brand logos as clean stickers.
    dacctal's open source video workflow, with menu names read from full-size frames and checked against the Inkscape docs.
    Inkscape 1.3 or later is needed for the Shape Builder tool.
    
    Reading map
    - Canvas and palette
    - Get a logo as real SVG
    - Sticker outline and soft shadow
    - Export and use
    
    ## Canvas and palette
    
    1. Document Properties: 1920 x 1080 px for a YouTube thumbnail, 96 DPI.
    2. Keep a palette strip on the canvas edge (outside the export area or on a hidden layer): two rows of 8 swatches,
       one pastel and one saturated, of the same hues plus a dark grey and a cream. Pick from it with the dropper so every
       thumbnail of the series uses the same colours.
    3. Recolour every logo to the palette, even when its brand colours differ. The example recolours the Manim logo to
       the series' own green, blue and red.
    - Use when / pitfalls: one fixed palette is what makes a series recognisable. Do not take colours from each logo.
    
    ## Get a logo as real SVG
    
    1. Open simpleicons.org, search the brand, click the copy button on its card. It copies the SVG markup itself, not a
       link.
    2. In Inkscape, Edit > Paste (Ctrl+V). The logo arrives as an editable path with all its nodes.
    3. A pointer graphic (white arrow with a dark outline, drawn as a vector object) points at the subject.
    - Use when / pitfalls: Simple Icons logos are single-colour. Check the brand's own usage rules before commercial use.
    
    ## Sticker outline and soft shadow
    
    1. Select the logo, Ctrl+C, then Edit > Paste In Place (Ctrl+Alt+V) to stack a copy exactly on top.
    2. Fill the lower copy white or cream, then Object > Lower One Step (Page Down) so it sits under the logo.
    3. With the lower copy selected, Path > Dynamic Offset (Ctrl+J) and drag its handle out with the Node tool. Path >
       Outset (Ctrl+)) grows it by a fixed step instead. The video narrates Dynamic Offset while the menu shows Outset
       highlighted. Both give a rounded outline.
    4. Holes inside the logo still show through. Use the Shape Builder tool (Inkscape 1.3+) and click the gaps to fill
       them into one solid shape.
    5. Shadow: paste the outline in place again, run the same offset, fill it with the background colour, lower it one step.
    6. Filters > Blurs > Blur...: Horizontal blur 10, Vertical blur 10, Live preview on, then Apply and Close.
    7. Select logo, outline and shadow, Object > Group (Ctrl+G).
    - Use when / pitfalls: Dynamic Offset no longer switches to the Node tool by itself since Inkscape 1.2, so pick the
      Node tool to see the handle. A blur pushes past the object bounds. Leave margin so the shadow is not clipped.
    
    ## Export and use
    
    1. File > Export, Page, 1920 x 1080, PNG, into the video's folder as `thumbnail.png`.
    2. The example also puts the thumbnail as the first frames of the video, a habit from when YouTube only let you pick
       a frame as the thumbnail. It keeps the click promise visible at second 0.
    
    
  • plugins/2d-generalist/skills/2d-generalist/references/intent-brief.md4.5 KB81d0fc174e42upstream ↗
    # Intent brief: ask before you build
    
    A piece that misses what the user wanted is a failed piece, even when it is well made. Run this brief before the
    first step of any build. It costs one short round of questions and saves a full rebuild.
    
    ## Reading Map
    
    - When to run it
    - The five slots
    - How to ask
    - Write the brief
    - Checkpoints while building
    - Drift check before delivery
    
    ## When to run it
    
    - Run it at the start of every new piece, and when the user changes the goal mid-way.
    - Skip the questions, not the brief, when the request already fills every slot. Then write the brief and go.
    - When another skill called this one and passed a brief, use that brief. Do not ask again.
    - When the user says "just do it", "surprise me" or "you choose", take the defaults, state them in one line, and go.
    
    ## The five slots
    
    | Slot | What you need to know | Example options to offer |
    |---|---|---|
    | Purpose and audience | What the piece is for and who watches or uses it | TikTok or Shorts hook, YouTube explainer, X post, game asset, client pitch, portfolio piece |
    | Format | Aspect ratio, length, resolution, file type | 9:16 vertical 30 to 60 s, 16:9 2 to 5 min, 1:1 still, GLB model, PNG set |
    | Subject | Exactly what is shown and the facts or story beats that must be in it | the named object, place, period, character, the one moment that must land |
    | Look | Style, references, palette, mood | footage-led Vox (vox-now), Vox editorial paper and ink, clean flat infographic, archival collage, blueprint; a link or image the user likes |
    | Constraints | Must-haves, must-nots, tools, voice and music, language, deadline; whether real people, brands or owned characters appear (name the risk once, follow the answer) | "no voiceover", "use my logo", "Blender only", "Vietnamese captions", "by Friday" |
    
    ## How to ask
    
    1. Read everything first: the prompt, attached images and links, files in the project, earlier messages. Fill every slot
       you can infer and mark it as inferred.
    2. Do not ask what you can check yourself. Run the tool audit for installed software. Research facts from sources.
    3. Ask only about slots that are empty or ambiguous and would change the result. A slot with a safe default needs no
       question: state the default in the brief instead.
    4. One round, at most 4 questions. Each question names the slot, gives 2 to 4 concrete options, and puts your
       recommended option first. A second round is allowed only when an answer opens a real fork.
    5. Make the options visual when the look is open: two or three named styles with one line each, or quick thumbnails.
    6. Where the agent has a question tool (Claude Code: `AskUserQuestion`), use it. Elsewhere, send a numbered list and
       end with: "Reply with numbers, or 'ok' to take the first option of each."
    7. Never ask "is this plan OK?" with no options. Ask the decision itself.
    
    ## Write the brief
    
    Write `brief.md` in the project folder, 5 to 8 lines:
    
    - Goal in the user's own words, then one line on what done looks like (for example "a 45 s 9:16 MP4 with captions").
    - The five slots, each marked given, answered or default.
    - Out of scope: what you will not make.
    - A `## Progress` section, one line per step of the production spine (`references/pipeline-spine.md`),
      filled as each step finishes.
    
    Show the brief to the user in one short message and start work. Stop only if the user changes something.
    
    ## Checkpoints while building
    
    - The checkpoints are the production spine's (`references/pipeline-spine.md`): the prep sheet and options before the
      first expensive step (sketch, tools and resources ready, style frames A/B/C plus a blockout or animatic; the user
      picks, `LOOK.md` is written), a WIP demo of the first finished part (sent without waiting), and the fast preview
      before the full render. Every other step checks itself.
    - After the preview, offer two or three next directions and a "you decide" choice; the answer picks a fix round,
      a round in the user's direction, or free creative mode (the spine's last section).
    - When the user gives notes, update `brief.md` (or `LOOK.md`) first, then change the work. Notes that change the
      purpose or format restart the brief.
    - Keep previews fast and small. The user judges direction from them, not polish.
    
    ## Drift check before delivery
    
    Before handing over, compare the result with `brief.md` slot by slot. Fix what you can. List any slot that still
    differs, with the reason, in the delivery message. Never hand over a piece whose purpose or format differs from the
    brief without saying so first.
    
  • plugins/2d-generalist/skills/2d-generalist/references/maps-and-geodata-2d-3d.md13 KBacad9582df8eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/pipeline-spine.md12 KB2d275191b08cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/qa-and-gates.md3.6 KB85916270d5c3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/real-images.md3.8 KBa81fb1d1719cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/textures-retro-and-shading.md97 KBce88fe0f1e5dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/vox-modern-measured.md4.5 KB694f87fa0630upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/references/vox-psychology-and-design.md16 KBd0a91d20287cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • plugins/2d-generalist/skills/2d-generalist/agents/openai.yaml613 B1e8eb9f83d43upstream ↗
    interface:
      display_name: "Design and Build Vox-Style Motion Graphics (2D / 3D)"
      short_description: "Design, animate and finish Vox, Johnny Harris and WSJ style explainer videos in 2D, 2.5D and 3D with a free toolset (Blender, DaVinci Resolve Fusion, Remotion + Three.js, FFmpeg)."
      default_prompt: "Use the 2d-generalist skill to design and build a Vox-style (2D/3D) motion graphics scene with an asymmetric layout, flat paper cards, print-bordered photos, a true-scale timeline ruler and a dual highlighter; torn paper and halftone only if the look asks for them."
    policy:
      allow_implicit_invocation: true
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/codepawl-creator-generalist-plugins-2d-generalist-skills-2d-generalist.md

// REPO STATS

176 stars
0 open issues
Last commit: 3d ago