Ramakm/folio-anatomy

Folio

Eine Folio-Tafel erklärt eine Idee so, wie ein naturkundliches Museum ein Exponat erklärt. Es gibt ein Objekt auf einem Sockel, einen nummerierten Schlüssel daneben und Wandtexte, die erklären, wie man es betrachten soll. Das Objekt hier ist ein von Ihnen erfundenes Instrument, wie eine Werkbank, eine Waage, ein Webstuhl oder eine Destille, dessen Arbeitsteile die Idee ausführen. Leser können daran herumdrücken, und jede darauf abgelesene Angabe wird berechnet.

Drei Verpflichtungen

1. Mechanismus, nicht Metapher. Das Instrument muss die Idee ausführen, nicht als bloße Illustration daneben stehen. Schreiben Sie vor dem Zeichnen eine Zeile: „Wenn der Leser X tut, bewegt sich Teil Y, und diese Bewegung ist Z in der Idee.“
2. Eine einzige Zahlenquelle. Ein kleines, reines Modell berechnet alles: Zeigerwinkel, Flüssigkeitsstände, die Anzeige, den Schlüssel, die Tabellen. Die Seite zeigt nur das an, was das Modell zurückgibt, sodass keine zwei Stellen widersprüchliche Werte liefern können.
3. Eine geführte Lektüre. Eine gute Zeichnung braucht dennoch eine Anleitung. Jede Tafel enthält einen Schlüssel, eine schrittweise Erklärung, die vollständige Funktionsweise und einen ehrlichen Bericht darüber, was vereinfacht wurde.

Erste Schritte

• Drei Referenztafeln sind im Repository enthalten. Tafel I (examples/attention/, Aufmerksamkeit als Prüfbank) ist das Modell für Ideen, die aus diskreten Schritten und einer Formel bestehen. Tafel II (examples/heart/, das menschliche Herz als Doppelpumpe) ist das Modell für alles, was in der Zeit abläuft: eine Simulation, die in jedem Frame integriert wird, kontinuierlicher Fluss, Phasen und Diagramme, die nach jedem Zyklus neu gezeichnet werden. Tafel III (examples/grid/, ein Stromnetz im Miniaturformat) ist das Modell für Elektrizität, Magnetismus und Energieflüsse sowie für eine Werkbank, die aus freistehenden Maschinen statt aus Bändern besteht: eine Turbine, ein Generator mit rotierendem Rotor, Transformatoren, Masten und eine Stadt. Tafel IV (examples/hashmap/, eine Hashmap als Sortierstelle) ist das Modell für Algorithmen und Datenstrukturen, bei denen die Idee eine Folge diskreter Operationen ist: Jede Operation (Einfügen, Suchen, Vergrößern) wird zu einer kurzen Liste zeitlich gesteuerter Aktionen (Anheben, Tragen, Eintauchen zum Vergleichen, jede Karte an einen neuen Ort fliegen lassen), die nacheinander abgespielt werden, sodass der Leser den Algorithmus bei jedem Schritt beobachten kann. Öffnen Sie zuerst die passendste.
• Der schnellste Start ist das Kopieren einer Referenztabelle: node scripts/new-plate.mjs <name> erstellt examples/<name>/ aus Tafel I. Ersetzen Sie dann das Modell, die Szene und die Texte. Das Arbeiten von einer funktionierenden Tafel aus ist schneller und sicherer, als von Null zu beginnen.
• Gemeinsame Ausstellungsstile befinden sich in kit/folio-page.css; die page.html einer Tafel setzt /*CSS*/ innerhalb seines <style>-Tags und fügt nur eigene Regeln hinzu.
• node scripts/build-site.mjs erstellt jede Tafel sowie die Startseite (site/index.html) in docs/, eine für GitHub Pages bereite Website. Um eine Tafel hinzuzufügen, fügen Sie ihren Namen zu PLATES dort und eine Karte zur Startseite hinzu.
• Erstellen Sie jede Tafel in einer einzigen eigenständigen Datei mit node scripts/build.mjs examples/<name> dist/<name>.html.
• Wenn nur diese Datei installiert ist (kein Repository), enthält der Anhang am Ende die Zeichenbibliothek; speichern Sie sie als folio-kit.js.

Eine Tafel besteht aus fünf Dateien:

