تطوير

|trends.earth|هو برنامج مجاني ومفتوح المصدر، ومرخص بموجب (رخصة جنو العمومية العامة ، إصدار 2.0 أو أحدث <https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html> "_.

There are a number of components to the Trends.Earth tool. The first is a QGIS plugin supporting calculation of indicators, access to raw data, reporting, and production of print maps . The code for the plugin, and further instructions on installing it if you want to modify the code, are in trends.earth GitHub repository.

البرنامج الملحق لـ|trends.earth|QGIS مدعوم بعدد من نصوص Python المختلفة التي تسمح بحساب المؤشرات المختلفة على Google Earth Engine (GEE). توجد هذه البرامج النصية في المجلد الفرعي "gee" لملف GitHub هذا. يتم دعم البرامج النصية لـ GEE بواسطة وحدة Python الخاصة بـ "landdegradation"، والتي تتضمن تعليمات برمجية لمعالجة المدخلات والمخرجات للبرنامج الملحق، بالإضافة إلى الوظائف الشائعة الأخرى التي تدعم حساب تكاملات NDVI والأهمية الإحصائية والتعليمات البرمجية المشتركة الأخرى. التعليمات البرمجية لهذه الوحدة متاح في ملف ` landdegradation <https://github.com/ConservationInternational/landdegradation> `_ على GitHub.

يوجد مزيد من التفاصيل أدناه حول كيفية المساهمة في Trends.Earth من خلال العمل على التعليمات البرمجية للبرنامج الملحق، أو عن طريق تعديل التعليمات البرمجية للمعالجة، أو بالمساهمة في ترجمة موقع الويب والبرنامج الملحق.

تعديل التعليمات البرمجية للبرنامج الملحق QGIS

تثبيت البرامج الملحقة

Python

البرنامج الملحق تم برمجته في Python. بالإضافة إلى استخدامه لتشغيل البرنامج الملحق من خلال QGIS، يتم استخدام Python أيضًا لدعم إدارة البرنامج الملحق (تغيير الإصدار، تثبيت إصدارات مطورة، وما إلى ذلك). على الرغم من تضمين Python في QGIS، إلا أنك ستحتاج أيضًا إلى إصدار محلي من Python يمكنك إعداده باستخدام البرنامج المطلوب لإدارة البرنامج الملحق. أسهل طريقة لإدارة إصدارات متعددة من Python هي من خلال Anaconda distribution. للعمل على تطوير البرنامج الملحق، مطلوب Python 3. لتنزيل Python 3.7 (موصى به) برغم Anaconda ، انظر هذه الصفحة <https://www.anaconda.com/distribution/#download-section> _.

ملحقات Python

من أجل العمل مع التعليمات البرمجية لـ trends.earth، يجب أن يكون لديك Invoke مثبتًا على جهازك، بالإضافة إلى عدد من الحزم الأخرى المستخدمة لإدارة توثيق المستندات والترجمات وما إلى ذلك. هذه الحزم مدرجة جميعًا في ملف متطلبات "dev " لـ Trends.Earth، بحيث يمكن تثبيتها من خلال التنقل في موجّه الأوامر إلى المجلد الأساسي للتعليمات البرمجية لـ trends.earth والكتابة:

pip install -r requirements-dev.txt

ملاحظة

إذا كنت تستخدم Anaconda، فستحتاج أولاً إلى تنشيط البيئة الافتراضية لـ Python 3.7 قبل تشغيل الأمر أعلاه (وأي من أوامر الاستدعاء الأخرى المدرجة في الصفحة). طريقة واحدة للقيام بذلك هي عن طريق بدء "Anaconda prompt", من خلال "اتباع الإرشادات الموجودة على صفحة Anaconda <https://docs.anaconda.com/anaconda/user-guide/getting-started/#write-a-python-program-using-anaconda-prompt-or-terminal>` _.

PyQt

PyQt5 هي مجموعة أدوات الرسومات المستخدمة بواسطة QGIS3. لتجميع واجهة المستخدم الخاصة بـ Trends.Earth لـ QGIS3، يلزمك تثبيت PyQt5. يمكن تثبيت هذه الحزمة من pip باستخدام:

pip install PyQt5

ملاحظة

PyQt4 هي مجموعة أدوات الرسوم التي يستخدمها QGIS2. أفضل مصدر لهذه الحزمة على Windows هو من مجموعة الحزم التي يحتفظ بها Christoph Gohlke في UC Irvine. لتنزيل PyQt4، حدد الحزمة المناسبة من هذه الصفحة <https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyqt4> _. اختر الملف المناسب لإصدار Python الذي تستخدمه. على سبيل المثال، إذا كنت تستخدم Python 2.7، فاختر الإصدار الذي يحتوي على "cp27" في اسم الملف. إذا كنت تستخدم Python 3.7، فاختر الإصدار الذي يحتوي على "cp37" في اسم الملف. اختر "amd64" لـ 64-bit python، و "win32" لـ 32-bit python.

بعد التنزيل من الرابط أعلاه، استخدم `` pip `` لتثبيته. على سبيل المثال، بالنسبة إلى 64-bit wheel for Python 3.7، يمكنك تشغيل

pip install PyQt4-4.11.4-cp37-cp37m-win_amd64.whl

تغيير نسخة البرنامج الملحق

اتفاقية Trends.Earth هي أن أرقام الإصدارات المنتهية برقم فردي (على سبيل المثال 0.65) هي إصدارات مطورة، بينما الإصدارات المنتهية برقم زوجي (على سبيل المثال (0.66) هي إصدارات عامة. لا يتم إطلاق إصدارات مطورة من البرنامج الملحق عبر ملف QGIS، لذلك لا يراها المستخدمون العاديون للبرنامج الملحق مطلقًا. يستخدم فريق تطوير Trends.Earth الإصدارات المطورة ذات الأرقام الفردية أثناء اختبار الميزات الجديدة قبل إصدارها العام.

إذا كنت ترغب في إجراء تغييرات على التعليمات البرمجية وقمت بتنزيل إصدار عام من البرنامج الملحق (واحد ينتهي برقم زوجي)، فإن الخطوة الأولى هي تحديث إصدار البرنامج الملحق إلى الرقم الفردي التسلسلي التالي. لذلك، على سبيل المثال، إذا قمت بتنزيل الإصدار 0.66 من البرنامج الملحق، فستحتاج إلى تحديث الإصدار ليكون 0.67 قبل أن تبدأ في إجراء التغييرات. هناك العديد من الأماكن في التعليمات البرمجية حيث يتم ذكر الإصدار (وكذلك داخل كل برنامج نصي من GEE) لذلك هناك مهمة استدعاء للمساعدة في تغيير الإصدار. لتغيير الإصدار ليكون 0.67، يمكنك تشغيل

invoke set-version -v 0.67

سيؤدي تشغيل الأمر أعلاه إلى تحديث رقم الإصدار في كل مكان تتم الإشارة إليه في التعليمات البرمجية. لتجنب الالتباس، لا تقم أبدًا بتغيير الإصدار إلى إصدار تم إصداره بالفعل - قم دائمًا بزيادة قيمة علامة الإصدار إلى الرقم الفردي التالي.

اختبار التغييرات على البرنامج الملحق

بعد إجراء التغييرات على التعليمات البرمجية للبرنامج الملحق، ستحتاج إلى اختبارها للتأكد من أن البرنامج الملحق يعمل كما هو متوقع، ولضمان عدم ظهور عيوب أو أخطاء. يجب أن يخضع المكون الإضافي لاختبارات مكثفة قبل إصداره في ملف QGIS (حيث يمكن الوصول إليه من قبل مستخدمين آخرين) للتأكد من أن أي تغييرات في التعليمات البرمجية لا تعطل البرنامج الملحق.

لاختبار أي تغييرات أجريتها على البرنامج الملحق داخل QGIS، ستحتاج إلى تثبيته محليًا. هناك استدعاء للمهام التي تساعد في هذه العملية. تتمثل الخطوة الأولى قبل تثبيت البرنامج الملحق في التأكد من إعداد البرنامج الملحق بكل الملحقات التي يحتاج لها للتشغيل من داخل QGIS. للقيام بذلك، قم بتشغيل

invoke plugin-setup

لا يلزم تشغيل المهمة المذكورة أعلاه فورًا إلا بعد تنزيل التعليمات البرمجية لـ trends.earth، أو إذا تم إجراء أي تغييرات على الملحقات الخاصة بالبرنامج الملحق. بشكل افتراضي، سيعيد إعداد البرنامج الملحق'' استخدام أي ملفات مخزنة مؤقتًا على جهازك. للبدء من الصفر، أضف علامة ``-c (clean) إلى الأمر أعلاه.

بعد تشغيل plugin-setup، أنت جاهز لتثبيت البرنامج الملحق في مجلد ملحقات QGIS على جهازك. للقيام بذلك، قم بتشغيل

invoke plugin-install

بعد تشغيل الأمر أعلاه، ستحتاج إما إلى 1) إعادة تشغيل QGIS، أو 2) استخدام Plugin Reloader <https://plugins.qgis.org/plugins/plugin_reloader/>` _ لإعادة تحميل البرنامج الملحق Trends.Earth من أجل رؤية تأثيرات التغييرات التي أجريتها.

