ee.Image의 영역에서 픽셀 값의 통계를 가져오려면 image.reduceRegion()를 사용합니다.
이렇게 하면 영역의 모든 픽셀이 통계 또는 영역의 픽셀 데이터를 간단하게 나타내는 다른 표현(예: 히스토그램)으로 축소됩니다. 영역은 Geometry로 표시되며, 이는 다수의 픽셀을 포함하는 다각형일 수도 있고 단일 지점일 수도 있습니다. 이 경우 영역에 픽셀이 하나만 있습니다. 두 경우 모두 그림 1과 같이 출력은 영역의 픽셀에서 파생된 통계입니다.
그림 1. 이미지와 영역에 적용된 ee.Reducer의 그림입니다.
reduceRegion()를 사용하여 이미지의 특정 영역에서 픽셀 통계를 가져오는 예를 들어보자면 시에라 네바다 침엽수림 경계 내에서 5년간의 Landsat 합성물의 평균 스펙트럼 값을 찾는 경우를 들 수 있습니다 (그림 2 참고).
그림 2. 캘리포니아와 네바다의 Landsat 이미지 데이터를 합성한 가짜 컬러 이미지입니다. 줄일 영역은 흰색으로 표시됩니다.
이 예에서는 reducer(ee.Reducer.mean()), geometry(region.geometry()), scale(30미터), maxPixels(최대 픽셀 수)를 제공하여 축소를 지정합니다. reduceRegion() 호출에서 항상 크기를 지정해야 합니다. 이는 규모가 다른 여러 소스의 데이터가 포함될 수 있는 복잡한 처리 흐름에서 출력의 규모가 입력에서 명확하게 결정되지 않기 때문입니다. 이 경우 눈금은 기본적으로 1도로 설정되며, 일반적으로 만족스러운 결과를 얻을 수 없습니다. Earth Engine에서 크기를 처리하는 방법에 관한 자세한 내용은 이 페이지를 참고하세요.
scale 매개변수를 지정하거나 CRS 및 CRS 변환을 지정하는 두 가지 방법으로 배율을 설정할 수 있습니다. CRS 및 CRS 변환에 관한 자세한 내용은 용어집을 참고하세요. 예를 들어 위의 meanDictionary 감소는 다음과 같습니다.
일반적으로 크기를 지정하는 것으로 충분하며 더 읽기 쉬운 코드가 됩니다.
Earth Engine은 먼저 영역을 래스터화하여 감소기에 입력할 픽셀을 결정합니다.
CRS 없이 배율이 지정된 경우 지정된 해상도로 크기가 조정된 이미지의 기본 프로젝션에서 영역이 래스터화됩니다. CRS와 배율이 모두 지정된 경우 이를 기반으로 영역이 래스터화됩니다.
영역의 픽셀
지정된 크기 및 투영에 적용되는 다음 규칙에 따라 픽셀이 영역에 있는 것으로 결정되고 가중치가 부여됩니다.
가중치 없는 감소 함수 (예: ee.Reducer.count() 또는 ee.Reducer.mean().unweighted()): 중앙값이 영역 내에 있고 이미지의 마스크가 0이 아닌 경우 픽셀이 포함됩니다.
가중치 적용 감소 함수 (예: ee.Reducer.mean()): 픽셀의 (대략) 0.5% 이상이 영역에 있고 이미지의 마스크가 0이 아닌 경우 픽셀이 포함됩니다. 가중치는 이미지의 마스크와 영역에서 차지하는 픽셀의 (대략적인) 비율 중 최솟값입니다.
계산을 성공적으로 실행하려면 maxPixels 매개변수가 필요합니다. 이 매개변수를 예에서 생략하면 다음과 같은 오류가 반환됩니다.
이러한 오류를 해결하는 방법에는 여러 가지가 있습니다. 예와 같이 maxPixels를 늘리거나 scale를 늘리거나 bestEffort를 true로 설정하면 됩니다. 그러면 maxPixels가 초과되지 않도록 새 (더 큰) 스케일이 자동으로 계산됩니다. maxPixels를 지정하지 않으면 기본값이 사용됩니다.
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\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."]]
