Review of `ol/style/Image` and subclass options

[mike-000]

Following on from https://github.com/openlayers/openlayers/pull/13975#issuecomment-1216276968 here are the options supported by the Mapbox specification https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#symbol and their equivalents in OpenLayers.

icon-allow-overlap declutterMode

icon-anchor Similar to anchorOrigin but has more options so ol-mapbox-style sets an appropriate fractional anchor.

icon-color color

icon-halo-blur n/a

icon-halo-color n/a

icon-halo-width n/a

icon-ignore-placement declutterMode

icon-image Derived from sprite related options img, imgSize, offset, offsetOrigin, size, src.

icon-keep-upright n/a Relates to line placement icons, similar to keeping line placement text upright - Mapbox has a similar text-keep-upright option but OpenLayers does this unconditionally

icon-offset Corresponds to the current meaning of displacement "Each component is multiplied by the value of icon-size to obtain the final offset in pixels" (except OpenLayer is positive y up, Mapbox positive y down). Similarly ol-mapbox-style multiplies text-offset by text-size when setting offsetX and offsetY

icon-opacity opacity

icon-optional n/a

icon-padding n/a

icon-pitch-alignment n/a

icon-rotate rotation (OpenLayers uses radians, Mapbox degrees)

icon-rotation-alignment rotateWithView

icon-size scale

icon-text-fit n/a

icon-text-fit-padding n/a

icon-translate This could be achieved using anchor or displacement but unlike icon-offset the behavior is affected by icon-translate-anchor

icon-translate-anchor n/a How icon-translate relates to rotation - there is a similar text-translate-anchor option, which possibly corresponds to the differences seen in #13981 except that is text-offset not text-translate so it should not happen

[mike-000]

My first thoughts would be to use either offsetX/offsetY or displacement for both image and text and deprecate the other. If displacement is used it would have the same meaning as the current [offsetX, offsetY] for both. ol-mapbox-style currently sets offsetX and offsetY via their setter methods, which could be retained as non-API to maintain backward compatibility if replaced by displacement in the constructor options. Only tests and examples appear to use offsetX and offsetY in the constructor.

Documentation for offset, offsetOrigin and size should all refer to the original (sprite) icon image and should appear together in the options list.