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، تناظر ۱:۱ بین هر
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] برای یک تکه
۱۶×۱۶ پیکسلی.
درحال صادر کردن تصاویر
وقتی تصویری را صادر می‌کنید، داده‌ها به‌صورت کانال، ارتفاع، عرض (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 قرار دارد، حاوی داده‌های کاملاً معتبر است. آرایش فضایی تکه‌ها در فضا در شکل ۱ نشان داده شده است، که در آن «بُعد حاشیه‌گذاری» با بخشی از هسته که با تصویر مجاور هم‌پوشانی دارد مطابقت دارد:
kernelSize/2 است.
formatOptions
پارامترهای patchSize، maxFileSize، و kernelSize
ازطریق فرهنگ لغت formatOptions به تماس ee.Export (جاوا اسکریپت) یا ee.batch.Export
(Python) منتقل می‌شوند، که در آن کلیدها نام
پارامترهای اضافی منتقل‌شده به Export هستند. formatOptions ممکن
برای تصویری که به قالب TFRecord صادر شده است عبارتند از:
| دارایی | شرح | نوع |
|---|---|---|
patchDimensions |
ابعاد کاشی‌شده روی ناحیه صادرشده، که هر پیکسل را در کادر محدودکننده دقیقاً یک‌بار پوشش می‌دهد (مگر زمانی که ابعاد وصله کادر محدودکننده را به‌طور مساوی تقسیم نکند، که در این صورت کاشی‌های مرزی در امتداد بزرگ‌ترین لبه‌های x/y حذف خواهند شد). ابعاد باید > ۰ باشد. | Array<int>[2]. |
kernelSize |
اگر مشخص شود، کاشی‌ها با ابعاد حاشیه هم به‌صورت مثبت و هم منفی بافر می‌شوند، که منجر به هم‌پوشانی بین وصله‌های همسایه می‌شود. اگر مشخص شده باشد، باید دو بُعد ارائه شود (به‌ترتیب X و Y). | Array<int>[2]. پیش‌فرض: [1, 1] |
compressed |
اگر درست باشد، فایل‌های tfrecord .را با gzip فشرده می‌کند و پسوند «gz.» را اضافه می‌کند | بولی. پیش‌فرض: true |
maxFileSize |
حداکثر اندازه، به بایت، برای tfrecord .صادرشده (قبل‌از فشرده‌سازی). اندازه فایل کوچک‌تر منجر به قطعه‌بندی بیشتر (و درنتیجه فایل‌های خروجی بیشتر) می‌شود. | داخلی. پیش‌فرض: ۱ گیبی‌بایت |
defaultValue |
مقدار تنظیم‌شده در هر باند پیکسلی که به‌طور جزئی یا کامل ماسک شده است، و مقدار تنظیم‌شده در هر مقدار در یک ویژگی سه‌بعدی خروجی ساخته‌شده از یک باند آرایه که در آن طول آرایه در پیکسل منبع کمتر از عمق مقدار ویژگی بود (یعنی مقدار در نمایه ۳ یک پیکسل آرایه با طول ۲ در یک باند آرایه با عمق ویژگی متناظر ۳). بخش کسری برای باندهای نوع عدد صحیح حذف می‌شود و به محدوده نوع باند محدود می‌شود. پیش‌فرض ۰ است. | عدد صحیح. پیش‌فرض: ۰ |
tensorDepths |
نگاشت از نام‌های باند آرایه ورودی به عمق تانسورهای سه‌بعدی که ایجاد می‌کنند. آرایه‌ها کوتاه می‌شوند یا با مقادیر پیش‌فرض تکمیل می‌شوند تا با شکل مشخص‌شده مطابقت داشته باشند. برای هر باند آرایه، این باید ورودی متناظری داشته باشد. | Array<int>[]. Default: [] |
sequenceData |
اگر درست باشد، هر پیکسل به‌عنوان SequenceExample که باندهای اسکالر را به بافت و باندهای آرایه را به توالی‌های مثال نگاشت می‌کند، برونداد می‌شود. SequenceExamples به‌صورت خروجی در ترتیب ردیف-اصلی پیکسل‌ها در هر وصله، و سپس براساس ترتیب ردیف-اصلی وصله‌های ناحیه در توالی فایل ارائه می‌شود. | بولی. پیش‌فرض: نادرست |
collapseBands |
اگر درست باشد، همه باندها در یک تانسور سه‌بعدی واحد ترکیب می‌شوند و نام اولین باند در تصویر را می‌گیرند. همه باندها به‌ترتیب به بایت، int64، و سپس اعشاری ارتقا می‌یابند، بسته به نوعی که در آن توالی در همه باندها دورترین است. تا زمانی که tensor_depths مشخص شده باشد، باندهای آرایه مجاز هستند. | بولی. پیش‌فرض: نادرست |
maskedThreshold |
حداکثر نسبت مجاز پیکسل‌های ماسک‌شده در یک وصله. وصله‌هایی که از این حد مجاز فراتر بروند به‌جای نوشته شدن در فایل‌ها، حذف خواهند شد. اگر این فیلد روی هر چیزی به‌جز ۱ تنظیم شود، فایل جانبی JSON تولید نخواهد شد. پیش‌فرض ۱ است. | شناور. پیش‌فرض: ۱ |
فایل «میکسر» TFRecord
وقتی به TFRecord صادر می‌کنید، Earth Engine یک فایل جانبی با فایل‌های TFRecord شما به نام «میکسر» تولید می‌کند. این یک فایل JSON ساده است که برای تعریف ترتیب فضایی وصله‌ها (یعنی ارجاع جغرافیایی) استفاده می‌شود. این فایل برای بارگذاری پیش‌بینی‌های انجام‌شده روی تصاویر لازم است، همان‌طور که در بخش بعدی توضیح داده شده است.
درحال صادر کردن سری زمانی
صادر کردن تصویر به Examples و SequenceExamples پشتیبانی می‌شود. When you export to
Examples, the export region is cut into patches and those patches are exported in
row-major order to some number of .tfrecord files with each band its own feature
(unless you specify collapseBands). When you export to SequenceExamples,
a SequenceExample per-pixel will be exported, with those SequenceExamples in row-major
order within a patch, and then in row-major order of patches in the original export region
(if you’re ever unsure, always assume things will be in row-major order in some capacity).
توجه: هر باند اسکالر تصویر در بافت SequenceExample بسته‌بندی می‌شود،
درحالی‌که باندهای آرایه به داده‌های توالی واقعی تبدیل می‌شوند.
بندهای آرایه‌ای
وقتی تصویری به قالب TFRecord صادر می‌شود، باندهای آرایه قابل‌صادر کردن هستند. صادر کردن
باندهای آرایه ابزاری برای پر کردن «FeatureLists» از SequenceExamples و
روشی برای ایجاد تانسورهای سه‌بعدی هنگام صادر کردن به Examples معمولی فراهم می‌کند. برای کسب اطلاعات درباره نحوه مدیریت طول/عمق باندهای آرایه، به collapseBands و/یا tensorDepths در جدول بالا مراجعه کنید. توجه: استفاده از collapseBands
و صادر کردن به SequenceExamples (بنابراین تنظیم پارامتر sequenceData)
منجر به فروپاشی همه باندها به یک سری زمانی تک‌پیکسلی می‌شود.
درحال بارگذاری TFRecords در Earth Engine
می‌توانید جدول‌ها (فقط خط فرمان) و تصاویر را به‌عنوان فایل‌های TFRecord در Earth Engine بارگذاری کنید. برای جدول‌ها، رابطه ۱:۱
که قبلاً شرح داده شد در جهت معکوس
اعمال می‌شود (یعنی tf.train.Example -> ee.Feature).
درحال بارگذاری تصاویر
اگر پیش‌بینی‌ها را روی تصاویر صادرشده تولید می‌کنید، هنگام بارگذاری پیش‌بینی‌ها (به‌عنوان فایل‌های TFRecord) میکسر را ارائه دهید تا تصاویر زمین‌مرجع‌شده را به‌دست آورید. توجه داشته باشید که بخش هم‌پوشان وصله‌ها (بُعد حاشیه در شکل ۱) دور انداخته می‌شود تا پوشش هم‌مرز منطقه صادرشده حاصل شود. پیش‌بینی‌ها باید به‌صورت دنباله‌ای از tf.train.Example با همان تعداد و ترتیب نمونه‌های تصویر صادرشده اصلی شما (حتی بین تعداد دلخواهی از فایل‌ها) مرتب شوند.