MBehtemam/montagent-skills: Pre-Render – Generative Visuals, SV…

Vor-Render: generative Visuelle Effekte und stabilisiertes Footage

Fünf Routen, ein Satz gemeinsamer Regeln. Ein codebasiert gezeichnetes Stück wird zu Footage, platziert als video: lies es zuerst. Ein SVG-Standbild wird zu einem PNG, platziert als image: springe zur SVG-Route. Eine Lottie-Animation wird ebenfalls zu Footage, ein frischer Player pro Frame: springe zur Lottie-Route. Eine 3D-Szene wird zu transparentem Footage oder einem Stand-PNG: springe zur 3D-Szenen-Route. Quellvideo-Stabilisierung erzeugt einen neuen Clip: springe zur Stabilisierungs-Route. Alles läuft außerhalb des Render-Vorgangs, sodass jeder Painter die gleichen Pixel dekodiert.

Montagent hat keine Shader- oder Skriptdatei (ADR-0017). Ein Look außerhalb der effects-Liste wird im eigenen Code gezeichnet, einmal als Footage enkodiert und als gewöhnliches video platziert. Das Format, das Schema und der Painter bleiben unverändert (ADR-0156 §7, ADR-0233).

Wann du sie anwenden solltest

Nutze zuerst die benannte Route. Lies die effects-Liste in montagent://schema/index.json: Wenn ein Member den Look erzeugt (Weichzeichner, Schatten, Tönung, ein blend, eine keyed mask), verwende ihn. Rendere vor nur dann, wenn kein Member, Paint oder Blend den Look zusammensetzt: Verzerrungen, Mosaik, Lens Flare, Partikel, ein prozedurales Muster oder ein externes 3D-Modell/Szene.

Greife zur SVG-Route, wenn du eine Vektorgrafik (ein Logo, ein Icon, eine Illustration) als SVG-Datei erhältst oder wenn ein Standbild am einfachsten als SVG zu zeichnen ist. Kein Element akzeptiert eine SVG-Datei (ADR-0171). Ein animiertes SVG (SMIL oder CSS) ist nicht für diese Route geeignet: Es rastersiert als ein einziges Standbild und die Bewegung geht verloren. Taste stattdessen die eigenen scale-, rotation- und opacity-Eigenschaften des platzierten Bildes an.

Greife zur 3D-Szenen-Route, wenn du ein 3D-Asset (.glb, .gltf, .obj, .fbx, .blend, .c4d) oder eine 3D-Szene erhältst. Kein Element akzeptiert ein 3D-Modell oder einen Multichannel-Pass (ADR-0167, ADR-0233). Headless-Rendering produziert transparentes ProRes 4444 / PNG-Footage außerhalb des Renders, bereit zur direkten 2D-Platzierung.

Greife zur Lottie-Route, wenn du eine Lottie-JSON-Datei (einen After Effects Export, eine LottieFiles-Animation) erhältst oder wenn eine Bewegung am einfachsten von einer solchen übernommen wird. Kein Element akzeptiert eine Lottie-Datei (ADR-0171). Sie kostet drei Dinge: Eine feste Auflösung: das Footage ist ein Raster in der Größe, in der du es renderst. Eine Rezept-Toolchain: Ein installierter Lottie-Player, um das Stück zu reproduzieren (niemals das Projekt zu rendern). Footage-Größe: PNG in einem MOV reicht von etwa 6 MB pro Sekunde für glatte Kunst bis zu 141 MB pro Sekunde für verrauschte Kunst, bei 1080p und 25 fps; rendere daher in der gezeigten Größe und nicht größer. Wenn die Bewegung aus wenigen Formen besteht, ist das Keying von nativen rect-, ellipse- und path-Elementen kleiner und bleibt scharf.

Ein vorgerendertes Stück ist festes Footage. Seine Größe, fps und Länge werden beim Rendern festgelegt. Eine Änderung des Looks erfordert ein erneutes Rendern; lege daher zuerst die Größe, fps und Dauer des Briefings fest und stimme sie mit der fps des Projekts ab.