بشكل افتراضي، سيقوم plugin-install بالكتابة فوق أي ملفات للبرنامج الملحق الموجودة على جهازك، لكنه يترك في مكانه أي بيانات (حدود إدارية، وما إلى ذلك) قد يكون البرنامج الملحق قد قام بتنزيلها. للبدء من الصفر، أضف علامة -c (clean) إلى الأمر أعلاه. قد تحتاج إلى إغلاق QGIS من أجل إجراء تثبيت نظيف بنجاح للبرنامج الملحق باستخدام علامة -c.

ملاحظة

يفترض تثبيت البرنامج الملحق أنك تريد تثبيت البرنامج الملحق لاستخدامه في QGIS3. لتثبيت البرنامج الملحق للاستخدام في QGIS3، أضف العلامة``-v 2`` إلى أمر``plugin-install``. تذكر أن البرنامج الملحق قد يعمل أو لا يعمل بشكل كامل على QGIS3 - تم تصميم البرنامج الملحق في الأصل لـ QGIS2 ولا يزال قيد الاختبار على QGIS3.

مزامنة ونشر التغييرات على الثنائيات

لتسريع الحسابات في Trends.Earth، تسمح بعض الأدوات باستخدام الثنائيات المجمعة مسبقًا والتي تم تجميعها باستخدام `` numba <https://numba.pydata.org> `_. Numba هو برنامج مجمّع مفتوح المصدر يمكنه تجميع رمز Python وNumPy، مما يجعله أسرع من تشغيله مثل Python العادي. لتجنب مستخدمي Trends.Earth، تحتاج إلى تنزيل Numba وجميع ملحقاته، يوفر فريق Trends.Earth الثنائيات المجمعة مسبقًا للتنزيل إذا اختار المستخدمون تثبيتها.

لإنشاء ثنائيات مجمعة مسبقًا لنظام التشغيل و bitness (32/64 بت) وإصدار Python الذي تقوم بتشغيله على جهازك، استخدم

invoke binaries-compile

ملاحظة

ستحتاج إلى مجمّع C ++ حتى يعمل الأمر أعلاه. في نظام التشغيل Windows، راجع this github page للحصول على تفاصيل حول كيفية تثبيت برنامج التحويل البرمجي Microsoft Visual C ++ المطلوب لإصدار Python الخاص بك. على نظام MacOS، ستحتاج على الأرجح إلى تثبيت Xcode. على نظام Linux، قم بتثبيت الإصدار المناسب من GCC.

