פרויקט של Ignition Robotics

בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.

סיכום הפרויקט

ארגון קוד פתוח:

Ignition Robotics

כותבים טכניים:

An Thai Le

שם הפרויקט:

מדריכים בנושא פיזיקה ב-Ignition ומסמכי עזר של ממשקי API

אורך הפרויקט:

אורך רגיל (3 חודשים)

תיאור הפרויקט

מוטיבציה

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

• מדריכים מקיפים ליצירת יישומי פלאגין מותאמים אישית של פיזיקה שמשתמשים במנועי פיזיקה מותאמים אישית כדי להפעיל סימולציות
• מסמכי תיעוד של API קוהרנטיים

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

תיאור

לפרויקט הזה יש שני יעדים עיקריים:

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

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

1. מבוא: תיאור הארכיטקטורה ברמה גבוהה של ספריית הפיזיקה של Ignition, מנועי הפיזיקה הנתמכים והיעדים.
2. התקנה: הנחיות למשתמש להתקנה אופציונלית של מנועי הפיזיקה הנדרשים, בהתאם להקשרים של האפליקציה. במדריך הזה מוצגות גם דוגמאות לתצורות של כל פלאגין של מנוע פיזיקה, כדי להתאים סימולציה ספציפית.
3. שימוש בפלאגין DART: תיאור של דוגמה לשימוש במנוע הפיזיקה DART בסימולציה של Gazebo. המדריך מורכב מרצף של פעולות ותצורות שנועדו להפעיל את הספרייה הזו כקצה העורפי של סימולציית Gazebo בסביבה ספציפית לדוגמה.
4. יצירת פלאגין בהתאמה אישית: מדריך למשתמש או למפתח חדשים ליצירת פלאגין בהתאמה אישית על סמך מנוע פיזיקה בהתאמה אישית באמצעות צורות מסוימות של קובצי תצורה (אולי תבניות של כיתות), ופיתוח ממשק בין ממשק ה-API של מנוע הפיזיקה לבין ממשק ה-API של הספרייה הזו. בסוף המדריך אפשר למצוא כמה בדיקות תקינות.
5. שימוש בכמה יישומי פלאגין בסימולציה (נדרשת דיון): תיאור של שימוש בו-זמנית בכמה יישומי פלאגין בזמן ריצה, באמצעות סימולציה לדוגמה.

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

למסמכי תיעוד של API, ניתן להתאים את עצמם לסגנון המסמכים של Google C++ בספרייה הזו. לדוגמה, לכל הכיתות צריך להיות תיאור ברמת הכיתה. בנוסף, כל הפונקציות הציבוריות חייבות להיות מתועדות עם תיאור, כל הארגומנטים שלהן וכן ערכים אפשריים להחזרה וחריגות. כדאי לתעד קודם את הסוגים החשובים ביותר (למשל dartsim::RetrieveWorld, Feature וכו') כגישה קלה יותר מלמעלה למטה. סגנון תיעוד נוסף, זיהוי חשוב של הכיתה ידונו בתקופה של יצירת הקשר בקהילה.

אבני דרך

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

• 17 באוגוסט עד 13 בספטמבר: יצירת קשרים בקהילה:

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

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

• 1 בנובמבר עד 30 בנובמבר: כתיבת מסמכי עזרה של API לכיתות החשובות ביותר וקיבוץ המסמכים באמצעות Doxygen.

• 1 בדצמבר עד 5 בדצמבר: כתיבת דוח הפרויקט.

• אחרי GSoD 2020: אני רוצה לשמור על קשר עם Ignition Robotics כדי להמשיך לשפר ולתחזק את העבודות שלי.

הערות לסיכום

חשוב לתקן את הקובץ README.md הנוכחי בדף הראשי של Ignition Physics, מאחר שההתקנה הבינארית באמצעות apt-get לא פועלת ב-Ubuntu 18.04. צריך לתקן גם את הקטע של התקנת המקור בגלל פורמט שגוי.