clarification on representation of 1-band images

[geospatial-jeff]

First off thanks for taking the time to write this, its great!

I am a little confused by the shape requirements of the spec, in particular these two:

• The output file MUST contain AT LEAST ONE two-dimensional array. (E.G. a shape of (1, 256, 256)).
• Additional bands SHALL be in subsequent two-dimensional arrays. (E.G. a tile containing three bands shall have a shape of (3, 256, 256).)

My assumption from reading the example in the first bullet point is that numpy tiles should always be 3D, which makes a lot of sense. But a 2D array like (256, 256) also satisfies both requirements and could be considered a valid numpy tile. Whatever the intent, I think it's important to be explicit about how numpy tiles represent single channel images as there is some nuance where some software represents them as (256, 256) while others do (1, 256, 256).

[vincentsarago]

Maybe It should be part of another issue but I think its important to specify the axis order of the array (being bands, height, width). If we don't want to fix this, I think we should at least mention that it's up to the user to choose the order.

ref: https://github.com/mapbox/rasterio/blob/960a906dad2a4e426387ce048a52c6e90afdcd2b/docs/topics/image_processing.rst#image-processing-software

[theduckylittle]

A single band image should have the shape (1, 256, 256).

That assumption should allow clients' logic to be simpler.

For example (psuedoish code):

for (band in bands) {
  processBand(band)
}

Vs:

if (arr.shape.length == 2) {
 processBand(img)
} else {
 for (band in bands) {
   processBand(band)
 }
}

The second version is more verbose, less immediate descriptive, and adds unnecessary LOCs.

[theduckylittle]

Would the following addition help clarify?

• The output file MUST have the shape of a 3D array given as (bands, height, width)