لإتاحة الثنائيات للجمهور، يتم توزيعها من خلال وحدة التخزين السحابي Amazon Web services S3. لتحميل الثنائيات التي تم إنشاؤها باستخدام الأمر أعلاه إلى، تشغيل

invoke binaries-sync

ملاحظة

سيفشل الأمر أعلاه إذا لم يكن لديك مفاتيح تسمح لك بالوصول للكتابة إلى وحدة تخزين``Trends.earth`` في S3.

سيقوم الأمر أعلاه بمزامنة كل ملف ثنائي فردي مع S3. ومع ذلك، يقوم مستخدمو toolbox بتنزيل الثنائيات كملف مضغوط واحد مرتبط بإصدار البرنامج الملحق الذي يستخدمونه. لإنشاء هذا الملف المضغوط بحيث يمكن الوصول إليه بواسطة مستخدمي Trends.Earth، قم بتشغيل:

invoke binaries-deploy

ملاحظة

سيفشل الأمر أعلاه إذا لم يكن لديك مفاتيح تسمح لك بالوصول للكتابة إلى وحدة تخزين``Trends.earth`` في S3.

بناء ملف مضغوط للبرنامج الملحق

هناك العديد من مهام الاستدعاء للمساعدة في إنشاء ملف مضغوط لنشر البرنامج الملحق في ملف QGIS، أو لمشاركة تطير إصدار من البرنامج الملحق مع الآخرين. لضغط البرنامج الملحق وجميع تبعياته في ملف ZIP يمكن تثبيته باتباع the process described in the Trends.Earth readme, تشغيل

invoke zipfile-build

سيؤدي هذا الأمر إلى إنشاء مجلد باسم `` build '' في مجلد التعليمات البرمجية الأساسي trends.earth، وفي هذا المجلد سيتم إنشاء ملف يسمى `` LDMP.zip ''. يمكن مشاركة هذا الملف مع الآخرين الذين يمكنهم استخدامه لتثبيت برنامج Trends.Earth يدويًا <https://github.com/ConservationInternational/trends.earth#installing-latest-packaged-development-version> `_. يمكن أن يكون هذا مفيدًا إذا كانت هناك حاجة لمشاركة أحدث الميزات مع شخص ما قبل توفرها في الإصدار العام من البرنامج الملحق.

نشر ملف ZIP الخاص بتطوير إصدار

توفر صفحة Trends.Earth GitHub ارتباطًا بملف ZIP يسمح للمستخدمين الذين قد لا يكونون مطورين بالوصول إلى تطوير إصدار من Trends.Earth. لإنشاء ملف ZIP وإتاحته على تلك الصفحة (يتم تخزين ملف ZIP على S3)، تشغيل

invoke zipfile-deploy

سيقوم هذا الأمر بضغط البرنامج الملحق ونسخه إلى `` https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip <https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip> `_.

ملاحظة

سيفشل الأمر أعلاه إذا لم يكن لديك مفاتيح تسمح لك بالوصول للكتابة إلى وحدة تخزين``Trends.earth`` في S3.

تعديل التعليمات البرمجية لمعالجة Earth Engine

يتم تخزين البرامج النصية لمعالجة Google Earth Engine (GEE) المستخدمة بواسطة Trends.Earth في مجلد "gee" ضمن مجلد trends.earth الرئيسي. لكي يكون هذا البرنامج النصي متاحًا لمستخدمي البرنامج الملحق Trend.earth QGIS، يجب نشرهم في خدمة api.trends.earth التي تحتفظ بها منظمة Conservation International للسماح لمستخدمي البرنامج الملحق باستخدام Earth Engine دون الحاجة إلى معرفة الكيفية لبرمجة أو الحصول على حسابات مستخدمين فردية على GEE. يوضح ما يلي كيفية اختبار ونشر البرامج النصية لـ GEE لاستخدامها مع Trends.Earth.

إعداد البرامج الملحقة

دوكر(docker)

تتطلب حزمة Trends.earth-CLI docker لكي تعمل. اتبع هذه الإرشادات لتثبيت docker على Windows, ، وهذه الإرشادات لتثبيت docker على Mac OS <https://docs.docker.com/docker-for-mac/install/>`_. إذا كنت تعمل على Linux، فاتبع الإرشادات الموجودة في هذه الصفحة <https://docs.docker.com/install> `_ المناسبة لتوزيع Linux الذي تستخدمه.

اختبار برنامج Earth Engine النصي محليًا

بعد تثبيت حزمة Trend.earth-CLI، ستحتاج إلى إعداد ملف .tecli.yml برمز token للوصول إلى حساب خدمة GEE من أجل اختبار البرامج النصية على GEE. لإعداد حساب خدمة GEE لـ tecli، احصل أولاً على مفتاح حساب الخدمة الخاص بك بتنسيق JSON (من وحدة التحكم السحابية في google)، ثم قم بترميزه في base64. قم بتوفير هذا المفتاح المشفر base64 إلى tecli بالأمر التالي:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

حيث "key" هو مفتاح حساب خدمة تنسيق JSON بترميز base64.

أثناء تحويل برنامج نصي حدد التعليمات البرمجية ليتم تشغيله على GEE من JavaScript إلى Python، أو عند إجراء تعديلات على هذه التعليمات البرمجية، قد يكون من المفيد اختبار البرنامج النصي محليًا، دون نشره على خادم api.trends.earth. للقيام بذلك، استخدم مهمة استدعاء run. على سبيل المثال، لاختبار البرنامج النصي "land_cover"، انتقل إلى الملف الرئيسي للتعليمات البرمجية الخاصة بـ Trends.Earth، وفي موجه الأوامر، قم بتشغيل

invoke tecli-run land_cover

سيستخدم هذا حزمة trends.earth-CLI لإنشاء وتشغيل حاوية Docker ستحاول تشغيل البرنامج النصي "land_cover". إذا كانت هناك أية أخطاء في بناء الجملة في البرنامج النصي، فستظهر هذه الأخطاء عند تشغيل الحاوية. قبل إرسال برنامج نصي جديد إلى api.trends.earth، تأكد دائمًا من أن invoke tecli-run قادر على تشغيل البرنامج النصي دون أي أخطاء.