Datei	Rolle
folio-kit.js	die Zeichenbibliothek (gemeinsam genutzt, niemals pro Tafel bearbeitet)
folio-live.js	die drei Ansichten: Bühne, Lichtebene, Orbit, Ansichtsumschalter (gemeinsam genutzt)
model.js	das reine Modell; stellt ein Objekt auf window
plate.js	das Instrument: statische Geometrie, Live-Slots, Eingabe
page.js	Schlüssel, Bedienelemente, Wandtexte, Verzeichnis; hört auf die Tafel
page.html	der Sockel und die Stile mit /*KIT*/ /*MODEL*/ /*PLATE*/ /*PAGE*/ Platzhaltern

Phase A: Das Briefing (noch kein Zeichnen)

A1. Umfang. Teilen Sie dem Benutzer vor dem Start mit, welche der folgenden Optionen er erhält und wie lange es in etwa dauern wird:

Umfang	Inhalt	Typische Zeit
Skizze	Instrument + Schlüssel + Anzeige, keine Wandtexte	unter einer Stunde
Tafel	die vollständige Ausstellungsseite (Standard für „erkläre X“)	eineinhalb bis drei Stunden
Serie	mehrere Tafeln auf einer gemeinsamen Werkbank, Maßstab und Farbpalette	zuerst die Liste vereinbaren, dann eine Tafel nach der anderen

A2. Das Modell. Schreiben Sie model.js, bevor Sie etwas Visuelles tun. Sammeln Sie die echte Formel, Einheiten und Größenordnungen. Geben Sie einfache Objekte zurück: Eingaben hinein, alle Größen, die die Seite anzeigen wird, heraus. Führen Sie es in Node aus und geben Sie einige Fälle aus. Suchen Sie jetzt nach Randfällen (eine leere Menge, eine maskierte Zeile, ein Wert am Limit). Wenn etwas erfunden wurde, wie Spielgewichte oder Beispieldaten, vermerken Sie dies für den Wandtext „Über dieses Exponat“.

A2b. Modelle, die in der Zeit laufen. Wenn die Idee ein Prozess ist (ein Herzschlag, eine ablaufende Warteschlange, eine Lernkurve), schreiben Sie sie als Zustand plus eine step(s, dt)-Funktion und ein read(s), das alles Angezeigte zurückgibt. Stimmen Sie Parameter gegen bekannte Werte in Node ab, bevor Sie zeichnen, wie Tafel II dies für einen ruhenden Erwachsenen tut (etwa 115/80 mmHg, 70 mL pro Schlag, 5 L/min). Lassen Sie die Simulation weiterlaufen, während die Zeichnung nicht sichtbar ist, und überspringen Sie nur das Malen; andernfalls frieren die Zahlen ein, wenn ein weiter unten auf der Seite befindliches Bedienelement geändert wird.

A3. Das Instrument und seine Entsprechungstabelle. Suchen Sie ein Instrument aus der Welt der Labore, Werkstätten, Observatorien oder Druckereien. Erstellen Sie dann die Tabelle, die jeden Begriff mit einem Teil verknüpft:

Begriff in der Idee	Teil des Instruments	Was der Leser sehen kann
Abfrage	ein Wagen auf einer Überkopfschiene	er parkt über dem Wort, das fragt
skalierter Wert	ein Zifferblatt pro Wort	Zeigerposition
Softmax	ein versiegelter Behälter	die Säulen können nur das teilen, was er enthält
Maske	Hähne mit Kappen	spätere Wörter werden abgesperrt
gewichtete Summe	ein Tablett mit geschichteten Ablagerungen	die Länge jeder Schicht ist ein Gewicht

Jede Zeile benötigt ein Teil, und jedes wichtige Teil benötigt eine Zeile. Einige zuverlässige Zuordnungen: Ein fester Gesamtwert wird zu einem Behälter, einer Geldbörse oder einem Gewichtsbeutel. Vergleich wird zu einem Zifferblatt, einer Waage oder einem Messschieber. Auswahl wird zu einem Ventil, einem Schalter oder einem Weichenhebel. Akkumulation wird zu Schichten, einem Stapel oder einer Strichliste. Ordnung wird zu einer Schiene, einem Gestell oder einer Rutsche.

Phase B: Die Werkbank

B1. Inventar. Listen Sie die Teile auf, bevor Sie sie platzieren. Zielen Sie auf 30 bis 60. Gruppieren Sie sie nach Zweck: Begriffsteile (aus der Tabelle, pro Element wiederholt), Stützteile (Sockel, Füße, Pfosten, Schienen, Manschetten, Konsolen), Steuerungsteile (Wähler, gerändelte Knöpfe, Hebel) und Befestigungsdetails (Katalogplatte, gravierte Etiketten, Maßskalen, Schrauben). Genau eine Größe, um die es bei der Idee geht, erhält die rote Farbe.

