روال‌های مطلوب کدنویسی

این سند شیوه‌های کدنویسی را شرح می‌دهد که هدفشان به‌حداکثر رساندن احتمال موفقیت برای محاسبات پیچیده یا پرهزینه Earth Engine است. روش‌های شرح‌داده‌شده در اینجا هم برای محاسبات تعاملی (مثلاً Code Editor) و هم برای محاسبات دسته‌ای (Export) قابل‌استفاده هستند، هرچند محاسباتی که معمولاً طولانی‌مدت هستند باید در سیستم دسته‌ای اجرا شوند.

از ترکیب کردن توابع و اشیاء کارخواه با توابع و اشیاء سرور خودداری کنید

اشیاء سرور Earth Engine اشیایی با سازنده‌هایی هستند که با ee شروع می‌شوند (برای مثال ee.Image، ee.Reducer) و هر روشی در این اشیاء، تابع سرور است. هر شیئی که به این روش ساخته نشده باشد، شیء کارخواه است. اشیاء کارخواه ممکن است از «ویرایشگر کد» (مثلاً Map، Chart) یا زبان JavaScript (مثلاً Date، Math، []، {}) بیایند.

برای جلوگیری از رفتار ناخواسته، توابع کارخواه و سرور را در دستوراتتان ترکیب نکنید، همان‌طور که در اینجا و اینجا و اینجا توضیح داده شده است. برای توضیح دقیق درباره کارخواه درمقابل سرور در Earth Engine، به این صفحه و/یا این آموزش مراجعه کنید. مثال زیر خطرات ترکیب عملکرد کارخواه و سرور را نشان می‌دهد:

خطا — این کد کار نمی‌کند!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');

// Won't work.
for(var i=0; i<table.size(); i++) {
  print('No!');
}

می‌توانید خطا را تشخیص دهید؟ توجه داشته باشید که table.size() یک روش سرور در شیء سرور است و نمی‌تواند با عملکرد سمت کارخواه مانند شرطی < استفاده شود.

موقعیتی که ممکن است بخواهید از حلقه‌های for استفاده کنید، در راه‌اندازی میانای کاربر است، زیرا اشیاء و روش‌های «ویرایشگر کد» ui سمت کارخواه هستند. (درباره ایجاد میانای کاربر در Earth Engine بیشتر بدانید). برای مثال:

از توابع کارخواه برای راه‌اندازی میانای کاربر استفاده کنید.

var panel = ui.Panel();
for(var i=1; i<8; i++) {
  panel.widgets().set(i, ui.Button('button ' + i))
}
print(panel);

برعکس، map() یک تابع سرور است و عملکرد کارخواه در داخل تابعی که به map() منتقل شده است کار نخواهد کرد. برای مثال:

خطا — این کد کار نمی‌کند!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');

// Error:
var foobar = table.map(function(f) {
  print(f); // Can't use a client function here.
  // Can't Export, either.
});

برای انجام کاری روی هر عنصر در یک مجموعه، یک تابع را روی مجموعه map() کنید و یک ویژگی را set() کنید:

از map() و set() استفاده کنید!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');
print(table.first());

// Do something to every element of a collection.
var withMoreProperties = table.map(function(f) {
  // Set a property.
  return f.set('area_sq_meters', f.area())
});
print(withMoreProperties.first());

همچنین می‌توانید مجموعه را براساس ویژگی‌های محاسبه‌شده یا موجود filter() کنید و نتیجه را print() کنید. توجه داشته باشید که نمی‌توانید مجموعه‌ای با بیش‌از ۵۰۰۰ عنصر را چاپ کنید. اگر خطای «Collection query aborted after accumulating over 5000 elements» را دریافت کردید، قبل‌از چاپ کردن، مجموعه را filter() یا limit() کنید.

از تبدیل کردن غیرضروری به فهرست خودداری کنید

مجموعه‌ها در Earth Engine بااستفاده از بهینه‌سازی‌هایی پردازش می‌شوند که با تبدیل مجموعه به نوع List یا Array شکسته می‌شوند. مگر اینکه به دسترسی تصادفی به عناصر مجموعه نیاز داشته باشید (یعنی نیاز داشته باشید عنصر iام مجموعه را دریافت کنید)، از فیلترها در مجموعه برای دسترسی به عناصر مجموعه تکی استفاده کنید. مثال زیر تفاوت بین تبدیل نوع (توصیه نمی‌شود) و فیلتر کردن (توصیه می‌شود) را برای دسترسی به عنصری در مجموعه نشان می‌دهد:

بی‌دلیل به فهرست تبدیل نکنید!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');

// Do NOT do this!!
var list = table.toList(table.size());
print(list.get(13)); // User memory limit exceeded.

توجه داشته باشید که با تبدیل غیرضروری مجموعه به فهرست، به‌راحتی می‌توانید خطا ایجاد کنید. روش ایمن‌تر استفاده از filter() است:

از filter() استفاده کنید!

print(table.filter(ee.Filter.eq('country_na', 'Niger')).first());

توجه داشته باشید که باید در اولین فرصت ممکن در تجزیه‌وتحلیل خود از فیلترها استفاده کنید.

اجتناب از ee.Algorithms.If()

