TFRecord وEarth Engine

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

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

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

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

عند تصدير ee.FeatureCollection إلى ملف TFRecord، يكون هناك تطابق بنسبة 1:1 بين كل ee.Feature في الجدول وكل tf.train.Example (أي كل سجلّ) في ملف TFRecord. يتم ترميز كل سمة من سمات ee.Feature على أنّها tf.train.Feature مع قائمة بالأعداد العشرية التي تتوافق مع الرقم أو ee.Array المخزّن في سمة. في حال تصدير جدول يحتوي على صفائف في السمات، عليك إخبار TensorFlow بشكل الصفيف عند قراءته. سيتم دائمًا استخدام نوع الضغط GZIP في ضغط الجدول الذي يتم تصديره إلى ملف TFRecord. ستحصل دائمًا على ملف 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	في حال القيمة "true"، يتم ضغط ملفات ‎.tfrecord باستخدام gzip وإلحاق اللاحقة "‎.gz".	منطقي. الإعداد التلقائي: true
maxFileSize	الحد الأقصى للحجم، بالبايت، لملف tfrecord. الذي تم تصديره (قبل الضغط) سيؤدي حجم الملف الأصغر إلى زيادة تقسيم البيانات (وبالتالي زيادة عدد ملفات الإخراج).	الإعداد التلقائي: 1 غيغابايت
defaultValue	القيمة التي تم ضبطها في كل نطاق من وحدات البكسل التي تم حجبها جزئيًا أو كليًا، و القيمة التي تم ضبطها في كل قيمة في سمة ثلاثية الأبعاد في الناتج تم إنشاؤها من نطاق صفيف حيث كان طول الصفيف في وحدات البكسل المصدر أقل من عمق قيمة السمة (أي القيمة في الفهرس 3 لوحدة بكسل صفيف بطول 2 في نطاق صفيف مع عمق سمة مقابل يبلغ 3). يتم حذف الجزء الكسري لنطاقات نوع الأعداد الصحيحة، ويتم تقييدها بنطاق نوع النطاق. القيمة التلقائية هي 0.	عدد صحيح. القيمة التلقائية: 0
tensorDepths	الربط من أسماء نطاقات صفيف الإدخال إلى عمق مصفوفات الخلاصات الثلاثية الأبعاد التي يتم إنشاؤها سيتم اقتطاع المصفوفات أو إضافة قيم تلقائية إليها لتلائم الشكل المحدّد. يجب أن يكون لكل نطاق مصفوفة إدخال مناظر.	صفيف<int>[]. الإعداد التلقائي: []
sequenceData	إذا كانت القيمة "صحيحة"، يتم إخراج كل بكسل كمثال تسلسل يربط بين النطاقات المقاسة بالسلّسل و السياق ونطاقات الصفيف والتسلسلات في المثال. يتم عرض SequenceExamples بترتيب تنازلي للبكسل في كلّ رقعة، ثمّ بترتيب تنازلي للرقعة في تسلسل الملف.	منطقي. القيمة التلقائية: false
collapseBands	إذا كانت القيمة "صحيح"، سيتم دمج جميع النطاقات في مصفوفة ثلاثية الأبعاد واحدة، وستأخذ اسم النطاق الأول في الصورة. يتم ترقية جميع النطاقات إلى وحدات بايت وint64 ثم إلى أعداد كسرية في هذا الترتيب استنادًا إلى النوع الأبعد في هذا التسلسل ضمن جميع النطاقات. يُسمح بمجموعات الصفوف طالما تم تحديد tensor_depths.	منطقي. القيمة التلقائية: false
maskedThreshold	الحد الأقصى المسموح به لنسبة البكسلات التي تم حجبها في رقعة. سيتم تجاهل الرقع التي تتجاوز هذا الحدّ المسموح به بدلاً من كتابتها في الملفات. إذا تم ضبط هذا الحقل على أي قيمة غير 1، لن يتم إنشاء ملف JSON الجانبي. القيمة التلقائية هي 1.	انتظر. الإعداد التلقائي: 1

ملف "المزجّ" في TFRecord

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

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

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

مجموعات القنوات

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

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

يمكنك تحميل الجداول (سطر الأوامر فقط) والصور إلى Earth Engine كملفات TFRecord. بالنسبة إلى الجداول، تنطبق العلاقة بنسبة 1:1 الموضّحة سابقًا في الاتجاه противоположн (أي tf.train.Example -> ee.Feature).

تحميل الصور

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