B2. Bänder. Verwenden Sie Weltkoordinaten mit x entlang der Werkbank, y zum Betrachter hin und z nach oben. Teilen Sie die Werkbank in Tiefenbänder von hinten nach vorne und geben Sie jedem Band eine Art von Teilen. Tafel I verwendet Schiene, Säulen, Hähne, Verteiler, Zifferblätter, Tablett. Lassen Sie Spielraum zwischen den Bändern in Welteinheiten, da ein Teil, das in das nächste Band hineinragt, in der falschen Reihenfolge gemalt wird. Zeichnen Sie innerhalb eines Bandes von fern nach nah. Setzen Sie die Kamera (az nahe -24 für eine lange Werkbank, el 30) und passen Sie sie mit Folio.fit an die Ecken an.

B3. Statische Zeichenketten, Live-Slots. Durchlaufen Sie die Bänder einmal und fügen Sie SVG-Zeichenketten in eine geordnete Liste ein. Überall dort, wo sich etwas bewegt, fügen Sie stattdessen einen benannten Slot ein. Zur Montagezeit wird die Liste zu einem SVG mit einem leeren <g> pro Slot. Jeder Animationsframe zeichnet nur die Slots neu, basierend auf interpolierten Werten, die die Modell-Zielwerte verfolgen. Das Zeichnen stoppt, sobald jeder Wert angekommen ist.

B4. Pins. Platzieren Sie 6 bis 10 nummerierte Pins direkt auf den Teilen, die die Idee tragen, nummeriert in der Reihenfolge, in der ein Neuling sie betrachten sollte. Pins sind die einzigen Markierungen, die über die Zeichnung gelegt werden. Der gesamte andere Text ist in eine Oberfläche graviert: Namen auf Vorderseiten von Pads, Zahlen auf Skalen, eine Katalogplatte auf dem Sockel.

Phase C: Der Sockel

Die Seite ist Teil der Erklärung. Bauen Sie sie aus diesen Blöcken von oben nach unten auf:

1. Kopfzeile. Die Serie links, das Wortzeichen zentriert, die Tafelnummer rechts.
2. Titelblock. Eine einprägsame Überschrift, die die Idee als Instrument benennt („Aufmerksamkeit, als Prüfbank.“), drei Sätze darüber, was passiert, und eine kleine Katalogliste: Objekt, Idee, Modell, Katalog.
3. Die montierte Tafel. Ein Papiersockel mit einem haardünnen Innenrahmen. Seine Ecken tragen die Tafelnummer, eine kurze Bildunterschrift, den Interaktionshinweis und eine Live-Anzeige.
4. Der Schlüssel. Ein Eintrag pro Pin mit dem Namen des Teils und einer Zeile darüber, was es berechnet, mit der Mathematik in Monospace. Beim Überfahren eines Eintrags wird sein Pin hervorgehoben, und beim Überfahren eines Pins wird sein Eintrag hervorgehoben.
5. An der Werkbank. Gewöhnliche Schaltflächen und Schieberegler, die das tun, was die eigenen Knöpfe des Instruments tun.
6. Wandtext I: Die Tafel lesen. Eine Spalte für jeden Begriff in der Reihenfolge, in der die Formel geschrieben ist: eine römische Ziffer, ein Verb, der Begriff, zwei Sätze, die sich auf Pins beziehen, und ein Kasten mit aktuellen Zahlen.
7. Wandtext II: Das Verzeichnis. Die vollständige Berechnung für den aktuellen Zustand, eine Zeile pro Element. Ein Klick auf eine Zeile wählt dieses Element aus.
8. Wandtext III: Der weitere Blick. Was auch immer das Instrument als Ausschnitt zeigt (die vollständige Matrix, die gesamte Sequenz, jeden Eimer) und die Varianten, zwischen denen der Wähler wechselt.
9. Wandtext IV: Über dieses Exponat. Drei Anmerkungen: Was genau berechnet wird, was von Hand gewählt wurde und was weggelassen wurde. Immer enthalten.
10. Kolophon. Wer die Tafel erstellt hat und welche Schriftarten verwendet werden.

Bedienelemente reagieren auf Zeiger und Tastatur: Klicken auf eine Station, Pfeile schreiten, Ziffern wählen eine Variante, Klammern drehen einen Knopf, ein Buchstabe kippt einen Schalter. Wenn niemand interagiert, zeigt sich die Tafel langsam selbst. Sie pausiert bei Mauskontakt oder Fokus, ruht, wenn weggescrollt wurde, und zeigt unter reduzierter Bewegung einen eingefrorenen Frame. Die Anzeige verwendet aria-live.

