update documentation for new polygon operations

[MaartenHilferink]

See #604

• bg_intersect
• bg_union
• bg_xor
• bg_difference
• bg_overlay_polygon
• bp_overlay_polygon

we need to update the documentation.

Originally posted by @jipclaassens in https://github.com/ObjectVision/GeoDMS/issues/604#issuecomment-2205470805

[mtbeek32]

these functions need to be added to the operator test as well.

[eoudejans]

See also #757

[MaartenHilferink]

Binary map-algebraic polygon operations on related polygon sets a and b which must match in domain and base projection of the values.

• bg_X(a: D->P, b: D->P) -> (D->*P) with X any of { intersect, xor, union, difference } do the corresponding operations resulting in a sequence for each element i of D that represents a multi polygon that bounds the points that come from combining a[i] and b[]i with that operation X, and P is any GeoDms point type, i.e. with signed or unsigned 16, 32, or 64 bits integer or 32 or 64 bits floating point coordinates.
• bp_X(a: D->P, b:D->P) -> (D->*P) with X any of { intersect, xor, union, difference } do the corresponding operations resulting in a sequence for each element i of D that represents a multi polygon that bounds the points that come from combining a[i] and b[]i with that operation X, and P is a GeoDms point type with signed integer coordinates, i.e. with signed 16, 32, or 64 bits integers.
• Shorthands bg_X are: (a: D->P) X (b:D->P)->(D->P) with X any of { , ^, &&, +, ||, - } and P is any GeoDms point with floating point coordinates, i.e. 32 or 64 bits floating points
• Shorthands for bp_X are: (a: D->P) X (b:D->P)->(D->P) with X any of { , ^, &&, +, ||, - } and P is any GeoDms point with signed integer coordinates, i.e. 16, 32, or 64 bits integers

Variants on the bp-based split and (partitioned) union operations:

• bp_polygon(D->P) -> D->P: NOP
• bp_split_polygon(D->P) -> S { geometry: S->P; polygon_rel: S->D }
• bp_union_polygon(D->P) -> void->P
• bp_split_union_polygon(D->P)-> S { geometry: S->P }
• bp_union_polygon(D->P, D->R) -> R->P
• bp_split_union_polygon(D->P, D->R)-> S { geometry: S->P, part_rel->S->R }

where P is a GeoDms point type with signed integer coordinates, i.e. 16, 32, or 64 bits signed integers. S is a resulting uint32 set of split polygons, and D is the original domain.

Similar operations based on the bg library

• bg_polygon(D->P) -> D->P: NOP
• bg_split_polygon(D->P) -> S { geometry: S->P; polygon_rel: S->D }
• bg_union_polygon(D->P) -> void->P
• bg_split_union_polygon(D->P)-> S { geometry: S->P }
• bg_union_polygon(D->P, D->R) -> R->P
• bg_split_union_polygon(D->P, D->R)-> S { geometry: S->P, part_rel->S->R } where P is any GeoDms point type.

Note that all bg_... operations are processed in Float64 (a.k.a. double) coordinates and coordinates of the results are converted back to the coordinates of the argument(s).