TFRecord هو تنسيق ثنائي لترميز التسلسلات الطويلة من tf.Example protos بكفاءة. يتم تحميل ملفات 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، يكون هناك تطابق بنسبة 1:1 بين كل 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 الترتيب المكاني للأجزاء في المساحة، حيث يتوافق بُعد المساحة المتروكة مع جزء النواة الذي يتداخل مع الصورة المجاورة:
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 بالعدد والترتيب نفسهما لأمثلة الصور التي تم تصديرها في الأصل (حتى بين عدد عشوائي من الملفات).