Gemeinsame Regeln

Jede Route liest diese. Sie sind einmal geschrieben.

• Größe. Rasterisiere oder zeichne in der größten Größe, in der das Stück jemals gezeigt wird, nach fit, scale und jedem keyed Zoom, als literal width und height. Leite sie niemals von einem SVG-viewBox ab: Ein viewBox setzt die Proportionen der Zeichnung, nicht ihre Pixel, und die Tools sind sich bei einer Datei ohne solche uneinig. Schreibe die Größe in das Rezept. Ein späterer Zoom darüber hinaus tastet ein Raster neu ab, führe daher das Rezept stattdessen in einer größeren Größe aus, anstatt zu skalieren.
• Text. Nur gebündelte Schriften oder in Pfade umgewandelter Text. Niemals eine System-Schrift: Ein Rechner ohne sie zeichnet etwas anderes. Eine Schrift, die nicht gefunden werden kann, ist ein Build-Fehler, keine ausgelassene Textspanne. usvg zum Beispiel protokolliert den Fehlschlag und überspringt den Text, daher liest build die font-family-Werte des SVG gegen die Schriftdateien, die du in fonts auflistest, und schlägt auch bei der eigenen Schriftwarnung des Rasterierers fehl.
• Rezept. Quellkopie, genaue Befehle, Tool-Versionen, Größe und ein Hash der dekodierten Pixel, aufgenommen durch denselben Lesevorgang, den der Dekodierer verwendet. Der Wiederaufbau meldet eine Übereinstimmung oder die erste Abweichung und vergleicht niemals Datei-Bytes. Das Rezept sagt, wo es sich befindet.

Die Schritte

Führe jeden Schritt in der Reihenfolge aus. Das Stück ist platziert, wenn Schritt 5 bestanden ist.

1. Zeichnen. Schreibe Code, in einem beliebigen Tool, der RGBA-Frames einer festen Anzahl von width, height und frames erzeugt: transparent, wo nichts gezeichnet wird. Er schreibt rohes RGBA nach stdout oder PNG-Dateien f00000.png, f00001.png und so weiter in den Ordner, der durch PRERENDER_FRAMES_DIR benannt ist. Lies seine Größe aus PRERENDER_WIDTH, PRERENDER_HEIGHT, PRERENDER_FPS und PRERENDER_FRAMES. Verwende Integer-Arithmetik oder einen festen Seed, damit ein zweiter Durchlauf die gleichen Bytes zeichnet. Das Beispiel-Stück ist das kleinste funktionierende.
2. Spezifikation. Schreibe eine Build-Spezifikation neben dem Code: name, out (der Medienordner des Projekts), width, height, fps, frames, render (das argv, das deinen Code ausführt), files (jede Datei, die der Code benötigt) und input von "png", wenn er PNGs schreibt. Führe python3 scripts/prerender.py --help für jeden Schlüssel aus. Füge versions für jede Bibliothek hinzu, deren Version die Pixel ändert (eine Canvas-Bibliothek, ein Headless-Browser).
3. Bauen. python3 scripts/prerender.py build <spec>. Es führt den Code aus, enkodiert ein <name>.mov, dekodiert es und schlägt beim ersten Frame fehl, der sich von dem unterscheidet, was dein Code gezeichnet hat. Lies seine letzte Zeile: N frames, decoded = drawn.
4. Platzieren. Füge das Footage als einfaches video-Element zum Projekt hinzu (siehe unten) oder führe python3 scripts/prerender.py place <project> <placing> aus, wobei <placing> eine JSON-Datei ist: {"source": "media/<name>.mov"} plus optional eines von id, at, x, y, origin, width, height, fit, track, layer. Es gibt das Projekt mit dem hinzugefügten Element aus, leite es also in eine neue Datei um.
5. Überprüfen. Validiere das Projekt und behebe jeden Fehler. Führe dann montagent probe für das Footage aus und bestätige, dass es Alpha meldet (carries: true). Erst dann frame eine Kachel, in der das Stück sichtbar ist, und überprüfe, ob die transparenten Teile das dahinter Liegende zeigen.

