TFRecord وEarth Engine

TFRecord هو تنسيق ثنائي لترميز التسلسلات الطويلة من نماذج tf.Example الأولية بكفاءة. يتم تحميل ملفات TFRecord بسهولة من خلال TensorFlow عبر حزمة tf.data كما هو موضّح هنا وهنا. توضّح هذه الصفحة كيفية تحويل Earth Engine بين تنسيقَي ee.FeatureCollection أو ee.Image وتنسيق TFRecord.

تصدير البيانات إلى TFRecord

يمكنك تصدير الجداول (ee.FeatureCollection) أو الصور (ee.Image) إلى ملفات TFRecord في Google Drive أو Cloud Storage. تعتمد عملية ضبط التصدير على ما يتم تصديره كما هو موضّح أدناه. يتم فرض نوع البيانات العشرية على جميع الأرقام التي يتم تصديرها من Earth Engine إلى TFRecord.

تصدير الجداول

عند تصدير ee.FeatureCollection إلى ملف TFRecord، يكون هناك تطابق تام بين كل ee.Feature في الجدول وكل tf.train.Example (أي كل سجلّ) في ملف TFRecord. يتم ترميز كل سمة من سمات ee.Feature على شكل tf.train.Feature مع قائمة بالأرقام العشرية التي تتوافق مع الرقم أو ee.Array المخزَّن في السمة. إذا صدّرت جدولاً يحتوي على صفائف في السمات، عليك إعلام TensorFlow بشكل الصفيف عند قراءته. سيتم دائمًا ضغط الجدول الذي يتم تصديره إلى ملف TFRecord باستخدام نوع الضغط GZIP. ستحصل دائمًا على ملف TFRecord واحد بالضبط لكل عملية تصدير.

يوضّح المثال التالي تحليل البيانات من جدول تم تصديره للسمات العددية ('B2'،...،'B7'، 'landcover'). يُرجى العِلم أنّ سمة قوائم الأعداد العشرية هي [1] والنوع هو tf.float32:

Python

dataset = tf.data.TFRecordDataset(exportedFilePath)

featuresDict = {
  'B2': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B3': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B4': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B5': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B6': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B7': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'landcover': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32)
}

parsedDataset = dataset.map(lambda example: tf.io.parse_single_example(example, featuresDict))
        

يُرجى العِلم أنّ هذا المثال يوضّح قراءة الميزات العددية (أي shape=[1]). إذا كنت بصدد تصدير مصفوفات ثنائية أو ثلاثية الأبعاد (مثل أجزاء الصور)، عليك تحديد شكل الأجزاء في وقت التحليل، على سبيل المثال shape=[16, 16] لجزء بحجم 16×16 بكسل.

جارٍ تصدير الصور

عند تصدير صورة، يتم ترتيب البيانات كقنوات وارتفاع وعرض (CHW). قد يتم تقسيم عملية التصدير إلى عدة ملفات TFRecord، بحيث يحتوي كل ملف على جزء واحد أو أكثر بحجم patchSize، وهو ما يحدّده المستخدم في عملية التصدير. يحدّد المستخدم حجم الملفات بالبايت في المَعلمة maxFileSize. هناك تطابق تام بين كل جزء وكل tf.train.Example في ملف TFRecord الناتج. يتم تخزين كل نطاق من الصورة كسمة tf.train.Feature منفصلة في كل tf.train.Example، حيث يكون طول قائمة الأعداد العشرية المخزَّنة في كل سمة هو عرض الجزء * الارتفاع. يمكن تقسيم القوائم المسطّحة إلى عدّة وحدات بكسل فردية كما هو موضّح في هذا المثال. أو يمكن استرداد شكل التصحيح الذي تم تصديره كما هو موضّح في هذا المثال.

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