عند استخدام invoke tecli-run، قد تظهر رسالة خطأ تقول:

Invalid JWT: Token must be a short-lived token (60 minutes) and in a
reasonable timeframe. Check your iat and exp values and use a clock with
skew to account for clock differences between systems.

يمكن أن يحدث هذا الخطأ إذا خرجت الساعة الموجودة في حاوية docker عن المزامنة مع ساعة النظام. يجب أن يؤدي إعادة تشغيل docker إلى إصلاح هذا الخطأ.

تعديل قوالب vector layer

Trends.Earth يسمح للمستخدمين برقمنة ميزات vector الجديدة لتحديد المناطق ذات الأهمية الخاصة.

في الوقت الحالي يتم دعم الطبقات "الإيجابية/ السلبية الخاطئة" فقط، ولكن يمكن إضافة المزيد إذا لزم الأمر. يتم إنشاء أي طبقة متجهة من ملفات قالب GeoPackage، والتي يمكن العثور عليها داخل مجلد data/error_recode في ملف تثبيت البرنامج الملحق. لكل نوع (vector ) 6 ملفات نموذجية، ملف واحد لكل لغة رسمية للأمم المتحدة. تمت إضافة رمز لغة ISO كلاحقة لاسم الملف. يعد ذلك ضروريًا لتوفير تسميات مترجمة في نماذج السمات. عند طلب إنشاء طبقة vector، سيبحث QGIS عن ملف القالب الذي يأخذ لغة QGIS إلى حساب، حيث يتم استخدام نسخة إنجليزية للخيار الخلفي من ملف القالب.

لتغيير مخطط الطبقة، من الضروري تغيير ملفات القالب المقابلة في مجلد data/error_recode في ملف تثبيت البرنامج الملحق. يحتوي ملف القالب أيضًا على تصميم افتراضي مدمج وتكوين نموذج السمة والذي سيتم تطبيقه تلقائيًا على الطبقة عند التحميل في QGIS.

لعرض المخطّطات في شكل سمة، يتم استخدام عنصر واجهة QML مدمج. يتم تخزين بيانات المخطّطات في جدول سمات vector layer. القيم من الحقول المقابلة مستخرجة بمساعدة التعبيرات.

التعليمات البرمجية المستخدمة لعمل المخطّطات تظهر مثل هذا:

import QtQuick 2.0
import QtCharts 2.0

ChartView {
    width: 380
    height:200
    margins {top: 0; bottom: 0; left: 0; right: 0}
    backgroundColor: "#eeeeec"
    legend.alignment: Qt.AlignBottom
    antialiasing: true
    ValueAxis {
        id: valueAxisY
        min: 0
        max: 100
    }

    BarSeries {
        id: mySeries
        axisY: valueAxisY
        axisX: BarCategoryAxis { categories: ["Productivity", "Land cover", "Soil organic carbon"] }
        BarSet { label: "Degraded"; color: "#9b2779"; values: [expression.evaluate("\"prod_deg\""), expression.evaluate("\"land_deg\""), expression.evaluate("\"soil_deg\"")] }
        BarSet { label: "Improved"; color: "#006500"; values: [expression.evaluate("\"prod_imp\""), expression.evaluate("\"land_imp\""), expression.evaluate("\"soil_imp\"")] }
        BarSet { label: "Stable"; color: "#ffffe0"; values: [expression.evaluate("\"prod_stab\""), expression.evaluate("\"land_stab\""), expression.evaluate("\"soil_stab\"")] }
    }
}

لاستخراج دالة قيمة الحقل تستخدم expression.evaluate("\"prod_deg\"")، الحجة الوحيدة التي تقبلها هي اسم الحقل. يحتوي الرسم البياني للطبقات الإيجابية / السلبية الخاطئة على ثلاثة مؤشرات: الإنتاجية والغطاء الأرضي والكربون العضوي للتربة. كل مؤشر للبرنامج الملحق نسبة إنتاجية لمنطقة المضلع وتحافظ على استقرار ثلاث قيم: مستقرة ومتردية محسّنة. على سبيل المثال، في حالة وجود حقول مؤشر الإنتاجية ستكون:

  • prod_deg - إنتاجية متردية

  • prod_stab - إنتاجية مستقرة

  • prod_imp - إنتاجية محسّنة

يتم تطبيق نفس نهج التسمية على الغطاء الأرضي (land_* fields) والكربون العضوي للتربة (land_* fields).

يتم حساب النسبة المئوية للمساحة باستخدام وظيفة التعبير المخصص، ويمكن العثور على التعليمات البرمجية الخاصة بها في ملف `` charts.py '' في الملف الرئيسي للبرنامج الملحق. تم تحسّين الوظيفة للعمل مع المضلعات الكبيرة واستخدامات سير العمل التالية. للحصول على هندسة معينة، ابحث عن bbox واستخرج raster susbset باستخدام bbox هذا. قم بإجراء تنقيط هندسي في الذاكرة وقم بتطبيقه كقناع على raster. ثم عد عدد البيكسلات التي لها قيمة محددة وحساب النسبة المئوية. نظرًا لأن عد البكسل مبني على وظائف مصفوفة عددية ، فهو سريع جدًا حتى بالنسبة للمضلعات الكبيرة.

في المحاولة الأولى لتعديل طبقة vector، سيُعرض على المستخدم مربع حوار حيث يجب عليه تحديد مجموعات البيانات التي سيستخدمها للمؤشرات. ثم سيقوم البرنامج الملحق بإعداد قيم التعبير الافتراضية لجميع حقول المؤشر، لذلك سيتم تحديث القيمة في كل تغيير هندسي.

معالجة البيانات الوصفية لمجموعة البيانات

