Merge powsybl-network-area-diagram into powsybl-single-line-diagram

.github/workflows/maven.yml

@@ -34,14 +34,8 @@ jobs:
           mvn --batch-mode -Pjacoco verify sonar:sonar
           -Dsonar.host.url=https://sonarcloud.io
           -Dsonar.organization=powsybl-ci-github
-          -Dsonar.projectKey=com.powsybl:powsybl-single-line-diagram
+          -Dsonar.projectKey=com.powsybl:powsybl-diagram
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
-      - name: Broadcast update event
-        if: matrix.os == 'ubuntu-latest' && github.ref == 'refs/heads/main'
-        uses: gridsuite/broadcast-event@main
-        with:
-          token: ${{ secrets.REPO_ACCESS_TOKEN }}
-          event-type: single_line_diagram_updated

README.md

@@ -1,8 +1,8 @@
-# PowSyBl Single Line Diagram
+# PowSyBl Diagram
 
-[![Actions Status](https://github.com/powsybl/powsybl-single-line-diagram/workflows/CI/badge.svg)](https://github.com/powsybl/powsybl-single-line-diagram/actions)
-[![Coverage Status](https://sonarcloud.io/api/project_badges/measure?project=com.powsybl%3Apowsybl-single-line-diagram&metric=coverage)](https://sonarcloud.io/component_measures?id=com.powsybl%3Apowsybl-single-line-diagram&metric=coverage)
-[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=com.powsybl%3Apowsybl-single-line-diagram&metric=alert_status)](https://sonarcloud.io/dashboard?id=com.powsybl%3Apowsybl-single-line-diagram)
+[![Actions Status](https://github.com/powsybl/powsybl-diagram/workflows/CI/badge.svg)](https://github.com/powsybl/powsybl-diagram/actions)
+[![Coverage Status](https://sonarcloud.io/api/project_badges/measure?project=com.powsybl%3Apowsybl-diagram&metric=coverage)](https://sonarcloud.io/component_measures?id=com.powsybl%3Apowsybl-diagram&metric=coverage)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=com.powsybl%3Apowsybl-diagram&metric=alert_status)](https://sonarcloud.io/dashboard?id=com.powsybl%3Apowsybl-diagram)
 [![MPL-2.0 License](https://img.shields.io/badge/license-MPL_2.0-blue.svg)](https://www.mozilla.org/en-US/MPL/2.0/)
 [![Slack](https://img.shields.io/badge/slack-powsybl-blueviolet.svg?logo=slack)](https://join.slack.com/t/powsybl/shared_invite/zt-rzvbuzjk-nxi0boim1RKPS5PjieI0rA)
 
@@ -17,7 +17,7 @@ within the energy and electricity sectors.
 <img src="https://raw.githubusercontent.com/powsybl/powsybl-gse/main/gse-spi/src/main/resources/images/logo_lfe_powsybl.svg?sanitize=true" alt="PowSyBl Logo" width="50%"/>
 </p>
 
-Read more at https://www.powsybl.org !
+Read more at https://www.powsybl.org!
 
 This project and everyone participating in it is governed by the [PowSyBl Code of Conduct](https://github.com/powsybl/.github/blob/main/CODE_OF_CONDUCT.md).
 By participating, you are expected to uphold this code. Please report unacceptable behavior to [powsybl-tsc@lists.lfenergy.org](mailto:powsybl-tsc@lists.lfenergy.org).
@@ -90,3 +90,97 @@ We obtain the SVG below.
 ![Diagram demo](.github/example_n.svg)
 
 Note that a JSON file named `n_metadata.json` is also generated in the same folder, containing all the metadata needed to interact with the diagram.
+
+
+## PowSyBl vs PowSyBl Network Area Diagram
+
+<p align="center">
+<img src="https://user-images.githubusercontent.com/66690739/158350044-36293484-0b0b-4cca-91fa-e8037d4b76bb.png?sanitize=true" alt="Diagram example" width="50%"/>
+</p>
+
+PowSyBl Network Area Diagram is a component build on top of the `Network` model available in the PowSyBl Core repository responsible for generating a concise diagram of the whole network or of a part of the network, showing in particular the interconnections between the different voltage levels.
+A network area diagram emphasizes the electrical structure of the network, and may differ substantially from the network physical geography.
+It displays the graph whose nodes are the network voltage levels, and whose edges are the lines and transformers between those voltage levels.
+
+## Getting started
+In order to generate a SVG from a given network, we need to add some Maven dependencies:
+- `powsybl-network-area-diagram` for the network area diagram itself
+- `powsybl-iidm-impl` for the network model
+- `powsybl-config-test` and `powsybl-ieee-cdf-converter` to load the `Network` example
+- `slf4j-simple` for simple logging capabilities
+
+```xml
+<properties>
+    <powsybl.nad.version>0.6.0</powsybl.nad.version>
+    <powsybl.core.version>4.10.0</powsybl.core.version>
+    <slf4j.version>1.7.22</slf4j.version>
+</properties>
+
+<dependencies>
+    <dependency>
+        <groupId>com.powsybl</groupId>
+        <artifactId>powsybl-network-area-diagram</artifactId>
+        <version>${powsybl.nad.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>com.powsybl</groupId>
+        <artifactId>powsybl-iidm-impl</artifactId>
+        <version>${powsybl.core.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>com.powsybl</groupId>
+        <artifactId>powsybl-config-test</artifactId>
+        <version>${powsybl.core.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>com.powsybl</groupId>
+        <artifactId>powsybl-ieee-cdf-converter</artifactId>
+        <version>${powsybl.core.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>org.slf4j</groupId>
+        <artifactId>slf4j-simple</artifactId>
+        <version>${slf4j.version}</version>
+    </dependency>
+</dependencies>
+```
+
+Then we simply need to load the IEEE 30-bus example network and then generate the corresponding network area diagram SVG.
+```java
+Network network = IeeeCdfNetworkFactory.create30();
+new NetworkAreaDiagram(network).draw(Path.of("/tmp/diagram.svg"));
+```
+We obtain the following SVG:
+
+<p align="center">
+<img src=".github/diagram_example.svg?sanitize=true" alt="Diagram IEEE30 network" width="65%"/>
+</p>
+
+If only part of the network is wanted, we can generate a partial graph of the network, by providing
+- either a voltage level id and a depth,
+- or a list of voltage level ids and a (unique) depth.
+
+For instance let's generate the subgraph centered on voltage level `"VL25"` with a depth of `2`:
+
+```java
+new NetworkAreaDiagram(network, "VL25", 2).draw(Path.of("/tmp/partial_diagram_25.svg"));
+```
+
+This leads to following diagram:
+
+<p align="center">
+<img src=".github/partial_diagram_example_25.svg?sanitize=true" alt="Diagram IEEE30 partial network VL25" width="80%"/>
+</p>
+
+Now let's generate the subgraph with voltage levels at a maximum distance of 2 from `"VL1"` and `"VL25"`:
+
+```java
+new NetworkAreaDiagram(network, List.of("VL1", "VL25"), 2).draw(Path.of("/tmp/partial_diagram_1_25.svg"));
+```
+
+This gives us the diagram below. Note that nothing ensures that the parts displayed in resulting diagram are connected.
+That is, the voltage levels between two voltage levels which are connected in the full graph are not necessarily drawn.
+
+<p align="center">
+<img src=".github/partial_diagram_example_1_25.svg?sanitize=true" alt="Diagram IEEE30 partial network VL1-VL25" width="65%"/>
+</p>

diagram-util/pom.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2022, RTE (http://www.rte-france.com)
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.powsybl</groupId>
+        <artifactId>powsybl-diagram</artifactId>
+        <version>3.0.0-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>powsybl-diagram-util</artifactId>
+    <name>PowSyBl diagram util</name>
+    <description>Force layout for PowSyBl Diagram</description>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>templating-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>buildnumber-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <!-- compilation dependencies -->
+        <dependency>
+            <groupId>com.powsybl</groupId>
+            <artifactId>powsybl-tools</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.jgrapht</groupId>
+            <artifactId>jgrapht-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
+
+        <!-- test dependencies -->
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

diagram-util/src/main/java-templates/com/powsybl/diagram/util/PowsyblDiagramVersion.java

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2022, RTE (http://www.rte-france.com)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package com.powsybl.diagram.util;
+
+import com.google.auto.service.AutoService;
+import com.powsybl.tools.*;
+
+/**
+ * @author Florian Dupuy <florian.dupuy at rte-france.com>
+ */
+@AutoService(Version.class)
+public class PowsyblDiagramVersion extends AbstractVersion {
+
+    public PowsyblDiagramVersion() {
+        super("powsybl-diagram", "${project.version}", "${buildNumber}", "${scmBranch}", Long.parseLong("${timestamp}"));
+    }
+}

diagram-util/src/main/java/com/powsybl/diagram/util/forcelayout/BoundingBox.java

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2021, RTE (http://www.rte-france.com)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package com.powsybl.diagram.util.forcelayout;
+
+import java.util.Collection;
+
+/**
+ * @author Mathilde Grapin <mathilde.grapin at rte-france.com>
+ */
+public final class BoundingBox {
+
+    private final double left;
+    private final double bottom;
+    private final double right;
+    private final double top;
+
+    private BoundingBox(double left, double top, double right, double bottom) {
+        this.left = left;
+        this.top = top;
+        this.right = right;
+        this.bottom = bottom;
+        if (left > right || bottom < top) {
+            throw new IllegalStateException("Bounding box with negative width or height");
+        }
+    }
+
+    public static BoundingBox computeBoundingBox(Collection<Point> points) {
+        double left = points.stream().mapToDouble(p -> p.getPosition().getX()).min().orElse(-2);
+        double top = points.stream().mapToDouble(p -> p.getPosition().getY()).min().orElse(-2);
+        double right = points.stream().mapToDouble(p -> p.getPosition().getX()).max().orElse(2);
+        double bottom = points.stream().mapToDouble(p -> p.getPosition().getY()).max().orElse(2);
+        return new BoundingBox(left, top, right, bottom);
+    }
+
+    public double getHeight() {
+        return bottom - top;
+    }
+
+    public double getWidth() {
+        return right - left;
+    }
+
+    public double getLeft() {
+        return left;
+    }
+
+    public double getTop() {
+        return top;
+    }
+}

diagram-util/src/main/java/com/powsybl/diagram/util/forcelayout/Canvas.java

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2021, RTE (http://www.rte-france.com)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+package com.powsybl.diagram.util.forcelayout;
+
+import java.util.Objects;
+
+/**
+ * @author Mathilde Grapin <mathilde.grapin at rte-france.com>
+ */
+public class Canvas {
+    private final double width;
+    private final double height;
+    private final BoundingBox boundingBox;
+    private final double margin;
+    private final double scale;
+
+    public Canvas(BoundingBox boundingBox, double height, double margin) {
+        this.boundingBox = Objects.requireNonNull(boundingBox);
+        this.height = height;
+        this.scale = (height - 2 * margin) / boundingBox.getHeight(); // scale has to be computed and used without margins
+        this.width = boundingBox.getWidth() * scale + 2 * margin;
+        this.margin = margin;
+    }
+
+    public Vector toScreen(Vector position) {
+        double screenX = (position.getX() - boundingBox.getLeft()) * scale + margin;
+        double screenY = (position.getY() - boundingBox.getTop()) * scale + margin;
+        return new Vector(screenX, screenY);
+    }
+
+    public double getWidth() {
+        return width;
+    }
+
+    public double getHeight() {
+        return height;
+    }
+}