פורמט תוכנית הסצנה

תוכנית סצנה היא הנתונים ש-Nodaro שומר עבור סצנת תלת־ממד שאפשר לערוך: קומפוזיציה עם planType: "3d-scene" ועם schemaVersion מפורש. משימות של הרכיבים יצירת סצנת תלת־ממד ועריכת סצנת תלת־ממד מחזירות תוכנית כזו ב-output_data.scenePlan, רכיב רינדור וידאו הופך אותה ל-MP4, והתצוגה התלת־ממדית מציגה אותה. הדף הזה מסביר איך תוכנית בנויה, כדי שהקוד שלכם יוכל לשמור תוכניות, לבדוק את התקינות שלהן, להציג אותן ולערוך אותן.

כללים לכל גרסאות הפורמט

• יחידות וצירים. המיקומים נמדדים במטרים, במערכת צירים ימנית שבה ציר Y מצביע למעלה. סיבובי אוילר נמדדים ברדיאנים.
• זמן. הפריימים נספרים מאפס. סצנה נמשכת 1–60 שניות, בקצב של 15–60 פריימים לשנייה; ברירת המחדל היא 4 שניות ב-24 פריימים לשנייה.
• גרסאות. לכל תוכנית יש revisionId. עריכה אף פעם לא משנה תוכנית: היא יוצרת גרסה חדשה, שה-parentRevisionId שלה הוא הגרסה שממנה היא נוצרה. כל קובץ MP4 שרונדר מבוסס על גרסה מסוימת אחת.
• גרסאות פורמט. בדקו את schemaVersion לפני שאתם קוראים שדה כלשהו ששייך לגרסת פורמט אחת בלבד. גרסת פורמט 1 מתארת גאומטריה של צורות פשוטות; גרסת פורמט 2 מוסיפה שוטים וגאומטריה אפויה, כלומר גאומטריה שנקבעה מראש בקובצי GLB.
• גילוי היכולות. הנתיב GET /v1/3d-scene/capabilities מציין באילו מנועי יצירה, ולכן באילו גרסאות פורמט של סצנות, הפריסה תומכת. הזמינות של המנועים האופציונליים נקבעת לפי התצורה של הפריסה. מנוע ברירת המחדל, המנוע הבסיסי, מפיק סצנות בגרסת פורמט 1.

טיפוסים וסכמות

החבילה @nodaro/shared מייצאת את הטיפוסים ואת סכמות הבדיקה:

סכמות הבדיקה בודקות את המבנה ואת הכללים שחלים על כמה שדות יחד: מעגלים ביחסי האב, אבות שלא קיימים, פריימי מפתח אחרי הפריים האחרון ותקרת האורך. תוכנית שנכשלת בבדיקה נדחית כולה.

גרסת פורמט 1: צורות פשוטות ופריימי מפתח

סצנה בגרסת פורמט 1 שלמה בפני עצמה. היא מתארת צורות פשוטות וקבוצות בהיקף מוגבל, כולל דמויות פשוטות שממלאות מקום, עם פריימי מפתח מעטים לכל אובייקט ולמצלמה. היא לא משחזרת מודלי תלת־ממד מפורטים עם טקסטורות, וגם לא סימולציות פיזיקליות.

תוכנית בגרסת פורמט 1 שומרת:

• את המזהים, הטרנספורמציות והמידות של האובייקטים;
• את המיקום, היעד והעדשה של המצלמה;
• את התאורה ואת הרקע;
• את פריימי המפתח של כל אובייקט ושל המצלמה.

עריכת סצנה בגרסת פורמט 1

הנתיב POST /v1/3d-scene/edit מקבל scenePlan ו-expectedRevisionId, ובנוסף אחד מאלה: השדה prompt עם הוראה, או רשימה של operations. בקשה עם גרסה שלא תואמת נדחית. פעולות רצות בלי לקרוא למודל:

פעולה משנה בדיוק את השדות ששלחתם. כדי לשנות תנוחה שמוגדרת בפריימי מפתח, כללו גם את השינויים בפריימי המפתח. כל הסצנה הערוכה נבדקת שוב, ולכן עריכה לא יכולה להשאיר מצביע לאובייקט אב או לייחוס שכבר לא קיימים. שלחו lockedObjectIds כדי לשמור על אובייקטים ללא שינוי בעריכה עם הוראה. ראו את הדף עריכת סצנת תלת־ממד.

גרסת פורמט 2: גאומטריה אפויה

סצנה בגרסת פורמט 2 מוסיפה ארבעה דברים למושגים של גרסת פורמט 1:

• גאומטריית GLB שמורה, בקבצים שאי אפשר לשנות.
• ישויות סמנטיות, החלקים בסצנה שיש להם שמות, שהמשתמשים בוחרים ועורכים אותם.
• מסלול מצלמה צפוף, עם תנוחת מצלמה לכל פריים.
• שוטים רציפים, טווחים של פריימים עם חיתוכים מדויקים ביניהם.

קבצים

בגרסת פורמט 2, הרשומה שמצביעה על קובץ כוללת assetId אטום, סוג, תפקיד, אורך בבייטים וגיבוב SHA-256. היא לא כוללת פרטי גישה לאחסון או כתובת URL להורדה.

• קורא הסצנות צריך בדיוק את הבייטים שהרשומה מצביעה עליהם. הוא דוחה קובץ חסר, גדול מדי או שהשתנה, עוד לפני שהוא מציג משהו.
• הניגון טוען את הגאומטריה ואת נתוני המצלמה. קובצי המקור של סצנה, בפורמט המקורי של המנוע, הם הורדה נפרדת עם הרשאה משלה.
• כל גרסה שמורה מקבעת את כל הקבצים שלה, כולל בייטים שהיא משתמשת בהם שוב מגרסה קודמת.

ישויות

ישויות סמנטיות נותנות שמות לשורשים בגאומטריית ה-GLB ולתפקידי החומרים של השורשים האלה, כדי שאפשר יהיה לבחור ולערוך אותם.

• חומרים. כל תפקיד חומר שאפשר לערוך מציין חומר בתוך הגאומטריה של הישות עצמה. הצללת החימר שומרת את צבע הבסיס של כל חומר, ולכן שינוי של צבע המרכב של רכב לא משנה את הצמיגים שלו.
• ישויות אב. ישות יכולה להגדיר ישות אב. השורש המיוצא שלה מקונן אז בתוך השורש של האב, והטרנספורמציה של הצומת שלה יחסית לאב. המיקום של האב והאנימציה האפויה שלו מגיעים לצאצא דרך הקובץ עצמו.
• התאמה. התוכנית וקובץ ה-GLB חייבים לתאר את אותם יחסי אב וצאצא. קורא הסצנות דוחה סצנה שבה הם לא תואמים.
• בעלות. גאומטריה, חומרים ובחירה שייכים לישות שמגדירה אותם. צביעה מחדש של ישות אב אף פעם לא מגיעה לישות שמקוננת בתוכה.
• שורשים לארגון בלבד. ישות אב יכולה להיות בלי גאומטריה בכלל, ולכלול רק טרנספורמציה אפויה, שיכולה להיות מונפשת, לישויות שמקוננות בתוכה. קורא הסצנות מקבל אותה כל עוד משהו מקונן בתוכה.

עוגנים

עוגן של ישות הוא נקודה עם שם: שם יציב בשדה name ומיקום בשדה position, במרחב המקומי של הישות.