از ee.Algorithms.If() برای پیاده‌سازی منطق انشعاب استفاده نکنید، به‌ویژه در تابع نگاشت‌شده. همان‌طور که مثال زیر نشان می‌دهد، ee.Algorithms.If() می‌تواند حافظه زیادی مصرف کند و توصیه نمی‌شود:

از If() استفاده نکنید!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');

// Do NOT do this!
var veryBad = table.map(function(f) {
  return ee.Algorithms.If({
    condition: ee.String(f.get('country_na')).compareTo('Chad').gt(0),
    trueCase: f,      // Do something.
    falseCase: null   // Do something else.
  });
}, true);
print(veryBad); // User memory limit exceeded.

// If() may evaluate both the true and false cases.

توجه داشته باشید که شناسه دوم map()‏ true است. این یعنی تابع نگاشت‌شده ممکن است مقادیر تهی برگرداند و این مقادیر در مجموعه حاصل حذف خواهند شد. این کار می‌تواند مفید باشد (بدون If())، اما در اینجا ساده‌ترین راه‌حل استفاده از فیلتر است:

از filter() استفاده کنید!

print(table.filter(ee.Filter.eq('country_na', 'Chad')));

همان‌طور که در این آموزش نشان داده شده است، رویکرد برنامه‌نویسی تابعی بااستفاده از فیلترها روش صحیح اعمال یک منطق بر برخی عناصر مجموعه و منطق دیگر بر سایر عناصر مجموعه است.

اجتناب از reproject()

از بازطرح استفاده نکنید مگر اینکه کاملاً ضروری باشد. یکی از دلایلی که ممکن است بخواهید از reproject() استفاده کنید، اجبار محاسبات «ویرایشگر کد» به انجام در یک مقیاس خاص است تا بتوانید نتایج را در مقیاس تحلیل موردنظر خود بررسی کنید. در مثال بعدی، تکه‌های پیکسل‌های داغ محاسبه می‌شود و تعداد پیکسل‌ها در هر تکه محاسبه می‌شود. نمونه را اجرا کنید و روی یکی از وصله‌ها کلیک کنید. توجه داشته باشید که تعداد پیکسل‌ها بین داده‌های بازطرح‌ریزی‌شده و داده‌هایی که بازطرح‌ریزی نشده‌اند متفاوت است.

var l8sr = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');
var sf = ee.Geometry.Point([-122.405, 37.786]);
Map.centerObject(sf, 13);

// A reason to reproject - counting pixels and exploring interactively.
var image = l8sr.filterBounds(sf)
    .filterDate('2019-06-01', '2019-12-31')
    .first();

image = image.multiply(0.00341802).add(149);  // Apply scale factors.
Map.addLayer(image, {bands: ['ST_B10'], min: 280, max: 317}, 'image');

var hotspots = image.select('ST_B10').gt(317)
  .selfMask()
  .rename('hotspots');
var objectSize = hotspots.connectedPixelCount(256);

Map.addLayer(objectSize, {min: 1, max: 256}, 'Size No Reproject', false);

// Beware of reproject!  Don't zoom out on reprojected data.
var reprojected = objectSize.reproject(hotspots.projection());
Map.addLayer(reprojected, {min: 1, max: 256}, 'Size Reproject', false);

دلیل این اختلاف این است که مقیاس تحلیل توسط سطح بزرگ‌نمایی «ویرایشگر کد» تنظیم می‌شود. با فراخوانی reproject()، مقیاس محاسبات را به‌جای Code Editor تنظیم می‌کنید. به دلایلی که در این سند شرح داده شده است، از reproject() بااحتیاط استفاده کنید.

ابتدا فیلتر و select() کنید

به‌طور کلی، مجموعه‌های ورودی را براساس زمان، مکان، و/یا فراداده فیلتر کنید و سپس کارهای دیگر را روی مجموعه انجام دهید. فیلترهای انتخابی‌تر را قبل‌از فیلترهای کمتر انتخابی اعمال کنید. فیلترهای فضایی و/یا زمانی اغلب گزینشی‌تر هستند. برای مثال، توجه داشته باشید که select() و filter() پیش‌از map() اعمال می‌شوند:

var images = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED');
var sf = ee.Geometry.Point([-122.463, 37.768]);

// Expensive function to reduce the neighborhood of an image.
var reduceFunction = function(image) {
  return image.reduceNeighborhood({
    reducer: ee.Reducer.mean(),
    kernel: ee.Kernel.square(4)
  });
};

var bands = ['B4', 'B3', 'B2'];
// Select and filter first!
var reasonableComputation = images
    .select(bands)
    .filterBounds(sf)
    .filterDate('2018-01-01', '2019-02-01')
    .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', 1))
    .aside(print) // Useful for debugging.
    .map(reduceFunction)
    .reduce('mean')
    .rename(bands);
var viz = {bands: bands, min: 0, max: 10000};
Map.addLayer(reasonableComputation, viz, 'reasonableComputation');

استفاده از updateMask() به‌جای mask()