[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
    

يتداخل كل مربّع مع المربّعات المجاورة بمقدار [kernelSize[0]/2, kernelSize[1]/2]. نتيجةً لذلك، تحتوي نواة بحجم kernelSize تتمركز على بكسل حافة في جزء بحجم patchSize على بيانات صالحة بالكامل. يوضّح الشكل 1 الترتيب المكاني للأجزاء في المساحة، حيث يتوافق بُعد المساحة المتروكة مع جزء النواة الذي يتداخل مع الصورة المجاورة:

الشكل 1: كيفية تصدير أجزاء الصور بُعد المساحة المتروكة هو kernelSize/2.

formatOptions

يتم تمرير المَعلمات patchSize وmaxFileSize وkernelSize إلى طلب ee.Export (JavaScript) أو ee.batch.Export (Python) من خلال قاموس formatOptions، حيث تكون المفاتيح هي أسماء المَعلمات الإضافية التي تم تمريرها إلى Export. القيم المحتملة لـ formatOptions لصورة تم تصديرها بتنسيق TFRecord هي:

الموقع	الوصف	النوع
patchDimensions	تمثّل هذه السمة أبعاد المربّعات التي تغطي منطقة التصدير، وتغطي كل بكسل في المربّع المحيط مرة واحدة بالضبط (باستثناء الحالات التي لا تقسم فيها أبعاد المربّعات المربّع المحيط بالتساوي، وفي هذه الحالة سيتم تجاهل مربّعات الحدود على طول أكبر حواف x/y). يجب أن تكون الأبعاد أكبر من 0.	‫Array<int>[2].
kernelSize	في حال تحديد هذا الخيار، سيتم تخزين المربّعات مؤقتًا حسب أبعاد الهامش بشكل إيجابي وسلبي، ما يؤدي إلى تداخل بين الأجزاء المجاورة. في حال تحديدها، يجب توفير بُعدَين (X وY على التوالي).	‫Array<int>[2]. القيمة التلقائية: [1, 1]
compressed	في حال ضبطها على "صحيح"، يتم ضغط ملفات ‎ .tfrecord باستخدام gzip وإضافة اللاحقة "‎.gz"	منطقي. الإعداد التلقائي: true
maxFileSize	الحد الأقصى للحجم بالبايت لملف ‎.tfrecord تم تصديره (قبل الضغط) سيؤدي حجم الملف الأصغر إلى تقسيم أكبر (وبالتالي، المزيد من ملفات الإخراج).	عدد صحيح، القيمة التلقائية: 1 غيبي بايت
defaultValue	القيمة المحدّدة في كل نطاق من بكسل تم حجبه جزئيًا أو كليًا، والقيمة المحدّدة في كل قيمة في عنصر ثلاثي الأبعاد ناتج عن نطاق مصفوفة حيث كان طول المصفوفة في بكسل المصدر أقل من عمق قيمة العنصر (أي القيمة في الفهرس 3 لبكسل مصفوفة بطول 2 في نطاق مصفوفة بعمق عنصر مقابل يبلغ 3). يتم تجاهل الجزء الكسري للنطاقات من نوع العدد الصحيح، ويتم تثبيته على نطاق نوع النطاق. القيمة التلقائية هي 0.	عدد صحيح، القيمة التلقائية: 0
tensorDepths	تمثّل هذه السمة عملية الربط بين أسماء نطاقات مصفوفات الإدخال وعمق الموتّرات الثلاثية الأبعاد التي تنشئها. سيتم اقتطاع المصفوفات أو ملؤها بالقيم التلقائية لتناسب الشكل المحدّد. يجب أن يكون لكل نطاق مصفوفة إدخال مقابل.	‫Array<int>[]. القيمة التلقائية: []
sequenceData	إذا كانت القيمة "صحيح"، يتم إخراج كل بكسل على شكل SequenceExample يربط النطاقات العددية بالسياق ونطاقات الصفائف بتسلسلات المثال. يتم إخراج SequenceExamples بترتيب الصف الرئيسي لوحدات البكسل في كل رقعة، ثم بترتيب الصف الرئيسي لرقع المساحة في تسلسل الملفات.	منطقي. القيمة التلقائية: false
collapseBands	إذا كانت القيمة "صحيح"، سيتم دمج جميع النطاقات في موتر ثلاثي الأبعاد واحد، مع استخدام اسم النطاق الأول في الصورة. تتم ترقية جميع النطاقات إلى وحدات بايت، ثم إلى int64، ثم إلى أعداد عشرية بهذا الترتيب حسب النوع الأبعد في هذا التسلسل ضمن جميع النطاقات. يُسمح باستخدام مصفوفة نطاقات طالما تم تحديد tensor_depths.	منطقي. القيمة التلقائية: false
maskedThreshold	الحد الأقصى المسموح به لنسبة وحدات البكسل المحجوبة في جزء من الصورة. سيتم تجاهل التصحيحات التي تتجاوز هذا الحدّ بدلاً من كتابتها في الملفات. إذا تم ضبط هذا الحقل على أي قيمة غير 1، لن يتم إنشاء ملف JSON الجانبي. يكون الإعداد التلقائي بالقيمة 1.	عدد عائم القيمة التلقائية: 1

ملف TFRecord "mixer"

عند التصدير إلى TFRecord، سينشئ محرّك Earth Engine ملفًا مصاحبًا لملفات TFRecord يُعرف باسم "الخلاط". وهو ملف JSON بسيط يُستخدم لتحديد الترتيب المكاني للرقع (أي الإسناد الجغرافي). هذا الملف مطلوب لتحميل التوقّعات التي تم إجراؤها على الصور كما هو موضّح في القسم التالي.

تصدير السلسلة الزمنية

يمكن تصدير الصور إلى كل من Examples وSequenceExamples. عند التصدير إلى Examples، يتم تقسيم منطقة التصدير إلى أجزاء ويتم تصدير هذه الأجزاء بترتيب الصفوف الرئيسية إلى عدد من ملفات ‎ .tfrecord مع كل نطاق ميزته الخاصة (ما لم تحدّد collapseBands). عند التصدير إلى SequenceExamples، سيتم تصدير SequenceExample لكل بكسل، مع SequenceExamples بترتيب الصفوف الرئيسية داخل جزء، ثم بترتيب الصفوف الرئيسية للأجزاء في منطقة التصدير الأصلية (إذا لم تكن متأكدًا، افترض دائمًا أنّ العناصر ستكون بترتيب الصفوف الرئيسية بطريقة ما). ملاحظة: سيتم تجميع أي نطاقات عددية للصورة في سياق SequenceExample، بينما ستصبح نطاقات الصفائف هي بيانات التسلسل الفعلية.

أساور Array

يمكن تصدير نطاقات الصفائف عند تصدير صورة إلى تنسيق TFRecord. يتيح تصدير نطاقات الصفائف ملء FeatureLists في SequenceExamples وإنشاء موترات ثلاثية الأبعاد عند التصدير إلى Examples العادية. للحصول على معلومات حول كيفية إدارة أطوال/أعماق نطاقات الصفائف، يُرجى الاطّلاع على collapseBands و/أو tensorDepths في الجدول أعلاه. ملاحظة: سيؤدي استخدام collapseBands والتصدير إلى SequenceExamples (أي ضبط المَعلمة sequenceData) إلى تصغير جميع النطاقات إلى سلسلة زمنية واحدة لكل بكسل.

تحميل ملفات TFRecord إلى Earth Engine

يمكنك تحميل الجداول (سطر الأوامر فقط) والصور إلى Earth Engine كملفات TFRecord. بالنسبة إلى الجداول، تنطبق العلاقة بين جدول وآخر الموضّحة سابقًا في الاتجاه المعاكس (أي tf.train.Example -> ee.Feature).

جارٍ تحميل الصور

إذا كنت تنشئ توقّعات على الصور التي تم تصديرها، عليك توفير أداة المزج عند تحميل التوقّعات (كملفات TFRecord) للحصول على صور ذات مرجعية جغرافية. يُرجى العِلم أنّه سيتم تجاهل الجزء المتداخل من الرقع (بُعد المساحة المتروكة في الشكل 1) للحصول على تغطية متجاورة للمنطقة التي تم تصديرها. يجب ترتيب التوقّعات على شكل تسلسل tf.train.Example بالعدد والترتيب نفسهما لأمثلة الصور التي تم تصديرها في الأصل (حتى بين عدد عشوائي من الملفات).