공지사항:
2025년 4월 15일 전에 Earth Engine 사용을 위해 등록된 모든 비상업용 프로젝트는 Earth Engine 액세스를 유지하기 위해
비상업용 자격 요건을 인증해야 합니다.
Method: projects.assets.getPixels
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이미지 확장 소재에서 픽셀을 가져옵니다. 이 맞춤 메서드를 사용하면 호출자가 밴드와 지도 투영을 선택적으로 지정하여 이미지에서 임의의 픽셀 타일을 요청할 수 있습니다. 마스킹되거나 누락된 데이터는 0으로 인코딩됩니다.
요청은 요청당 압축되지 않은 데이터 48MB로 제한되며, 이는 요청 크기(픽셀), 요청된 이미지 밴드 수, 각 밴드의 픽셀당 바이트 수를 곱하여 계산됩니다. 요청은 둘 중 하나의 크기가 최대 32,000픽셀, 최대 1,024개 밴드로 제한됩니다. 이 한도를 초과하는 요청은 400 (BAD_REQUEST) 오류 코드를 발생시킵니다.
성공하면 응답 본문에 요청의 fileFormat 필드에 지정된 인코딩으로 요청된 픽셀 데이터가 포함됩니다.
HTTP 요청
POST https://earthengine.googleapis.com/v1alpha/{name=projects/*/assets/**}:getPixels
URL은 gRPC 트랜스코딩 문법을 사용합니다.
경로 매개변수
| 매개변수 |
name |
string
필수입니다. 픽셀을 가져올 이미지 확장 소재의 이름입니다. name는 'projects/*/assets/**' 형식입니다(예: "projects/earthengine-legacy/assets/users/[USER]/[ASSET]"). 모든 사용자 소유 애셋은 'earthengine-legacy' 프로젝트에 속합니다(예: "projects/earthengine-legacy/assets/users/foo/bar"). 그 밖의 모든 애셋은 'earthengine-public' 프로젝트에 속합니다(예: "projects/earthengine-public/assets/LANDSAT").
승인을 처리하려면 지정된 리소스 name에 대해 다음과 같은 IAM 권한이 필요합니다.
|
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
| 필드 |
fileFormat |
enum (ImageFileFormat)
픽셀 값을 반환할 출력 파일 형식입니다.
|
grid |
object (PixelGrid)
데이터를 가져올 픽셀 그리드를 설명하는 매개변수입니다. 기본값은 데이터의 기본 픽셀 그리드입니다.
|
region |
object (Struct format)
있는 경우 반환할 데이터 영역으로, GeoJSON 도형 객체로 지정됩니다 (RFC 7946 참고). 반환된 이미지는 항상 직사각형이므로 출력 좌표계에서 지정된 도형의 경계 상자가 실제로 사용됩니다. grid.dimensions도 지정하면 그리드가 요청된 크기로 다시 조정됩니다.
|
bandIds[] |
string
있는 경우 픽셀을 가져올 특정 밴드 세트를 지정합니다. 밴드는 ImageBand 프로토의 id 필드에 표시된 대로 ID로 식별됩니다.
|
visualizationOptions |
object (VisualizationOptions)
있는 경우 원시 데이터를 반환하는 대신 데이터의 8비트 RGB 시각화를 생성하는 데 적용할 시각화 옵션 집합입니다.
|
workloadTag |
string
사용자가 이 계산을 추적하기 위해 제공한 태그입니다.
|
응답 본문
성공한 경우 응답은 형식이 메서드에 의해 정의되는 일반 HTTP 응답입니다.
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/earthengine
https://www.googleapis.com/auth/earthengine.readonly
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/cloud-platform.read-only
자세한 내용은 OAuth 2.0 Overview를 참고하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-25(UTC)
[null,null,["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eFetches pixel data from Earth Engine image assets, allowing users to specify desired regions, bands, and output formats.\u003c/p\u003e\n"],["\u003cp\u003eRequests are limited to 48MB of uncompressed data, 32K pixels in each dimension, and 1024 bands; exceeding these limits will result in a 400 error.\u003c/p\u003e\n"],["\u003cp\u003eSuccessful responses contain the requested pixel data in the specified file format, or an 8-bit RGB visualization if visualization options are provided.\u003c/p\u003e\n"],["\u003cp\u003eThe request must specify the image asset name and can optionally include parameters for the output format, pixel grid, region, bands, visualization options, and a workload tag for tracking.\u003c/p\u003e\n"],["\u003cp\u003eAuthorization requires appropriate IAM permissions or one of the specified OAuth scopes, including 'earthengine', 'earthengine.readonly', 'cloud-platform', or 'cloud-platform.read-only'.\u003c/p\u003e\n"]]],[],null,["# Method: projects.assets.getPixels\n\nFetches pixels from an image asset. This custom method allows the caller to request an arbitrary tile of pixels from an image, optionally specifying the bands and map projection. Masked or missing data will be encoded as zeroes.\n\nRequests are limited to 48MB in uncompressed data per request, computed as the product of the request dimensions in pixels, the number of image bands requested, and the number of bytes per pixel for each band. Requests are also limited to at most 32K pixels in either dimension and at most 1024 bands. Requests exceeding these limits will result in an error code of 400 (BAD_REQUEST).\n\nIf successful, the response body contains the requested pixel data in the encoding specified in the `fileFormat` field of the request.\n\n### HTTP request\n\n`POST https://earthengine.googleapis.com/v1alpha/{name=projects/*/assets/**}:getPixels`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `name` | `string` Required. The name of the image asset from which to get pixels. `name` is of the format \"projects/\\*/assets/\\*\\*\" (e.g., \"projects/earthengine-legacy/assets/users/\\[USER\\]/\\[ASSET\\]\"). All user-owned assets are under the project \"earthengine-legacy\" (e.g., \"projects/earthengine-legacy/assets/users/foo/bar\"). All other assets are under the project \"earthengine-public\" (e.g., \"projects/earthengine-public/assets/LANDSAT\"). Authorization requires the following [IAM](https://cloud.google.com/iam/docs/) permission on the specified resource `name`: - `earthengine.assets.get` |\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"fileFormat\": enum (/earth-engine/reference/rest/v1alpha/ImageFileFormat), \"grid\": { object (/earth-engine/reference/rest/v1alpha/PixelGrid) }, \"region\": { object }, \"bandIds\": [ string ], \"visualizationOptions\": { object (/earth-engine/reference/rest/v1alpha/VisualizationOptions) }, \"workloadTag\": string } ``` |\n\n| Fields ||\n|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `fileFormat` | `enum (`[ImageFileFormat](/earth-engine/reference/rest/v1alpha/ImageFileFormat)`)` The output file format in which to return the pixel values. |\n| `grid` | `object (`[PixelGrid](/earth-engine/reference/rest/v1alpha/PixelGrid)`)` Parameters describing the pixel grid in which to fetch data. Defaults to the native pixel grid of the data. |\n| `region` | `object (`[Struct](https://protobuf.dev/reference/protobuf/google.protobuf/#struct)` format)` If present, the region of data to return, specified as a GeoJSON geometry object (see RFC 7946). Since the returned image is always rectangular, the bounding box of the given geometry in the output coordinate system will actually be used. If `grid.dimensions` is also specified then the grid will finally be rescaled to the requested size. |\n| `bandIds[]` | `string` If present, specifies a specific set of bands from which to get pixels. Bands are identified by id, as indicated by the `id` field of an ImageBand proto. |\n| `visualizationOptions` | `object (`[VisualizationOptions](/earth-engine/reference/rest/v1alpha/VisualizationOptions)`)` If present, a set of visualization options to apply to produce an 8-bit RGB visualization of the data, rather than returning the raw data. |\n| `workloadTag` | `string` User supplied tag to track this computation. |\n\n### Response body\n\nIf successful, the response is a generic HTTP response whose format is defined by the method.\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/earthengine`\n- `\n https://www.googleapis.com/auth/earthengine.readonly`\n- `\n https://www.googleapis.com/auth/cloud-platform`\n- `\n https://www.googleapis.com/auth/cloud-platform.read-only`\n\nFor more information, see the [OAuth 2.0 Overview](/identity/protocols/OAuth2)."]]