تفاوت بین updateMask() و mask() این است که اولی یک and() منطقی از متغیر مستقل (ماسک جدید) و ماسک تصویر موجود انجام می‌دهد درحالی‌که mask() به‌سادگی ماسک تصویر را با متغیر مستقل جایگزین می‌کند. خطر مورد دوم این است که ممکن است به‌طور ناخواسته پیکسل‌ها را آشکار کنید. در این مثال، هدف ماسک کردن پیکسل‌های کمتر یا مساوی با ارتفاع ۳۰۰ متر است. همان‌طور که می‌بینید (زوم‌پَس کنید)، استفاده از mask() باعث می‌شود پیکسل‌های زیادی از حالت ماسک خارج شوند، پیکسل‌هایی که به تصویر موردنظر تعلق ندارند:

var l8sr = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');
var sf = ee.Geometry.Point([-122.40554461769182, 37.786807309873716]);
var aw3d30 = ee.Image('JAXA/ALOS/AW3D30_V1_1');

Map.centerObject(sf, 7);

var image = l8sr.filterBounds(sf)
    .filterDate('2019-06-01', '2019-12-31')
    .first();

image = image.multiply(0.0000275).subtract(0.2);  // Apply scale factors.
var vis = {bands: ['SR_B4', 'SR_B3', 'SR_B2'], min: 0, max: 0.3};
Map.addLayer(image, vis, 'image', false);

var mask = aw3d30.select('AVE').gt(300);
Map.addLayer(mask, {}, 'mask', false);

// NO!  Don't do this!
var badMask = image.mask(mask);
Map.addLayer(badMask, vis, 'badMask');

var goodMask = image.updateMask(mask);
Map.addLayer(goodMask, vis, 'goodMask', false);

ترکیب کردن کاهنده‌ها

اگر به چند آمار (مثلاً میانگین و انحراف معیار) از یک ورودی (مثلاً ناحیه تصویر) نیاز دارید، ترکیب کردن کاهنده‌ها کارآمدتر است. برای مثال، برای دریافت آمار تصویر، کاهنده‌ها را به‌صورت زیر ترکیب کنید:

var image = ee.Image(
  'COPERNICUS/S2_HARMONIZED/20150821T111616_20160314T094808_T30UWU');

// Get mean and SD in every band by combining reducers.
var stats = image.reduceRegion({
  reducer: ee.Reducer.mean().combine({
    reducer2: ee.Reducer.stdDev(),
    sharedInputs: true
  }),
  geometry: ee.Geometry.Rectangle([-2.15, 48.55, -1.83, 48.72]),
  scale: 10,
  bestEffort: true // Use maxPixels if you care about scale.
});

print(stats);

// Extract means and SDs to images.
var meansImage = stats.toImage().select('.*_mean');
var sdsImage = stats.toImage().select('.*_stdDev');

در این مثال، توجه داشته باشید که کاهنده میانگین با کاهنده انحراف معیار ترکیب شده است و sharedInputs درست است تا یک گذر واحد از پیکسل‌های ورودی فعال شود. در واژه‌نامه خروجی، نام کاهنده به نام باند اضافه می‌شود. برای دریافت تصاویر میانگین و انحراف معیار (مثلاً برای نرمال‌سازی تصویر ورودی)، می‌توانید مقادیر را به تصویر تبدیل کنید و از عبارت‌های باقاعده برای استخراج میانگین‌ها و انحراف‌های معیار به‌صورت جداگانه استفاده کنید، همان‌طور که در مثال نشان داده شده است.

استفاده از Export

برای محاسباتی که منجر به خطاهای «از حد مجاز حافظه کاربر فراتر رفته است» یا «زمان محاسبه تمام شده است» در «ویرایشگر کد» می‌شوند، ممکن است بتوان بااستفاده از Export همان محاسبات را با موفقیت انجام داد. دلیل آن این است که زمان‌های اتمام طولانی‌تر است و ردپای حافظه مجاز هنگام اجرا در سیستم دسته‌ای (جایی که صادر کردن‌ها اجرا می‌شود) بزرگ‌تر است. (رویکردهای دیگری وجود دارد که ممکن است بخواهید ابتدا آن‌ها را امتحان کنید، همان‌طور که در سند اشکال‌زدایی به‌تفصیل شرح داده شده است). در ادامه مثال قبلی، فرض کنید که واژه‌نامه خطایی برگردانده است. می‌توانید با انجام کاری مثل این، نتایج را به‌دست آورید:

var link = '86836482971a35a5e735a17e93c23272';
Export.table.toDrive({
  collection: ee.FeatureCollection([ee.Feature(null, stats)]),
  description: 'exported_stats_demo_' + link,
  fileFormat: 'CSV'
});

توجه داشته باشید که پیوند در نام دارایی جاسازی شده است تا قابل‌بازتولید باشد. همچنین توجه داشته باشید که اگر می‌خواهید toAsset را صادر کنید، باید یک هندسه ارائه دهید، که می‌تواند هر چیزی باشد، برای مثال مرکز تصویر، که کوچک و ارزان برای محاسبه است. (یعنی اگر به هندسه پیچیده نیاز ندارید، از آن استفاده نکنید).

برای نمونه‌های استفاده از Export جهت رفع خطاهای Computation timed out و Too many concurrent aggregations، به صفحه اشکال‌زدایی مراجعه کنید. برای جزئیات بیشتر درباره صادر کردن به‌طور کلی، این سند را ببینید.

