تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
reduceRegion
للحصول على إحصاءات قيم البكسل في منطقة من ee.Image، استخدِم
image.reduceRegion().
يؤدي ذلك إلى تقليل جميع وحدات البكسل في المناطق إلى
إحصاءات أو تمثيل مكثّف آخر لبيانات وحدات البكسل في المنطقة (مثل تمثيل
الرسم البياني الشريطي). يتم تمثيل المنطقة على شكل Geometry، والذي قد يكون
مضلّعًا يحتوي على العديد من البكسلات، أو قد يكون نقطة واحدة، وفي هذه الحالة لن يكون هناك سوى
بكسل واحد في المنطقة. في كلتا الحالتَين، كما هو موضّح في الشكل 1، فإنّ القيمة المعروضة
هي إحصائية مستمَدة من وحدات البكسل في المنطقة.
الشكل 1. رسم توضيحي لتطبيق ee.Reducer على صورة
ومنطقة.
للحصول على مثال على الحصول على إحصاءات البكسل في منطقة من الصورة باستخدام
reduceRegion()، ننصحك بالعثور على متوسط القيم الطيفية
لمجمّع Landsat لعام 5 سنوات ضمن حدود غابة أشجار الصنوبر
في سييرا نيفادا (كما هو موضّح في الشكل 2):
لفرض إجراء العمليات الحسابية، يكفي طباعة النتيجة التي سيعرضها "أداة تعديل الرموز"
على شكل Dictionary في وحدة التحكّم. من المفترض أن يظهر الناتج على النحو التالي:
الشكل 2. صورة مركبة بألوان زائفة لبيانات صور Landsat في
كلّ من كاليفورنيا ونيفادا تظهر المنطقة التي سيتم تقليلها باللون الأبيض.
يُرجى العلم أنّه في هذا المثال، يتم تحديد عملية التقليل من خلال توفير reducer
(ee.Reducer.mean()) وgeometry (region.geometry())
وscale (30 مترًا) وmaxPixels للحد الأقصى لعدد
البكسل المطلوب إدخاله إلى أداة التقليل. يجب دائمًا تحديد مقياس في
طلبات reduceRegion(). ويعود السبب في ذلك إلى أنّ عمليات المعالجة المعقدة، والتي
قد تتضمّن بيانات من مصادر مختلفة بنطاقات مختلفة، لن تؤدي إلى تحديد نطاق الإخراج
بشكل لا لبس فيه من خلال الإدخالات. في هذه الحالة، يتم ضبط مقياس الدرجات تلقائيًا
على درجة واحدة، ما يؤدي بشكل عام إلى نتائج غير مرضية. اطّلِع على هذه
الصفحة للحصول على مزيد من المعلومات عن كيفية تعامل Earth Engine مع النطاق.
هناك طريقتان لضبط المقياس: من خلال تحديد المَعلمة scale،
أو من خلال تحديد نظام إحداثيات جغرافية وتحويل نظام إحداثيات جغرافية. (اطّلِع على مسرد المصطلحات للحصول على
المزيد من المعلومات عن أنظمة CRS وعمليات تحويلها). على سبيل المثال، فإنّ التخفيض الذي يُطبَّق على
meanDictionary (أعلاه) يعادل ما يلي:
بشكل عام، يكون تحديد المقياس كافيًا ويؤدي إلى إنشاء رمز أكثر سهولة في القراءة.
تحدِّد أداة Earth Engine وحدات البكسل التي سيتم إدخالها إلى أداة التقليل من خلال تحويل المنطقة إلى صورة نقطية أولاً.
في حال تحديد مقياس بدون نظام مرجعي جغرافي، يتم تحويل المنطقة إلى تنسيق ثنائي الأبعاد في إسقاط
الصورة الأصلي مع تحويله إلى درجة الدقة المحدّدة. في حال تحديد نظام مرجعي جغرافي ومقياس معيّنَين، تتم معالجة
المنطقة بالاستناد إليهما.
وحدات البكسل في المنطقة
يتم تحديد أنّ البكسل يقع ضمن المنطقة (وتحديد وزنه) وفقًا للقواعد التالية،
ويتم تطبيقها على النطاق وطريقة الإسقاط المحدّدة:
العوامل المُخفِّضة غير المرجحة (مثل ee.Reducer.count() أو
ee.Reducer.mean().unweighted()): يتم تضمين البكسلات إذا كان مركز ثقلها
في المنطقة وكان قناع الصورة غير صفري.
المُخفِّضات ذات الوزن (مثل ee.Reducer.mean()):
يتم تضمين البكسل إذا كان (تقريبًا) 0.5% من البكسل على الأقل في المنطقة
وكان قناع الصورة غير صفري، ويكون وزنها هو الحد الأدنى من قناع الصورة والاقتسام (التقريبي) للبكسل الذي تغطيه المنطقة.
يجب توفير المَعلمة maxPixels لكي تنجح عملية الحساب. في حال حذف المَعلمة
من المثال، يتم عرض خطأ يبدو على النحو التالي:
هناك خيارات متعدّدة لتخطّي هذه الأخطاء: زيادة maxPixels
كما هو موضّح في المثال، أو زيادة scale، أو ضبط bestEffort على
true، ما يؤدي تلقائيًا إلى احتساب مقياس جديد (أكبر) بحيث لا يتم تجاوز maxPixels. إذا لم تحدِّد maxPixels، يتم استخدام القيمة التلقائية.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003e\u003ccode\u003ereduceRegion\u003c/code\u003e calculates statistics of pixel values within a specified region of an \u003ccode\u003eee.Image\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe region can be a polygon or a single point, and the output is a statistic derived from the pixels within that region.\u003c/p\u003e\n"],["\u003cp\u003eA scale should always be specified in \u003ccode\u003ereduceRegion\u003c/code\u003e calls to ensure accurate results, either using the \u003ccode\u003escale\u003c/code\u003e parameter or by defining a CRS and CRS transform.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003emaxPixels\u003c/code\u003e parameter may need to be adjusted or \u003ccode\u003ebestEffort\u003c/code\u003e set to true to handle large regions and avoid computation errors.\u003c/p\u003e\n"],["\u003cp\u003ePixels are included in the calculation based on whether their centroid is within the region (unweighted reducers) or the fraction of the pixel covered by the region (weighted reducers), along with the image's mask.\u003c/p\u003e\n"]]],["`reduceRegion()` calculates statistics of pixel values within a specified region of an `ee.Image`. It uses a `Geometry` to define the region, which can range from a single point to a polygon. The key actions involve setting a `reducer` (e.g., `ee.Reducer.mean()`), `geometry`, `scale` or `crs`, and `maxPixels`. Pixel inclusion is determined by centroid location for unweighted reducers or pixel coverage for weighted ones, considering the image's mask. The output is a `Dictionary` of statistics derived from pixel values.\n"],null,["# Statistics of an Image Region\n\n`reduceRegion`\n--------------\n\nTo get statistics of pixel values in a region of an `ee.Image`, use\n[`image.reduceRegion()`](/earth-engine/apidocs/ee-image-reduceregion).\nThis reduces all the pixels in the region(s) to a\nstatistic or other compact representation of the pixel data in the region (e.g.\nhistogram). The region is represented as a `Geometry`, which might be a\npolygon, containing many pixels, or it might be a single point, in which case there will\nonly be one pixel in the region. In either case, as illustrated in Figure 1, the output\nis a statistic derived from the pixels in the region.\nFigure 1. An illustration of an `ee.Reducer` applied to an image and a region.\n\nFor an example of getting pixel statistics in a region of an image using\n`reduceRegion()`, consider finding the mean spectral\nvalues of a 5-year Landsat composite within the boundaries of the Sierra Nevada\nConiferous Forest (illustrated by Figure 2): \n\n```gdscript\n// Load input imagery: Landsat 7 5-year composite.\nvar image = ee.Image('LANDSAT/LE7_TOA_5YEAR/2008_2012');\n\n// Load an input region: Sierra Nevada.\nvar region = ee.Feature(ee.FeatureCollection('EPA/Ecoregions/2013/L3')\n .filter(ee.Filter.eq('us_l3name', 'Sierra Nevada'))\n .first());\n\n// Reduce the region. The region parameter is the Feature geometry.\nvar meanDictionary = image.reduceRegion({\n reducer: ee.Reducer.mean(),\n geometry: region.geometry(),\n scale: 30,\n maxPixels: 1e9\n});\n\n// The result is a Dictionary. Print it.\nprint(meanDictionary);\n```\n\nTo force the computation, it suffices to print the result, which the Code Editor will\ndisplay as a `Dictionary` in the console. The output should look something like: \n\n```\nB1: 25.406029716816853\nB2: 23.971497014238988\nB3: 22.91059593763103\nB4: 54.83164133293403\nB5: 38.07655472573677\nB6_VCID_2: 198.93216428012906\nB7: 24.063261634961563\n```\nFigure 2. False color composite of the Landsat image data for California and Nevada. The region over which to reduce is shown in white.\n\nNote that in this example the reduction is specified by providing the `reducer`\n(`ee.Reducer.mean()`), the `geometry` (`region.geometry()`),\nthe `scale` (30 meters) and `maxPixels` for the maximum number of\npixels to input to the reducer. A scale should always be specified in\n`reduceRegion()` calls. This is because in complex processing flows, which\nmay involve data from different sources with different scales, the scale of the output\nwill not be unambiguously determined from the inputs. In that case, the scale defaults\nto 1 degree, which generally produces unsatisfactory results. See [this\npage](/earth-engine/guides/scale) for more information about how Earth Engine handles scale.\n\nThere are two ways to set the scale: by specifying the `scale` parameter,\nor by specifying a CRS and CRS transform. (See [the glossary](/earth-engine/glossary) for\nmore information about CRS's and CRS transforms). For example, the\n`meanDictionary` reduction (above) is equivalent to the following: \n\n```gdscript\n// As an alternative to specifying scale, specify a CRS and a CRS transform.\n// Make this array by constructing a 4326 projection at 30 meters,\n// then copying the bounds of the composite, from composite.projection().\nvar affine = [0.00026949458523585647, 0, -180, 0, -0.00026949458523585647, 86.0000269494563];\n\n// Perform the reduction, print the result.\nprint(image.reduceRegion({\n reducer: ee.Reducer.mean(),\n geometry: region.geometry(),\n crs: 'EPSG:4326',\n crsTransform: affine,\n maxPixels: 1e9\n}));\n```\n\nIn general, specifying the scale is sufficient and results in more readable code.\nEarth Engine determines which pixels to input to the reducer by first rasterizing the region.\nIf a scale is specified without a CRS, the region is rasterized in the image's native\nprojection scaled to the specified resolution. If both a CRS and scale are specified, the\nregion is rasterized based on them.\n\nPixels in the region\n--------------------\n\nPixels are determined to be in the region (and weighted) according to the following rules,\napplied in the specified scale and projection:\n\n- **Unweighted reducers** (e.g. `ee.Reducer.count()` or `ee.Reducer.mean().unweighted()`): pixels are included if their centroid is in the region and the image's mask is non-zero.\n- **Weighted reducers** (e.g. `ee.Reducer.mean()`): pixels are included if at least (approximately) 0.5% of the pixel is in the region and the image's mask is non-zero; their weight is the minimum of the image's mask and the (approximate) fraction of the pixel covered by the region.\n\nThe `maxPixels` parameter is needed to get the computation to succeed. If this\nparameter is left out of the example, an error is returned, which looks something like:\n| Dictionary (Error) \n| Image.reduceRegion: Too many pixels in the region. Found 527001545, but only 10000000 allowed. \n\nThere are multiple options to get past these errors: increase `maxPixels`,\nas in the example, increase the `scale`, or set `bestEffort` to\ntrue, which automatically computes a new (larger) scale such that `maxPixels`\nis not exceeded. If you do not specify `maxPixels`, the default value is used."]]