Phase C2: Drei Ansichten

Jede Tafel bietet dasselbe Instrument auf drei Arten an, auswählbar über einen kleinen Schalter in der oberen Ecke des Sockels (SVG · WebGL · 3D). Das Modell, der Schlüssel und die Wandtexte ändern sich zwischen den Ansichten nicht; nur die Art, wie die Werkbank gezeigt wird, ist unterschiedlich.

SVG ist die oben beschriebene gestochene Zeichnung. Sie ist die Standardeinstellung und die einzige Ansicht, die immer funktionieren muss.

WebGL legt Licht über die Zeichnung, ohne sie neu zu zeichnen. Das Licht lebt in einer Leinwand über dem SVG und weiß, was durch eine Maske, die aus der Zeichnung selbst gerendert wird, sichtbar ist: light() klont das SVG, färbt jede Oberfläche nach ihrer Rolle neu ein (rot für den Boden, grün für Gefäße und Rohre, blau für Glas, schwarz für alles andere), behält die Reihenfolge des Malers bei und lädt das Ergebnis als Textur hoch. Alles, was die Zeichnung verbirgt, kann das Licht nicht berühren, sodass keine separate Okklusionslogik erforderlich ist. Geben Sie jeder Oberfläche ihre Rolle mit einer Klasse (floor auf dem Sockel, pad auf erhöhten Aufnehmern, pipe oder die Blut-Klassen auf Gefäßen) und übergeben Sie die Farbregeln als maskCss.

Innerhalb des Shaders verwandelt onPlane(vb, z) einen Pixel zurück in einen Weltpunkt auf einer horizontalen Ebene, project() geht den anderen Weg und fall() findet heraus, wo Licht durch ein Teil auf dem Boden landet (die Lampe sitzt hinter der Werkbank, sodass Lichtflecken vor den Teilen landen, wo der Leser sie sehen kann). Verwenden Sie das Licht nur für die betreffende Größe:

• Tafel I: Die Flüssigkeit jeder Säule leuchtet mit ihrem Gewicht, ein Schimmerlichtstrahl läuft von jeder Säule quer über die Werkbank, und Pulse laufen entlang des Verteilers, schneller, während sich die Gewichte verschieben.
• Tafel II: Pulse reisen entlang jedes Gefäßes mit dem wahren Fluss (dasselbe akkumulierte Volumen, das die SVG-Flussmarkierungen bewegt), jede Kammer wirft Licht in der Farbe ihres Blutes, und die Ventrikel flammen auf, wenn sie sich zusammenziehen.

Akkumulieren Sie Licht als vormultiplizierte Farbe (addLight) und wählen Sie Farben pro Thema: blasse Lichter und gesättigte Lachen auf Papier (normale Überblendung), hellere Leuchten auf dunklem Grund (Screen-Blending, gesetzt durch das --light-blend Token). Rendern Sie nur, während die Ansicht eingeschaltet und die Tafel auf dem Bildschirm ist, begrenzen Sie das Pixelverhältnis auf 1,5 und zeichnen Sie unter reduzierter Bewegung einen Standbild-Frame.

3D dreht die Werkbank vollständig. Da die gesamte Szene eine Funktion der Kamera ist, erstellt stage.mount(az, el) sie einfach aus dem neuen Winkel neu: Jede Fläche wird neu durch ihre Ausrichtung schattiert, jedes runde Teil neu silhouettiert, jede Schraffur neu beabstandet und jedes gravierte Etikett neu projiziert. Die Reihenfolge des Malers muss von jeder Seite gelten, also codieren Sie niemals fest „hinten nach vorne“:

• Verpacken Sie jedes Tiefenband als { y, draw } und übergeben Sie die Liste an api.bands(list); es sortiert sie von fern nach nah für die aktuelle Kamera. Von hinten wird das vordere Band zuerst gezeichnet.
• Geben Sie innerhalb eines Bandes oder für eine Werkbank aus separaten Maschinen jeder Einheit eine Weltposition und verwenden Sie api.units(list) mit { at: [x, y, z], draw }. Tafel III ist vollständig auf diese Weise aufgebaut.
• Wände eines offenen Gefäßes (ein Tablett, ein Tank) werden mit api.backIsFar und api.leftIsFar geordnet.
• Alles, was auf einer Seite des Sockels montiert ist (eine Messing-Katalogplatte, ein Steuernocken auf einer Frontplatte), wird nur gezeichnet, wenn diese Seite zum Betrachter zeigt: Überprüfen Sie zuerst das Vorzeichen von cam.view. faceText bereinigt sich bereits selbst.