اگر نیازی به کلیپ کردن ندارید، از clip() استفاده نکنید

استفاده غیرضروری از clip() زمان محاسبه را افزایش خواهد داد. از clip() اجتناب کنید، مگراینکه برای تحلیل شما ضروری باشد. اگر مطمئن نیستید، کلیپ نسازید. نمونه‌ای از استفاده نادرست از کلیپ:

ورودی‌ها را بی‌دلیل برش ندهید!

var table = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017');
var l8sr = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');

var belgium = table.filter(ee.Filter.eq('country_na', 'Belgium')).first();

// Do NOT clip unless you need to.
var unnecessaryClip = l8sr
    .select('SR_B4')                          // Good.
    .filterBounds(belgium.geometry())         // Good.
    .filterDate('2019-01-01', '2019-04-01')   // Good.
    .map(function(image) {
      return image.clip(belgium.geometry());  // NO! Bad! Not necessary.
    })
    .median()
    .reduceRegion({
      reducer: ee.Reducer.mean(),
      geometry: belgium.geometry(),
      scale: 30,
      maxPixels: 1e10,
    });
print(unnecessaryClip);

می‌توان از برش دادن تصاویر ورودی به‌طور کامل صرف‌نظر کرد، زیرا منطقه در فراخوانی reduceRegion() مشخص شده است:

منطقه را برای خروجی مشخص کنید!

var noClipNeeded = l8sr
    .select('SR_B4')                           // Good.
    .filterBounds(belgium.geometry())          // Good.
    .filterDate('2019-01-01', '2019-12-31') // Good.
    .median()
    .reduceRegion({
      reducer: ee.Reducer.mean(),
      geometry: belgium.geometry(), // Geometry is specified here.
      scale: 30,
      maxPixels: 1e10,
    });
print(noClipNeeded);

اگر این محاسبه به‌موقع انجام نشد، آن را مانند این مثال Export کنید.

اگر لازم است با مجموعه پیچیده‌ای برش دهید، از clipToCollection() استفاده کنید

اگر واقعاً نیاز به برش چیزی دارید و هندسه‌هایی که می‌خواهید برای برش استفاده کنید در یک مجموعه هستند، از clipToCollection() استفاده کنید:

var ecoregions = ee.FeatureCollection('RESOLVE/ECOREGIONS/2017');
var image = ee.Image('JAXA/ALOS/AW3D30_V1_1');

var complexCollection = ecoregions
    .filter(ee.Filter.eq('BIOME_NAME',
                         'Tropical & Subtropical Moist Broadleaf Forests'));
Map.addLayer(complexCollection, {}, 'complexCollection');

var clippedTheRightWay = image.select('AVE')
    .clipToCollection(complexCollection);
Map.addLayer(clippedTheRightWay, {}, 'clippedTheRightWay', false);

از featureCollection.geometry() یا featureCollection.union() در مجموعه‌های بزرگ و/یا پیچیده که ممکن است به حافظه بیشتری نیاز داشته باشند استفاده نکنید.

از مجموعه پیچیده به‌عنوان منطقه برای کاهنده استفاده نکنید

اگر لازم است کاهش فضایی انجام دهید به‌طوری‌که کاهنده ورودی‌ها را از چند منطقه در FeatureCollection جمع‌آوری کند، featureCollection.geometry() را به‌عنوان ورودی geometry به کاهنده ارائه نکنید. درعوض، از clipToCollection() و منطقه‌ای استفاده کنید که به‌اندازه کافی بزرگ باشد تا مرزهای مجموعه را دربرگیرد. برای مثال:

var ecoregions = ee.FeatureCollection('RESOLVE/ECOREGIONS/2017');
var image = ee.Image('JAXA/ALOS/AW3D30_V1_1');

var complexCollection = ecoregions
    .filter(ee.Filter.eq('BIOME_NAME', 'Tropical & Subtropical Moist Broadleaf Forests'));

var clippedTheRightWay = image.select('AVE')
    .clipToCollection(complexCollection);
Map.addLayer(clippedTheRightWay, {}, 'clippedTheRightWay');

var reduction = clippedTheRightWay.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: ee.Geometry.Rectangle({
    coords: [-179.9, -50, 179.9, 50],  // Almost global.
    geodesic: false
  }),
  scale: 30,
  maxPixels: 1e12
});
print(reduction); // If this times out, export it.

از errorMargin غیرصفر استفاده کنید

برای عملیات هندسی احتمالاً پرهزینه، با توجه به دقت موردنیاز محاسبات، از بزرگ‌ترین حاشیه خطای ممکن استفاده کنید. حاشیه خطا حداکثر خطای مجاز (به متر) را که درطول عملیات روی هندسه‌ها (مثلاً درطول بازطرح) مجاز است مشخص می‌کند. مشخص کردن حاشیه خطای کوچک می‌تواند منجر به نیاز به متراکم کردن هندسه‌ها (با مختصات) شود که می‌تواند حافظه زیادی مصرف کند. بهتر است تا حد امکان حاشیه خطای بزرگی برای محاسباتتان مشخص کنید:

var ecoregions = ee.FeatureCollection('RESOLVE/ECOREGIONS/2017');