{
  "frame": {"width": 640, "height": 360}, "fps": 25, "background": "#101418", "duration": 480, "output": "out/pulse.mp4",
  "tracks": [
    {"name": "prerender", "layer": 10, "elements": [
      {"id": "pulse", "type": "video", "start": 0, "end": 480, "source": "media/pulse.mov", "source_start": 0, "source_end": 480, "volume": 0, "x": 320, "y": 180, "origin": "center", "width": 320, "height": 240, "fit": "contain"}
    ]}
  ]
}

Das Element ist ein gewöhnliches video: Taste opacity, scale und position an, füge effects und ein blend hinzu und lege es auf einer Spur wie jeden anderen Clip ab. Das Footage hat keinen Ton, daher ist volume 0. Sein end minus start ist die Länge des Footages; source_end ist die gleiche Länge.

Die SVG-Route

Eingabe: Eine SVG-Datei und die Pixelgröße aus den gemeinsamen Regeln.

1. Bündele die Schriften, die der SVG-Text verwendet, mit montagent fonts vendor, und setze jeden <text> in dieser Familie mit einem font-family-Attribut. Oder wandle den Text in deinem Zeichenwerkzeug in Pfade um und verwende keine Schrift.
2. Spezifikation. Schreibe eine Build-Spezifikation neben dem SVG mit "input": "svg": name, out, svg, die literal width und height, render (das argv des Rasterierers, mit {width}, {height} und {out} an den entsprechenden Stellen), files, fonts und versions. Es gibt keine fps und keine Frame-Anzahl.
3. Rasterisieren. python3 scripts/prerender.py build <spec> führt den Rasterierer einmal aus, außerhalb des Renders. Jedes Tool, das ein RGBA-PNG schreibt, ist geeignet: die resvg-Kommandozeile, ein Headless-Browser, Inkscape. Überspringe System-Schriften und übergib die gebündelten, wie in der Spezifikation unten. Es schreibt <name>.png und sein Rezept und schlägt bei einer fehlenden Schrift fehl.
4. Platziere das PNG als einfaches image-Element (siehe unten) oder führe python3 scripts/prerender.py place <project> <placing> mit {"source": "media/<name>.png", "duration": <ms>} plus optional eines von id, at, x, y, origin, width, height, fit, track, layer aus.
5. Überprüfen. Führe validate aus und behebe jeden Fehler, dann frame eine Kachel, in der das Bild sichtbar ist, und überprüfe, ob die transparenten Teile das dahinter Liegende zeigen.

Die Beispiel-Spezifikation für das Beispiel-SVG (Formen, ein Verlauf und Text in einer gebündelten Schrift), rasterisiert auf das Dreifache seines viewBox:

{
  "name": "mark", "out": "media", "input": "svg", "svg": "sample_art.svg", "width": 480, "height": 270,
  "render": ["resvg", "--skip-system-fonts", "--use-font-file", "Inter-Bold.ttf", "-w", "{width}", "-h", "{height}", "sample_art.svg", "{out}"],
  "files": ["sample_art.svg"], "fonts": ["Inter-Bold.ttf"],
  "versions": {"resvg": ["resvg", "--version"]}
}

Das PNG hat intrinsische Pixelabmessungen, daher wird es als gewöhnliches image eingefügt, und die fit-Regeln von ADR-0015 gelten wie für jedes PNG: contain mit dem eigenen Seitenverhältnis des Rahmens oder literal. Die Platzierung in seiner eigenen Größe mit fit von contain ist eine 1:1-Zeichnung. Zeige es größer als die Größe, in der du es rasterisiert hast, und das Raster wird neu abgetastet: Führe das Rezept erneut in der größeren Größe aus.