• בישות שמבוססת על קובץ, השדה האופציונלי nodeName קושר את העוגן לאחד מצמתי ה-GLB הגולמיים שבתוך השורש של הישות עצמה. המיקום, והסיבוב האופציונלי, נמדדים אז בקואורדינטות המקומיות של הצומת המקושר, ונעים יחד עם האנימציה שלו, עם האבות שלו ועם עריכות ידניות של הישות.
• למשל, העוגן { "name": "door.tip", "nodeName": "car/door.hinge", "position": [1, 0, 0] } ממקם נקודה במרחק מטר אחד לאורך ציר X של car/door.hinge.
• קישור לצומת שלא קיים בקובץ, או קישור לתוך ישות צאצא מקוננת, נדחים לפני הניגון. עוגנים של צורות פשוטות ושל קבוצות נשארים במרחב המקומי של הישות.
• היכולת ליצור קישורים כאלה משתנה ממנוע יצירה אחד לאחר.

מצלמה ואנימציה

במסלול המצלמה הצפוף יש מיקום, סיבוב והטלה לכל פריים. קורא הסצנות שומר על הערכים האלה בדיוק, כולל הגלגול של המצלמה והחיתוכים המדויקים בין השוטים. האנימציה נדגמת מהפריים המבוקש, ולכן גלילה אחורה בציר הזמן ורינדור של פריים בודד כלשהו נותנים אותה תנוחה.

נראות

הדגל האופציונלי visible של ישות שומר את הנראות האפויה שלה; כשהוא חסר, הישות גלויה.

• גאומטריה מוסתרת נשארת טעונה, והאנימציה שלה ממשיכה לרוץ, כך ששכבת־על יכולה להציג אותה שוב מיד.
• שכבת־על גוברת על הערך האפוי, והסרת שכבת־העל מחזירה את הערך האפוי.
• ישות אב מוסתרת מסתירה גם את כל מה שמקונן בתוכה.
• אובייקטים מוסתרים לא מגיבים ללחיצות בתצוגה התלת־ממדית. כדי לבחור אותם ולהציג אותם, השתמשו ברשימת הישויות.
• הנראות האפויה היא חלק מגיבוב התוכן של הגרסה.

עריכת סצנה בגרסת פורמט 2 עם שכבות־על

עריכות בגרסת פורמט 2 הן שכבות־על שאי אפשר לשנות, מעל הסצנה האפויה. יש ארבעה סוגים: טרנספורמציה, צבע חומר, נראות והיסט מצלמה של שוט. שכבת־על אף פעם לא נוגעת בגאומטריית הבסיס ולא בבייטים של המצלמה.

• שכבת־על של טרנספורמציה חלה מעל המיקום האפוי של הישות ושל האבות שלה. השדה space שלה קובע באיזו מערכת צירים הערכים שלה מתפרשים:
  • הערך local פירושו מערכת הצירים של האב של הישות, כולל המיקום האפוי. הערכים נשארים קבועים במערכת הזו, והעריכה זזה יחד עם אב שזז.
  • הערך world פירושו הצירים של הסצנה. הערכים הם המיקום, הסיבוב וקנה המידה של הישות ביחס לצירי הסצנה; סיבוב, שינוי קנה מידה או אנימציה של אחד האבות משנים את המקום שבו הישות נמצאת בסוף, אבל אף פעם לא את המשמעות של המספרים. הישות נשארת צאצא של האב שלה ושומרת על האנימציה האפויה שלה, ורק הערוצים שהעריכה מציינת נשארים קבועים.
  • קורא הסצנות דוחה את המקרה היחיד ששתי מערכות הצירים לא יכולות לבטא: אב עם קנה מידה לא אחיד מתחת לסיבוב, כי אז הטרנספורמציה שמתקבלת היא לא צירוף של מיקום, סיבוב וקנה מידה.
• שכבת־על של נראות מסתירה את הישות ואת כל מה שמקונן בתוכה. כל ישות שומרת על הנראות שלה, ולכן כשמציגים שוב את האב, חוזרים בדיוק הצאצאים שלא הוסתרו בנפרד.
• כל עריכה יוצרת גרסה חדשה, עם גרסת אב וגיבוב תוכן חדש. נעילות של ישויות נאכפות, ועריכה שנעשתה מול גרסה או גיבוב לא עדכניים נדחית.
• קבצים נגזרים לא עוברים לגרסה החדשה. תמונות הפוסטר, דוחות הבדיקה וההורדות בפורמט המקורי נוצרים מחדש לגרסה הערוכה, ורק אז מצורפים אליה.