var complexCollection = ecoregions.limit(10);
Map.centerObject(complexCollection);
Map.addLayer(complexCollection);

var expensiveOps = complexCollection.map(function(f) {
  return f.buffer(10000, 200).bounds(200);
});
Map.addLayer(expensiveOps, {}, 'expensiveOps');

از مقیاس بسیار کوچک با reduceToVectors() استفاده نکنید

اگر می‌خواهید شطرنجی را به بردار تبدیل کنید، از مقیاس مناسب استفاده کنید. مشخص کردن مقیاس بسیار کوچک می‌تواند هزینه محاسبات را به‌طور قابل‌توجهی افزایش دهد. مقیاس را تا حد امکان بالا تنظیم کنید تا دقت لازم را ارائه دهد. برای مثال، برای دریافت چندضلعی‌هایی که توده‌های خشکی جهانی را نشان می‌دهند:

var etopo = ee.Image('NOAA/NGDC/ETOPO1');

// Approximate land boundary.
var bounds = etopo.select(0).gt(-100);

// Non-geodesic polygon.
var almostGlobal = ee.Geometry.Polygon({
  coords: [[-180, -80], [180, -80], [180, 80], [-180, 80], [-180, -80]],
  geodesic: false
});
Map.addLayer(almostGlobal, {}, 'almostGlobal');

var vectors = bounds.selfMask().reduceToVectors({
  reducer: ee.Reducer.countEvery(),
  geometry: almostGlobal,
  // Set the scale to the maximum possible given
  // the required precision of the computation.
  scale: 50000,
});
Map.addLayer(vectors, {}, 'vectors');

در مثال قبلی، به استفاده از چندضلعی غیرژئودزیک برای استفاده در کاهش‌های جهانی توجه کنید.

استفاده نکردن از reduceToVectors() با reduceRegions()

از FeatureCollection برگردانده‌شده توسط reduceToVectors() به‌عنوان ورودی reduceRegions() استفاده نکنید. درعوض، باندهایی را که می‌خواهید کاهش دهید قبل‌از فراخوانی reduceToVectors() اضافه کنید:

var etopo = ee.Image('NOAA/NGDC/ETOPO1');
var mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1');

// Approximate land boundary.
var bounds = etopo.select(0).gt(-100);

// Non-geodesic polygon.
var almostGlobal = ee.Geometry.Polygon({
  coords: [[-180, -80], [180, -80], [180, 80], [-180, 80], [-180, -80]],
  geodesic: false
});

var lst = mod11a1.first().select(0);

var means = bounds.selfMask().addBands(lst).reduceToVectors({
  reducer: ee.Reducer.mean(),
  geometry: almostGlobal,
  scale: 1000,
  maxPixels: 1e10
});
print(means.limit(10));

توجه داشته باشید که روش‌های دیگر کاهش پیکسل‌های یک تصویر در مناطق تصویر دیگر شامل reduceConnectedCommponents() و/یا کاهنده‌های گروه‌بندی است.

استفاده از fastDistanceTransform() برای عملیات همسایگی

برای برخی‌از عملیات پیچیدگی، fastDistanceTransform() ممکن است کارآمدتر از reduceNeighborhood() یا convolve() باشد. برای مثال، برای انجام فرسایش و/یا اتساع ورودی‌های دودویی:

var aw3d30 = ee.Image('JAXA/ALOS/AW3D30_V1_1');

// Make a simple binary layer from a threshold on elevation.
var mask = aw3d30.select('AVE').gt(300);
Map.setCenter(-122.0703, 37.3872, 11);
Map.addLayer(mask, {}, 'mask');

// Distance in pixel units.
var distance = mask.fastDistanceTransform().sqrt();
// Threshold on distance (three pixels) for a dilation.
var dilation = distance.lt(3);
Map.addLayer(dilation, {}, 'dilation');

// Do the reverse for an erosion.
var notDistance = mask.not().fastDistanceTransform().sqrt();
var erosion = notDistance.gt(3);
Map.addLayer(erosion, {}, 'erosion');

استفاده از بهینه‌سازی‌ها در reduceNeighborhood()

اگر لازم است پیچش انجام دهید و نمی‌توانید از fastDistanceTransform() استفاده کنید، از بهینه‌سازی‌های reduceNeighborhood() استفاده کنید.

var l8raw = ee.ImageCollection('LANDSAT/LC08/C02/T1_RT');
var composite = ee.Algorithms.Landsat.simpleComposite(l8raw);

var bands = ['B4', 'B3', 'B2'];

var optimizedConvolution = composite.select(bands).reduceNeighborhood({
  reducer: ee.Reducer.mean(),
  kernel: ee.Kernel.square(3),
  optimization: 'boxcar' // Suitable optimization for mean.
}).rename(bands);

var viz = {bands: bands, min: 0, max: 72};
Map.setCenter(-122.0703, 37.3872, 11);
Map.addLayer(composite, viz, 'composite');
Map.addLayer(optimizedConvolution, viz, 'optimizedConvolution');

بیش‌از نیازتان داده نمونه‌برداری نکنید

