[NAD] Edge routing (#714)

* Introduce EdgeRouting and CustomPathsRouting
* Add unit test and fixes
* Fix direction start
* Fix text-edge style
* Compute text edge points at once instead of shifting it in SvgWriter
* Fix code smells
* Add missing Objects.requireNonNull
* Compute arrow point and angle in EdgeRouting
* Add documentation
* Fix code smells
* Rename CustomPathsRouting -> CustomPathRouting
* Create RadiusUtils replacing public static methods of SvgWriter
* Fixes

---------

Signed-off-by: Florian Dupuy <florian.dupuy@rte-france.com>

Author: flo-dup

docs/_static/img/nad/3wt-edges.png

@@ -0,0 +1,44 @@
+# Edge Routing
+
+The `EdgeRouting` interface provides a way to customize the computation of paths of the network-area diagram.
+The chosen edge routing can be specified through `NadParameters::setEdgeRouting`.
+Note that, internally, the edge routing is passed to the `SvgWriter` which launches the computation.
+
+Currently, there are 2 implementations of the `EdgeRouting`: the `StraightEdgeRouting` and the `CustomPathRouting`.
+The default implementation if none specified is the `StraightEdgeRouting`.
+
+## Common features
+The common features are factorized in the abstract class `AbstractEdgeRouting`.
+
+### Loops
+The loop edges points are computed so that they are distributed between branch edges when the space available is big enough.
+
+![loops](/_static/img/nad/loops-distribution.png)
+
+### Injections
+If injections are displayed, the injection edge points are computed similarly to loops: they are distributed between branch edges when the space available is big enough.
+
+![injections](/_static/img/nad/injections-distribution.png)
+
+### Three-winding transformers
+The three-winding edge points are computed by finding a "leading" transformer edge and then placing the other edges at 120°.
+The leading edge is defined as the opposite edge of the smallest aperture.
+
+![3WTedges](/_static/img/nad/3wt-edges.png)
+
+## StraightEdgeRouting feature
+In the `StraightEdgeRouting` implementation,
+- the parallel edges points are computed so that they form a fork,
+- the other edges points are computed as straight lines.
+
+![forkstraight](/_static/img/nad/fork-straight.png)
+
+## CustomPathRouting feature
+In the `CustomPathRouting` implementation, custom paths can be provided through two maps in the constructor
+- a map whose keys are branch ids and whose values are the list of "bending" points to add to the corresponding branch edge,
+- a map whose keys are voltage level ids and whose values are the list of "bending" points to add to the corresponding text edge.
+
+If a branch id is missing in the given map, we fall back to `StraightEdgeRouting` implementation.
+Similarly for text edges, if a voltage level id is missing in the corresponding map, we fall back to `StraightEdgeRouting` implementation.
+
+![custompaths](/_static/img/nad/custom-paths.png)

docs/_static/img/nad/custom-paths.png

@@ -10,6 +10,7 @@ hidden: true
 layout/layout.md
 labelProvider/labelProvider.md
 styleProvider/styleProvider.md
+edgeRouting/edgeRouting.md
 ```
 
 
@@ -21,6 +22,7 @@ The powsybl-network-area-diagram artifact provides features to generate concise
     - Possible use of your own graph layout implementation;
     - Possible use of your own label provider to display custom directed values on the graph edges (default label provider displays the active power);
     - Possible use of your own style provider to have a custom style for nodes and edges (default style provider gives the nodes and edges a class corresponding to their voltage level and gives disconnected lines a specific class);
+    - Possible use of your own edge routing to have custom edge paths;
     - Possible use of your custom layout parameters and svg rendering parameters.
 
 ![nad-example](/_static/img/nad/nad-example.png)

docs/_static/img/nad/fork-straight.png

@@ -14,6 +14,8 @@
 import com.powsybl.nad.layout.LayoutParameters;
 import com.powsybl.nad.library.DefaultComponentLibrary;
 import com.powsybl.nad.library.NadComponentLibrary;
+import com.powsybl.nad.routing.StraightEdgeRouting;
+import com.powsybl.nad.routing.EdgeRouting;
 import com.powsybl.nad.svg.LabelProvider;
 import com.powsybl.nad.svg.SvgParameters;
 import com.powsybl.nad.svg.iidm.*;
@@ -33,6 +35,7 @@ public class NadParameters {
     private LayoutFactory layoutFactory = new BasicForceLayoutFactory();
     private IdProviderFactory idProviderFactory = IntIdProvider::new;
     private NadComponentLibrary componentLibrary = new DefaultComponentLibrary();
+    private EdgeRouting edgeRouting = new StraightEdgeRouting();
 
     public SvgParameters getSvgParameters() {
         return svgParameters;
@@ -96,4 +99,13 @@ public NadParameters setComponentLibrary(NadComponentLibrary componentLibrary) {
         this.componentLibrary = componentLibrary;
         return this;
     }
+
+    public EdgeRouting getEdgeRouting() {
+        return edgeRouting;
+    }
+
+    public NadParameters setEdgeRouting(EdgeRouting edgeRouting) {
+        this.edgeRouting = edgeRouting;
+        return this;
+    }
 }

docs/_static/img/nad/injections-distribution.png

@@ -103,7 +103,7 @@ private static Graph getLayoutResult(Network network, NadParameters param, Predi
 
     private static SvgWriter createSvgWriter(Network network, NadParameters param) {
         return new SvgWriter(param.getSvgParameters(), param.getStyleProviderFactory().create(network),
-                param.createLabelProvider(network), param.getComponentLibrary());
+                param.createLabelProvider(network), param.getComponentLibrary(), param.getEdgeRouting());
     }
 
     private static Path getMetadataPath(Path svgPath) {

docs/_static/img/nad/loops-distribution.png

@@ -37,6 +37,10 @@ public int getNum() {
 
     private List<Point> points1 = Collections.emptyList();
     private List<Point> points2 = Collections.emptyList();
+    private Point arrowPoint1 = new Point();
+    private Point arrowPoint2 = new Point();
+    private double arrowAngle1;
+    private double arrowAngle2;
     private final boolean[] visible = new boolean[] {true, true};
 
     public BranchEdge(String diagramId, String equipmentId, String nameOrId, String type) {
@@ -79,6 +83,50 @@ public void setPoints2(Point... points) {
         this.points2 = Arrays.asList(points);
     }
 
+    public Point getArrow(Side side) {
+        Objects.requireNonNull(side);
+        return side == Side.ONE ? getArrowPoint1() : getArrowPoint2();
+    }
+
+    public Point getArrowPoint1() {
+        return arrowPoint1;
+    }
+
+    public Point getArrowPoint2() {
+        return arrowPoint2;
+    }
+
+    public void setArrow(Side side, Point arrow) {
+        Objects.requireNonNull(side);
+        if (side == Side.ONE) {
+            setArrowPoint1(arrow);
+        } else {
+            setArrowPoint2(arrow);
+        }
+    }
+
+    public void setArrowPoint1(Point arrowPoint1) {
+        this.arrowPoint1 = arrowPoint1;
+    }
+
+    public void setArrowPoint2(Point arrowPoint2) {
+        this.arrowPoint2 = arrowPoint2;
+    }
+
+    public void setArrowAngle(Side side, double edgeStartAngle) {
+        Objects.requireNonNull(side);
+        if (side == Side.ONE) {
+            this.arrowAngle1 = edgeStartAngle;
+        } else {
+            this.arrowAngle2 = edgeStartAngle;
+        }
+    }
+
+    public double getArrowAngle(Side side) {
+        Objects.requireNonNull(side);
+        return side == Side.ONE ? arrowAngle1 : arrowAngle2;
+    }
+
     public boolean isVisible(Side side) {
         Objects.requireNonNull(side);
         return visible[side.ordinal()];