Add keepUpright parameter

This parameter allows to control whether text can be rendered upside-down
when rendering along a line or polygon. This can be useful when the text
has to follow the line direction regardless of its orientation, like an
arrow pointing the direction of the line element.

This setting already exists in Mapbox Style Spec, so ol-mapbox-style will
be able to follow more closely some style definitions.

src/ol/geom/flat/textpath.js

@@ -17,6 +17,7 @@ import {rotate} from './transform.js';
  * @param {string} font The font.
  * @param {Object<string, number>} cache A cache of measured widths.
  * @param {number} rotation Rotation to apply to the flatCoordinates to determine whether text needs to be reversed.
+ * @param {boolean} keepUpright Whether the text needs to be kept upright
  * @return {Array<Array<*>>|null} The result array (or null if `maxAngle` was
  * exceeded). Entries of the array are x, y, anchorX, angle, chunk.
  */
@@ -33,6 +34,7 @@ export function drawTextOnPath(
   font,
   cache,
   rotation,
+  keepUpright = true,
 ) {
   let x2 = flatCoordinates[offset];
   let y2 = flatCoordinates[offset + 1];
@@ -69,14 +71,16 @@ export function drawTextOnPath(
   const endX = lerp(x1, x2, interpolate);
   const endY = lerp(y1, y2, interpolate);
 
-  // Keep text upright
-  let reverse;
-  if (rotation) {
-    const flat = [beginX, beginY, endX, endY];
-    rotate(flat, 0, 4, 2, rotation, flat, flat);
-    reverse = flat[0] > flat[2];
-  } else {
-    reverse = beginX > endX;
+  // Keep text upright if the option is selected
+  let reverse = false;
+  if (keepUpright) {
+    if (rotation) {
+      const flat = [beginX, beginY, endX, endY];
+      rotate(flat, 0, 4, 2, rotation, flat, flat);
+      reverse = flat[0] > flat[2];
+    } else {
+      reverse = beginX > endX;
+    }
   }
 
   const PI = Math.PI;

src/ol/render/canvas/Executor.js

@@ -1001,6 +1001,7 @@ class Executor {
           ];
           declutterMode = instruction[14] || 'declutter';
 
+          const textKeepUpright = /** @type {boolean} */ (instruction[15]);
           const textState = this.textStates[textKey];
           const font = textState.font;
           const textScale = [
@@ -1037,6 +1038,7 @@ class Executor {
               font,
               cachedWidths,
               viewRotationFromTransform ? 0 : this.viewRotation_,
+              textKeepUpright,
             );
             drawChars: if (parts) {
               /** @type {Array<ReplayImageOrLabelArgs>} */

src/ol/render/canvas/TextBuilder.js

@@ -79,6 +79,12 @@ class CanvasTextBuilder extends CanvasBuilder {
      */
     this.textRotateWithView_ = undefined;
 
+    /**
+     * @private
+     * @type {boolean|undefined}
+     */
+    this.textKeepUpright_ = undefined;
+
     /**
      * @private
      * @type {number}
@@ -538,6 +544,7 @@ class CanvasTextBuilder extends CanvasBuilder {
       textKey,
       1,
       this.declutterMode_,
+      this.textKeepUpright_,
     ]);
     this.hitDetectionInstructions.push([
       CanvasInstruction.DRAW_CHARS,
@@ -555,6 +562,7 @@ class CanvasTextBuilder extends CanvasBuilder {
       textKey,
       1 / pixelRatio,
       this.declutterMode_,
+      this.textKeepUpright_,
     ]);
   }
 
@@ -632,12 +640,15 @@ class CanvasTextBuilder extends CanvasBuilder {
       const textOffsetX = textStyle.getOffsetX();
       const textOffsetY = textStyle.getOffsetY();
       const textRotateWithView = textStyle.getRotateWithView();
+      const textKeepUpright = textStyle.getKeepUpright();
       const textRotation = textStyle.getRotation();
       this.text_ = textStyle.getText() || '';
       this.textOffsetX_ = textOffsetX === undefined ? 0 : textOffsetX;
       this.textOffsetY_ = textOffsetY === undefined ? 0 : textOffsetY;
       this.textRotateWithView_ =
         textRotateWithView === undefined ? false : textRotateWithView;
+      this.textKeepUpright_ =
+        textKeepUpright === undefined ? true : textKeepUpright;
       this.textRotation_ = textRotation === undefined ? 0 : textRotation;
 
       this.strokeKey_ = strokeState

src/ol/style/Text.js

@@ -39,6 +39,7 @@ const DEFAULT_FILL_COLOR = '#333';
  * the distance between two text anchors in pixels. Only available when `placement` is set to `'line'`. Overrides 'textAlign'.
  * @property {number|import("../size.js").Size} [scale] Scale.
  * @property {boolean} [rotateWithView=false] Whether to rotate the text with the view.
+ * @property {boolean} [keepUpright=true] Whether the text can be rotated 180° to prevent being rendered upside down.
  * @property {number} [rotation=0] Rotation in radians (positive rotation clockwise).
  * @property {string|Array<string>} [text] Text content or rich text content. For plain text provide a string, which can
  * contain line breaks (`\n`). For rich text provide an array of text/font tuples. A tuple consists of the text to
@@ -95,6 +96,12 @@ class Text {
      */
     this.rotateWithView_ = options.rotateWithView;
 
+    /**
+     * @private
+     * @type {boolean|undefined}
+     */
+    this.keepUpright_ = options.keepUpright;
+
     /**
      * @private
      * @type {number|import("../size.js").Size|undefined}
@@ -228,6 +235,7 @@ class Text {
       overflow: this.getOverflow(),
       rotation: this.getRotation(),
       rotateWithView: this.getRotateWithView(),
+      keepUpright: this.getKeepUpright(),
       scale: Array.isArray(scale) ? scale.slice() : scale,
       text: this.getText(),
       textAlign: this.getTextAlign(),
@@ -329,6 +337,15 @@ class Text {
     return this.rotateWithView_;
   }
 
+  /**
+   * Determine whether the text can be rendered upside down.
+   * @return {boolean|undefined} Keep text upright.
+   * @api
+   */
+  getKeepUpright() {
+    return this.keepUpright_;
+  }
+
   /**
    * Get the text rotation.
    * @return {number|undefined} Rotation.
@@ -515,6 +532,16 @@ class Text {
     this.rotateWithView_ = rotateWithView;
   }
 
+  /**
+   * Set whether the text can be rendered upside down.
+   *
+   * @param {boolean} keepUpright Keep text upright.
+   * @api
+   */
+  setKeepUpright(keepUpright) {
+    this.keepUpright_ = keepUpright;
+  }
+
   /**
    * Set the fill.
    *