Clarified merge behavior of merge_cubes #87

[m-mohr]

I tried to clarify how merge_cubes works.

For easier reading, here's the new process description:

The data cubes have to be compatible. A merge is the inverse of a split if there is no overlap. The process doesn't add dimensions.

This means that the data cubes must have the same dimensions. Each dimension must be available in both data cubes have the same name, type, reference system and resolution. One of the dimensions can have different labels, for all other dimensions the labels must be equal. If data overlaps, the parameter overlap_resolver must be specified to resolve the overlap.

Examples for merging two data cubes:

1. Data cubes with the dimensions x, y, t and bands have the same dimension labels in x,y and t, but the labels for the dimension bands are B1 and B2 for the first cube and B3 and B4. An overlap resolver is not needed. The merged data cube has the dimensions x, y, t and bands and the dimension bands has four dimension labels: B1, B2, B3, B4.
2. Data cubes with the dimensions x, y, t and bands have the same dimension labels in x,y and t, but the labels for the dimension bands are B1 and B2 for the first cube and B2 and B3. An overlap resolver is required to resolve overlap in band B2. The merged data cube has the dimensions x, y, t and bands and the dimension bands has three dimension labels: B1, B2, B3.
3. Data cubes with the dimensions x, y and t have the same dimension labels in x,y and t. There are two options:
   1. Keep the overlapping values separately in the merged data cube: An overlap resolver is not needed, but for each data cube you need to add a new dimension using add_dimension(). The new dimensions must be equal, except that the labels for the new dimensions must differ by name. The merged data cube has the same dimensions and labels as the original data cubes, plus the dimension added with add_dimension(), which has the two dimension labels after the merge.
   2. Combine the overlapping values into a single value: An overlap resolver is required to resolve the overlap for all pixels. The merged data cube has the same dimensions and labels as the original data cubes, but all pixel values have been processed by the overlap resolver.
4. Data cubes with the dimensions x, y and t have the same dimension labels in x,y and t. An overlap resolver is required to resolve the overlap for all pixels. The merged data cube has the same dimensions and labels as the original data cubes, but all pixel values have been processed by the overlap resolver.

@jdries What do you think?

[soxofaan]

what is the difference between 3ii and 4?

[m-mohr]

what is the difference between 3ii and 4?

Hah, good point. I added the split into 3i/ii later and forgot to remove 4. Fixed.

[soxofaan]

while at it, maybe also improve this part

        "OverlapResolverMissing": {
            "message": "Two data cubes with overlap but without an overlap resolver have been specified."
        }

e.g "Overlapping data cubes, but no overlap resolver has been specified"

[m-mohr]

e.g "Overlapping data cubes, but no overlap resolver has been specified"

Sounds good, fixed.

[m-mohr]

Seems there are no more objections => merging.