يتم تخزين البيانات الوصفية لمجموعة البيانات بتنسيق QGIS QMD. يمكن إنشاء ملفات QMD هذه لكل raster على حدة وأيضًا لمجموعة البيانات بأكملها. يتم فتح مربع حوار محرر البيانات الوصفية من قائمة ** Edit metadata ** في Trends.Earth dock.

عندما يتم تصدير مجموعة البيانات إلى ZIP، يتم إجراء التحويل إلى ISO XML باستخدام تحويل XSLT. يوجد التحويل المقابل في الملف الفرعي data\xsl لمجلد تثبيت البرنامج الملحق.

تحديث إطار عمل التقارير

نظرة عامة على إطار عمل إعداد التقارير

تم تصميم إطار عمل التقارير ليكون قابلاً للتوسعة مع توفير التفاعل للمستخدم من خلال عمليات غير محظورة. يمكن عمل رفع ثقيل لإطار العمل من خلال فئات :التعليمات البرمجية: QgsProject و` QgsPrintLayout` والتي ليست موضوع آمن وبالتالي، لذلك استخدم :الكود البرمجي: qgis_process للقيام برفع ثقيل لإنشاء التقارير (والمخططات). يمكنك العثور على مزيد من المعلومات حول: الرمز البرمجي: qgis_process` هنا <https://docs.qgis.org/3.22/en/docs/user_manual/processing/standalone.html> `_.

هناك خطوتان رئيسيتان ينفذهما toolbox عند إنشاء التقارير (والمخططات) للطبقات الافتراضية في وظيفة:

  1. It creates a ReportTaskContext object that constitutes a ReportConfiguration object (see تكوين معلمات التقرير) and a Job object that is represented in the Datasets panel. This ReportTaskContext object is serialized to a JSON file and then passed as one of the arguments in a ReportProcessHandlerTask object (that inherits from QgsTask).

  2. يقوم كود ReportProcessHandlerTask ببدء مثيل منفصل من:code:qgis_process ويمرر المسار إلى ملف JSON كمدخل إلى خوارزمية معالجة: trendsearth:reporttask. هذا غلاف رفيع يقوم بإلغاء تسلسل الملف إلى كود ReportTaskContext ويمرره إلى كود ReportTaskProcessor المسؤول عن إنشاء التقارير ومشروع QGIS للوظيفة. بالنسبة للخوارزميات التي تتطلب مخططات، يقوم كود:code:`ReportTaskProcessor بتمرير كود الوظيفة إلىة كود AlgorithmChartsManager الذي يتحقق مما إذا كان هناك تكوين مخطط محدد لخوارزمية الوظيفة. إذا تم تعريفه، فإنه ينشئ المخططات المقابلة كملفات PNG. (راجع إضافة تكوينات الرسم البياني للحصول على مزيد من المعلومات حول تكوينات المخططات)

يوفر الرسم البياني أدناه توضيحًا عالي المستوى لهذه العملية:

../_images/report_dev_process.png

* اضغط على الصورة للحصول على رؤية مكبرة.

ملاحظة

تم تبسيط بعض أسماء الوظائف في الرسم البياني أعلاه لأغراض التوضيح. يمكن العثور على الفئات المذكورة أعلاه في وحدات LDMP.reports و`LDMP.processing_provider.report <https://github.com/ConservationInternational/trends.earth/tree/master/LDMP/processing_provider/report.py>`_ .

إضافة متغيرات مخطط التقرير

توفر متغيرات التقرير معلومات السياق المتعلقة بوظيفة أو طبقة (أو نطاق) أو:ref:report_settings أثناء عملية تنفيذ التقرير. حاليًا، يدعم toolbox المتغيرات المدرجة في قسم متغيرات تعبير التخطيط

يتم تعريف كل متغير على أنه : code: namedtuple في الوحدة LDMP.reports.expressions ويتم لاحقًا تحديثها وتقييمها من خلال كود ReportTaskProcessor.

اتبع الإرشادات أدناه حول كيفية إضافة وظيفة جديدة أو متغيرات الطبقة الحالية.

متغير الوظيفة

يتيح معلومات حول الوظيفة الحالية - التي يتم تنفيذها - ليتم إضافتها إلى مخطط التقرير. يتم تغليف المعلومات حول كل متغير وظيفة في كود:code:JobAttrVarInfo المكون من أربع سمات:

اسم السمة

الوصف

نوع البيانات

القيمة الافتراضية

job_attr

اسم السمة للكود Job كما هو مستخدم في dot notation. على سبيل المثال، id يتوافق مع job.id. يمكنك حتى استخدام dot notation للإشارة إلى السمات في الفئات المتداخلة الداخلية، على سبيل المثال results.uri.uri.

سلسلة

N/A

var_name

اسم متغير مخطط التقرير. يجب أن يكون مسبوق بـ te_job_.

سلسلة

N/A

default_value

قيمة افتراضية لاستخدامها لـ var_name, يتم تطبيقها غالبًا عند تصميم التخطيطات.

الكود

الكود

fmt_func

كود الدالة سيتم استخدامه لتحويل قيمة سمة الوظيفة إلى تنسيق متوافق مع تعبيرات QGIS. على سبيل المثال يمكن استخدام str لتحويل قيمة` id` للوظيفة من UUID إلى سلسلة. يمكنك أيضًا استخدام وظائف lambda هنا.

كود الدالة

لاشيء

يوضح كود snippet أدناه كيفية إضافة متغير`te_job_result_name` يتوافق مع job.results.name.

# LDMP/reports/expressions.py
def _job_attr_var_mapping() -> typing.List[JobAttrVarInfo]:
    return [
        ...
        JobAttrVarInfo('results.name', 'te_job_result_name', '', str),
        ...
    ]

متغير طبقة

يوفر معلومات حول طبقة raster الحالية الجاري تنفيذها. يتم تغليف هذه المعلومات المتغيرة في كود LayerVarInfo المكون من ثلاث سمات:

اسم السمة

الوصف

نوع البيانات

القيمة الافتراضية

var_name

اسم متغير تخطيط التقرير. يجب أن يكون مسبوق بـ te_current_layer_.

سلسلة

N/A

default_value

قيمة افتراضية لاستخدامها لـ var_name, يتم تطبيقها غالبًا عند تصميم التخطيطات.

الكود

الكود

fmt_func

كود دالة سيتم استخدامه لاستخراج و/أو تحويل قيمة من كود QgsRasterLayer <https://qgis.org/pyqgis/master/core/QgsRasterLayer.html> _ إلى تنسيق متوافق مع تعبيرات QGIS. يمكنك أيضًا استخدام وظائف lambda هنا.

على سبيل المثال lambda layer: layer.name() يُرجع اسم الطبقة.

كود الدالة

لاشيء

يوضح كود snippet أدناه كيفية إضافة متغير te_current_layer_height يتوافق مع ارتفاع طبقة raster .

# LDMP/reports/expressions.py
def _current_job_layer_var_mapping() -> typing.List[LayerVarInfo]:
    return [
        ...
        LayerVarInfo(
            'te_current_layer_height',
            '',
            lambda layer: layer.height()
        )
        ...
    ]

ملاحظة

هذه المتغيرات متاحة فقط في نطاق التخطيط.

إضافة تكوينات الرسم البياني

يمكن تجميع المخططات باستخدام كود تكوين مخطط يتوافق مع خوارزمية محددة. تحديد تكوين مخطط جديد هو عملية من ثلاث خطوات:

  1. أنشئ فئة مخطط جديدة تستقبل من code:BaseChart في وحدة LDMP.reports.charts. قم بتنفيذ دالة export لتحديد نوع المخطط والخصائص وما إلى ذلك باستخدام Plotly Python library التي تأتي مع QGIS. أخيرًا ، داخل دالة export قم باستدعاء دالة : save_image لكتابة كود Plotly Figure كملف صورة باستخدام أي من التنسيقات التي تدعمها فئات QImageWriter. يمكنك أيضًا تحديد المسار بالنسبة إلى ملف الإخراج الأساسي والذي يتوفر أيضًا كسمة في الفئة الأساسية. انظر كود snippet أدناه:

    # LDMP/reports/charts.py
Class MyCustomChart(BaseChart):
    def export(self) -> typing.Tuple[bool, list]:
        status = True
        messages = []

        # Create chart Figure using Plotly and set properties
        fig = go.Figure(...)

        # Add warning or error messages
        messages.append('Colour list not supported.')

        # Set image path in dataset's reports folder
        img_path = f'{self.root_output_dir}/chart-NDVI.png'

        # Save image and append its path
        self.save_image(fig, img_path)
        self._paths.append(img_path)

        return status, messages

    يمكنك الرجوع إلى فئة UniqueValuesPieChart للحصول على أمثاله أكثر اكتمالاً.

  2. أنشئ فئة تكوين مخطط ترث من:BaseAlgorithmChartsConfiguration ونفِّذ دالة _add_charts. تحدد فئة تكوين المخطط بشكل أساسي المخططات التي سيتم استخدامها لخوارزمية معينة. السمة layer_band_infos`هي قائمة من التعليمات البرمجية الخاصة بـ :code:`LayerBandInfo التي تحتوي على بيانات الطبقة ومعلومات النطاق المطلوبة لإنتاج المخططات. يمكنك الرجوع إلى فئة LandCoverChartsConfiguration للحصول على مثال أكثر اكتمالاً.

  3. أخيراً، قم بتعيين خوارزمية (name) إلى فئة تكوين المخطط المقابل في AlgorithmChartsManager كما هو موضح أدناه:

    # LDMP/reports/charts.py
Class AlgorithmChartsManager:
    def _set_default_chart_config_types(self):
        ...
        self.add_alg_chart_config('land-cover', LandCoverChartsConfiguration)
        self.add_alg_chart_config('productivity', MyCustomLandProductivityChartsConfiguration)
        ...

    إن فئة AlgorithmChartsManager، والتي تم إنشاء مثيل لها في كود ReportTaskProcessor، ستنشئ كوداً جديدًا لتكوين مخطط لخوارزمية مهمة مقابلة عند إنشاء التقارير.

المساهمة في التوثيق

نظرة عامة

تم إنتاج وثائق Trends.Earth باستخدام Sphinx <http://www.sphinx-doc.org/en/master/> _ ، وهي مكتوبة بتنسيق reStructuredText <http://docutils.sourceforge.net/rst.html> `_. إذا لم تكن معتادًا على أي من هذه الأدوات، فراجع وثائقها للحصول على مزيد من المعلومات حول كيفية استخدامها.

يتم تخزين مستندات Trends.Earth في مجلد "docs" ضمن ملف trends.earth. يوجد داخل هذا المجلد عدد من الملفات والمجلدات الرئيسية التي يجب أن تكون على دراية بها:

  • الإنشاء: يحتوي على وثائق الإنشاء الخاصة trends.earth (بتنسيق PDF و HTML). لاحظ أنه لن يظهر على جهازك إلا بعد تشغيل مهمة استدعاء docs-build

  • i18n: يحتوي على ترجمات للوثائق إلى لغات أخرى. عادةً ما تتم معالجة الملفات الموجودة هنا تلقائيًا باستخدام مهام الاستدعاء، لذلك لن يكون لديك سبب لتعديل أي شيء في هذا المجلد.

  • الموارد: تحتوي على أي موارد (صور أو ملفات PDF بشكل أساسي) يشار إليها في الوثائق. يوجد حاليًا مجلد واحد فقط ("EN"، للغة الإنجليزية) حيث أن جميع الصور الموجودة في الوثائق مأخوذة من النسخة الإنجليزية من البرنامج الملحق - إذا كان من الممكن إضافة مجلدات إضافية مناسبة ضمن "الموارد" برموز لغة مكونة من حرفين لتضمينها صور خاصة بلغة معينة.

  • المصدر: يحتوي على ملفات المصدر reStructuredText التي تحدد الوثائق (هذا النص الإنجليزي الفعلي للوثائق، وهذه الملفات التي من المرجح أن تحتاج إلى تعديلها).