دربرابر وسوسه افزایش غیرضروری اندازه مجموعه داده‌های آموزشی مقاومت کنید. اگرچه افزایش مقدار داده‌های آموزشی یک استراتژی مؤثر یادگیری ماشین در برخی شرایط است، اما می‌تواند هزینه محاسباتی را نیز بدون افزایش متناظر در دقت افزایش دهد. (برای درک اینکه چه زمانی باید اندازه مجموعه داده آموزشی را افزایش دهید، به این مرجع مراجعه کنید). مثال زیر نشان می‌دهد که چگونه درخواست داده‌های آموزشی بیش‌ازحد می‌تواند منجر به خطای ترسناک «مقدار محاسبه‌شده بسیار بزرگ است» شود:

از داده‌های زیادی نمونه‌برداری نکنید!

var l8raw = ee.ImageCollection('LANDSAT/LC08/C02/T1_RT');
var composite = ee.Algorithms.Landsat.simpleComposite(l8raw);
var labels = ee.FeatureCollection('projects/google/demo_landcover_labels');

// No!  Not necessary.  Don't do this:
labels = labels.map(function(f) { return f.buffer(100000, 1000); });

var bands = ['B2', 'B3', 'B4', 'B5', 'B6', 'B7'];

var training = composite.select(bands).sampleRegions({
  collection: labels,
  properties: ['landcover'],
  scale: 30
});

var classifier = ee.Classifier.smileCart().train({
  features: training,
  classProperty: 'landcover',
  inputProperties: bands
});
print(classifier.explain()); // Computed value is too large

رویکرد بهتر این است که با مقدار متوسطی از داده‌ها شروع کنید و فراپارامترهای طبقه‌بندی‌کننده را تنظیم کنید تا ببینید آیا می‌توانید به دقت موردنظرتان برسید یا نه:

ابرپارامترها را تنظیم کنید!

var l8raw = ee.ImageCollection('LANDSAT/LC08/C02/T1_RT');
var composite = ee.Algorithms.Landsat.simpleComposite(l8raw);
var labels = ee.FeatureCollection('projects/google/demo_landcover_labels');

// Increase the data a little bit, possibly introducing noise.
labels = labels.map(function(f) { return f.buffer(100, 10); });

var bands = ['B2', 'B3', 'B4', 'B5', 'B6', 'B7'];

var data = composite.select(bands).sampleRegions({
  collection: labels,
  properties: ['landcover'],
  scale: 30
});

// Add a column of uniform random numbers called 'random'.
data = data.randomColumn();

// Partition into training and testing.
var training = data.filter(ee.Filter.lt('random', 0.5));
var testing = data.filter(ee.Filter.gte('random', 0.5));

// Tune the minLeafPopulation parameter.
var minLeafPops = ee.List.sequence(1, 10);

var accuracies = minLeafPops.map(function(p) {
  var classifier = ee.Classifier.smileCart({minLeafPopulation: p})
      .train({
        features: training,
        classProperty: 'landcover',
        inputProperties: bands
      });

  return testing
    .classify(classifier)
    .errorMatrix('landcover', 'classification')
    .accuracy();
});

print(ui.Chart.array.values({
  array: ee.Array(accuracies),
  axis: 0,
  xLabels: minLeafPops
}));

در این مثال، طبقه‌بندی‌کننده ازقبل بسیار دقیق است، بنابراین تنظیمات زیادی برای انجام دادن وجود ندارد. ممکن است بخواهید کوچک‌ترین درخت ممکن (یعنی بزرگ‌ترین minLeafPopulation) را انتخاب کنید که هنوز دقت لازم را دارد.

‫Export نتیجه متوسط

فرض کنید هدف شما نمونه‌برداری از یک تصویر محاسباتی نسبتاً پیچیده است. اغلب کارآمدتر است که تصویر را Export کنید toAsset()، تصویر صادرشده را بار کنید، سپس نمونه‌برداری کنید. برای مثال:

var image = ee.Image('UMD/hansen/global_forest_change_2025_v1_13');
var geometry = ee.Geometry.Polygon(
    [[[-76.64069800085349, 5.511777325802095],
      [-76.64069800085349, -20.483938229362376],
      [-35.15632300085349, -20.483938229362376],
      [-35.15632300085349, 5.511777325802095]]], null, false);
var testRegion = ee.Geometry.Polygon(
    [[[-48.86726050085349, -3.0475996402515717],
      [-48.86726050085349, -3.9248707849303295],
      [-47.46101050085349, -3.9248707849303295],
      [-47.46101050085349, -3.0475996402515717]]], null, false);

// Forest loss in 2016, to stratify a sample.
var loss = image.select('lossyear');
var loss16 = loss.eq(16).rename('loss16');

// Scales and masks Landsat 8 surface reflectance images.
function prepSrL8(image) {
  var qaMask = image.select('QA_PIXEL').bitwiseAnd(parseInt('11111', 2)).eq(0);
  var opticalBands = image.select('SR_B.').multiply(0.0000275).add(-0.2);
  var thermalBands = image.select('ST_B.*').multiply(0.00341802).add(149.0);
  return image.addBands(opticalBands, null, true)
      .addBands(thermalBands, null, true)
      .updateMask(qaMask);
}

var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2')
    .map(prepSrL8);

// Create two annual cloud-free composites.
var composite1 = collection.filterDate('2015-01-01', '2015-12-31').median();
var composite2 = collection.filterDate('2017-01-01', '2017-12-31').median();

