Page Summary
-
This method concatenates multiple images into a single array image.
-
The output will be masked if any of the input images are masked.
-
The method
ImageCollection.toArrayPerBand(axis)is used for this operation and returns an Image. -
The images in the collection must have the same dimensionality and shape per band for successful concatenation.
-
The
axisparameter determines the dimension along which concatenation occurs.
| Usage | Returns |
|---|---|
ImageCollection.
toArrayPerBand
( axis
, dropMasked
)
|
Image |
| Argument | Type | Details |
|---|---|---|
|
this:
collection
|
ImageCollection | Images to concatenate. A separate concatenation is done per band, so all the images must have the same dimensionality and shape per band, except length along the concatenation axis. |
axis
|
Integer, default: 0 | Axis to concatenate along; must be at least 0 and at most the minimum dimension of any band in the collection. |
dropMasked
|
Boolean, default: false | If false (the default), the mask value of the output pixel is the minimum of the masks of the input pixels. If any image in the collection within the computation bounding box is completely masked at a pixel, that output pixel will be masked. As a result, every unmasked output pixel array will have the same size. If true, the mask value of the output pixel is the maximum of the mask of the inputs. Completely masked images at that pixel are ignored and do not contribute data to the output array. The output arrays will therefore not necessarily have the same size for each pixel. |
Examples
Code Editor (JavaScript)
// A function to extract and print the array of a selected pixel. function sampleArrayImage ( arrImg ) { var point = ee . Geometry . Point ([ 0 , 0 ]); return arrImg . sample ( point , 1 ). first (). get ( 'b1' ); } // Define three single-band constant images with unified data types. var img0 = ee . Image ( 0 ). byte (). rename ( 'b1' ); var img1 = ee . Image ( 1 ). byte (). rename ( 'b1' ); var img2 = ee . Image ( 2 ). byte (). rename ( 'b1' ); // 1. Basic usage: concatenate fully valid images along axis 0. var colSimple = ee . ImageCollection ([ img0 , img1 , img2 ]); var arrayBasic = colSimple . toArrayPerBand (); print ( 'Basic toArrayPerBand (pixel array):' , sampleArrayImage ( arrayBasic )); // Result: [0, 1, 2] // 2. Masking behavior: introduce an image with a masked pixel. // Update mask so img1 has no valid data at the sampled pixel. var img1Masked = img1 . updateMask ( 0 ); var colMasked = ee . ImageCollection ([ img0 , img1Masked , img2 ]); // By default (dropMasked = false), if any input image is masked at a pixel, // the output array is masked at that pixel. Since sampling a masked pixel // returns no features, we inspect the output image's mask directly. var arrayDefault = colMasked . toArrayPerBand (); print ( 'Default masking behavior (pixel mask is 0):' , sampleArrayImage ( arrayDefault . mask ())); // Result: 0 // With dropMasked = true, if any input image is masked at a specific pixel, // its value is omitted from the output array at that pixel. As a result, // array lengths can vary across different pixels. var arrayDropped = colMasked . toArrayPerBand ( 0 , true ); print ( 'dropMasked=true (pixel array omits image-specific masked pixels):' , sampleArrayImage ( arrayDropped )); // Result: [0, 2]
import ee import geemap.core as geemap
Colab (Python)
# A function to extract and print the array of a selected pixel. def sample_array_image ( arr_img ): point = ee . Geometry . Point ([ 0 , 0 ]) return arr_img . sample ( point , 1 ) . first () . get ( 'b1' ) # Define three single-band constant images with unified data types. img0 = ee . Image ( 0 ) . byte () . rename ( 'b1' ) img1 = ee . Image ( 1 ) . byte () . rename ( 'b1' ) img2 = ee . Image ( 2 ) . byte () . rename ( 'b1' ) # 1. Basic usage: concatenate fully valid images along axis 0. col_simple = ee . ImageCollection ([ img0 , img1 , img2 ]) array_basic = col_simple . toArrayPerBand () display ( 'Basic toArrayPerBand (pixel array):' , sample_array_image ( array_basic )) # Result: [0, 1, 2] # 2. Masking behavior: introduce an image with a masked pixel. # Update mask so img1 has no valid data at the sampled pixel. img1_masked = img1 . updateMask ( 0 ) col_masked = ee . ImageCollection ([ img0 , img1_masked , img2 ]) # By default (dropMasked = False), if any input image is masked at a pixel, # the output array is masked at that pixel. Since sampling a masked pixel # returns no features, we inspect the output image's mask directly. array_default = col_masked . toArrayPerBand () display ( 'Default masking behavior (pixel mask is 0):' , sample_array_image ( array_default . mask ()), ) # Result: 0 # With dropMasked = true, if any input image is masked at a specific pixel, # its value is omitted from the output array at that pixel. As a result, # array lengths can vary across different pixels. array_dropped = col_masked . toArrayPerBand ( 0 , True ) display ( 'dropMasked=True (pixel array omits image-specific masked pixels):' , sample_array_image ( array_dropped ), ) # Result: [0, 2]