{
  "frame": {"width": 640, "height": 360}, "fps": 25, "background": "#101418", "duration": 2000, "output": "out/mark.mp4",
  "tracks": [
    {"name": "art", "layer": 10, "elements": [
      {"id": "mark", "type": "image", "start": 0, "end": 2000, "source": "media/mark.png", "x": 320, "y": 180, "origin": "center", "width": 480, "height": 270, "fit": "contain"}
    ]}
  ]
}

Führe validate aus. Das Bild ist ein gewöhnliches: Taste opacity, scale und position an, füge effects hinzu, lege es auf einer Spur ab.

Die Lottie-Route

Eingabe: Eine Lottie-JSON-Datei, eine Größe, eine fps und ein Frame-Bereich. Die eigenen w-, h- und fr-Werte des Lottie sind Eingaben, aus denen du wählen kannst, keine Regeln: Die Größe folgt den gemeinsamen Regeln (die größte gezeigte Größe, als Literale), und du schreibst die fps und die Frame-Anzahl in die Spezifikation.

1. Wähle einen Player aus, der RGBA-Frames schreiben kann, und notiere seinen Namen und seine Version in versions. Die Skill wählt keinen aus: Das Vor-Render läuft einmal außerhalb des Renders und die Painter sehen den Player nie. Der Beispiel-Player ist ThorVG über pip install thorvg-python==1.1.3.
2. Spezifikation. Schreibe eine Build-Spezifikation neben der Lottie-Datei mit "input": "lottie": name, out, lottie, die literal width und height, fps, frames, render, files, fonts und versions. render ist das argv des Players, mit {width}, {height}, {frame} und {out} an den entsprechenden Stellen: Es zeichnet einen Frame als rohes RGBA in {out}. Optionale start und step legen fest, welcher Lottie-Frame jedem Footage-Frame entspricht (Frame i ist start + i * step; step hat standardmäßig den Wert von fr des Lottie geteilt durch fps). Führe python3 scripts/prerender.py --help für jeden Schlüssel aus.
3. Bauen. python3 scripts/prerender.py build <spec> liest zuerst die Lottie-Datei und lehnt sie ab, benenne jeden Fall, wenn sie einen Ausdruck, einen Layer-Effekt, den der Player nicht als zeichnend aufgezeichnet ist (liste diejenigen, die er ist, in allow_effects auf), oder Text verwendet, dessen Schrift weder eingebettete Glyphenpfade noch eine gebündelte Datei in fonts hat. Ein Player überspringt all dies ohne Ton, daher würde ein fortgeführter Build eine andere Animation ausliefern. Es führt dann render einmal pro Frame aus, einen neuen Prozess jedes Mal, liest den eigenen Bericht des Players darüber, was er übersprungen hat (jede Zeile, die 'skipped', 'ignored' oder 'unsupported' sagt, ist ein Build-Fehler: behandle sie als solchen), enkodiert ein <name>.mov wie der Codec sagt, und schlägt beim ersten Frame fehl, der sich von dem unterscheidet, was der Player gezeichnet hat.
4. Platziere das Footage als einfaches video-Element oder mit place wie in den Schritten. Führe validate und montagent probe für das MOV aus: Bestätige, dass es Alpha meldet (carries: true). Dann frame eine Kachel, in der das Stück sichtbar ist, und überprüfe, ob die transparenten Teile das dahinter Liegende zeigen.

Warum ein frischer Player pro Frame. Die Umgebung sucht nie einen Player vorwärts. ThorVG ignoriert eine Frame-Änderung unter 0,001, daher hängt die Position eines Suchvorgangs von der vorherigen Suche ab, und Skotties Suchvorgang verändert sein Animationsobjekt. Ein Frame, der nach anderen gezeichnet wird, kann sich vom gleichen Frame unterscheiden, der zuerst gezeichnet wurde, und der Wiederaufbau würde nicht übereinstimmen.

…

[Der Rest wurde aus Gründen der Kürze abgeschnitten – bitte beachte, dass die vollständige Übersetzung aufgrund der Länge des Originals hier endet.]