// We want a strtatified sample of this stack.
var stack = composite1.addBands(composite2)
    .float(); // Export the smallest size possible.

// Export the image.  This block is commented because the export is complete.
/*
var link = '0b8023b0af6c1b0ac7b5be649b54db06'
var desc = 'Logistic_regression_stack_' + link;
Export.image.toAsset({
  image: stack,
  description: desc,
  assetId: desc,
  region: geometry,
  scale: 30,
  maxPixels: 1e10
})
*/

// Load the exported image.
var exportedStack = ee.Image(
  'projects/google/Logistic_regression_stack_0b8023b0af6c1b0ac7b5be649b54db06');

// Take a very small sample first, to debug.
var testSample = exportedStack.addBands(loss16).stratifiedSample({
  numPoints: 1,
  classBand: 'loss16',
  region: testRegion,
  scale: 30,
  geometries: true
});
print(testSample); // Check this in the console.

// Take a large sample.
var sample = exportedStack.addBands(loss16).stratifiedSample({
  numPoints: 10000,
  classBand: 'loss16',
  region: geometry,
  scale: 30,
});

// Export the large sample...

در این مثال، توجه داشته باشید که تصاویر به‌عنوان float صادر می‌شوند. مگر در موارد کاملاً ضروری، با دقت مضاعف صادر نکنید. هنگام انجام این صادر کردن، توجه داشته باشید که پیوند «ویرایشگر کد» (که بلافاصله قبل‌از صادر کردن به‌دست آمده است) در نام فایل برای بازتولیدپذیری جاسازی شده است.

وقتی صادر کردن تکمیل شد، دارایی را مجدداً بار کنید و نمونه‌برداری از آن را ادامه دهید. توجه داشته باشید که ابتدا نمونه بسیار کوچکی در منطقه آزمایشی بسیار کوچکی برای اشکال‌زدایی اجرا می‌شود. وقتی این کار با موفقیت انجام شد، نمونه بزرگ‌تری بگیرید و آن را صادر کنید. چنین نمونه‌های بزرگی معمولاً باید صادر شوند. انتظار نداشته باشید که این نمونه‌ها به‌صورت تعاملی (مثلاً ازطریق print()) دردسترس باشند یا بدون صادر کردن آن‌ها قابل‌استفاده باشند (مثلاً به‌عنوان ورودی برای طبقه‌بندی‌کننده).

پیوستن درمقابل فیلتر نقشه

فرض کنید می‌خواهید مجموعه‌ها را براساس زمان، مکان، یا برخی‌از ویژگی‌های فراداده به‌هم بپیوندید. به‌طور کلی، این کار با پیوستن به کارآمدترین شکل انجام می‌شود. مثال زیر یک اتصال فضایی-زمانی بین مجموعه‌های Landsat 8 و Sentinel-2 انجام می‌دهد:

var s2 = ee.ImageCollection('COPERNICUS/S2_HARMONIZED')
    .filterBounds(ee.Geometry.Point([-2.0205, 48.647]));

var l8 = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');

var joined = ee.Join.saveAll('landsat').apply({
  primary: s2,
  secondary: l8,
  condition: ee.Filter.and(
    ee.Filter.maxDifference({
      difference: 1000 * 60 * 60 * 24, // One day in milliseconds
      leftField: 'system:time_start',
      rightField: 'system:time_start',
    }),
    ee.Filter.intersects({
      leftField: '.geo',
      rightField: '.geo',
    })
  )
});
print(joined);

اگرچه ابتدا باید پیوستن را امتحان کنید (Export درصورت نیاز)، گاهی اوقات filter() در map() نیز می‌تواند مؤثر باشد، به‌ویژه برای مجموعه‌های بسیار بزرگ.

var s2 = ee.ImageCollection('COPERNICUS/S2_HARMONIZED')
    .filterBounds(ee.Geometry.Point([-2.0205, 48.647]));

var l8 = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');

var mappedFilter = s2.map(function(image) {
  var date = image.date();
  var landsat = l8
      .filterBounds(image.geometry())
      .filterDate(date.advance(-1, 'day'), date.advance(1, 'day'));
  // Return the input image with matching scenes in a property.
  return image.set({
    landsat: landsat,
    size: landsat.size()
  });
}).filter(ee.Filter.gt('size', 0));
print(mappedFilter);

‫reduceRegion() دربرابر reduceRegions() دربرابر حلقه for

فراخوانی reduceRegions() با FeatureCollection بسیار بزرگ یا پیچیده به‌عنوان ورودی ممکن است منجر به خطای ترسناک «مقدار محاسبه‌شده خیلی بزرگ است» شود. یک راه‌حل احتمالی این است که به‌جای آن، reduceRegion() را روی FeatureCollection نگاشت کنید. راه‌حل بالقوه دیگر استفاده از حلقه for است. اگرچه این کار در Earth Engine به‌شدت منع شده است، همان‌طور که در Map (what to do instead of a for-loop)، Functional programming concepts، و Loop شرح داده شده است، reduceRegion() را می‌توان در یک حلقه for برای انجام کاهش‌های بزرگ پیاده‌سازی کرد.