orbit({ wrap: true }) lässt den Azimut über 360° laufen, stage passt den Maßstab bei jedem Winkel neu an (begrenzt durch orbitScale, sodass die Werkbank nie in der Größe springt), Doppelklick kehrt zur Standardansicht zurück, und Umschalt mit den Pfeiltasten dreht sie über die Tastatur. Überprüfen Sie mit einem Raster von Winkeln alle 45° bei zwei Höhen. Ein vollständiger Neuaufbau von Tafel II dauert etwa 27 ms, was zum Ziehen glatt genug ist; wenn eine Tafel viel schwerer ist, speichern Sie die letzte Ausgabe jedes Slots zwischen und malen nur das neu, was sich geändert hat, wie Tafel III es tut.

Das Verlassen der 3D-Ansicht setzt die Kamera auf die Standardansicht zurück, sodass das WebGL-Licht (das diese annimmt) immer ausgerichtet ist.

Phase C2b: Bewegliche Innereien

Eine Tafel sollte niemals ein Standbild mit Zahlen daneben sein. Finden Sie die Teile, die sich wirklich bewegen würden, und steuern Sie sie aus dem Modell mit einer Geschwindigkeit, die das Auge verfolgen kann:

• Dinge, die sich drehen. Ein Strömungsrad in einem Schauglas dreht sich mit dem wahren Fluss (Tafel I Verteiler), Steuernocken drehen sich einmal pro Zyklus und zeigen, welche Phase aktiv ist (Tafel II), und der Rotor eines Generators, ein Wasserrad und ein Fliehkraftregler drehen sich mit der Geschwindigkeit der Maschine (Tafel III). Akkumulieren Sie den Winkel aus dem Modell (rot += ω·dt) und nicht aus der Uhr, sodass eine sich verlangsamende Maschine sichtbar langsamer wird.
• Dinge, die sich verschieben. Füllstände, Kolben, Ventilklappen, Zeiger, die Kugeln eines Fliehkraftreglers, die bei steigender Geschwindigkeit herausfliegen, ein Schalterhebel, der sich hebt.
• Dinge, die interagieren. Die Bewegung eines Teils löst die Bewegung eines anderen aus (ein Nocken drückt einen Stößel, ein Zahnrad dreht ein anderes).

Phase C2c: Varianten

Eine Tafel kann mehrere Varianten desselben Instruments enthalten, die über einen Wähler an der Werkbank umgeschaltet werden können. Tafel III bietet Netz-, Insel- und Notstrommodus. Tafel IV bietet Einfügen, Suchen und Vergrößern. Jede Variante teilt sich die meisten Teile, ändert aber einige davon. Schreiben Sie den Wähler als kleinen Satz von Schaltern, die die Liste der sichtbaren Teile und deren Verhalten ändern.

Phase D: Text

D1. Schlüssel. Ein nummerierter Eintrag pro Pin: Teilname, eine Zeile zur Funktion, die Mathematik in monospace. Überfahren hebt hervor.

D2. Wandtexte. Vier Abschnitte. Lesen, Verzeichnis, Warte, Über. Jeder Abschnitt ist eine Spalte. Die Lesespalte enthält römische Ziffern, Verben, Begriffe, Verweise auf Pins. Das Verzeichnis listet jedes Element mit seinem aktuellen Wert auf. Der Warte-Abschnitt zeigt das große Ganze. Der Über-Abschnitt enthält drei Notizen: was genau berechnet wird, was von Hand gewählt wurde, was weggelassen wurde.

Phase E: Bau

Führen Sie node scripts/build.mjs examples/<name> dist/<name>.html aus, um eine einzelne HTML-Datei zu erstellen, die die Tafel enthält. Diese Datei kann überall gehostet werden.

Führen Sie node scripts/build-site.mjs aus, um alle Tafeln und eine Startseite zu erstellen, gehostet auf GitHub Pages.

Anhang: folio-kit.js

[Das Zeichenbibliotheksmodul. Enthält Funktionen zum Erstellen von SVG, WebGL und 3D-Ansichten, zum Verwalten von Slots, zum Animieren von Werten, zum Platzieren von Pins, zum Erstellen von Masken und zum Verwalten der Szene. Es ist eine gemeinsame, gemeinsam genutzte Bibliothek, die niemals pro Tafel bearbeitet wird.]