כדי לשמור שכבות־על בלי משימת יצירה ובלי חיוב על מודל שפה, קראו ל-POST /v1/3d-scene/revisions/:revisionId/edits עם newRevisionId, עם ה-expectedContentHash של גרסת הבסיס, עם operations ועם lockedObjectIds אופציונלי, או השתמשו במתודה client.scene3d.applyEdits() ב-SDK. באפליקציות OAuth, הנתיב דורש את ההרשאה workflows:write. התצוגה התלת־ממדית מפיקה את הפעולות האלה בשבילכם.

רינדור

התצוגה התלת־ממדית בדפדפן ורינדור ה-MP4 משתמשים באותו קורא סצנות, ולכן סצנה נראית אותו דבר בשניהם. גרסת פורמט 2 מקבלת גאומטריית חימר ואנימציה קשיחה; קבצים עם טקסטורות, עם skinning או עם morph targets נדחים.

הסכמה מגבילה גם את התזמון, את המידות, את עומק ההיררכיה ואת גודל המניפסט. המחיר של רינדור נקבע לפי גודל הפריים של התוכנית; ראו את הדף רינדור וידאו.

קובצי GLB מיובאים

סצנה חדשה יכולה להתחיל מקובצי GLB שכבר קיימים בגרסאות שמורות. ב-POST /v1/3d-scene/generate, השדה inputAssets בוחר עד שמונה קבצים כאלה, כל אחד בצורה { id, revisionId, assetId, label? }. ייחוסי התמונה והווידאו נשארים בשדה נפרד, references.

• ייבוא דורש מנוע יצירה שתומך בייבוא. המנוע הבסיסי, וכל מנוע אחר שלא תומך בייבוא, דוחים אותו לפני כל חיוב.
• שולחים רק מזהים. Nodaro בודק את הגישה שלכם לגרסה המסוימת, ומוסיף בעצמו את הגיבוב ואת האורך בבייטים. בקשה שכוללת כתובת URL, או נתוני קובץ כאלה משלה, נדחית.
• כשהמנוע קורא קובץ GLB מיובא, Nodaro בודק שוב את הגישה ומנפיק הרשאת הורדה קצרת מועד. ההרשאות האלה הן פרטי גישה להעברה: הן אף פעם לא חלק מתוכנית הסצנה.
• גרסה שמורה יכולה לשמור עותקים פרטיים של הקבצים שהיא נבנתה מהם. העותקים שייכים לבעלים של הגרסה, נשארים מקובעים גם אחרי עריכות ידניות, ואף פעם לא מופיעים בין קובצי הניגון או ההורדות הציבוריות.

קריאת הקבצים הבינאריים דרך ה-API

המניפסט בגרסת פורמט 2 מפרט את הקבצים שלו, אבל הבייטים מגיעים מה-API, עם אימות Bearer רגיל:

• קובצי ניגון דורשים הרשאת צפייה בתהליך של הגרסה. קובץ המקור דורש הרשאת עריכה בתהליך. גרסאות אישיות זמינות לקריאה רק לבעלים שלהן.
• הנתיבים מחזירים 404 לגרסה שנמחקה או שאין אליה גישה, וכל תגובה כוללת Cache-Control: no-store.
• ב-SDK, המתודות client.scene3d.assetBytes(revisionId, asset) ו-client.scene3d.sourceBytes(revisionId) מחזירות ArrayBuffer, ובודקות את האורך המוצהר.

ראו את דף ה-API סצנות תלת־ממד לנקודות הקצה של היצירה, העריכה והרינדור.