فرض کنید هدف شما به‌دست آوردن میانگین پیکسل‌ها (یا هر آماری) در هر عارضه در FeatureCollection برای هر تصویر در ImageCollection است. مثال زیر سه رویکردی را که قبلاً شرح داده شد مقایسه می‌کند:

// Table of countries.
var countriesTable = ee.FeatureCollection("USDOS/LSIB_SIMPLE/2017");
// Time series of images.
var mod13a1 = ee.ImageCollection("MODIS/061/MOD13A1");

// MODIS vegetation indices (always use the most recent version).
var band = 'NDVI';
var imagery = mod13a1.select(band);

// Option 1: reduceRegions()
var testTable = countriesTable.limit(1); // Do this outside map()s and loops.
var data = imagery.map(function(image) {
  return image.reduceRegions({
    collection: testTable,
    reducer: ee.Reducer.mean(),
    scale: 500
  }).map(function(f) {
    return f.set({
      time: image.date().millis(),
      date: image.date().format()
    });
  });
}).flatten();
print(data.first());

// Option 2: mapped reduceRegion()
var data = countriesTable.map(function(feature) {
  return imagery.map(function(image) {
    return ee.Feature(feature.geometry().centroid(100),
        image.reduceRegion({
          reducer: ee.Reducer.mean(),
          geometry: feature.geometry(),
          scale: 500
        })).set({
          time: image.date().millis(),
          date: image.date().format()
        }).copyProperties(feature);
  });
}).flatten();
print(data.first());

// Option 3: for-loop (WATCH OUT!)
var size = countriesTable.size();
// print(size); // 312
var countriesList = countriesTable.toList(1); // Adjust size.
var data = ee.FeatureCollection([]); // Empty table.
for (var j=0; j<1; j++) { // Adjust size.
  var feature = ee.Feature(countriesList.get(j));
  // Convert ImageCollection > FeatureCollection
  var fc = ee.FeatureCollection(imagery.map(function(image) {
    return ee.Feature(feature.geometry().centroid(100),
        image.reduceRegion({
          reducer: ee.Reducer.mean(),
          geometry: feature.geometry(),
          scale: 500
        })).set({
          time: image.date().millis(),
          date: image.date().format()
        }).copyProperties(feature);
  }));
  data = data.merge(fc);
}
print(data.first());

توجه داشته باشید که first() مورد از هر مجموعه برای اهداف اشکال‌زدایی چاپ می‌شود. نباید انتظار داشته باشید که نتیجه کامل به‌صورت تعاملی دردسترس باشد: باید Export. همچنین توجه داشته باشید که از حلقه‌های for باید با احتیاط بسیار و فقط به‌عنوان آخرین راه‌حل استفاده شود. درنهایت، حلقه for نیازمند دریافت دستی اندازه مجموعه ورودی و کدگذاری ثابت آن در مکان‌های مناسب است. اگر هرکدام از این موارد برایتان نامفهوم است، از حلقه for استفاده نکنید.

استفاده از تفاضل پیش‌رو برای همسایگان در زمان

فرض کنید ImageCollection مرتب‌شده زمانی (یعنی سری زمانی) دارید و می‌خواهید هر تصویر را با تصویر قبلی (یا بعدی) مقایسه کنید. به‌جای استفاده از iterate() برای این منظور، ممکن است استفاده از تفاضل پیش‌رونده مبتنی بر آرایه کارآمدتر باشد. مثال زیر از این روش برای حذف موارد تکراری از مجموعه Sentinel-2 استفاده می‌کند، جایی که موارد تکراری به‌عنوان تصاویری با همان روز از سال تعریف می‌شوند:

var sentinel2 = ee.ImageCollection('COPERNICUS/S2_HARMONIZED');
var sf = ee.Geometry.Point([-122.47555371521855, 37.76884708376152]);
var s2 = sentinel2
    .filterBounds(sf)
    .filterDate('2018-01-01', '2019-12-31');

var withDoys = s2.map(function(image) {
  var ndvi = image.normalizedDifference(['B4', 'B8']).rename('ndvi');
  var date = image.date();
  var doy = date.getRelative('day', 'year');
  var time = image.metadata('system:time_start');
  var doyImage = ee.Image(doy)
      .rename('doy')
      .int();
  return ndvi.addBands(doyImage).addBands(time)
      .clip(image.geometry()); // Appropriate use of clip.
});

var array = withDoys.toArray();
var timeAxis = 0;
var bandAxis = 1;

var dedupe = function(array) {
  var time = array.arraySlice(bandAxis, -1);
  var sorted = array.arraySort(time);
  var doy = sorted.arraySlice(bandAxis, -2, -1);
  var left = doy.arraySlice(timeAxis, 1);
  var right = doy.arraySlice(timeAxis, 0, -1);
  var mask = ee.Image(ee.Array([[1]]))
      .arrayCat(left.neq(right), timeAxis);
  return array.arrayMask(mask);
};

var deduped = dedupe(array);

// Inspect these outputs to confirm that duplicates have been removed.
print(array.reduceRegion('first', sf, 10));
print(deduped.reduceRegion('first', sf, 10));

مجموعه‌های چاپ‌شده را بررسی کنید تا مطمئن شوید موارد تکراری برداشته شده‌اند.