Add symbol-line-anchor property for precise arrow placement on lines

[renefournier]

Feature Request: Add symbol-line-anchor property for enhanced arrow placement on lines

Description

We propose adding a new layout property symbol-line-anchor to the symbol layer, along with a complementary symbol-line-anchor-offset property. These additions aim to provide more control over the placement of symbols (particularly arrows) along lines, addressing common use cases in map design and improving the flexibility of line symbolization.

Use Case

When designing maps with directional lines (e.g., routes, flows, or rivers), it's often crucial to have precise control over where arrows are placed, especially at the start and end of lines. Current solutions require complex data preprocessing or multiple layers, which can be cumbersome and performance-intensive. This feature would allow designers to easily ensure that arrows are placed at critical points on the line while maintaining an even distribution of symbols.

Proposed API

New Properties

1. symbol-line-anchor

   • Type: enum
   • Default: "auto"
   • Possible values: "auto", "start", "end", "both"
   • Affect: Determines the anchoring behavior of symbols along a line

2. symbol-line-anchor-offset

   • Type: array of two numbers
   • Default: [0, 0]
   • Units: pixels
   • Affect: Offsets the placement of start and end anchored symbols

Behavior

• "auto": Maintains current behavior
• "start": Places first symbol at line start, distributes others along the line
• "end": Places last symbol at line end, distributes others along the line
• "both": Places symbols at both start and end, distributes others along the line

The symbol-line-anchor-offset allows fine-tuning of start/end symbol placement to avoid overlap with other map elements.

Code Example

{
  "id": "route-arrows",
  "type": "symbol",
  "source": "routes",
  "layout": {
    "symbol-placement": "line",
    "symbol-spacing": 200,
    "icon-image": "arrow",
    "icon-size": 0.5,
    "symbol-line-anchor": "both",
    "symbol-line-anchor-offset": [20, 20]
  }
}

This configuration ensures arrows at both the start and end of the line, offset by 20 pixels from the exact endpoints, with additional arrows distributed every 200 pixels along the line.

Implementation Considerations

1. When symbol-line-anchor is set to "start", "end", or "both", it should take precedence over symbol-spacing for the anchored symbols.
2. For MultiLineString geometries, the property applies to the overall start/end of the entire feature, not individual line segments.
3. The orientation of symbols should follow the existing behavior, determined by the line direction at the placement point.
4. Performance optimization should be considered, especially for real-time rendering scenarios with frequently updating data.

Benefits

1. Simplified workflow for creating maps with precisely placed directional symbols
2. Reduced need for data preprocessing or multiple layers to achieve desired symbol placement
3. Improved cartographic control, especially for route maps, flow diagrams, and river networks
4. Consistent symbol placement across different zoom levels and line geometries

Potential Challenges

1. Ensuring smooth integration with existing symbol placement logic
2. Handling edge cases, such as very short lines or lines with many segments
3. Maintaining rendering performance, especially for complex line geometries

Additional Context

This feature request aims to address a common pain point in map design and would significantly enhance the capabilities of MapLibre GL JS for creating informative and visually appealing directional line features.

We welcome feedback and suggestions from the community to refine this proposal and ensure it meets the needs of MapLibre GL JS users.

[HarelM]

Wouldn't extending symbol-placement be a better solution?
https://maplibre.org/maplibre-style-spec/layers/#symbol-placement

Note that rendering is done per tile, so if a line spreads to more than one tile, these definitions might prove hard to implement, but this is outside the scope of changing the spec.

[renefournier]

Wouldn't extending symbol-placement be a better solution? https://maplibre.org/maplibre-style-spec/layers/#symbol-placement

Note that rendering is done per tile, so if a line spreads to more than one tile, these definitions might prove hard to implement, but this is outside the scope of changing the spec.

Yes, that makes sense, re: symbol-placement. I suppose this is the beginning of an idea with regard to styling connecting arrow lines such that they are cognitively pleasant regardless of zoom level. If there is room for many mid-line arrows, great. But human-wise, the final arrow should point to the destination.