تثبيت البرامج الملحقة

ملحقات Python

من أجل العمل بالتوثيق المستندي، تحتاج إلى استدعاء Sphinx و sphinx-intl و sphinx-rtd-theme (سمة موقع Trends.Earth) المثبتة على جهازك. يتم سرد جميع هذه الحزم في ملف متطلبات "dev" الخاص بـ Trends.Earth، بحيث يمكن تثبيتها بالانتقال في موجه الأوامر إلى المجلد الرئيسي للتعليمات البرمجية الخاصة بـ trends.earth واكتب:

pip install -r requirements-dev.txt

LaTeX

يستخدم LaTeX لإنتاج مخرجات PDF لوثائق Trends.Earth.

للتثبيت على Windows، "اتبع العملية الموضحة هنا <https://www.tug.org/protext>`_ لتثبيت توزيع ProTeXt لـ LaTeX من zipfile المتوفر هنا. إن مثبّت LaTeX كبير جدًا (عدة غيغابايت) لذا قد يستغرق تنزيله وتثبيته بعض الوقت.

في نظام MacOS، يعد MacTeX خيارًا جيدًا ويمكن تثبيته "باتباع الإرشادات الواردة هنا في نظام MacOS، يعد MacTeX خيارًا جيدًا ويمكن تثبيته باتباع الإرشادات الواردة هنا.

على Linux، يجب أن يكون تثبيت LaTeX أسهل بكثير - استخدم مدير حزم التوزيع الخاص بك للعثور على أي توزيع LaTeX مضمّن افتراضيًا وتثبيته.

Qt Linguist

هناك حاجة أيضًا إلى Qt Linguist لسحب السلاسل من الكود وGUI للترجمة. يجب أن يكون الأمر "lrelease" متاحًا وفي مسارك. حاول تجربة:

lrelease

داخل نافذة طرفية. إذا لم يتم العثور على الملف، فستحتاج إلى تثبيت Qt Linguist. هذه الصفحة <https://github.com/lelegard/qtlinguist-installers/releases> _ هي أحد مصادر أدوات التثبيت لشركة Qt Linguist. بمجرد تثبيت Qt Linguist، تأكد من إضافة المجلد الذي يحتوي على lrelease إلى المسار الخاص بك حتى يتمكن البرنامج النصي invoke الخاص بـ Trends.Earth من العثور عليه.

تحديث وبناء الوثائق

بمجرد تثبيت متطلبات Sphinx، تكون جاهزًا لبدء تعديل الوثائق. توجد الملفات المراد تعديلها ضمن مجلد "docs\source". بعد إجراء أي تغييرات على هذه الملفات، ستحتاج إلى إنشاء الوثائق لعرض النتائج. يوجد إصداران من وثائق Trends.Earth: إصدار HTML (يُستَخدَم لموقع الويب) ونسخة PDF (للتنزيل دون اتصال بالإنترنت). لإنشاء وثائق لـ Trends.Earth، استخدم مهمة الاستدعاء "docs-build". بشكل افتراضي، ستنشئ هذه المهمة التوثيق الكامل لـ Trends.Earth، بتنسيق HTML وPDF لجميع اللغات المدعومة. قد يستغرق هذا بعض الوقت للتشغيل (حتى بضع ساعات). إذا كنت تقوم فقط باختبار نتائج بعض التغييرات الطفيفة على الوثائق، فمن الأفضل عادةً استخدام الخيار -f (for "fast"). سيؤدي هذا الخيار إلى إنشاء وثائق HTML باللغة الإنجليزية فقط، والتي يجب أن تستغرق بضع ثوانٍ فقط. للبناء باستخدام الخيار السريع، قم بتشغيل

invoke docs-build -f

سيستغرق تشغيل الأمر أعلاه بضع ثوانٍ، ثم إذا نظرت أسفل "docs\build\html\en"، فسترى إصدار HTML من الوثائق. قم بتحميل ملف "index.html" في متصفح الويب لترى كيف يبدو.

لإنشاء التوثيق الكامل، لجميع اللغات، بتنسيق PDF و HTML (تذكر أن هذا قد يستغرق بضع ساعات حتى يكتمل)، قم بتشغيل

invoke docs-build

بعد تشغيل الأمر أعلاه ، سترى (للغة الإنجليزية) وثائق HTML ضمن "docs\build\html\en"، وملفات PDF للوثائق ضمن "docs\build\html\en\pdfs".

إذا كنت ترغب في اختبار لغة معينة (عند اختبار الترجمات، على سبيل المثال)، يمكنك تحديد رمز لغة مكون من حرفين لإنشاء المستندات لتلك اللغة فقط. على سبيل المثال، لإنشاء الوثائق الإسبانية فقط، قم بتشغيل

invoke docs-build -l es

لاحظ أنه يمكن دمج الخيارات، بحيث يمكنك استخدام الخيار السريع لإنشاء إصدار HTML فقط من الوثائق الإسبانية عن طريق تشغيل

invoke docs-build -f -l es

عند إنشاء التوثيق الكامل لموقع الويب، من الأفضل إزالة أي نسخ قديمة من الوثائق أولاً، حيث قد تحتوي على ملفات لم تعد مستخدمة في الوثائق المحدثة. للقيام بذلك، استخدم خيار -c (clean)

invoke docs-build -c

