Foto-Tiefe: Ein Bild, das sich wie ein Ort verhält
0. setup Eine Python-Umgebung mit MoGe-2 (einmalig; fragt vor dem Download) scripts/setup.sh
1. depth Bild → Nahkarte (+ 16-bit Distanz, Kamera, rohes npz) scripts/depth.py
2a. window Das Bild als Fenster in three.js examples/portal.js
2b. place Ebenen und Punkte im eigenen 3D des Bildes scripts/fit_plane.py
3. check Betrachte es aus den extremen Blickwinkeln, die du wirklich verwenden wirst
scripts/ und examples/ beziehen sich auf die Ordner im eigenen Verzeichnis dieses Skills (${CLAUDE_SKILL_DIR}, sowohl für ein Plugin als auch ein kopiertes Skill), nicht auf das Projekt des Benutzers. Setze S auf den scripts/-Ordner und führe "$S/depth.py" und die anderen mit vollem Pfad aus.
0. Einrichtung (einmalig)
Überprüfe zuerst: Eine vorhandene Umgebung mit funktionierendem import moge kann wiederverwendet werden (frage den Benutzer, wo er eine aufbewahrt). Andernfalls frage den Benutzer vor dem Download, benenne, was heruntergeladen wird: PyTorch und Hilfsprogramme von PyPI (ca. 1 GB installiert), MoGes Quellcode und zwei kleine Bibliotheken von GitHub (festgelegte Commits, ein paar MB) und später die Modellgewichte (ca. 1,3 GB, Ruicheng/moge-2-vitl auf Hugging Face). Dann:
"$S/setup.sh" <ordner-fuer-die-umgebung> --yes
Details, GPU-Hinweise und andere Modelle: references/setup.md.
1. Tiefe
<umgebung>/.venv/bin/python "$S/depth.py" bild.jpg --out public/depth/ [--dist16] [--npz]
- Schreibt immer
<stamm>-near.webp: Nähe (Disparität), 0 der Himmel, 1 das nächste Objekt, Kanten um 2 px erweitert, sodass sich die Kante eines Objekts mitbewegt. 10-25 KB für ein 1-2K Bild. --dist16:<stamm>-dist16.webp(log-Distanz in 16 Bit, R hoch G niedrig, verlustfrei) und<stamm>-camera.json(die geschätzten intrinsischen Parameter). Zum Wiederaufbau des Bildes als Oberfläche.--npz: rohe metrische Tiefe fürfit_plane.py.- Es verweigert das Herunterladen von Gewichten, es sei denn,
--allow-downloadwird übergeben: frage zuerst den Benutzer. - Es gibt den gültigen Anteil, die Tiefenperzentile und das geschätzte Sichtfeld aus. Lies sie: „gültig 20 %“ oder ein Sichtfeld von 150° bedeutet, dass das Modell das Bild nicht verstanden hat.
Führe es erneut aus, wann immer sich das Bild ändert: Eine Tiefenkarte von einer älteren Version des Bildes verschiebt jede Kante.
2a. Das Fenster
examples/portal.js ist ein eigenständiges three.js-Material (kopiere es in das Projekt). Das Bild ist die Szene, gesehen von einem Ruhepunkt (deine Standardkameraposition). Von jedem anderen Punkt zeigt jedes Pixel des Glases, was entlang der Sichtlinie durch es liegt, gefunden durch Ablaufen der Nahkarte in 16 Schritten, sodass nahe Objekte ferne Objekte überdecken und Kanten nicht reißen. Details, Abstimmung und Fehlermodi: references/portal.md.
import { makePortal } from "./portal.js";
const portal = makePortal({ map, near, width: 4, height: 2.5 });
scene.add(portal.mesh); portal.setRest(defaultCameraPosition);
// jeden Frame: portal.update(camera);
examples/portal.html ist eine Ein-File-Demo: Server einen Ordner mit dem Bild, seiner Nahkarte, portal.js und der Seite, öffne portal.html?pic=<datei>&near=<datei> und bewege den Zeiger.
Überprüfe es so, wie es gesehen wird: Halte die Kamera an der linkesten, rechtesten, höchsten und tiefsten Position, die die Site wirklich verwendet (für eine automatisierte Prüfung ehrt die Demo window.__view = [x, y]) und betrachte jede:
- Keine Tiefe sichtbar? Die erste Version dieses Effekts auf einer echten Site war zu schwach, um bemerkt zu werden: senke
uQ.y(0,6 → 0,4). - Nahe Objekte bewegen sich am meisten gegen den Rahmen, oder der Himmel schwimmt? Die Tiefe ist umgekehrt (Entfernung als Nähe verwendet).
- Verschmierungen oder verdoppelte Objekte bei großen Bewegungen: Ein einzelnes Bild hat nichts hinter seinen nahen Objekten. Halte Kamerabewegungen klein, oder lasse sie ausklingen (
uEase), oder male eine Hintergrundebene (references/placing.md).
2b. Dinge im Bild platzieren
<umgebung>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260
<umgebung>/.venv/bin/python "$S/fit_plane.py" plane out/city-depth.npz --box 410,120,520,260 --corners 415,128 515,124 516,250 414,255
<umgebung>/.venv/bin/python "$S/fit_plane.py" point out/city-depth.npz 640,700
Pixel sind die des Bildes selbst (--norm für 0..1). Ausgabe ist JSON im three.js-Kameraraum (Kamera im Ursprung, Blick in -Z, Meter). flatness_rms_m gibt an, wie flach die Region wirklich ist: Ein paar Zentimeter auf einer 40 m entfernten Wand sind flach. Wähle Ecken innerhalb der eigenen Kanten einer Tafel (nicht eine Box darum) und die Werbetafel folgt der realen Form der Tafel, anstatt schief auszusehen. Wiederaufbau des gesamten Bildes als 3D-Oberfläche, ausgefranste Kanten, Hintergrundebenen: references/placing.md.
Regeln
- Lizenzen: MoGe-2s Code und Gewichte sind MIT. Mehrere verbreitete Tiefenmodelle sind nicht für die kommerzielle Nutzung freigegeben (siehe references/setup.md): Überprüfe vor dem Wechseln von Modellen für einen Kunden oder ein Portfolio, das Arbeiten verkauft.
- Die eigene Lizenz des Bildes gilt weiterhin für alles, was daraus erstellt wird.
- Masken im Alphakanal: Wenn ein Bild eine Maske im Alphakanal trägt (Wasser, Himmel), speichere das WebP verlustfrei mit exakten RGB-Werten (
cwebp -lossless -exact, Pillowexact=True). Verlustbehaftetes Alpha nullt die Farbe unter transparenten Pixeln und verschmiert sie. - Vor jedem Download um Erlaubnis fragen (Pakete, Gewichte), benennen, was, von wo und wie groß.