بشكل عام، يجب أن يكتمل بناء المستندات دون أي أخطاء إذا كنت تخطط لمشاركة الوثائق أو نشرها على موقع الويب. ومع ذلك، عند اختبار الأشياء محليًا، قد ترغب في تجاهل أخطاء التوثيق التي تظهر فقط لبعض اللغات (بسبب أخطاء بناء الجملة الناشئة عن أخطاء الترجمة، وما إلى ذلك)، والاستمرار في بناء الوثائق المتبقية بغض النظر عما إذا كانت هناك أية أخطاء. للقيام بذلك، استخدم خيار``-i`` (ignore errors)

invoke docs-build -i

متى قمت بإجراء أي تغييرات على نص الوثائق، فمن الأفضل دفع أحدث السلاسل إلى Transifex حتى يمكن ترجمتها. لتحديث السلاسل على Transifex بأي تغييرات جديدة، قم بتشغيل

invoke translate-push

ملاحظة

لتشغيل الأمر أعلاه بنجاح، يجب أن يكون لديك مفتاح حساب transifex لـ Trends.Earth

بناء وثائق للإصدار

قبل إصدار وثائق جديدة، اسحب دائمًا أحدث الترجمات من Transifex حتى تكون جميع الترجمات محدثة. للقيام بذلك، قم بتشغيل

invoke translate-pull

لإنشاء نسخة من التوثيق للإصدار العام (سواء لموقع الويب أو بتنسيق PDF) ، يجب عليك إنشاء الوثائق بالكامل باستخدام docs-build بدون أي معلمات إضافية:

invoke docs-build

يجب أن تكتمل هذه العملية بنجاح مع عدم وجود أخطاء. في حالة حدوث أي أخطاء أثناء العملية، راجع رسالة الخطأ وقم بإجراء أي تعديلات لازمة للسماح للإنشاء بنجاح تام. بمجرد اكتمال البناء بدون أخطاء، تكون الملفات جاهزة لإصدار على موقع الويب.

ملاحظة

يحتوي كلا الأمرين أعلاه أيضًا على خيارات -f (force) تفرض سحب أو دفع أحدث الترجمات من أو إلى Transifex (على التوالي). استخدم هذه الخيارات فقط إذا كنت متأكدًا تمامًا مما تفعله، حيث يمكنها الكتابة فوق الترجمات تماماً على Transifex، مما يؤدي إلى فقد العمل الذي قام به المترجمون إذا لم يتم الالتزام بأحدث الترجمات في github بعد.

إضافة نص وثائقي جديدة

يجب إضافة أي ملفات .rst جديدة تمت إضافتها إلى الوثائق إلى العديد من ملفات التكوين للتأكد من ظهورها في قائمة التنقل، وترجمتها بشكل صحيح، و (للبرامج التعليمية) لضمان إنشائها في PDF حتى يتمكنوا من ذلك. يمكن تنزيلها للاستخدام في وضع عدم الاتصال.

  • docs\source\index.rst: أضف ملفات .rst جديدة في المكان المناسب هنا للتأكد من أنها مرتبطة من قائمة التنقل.

  • .tx\config: قم بإدراج ملفات .rst الجديدة هنا (بنفس تنسيق الملفات الأخرى المضمنة بالفعل) من أجل جعل برنامج الترجمة على علم بها حتى يمكن ترجمتها

  • docs\source\conf.py: إذا كنت ترغب في إنشاء ملف PDF لصفحة من موقع الويب، فيجب عليك إدراج هذه الصفحة هنا في قائمة `latex_documents. عادةً ما نقوم بذلك فقط لصفحات البرامج التعليمية التي نريد إتاحتها للمشاركين في ورشة العمل في ملفات PDF فردية. سيتم تضمين كل صفحة على الموقع في نسخة PDF من الموقع ككل، بغض النظر عما إذا كانت مدرجة في قائمة latex_documents.

إضافة صور جديدة أو موارد أخرى

يجب إضافة أي صور جديدة أو موارد أخرى (ملفات PDF، إلخ) التي تحتاج لها الوثائق ضمن "docs\resources\en". إذا رغبت في ذلك، فمن الممكن تحميل إصدارات مختلفة من الصورة بحيث تظهر الصورة مع الترجمات المناسبة. قد يكون هذا مفيدًا إذا كنت تريد إظهار واجهة GUI باللغة المناسبة، على سبيل المثال. للقيام بذلك، قم أولاً بتحميل نسخة من الصورة إلى "docs\resourcesen" (مع نص باللغة الإنجليزية). بعد ذلك، أنشئ نسخة من الصورة بنص مترجم وضع تلك الصورة تحت المجلد المناسب لتلك اللغة (على سبيل المثال، ستظهر صورة تظهر الترجمات الإسبانية ضمن "docs\resources\es"). سيتم استخدام النسخة الإنجليزية من الصورة كإصدار افتراضي لجميع اللغات التي لم يتم توفير نسخة أصلية من الصورة لها، بينما سيتم استخدام النسخة المترجمة عند توفرها.

ملاحظة

يوجد مجلد آخر،docs\\source\\static، يستخدم للاحتفاظ بالموارد مؤقتًا أثناء تشغيل البرامج النصية التي تبني توثيق مستندي Trends.Earth. قد يكون لديك صور مدرجة تحت هذا المجلد إذا كنت قد بنيت التوثيق على هذا الجهاز. ** يجب عدم استخدام هذا المجلد مطلقًا لإضافة موارد جديدة ** - يجب دائمًا وضع الموارد الجديدة ضمن docs\\resources\\en أو، بالنسبة للصور المترجمة، المجلد المناسب الخاص باللغة ضمن docs\\resources.

المساهمة كمترجم

تتم إدارة الترجمات لكل من البرنامج الملحق QGIS وكذلك لهذا الموقع بواسطة transifex <http://www.transifex.com> _. إذا كنت ترغب في المساهمة في ترجمة البرنامج الملحق والوثائق (ونرغب في الحصول على مساعدتك!) يمكنك طلب الانضمام إلى فريقنا من خلال transifex <https://www.transifex.com/conservation-international/trendsearth> _ ، أو عن طريق مراسلتنا عبر البريد الإلكتروني على `trends.earth@conservation.org.