extends NadProfile with style customizations (#976)

Signed-off-by: Christian Biasuzzi <christian.biasuzzi@soft.it>

Author: CBiasuzzi

cpp/powsybl-cpp/powsybl-cpp.cpp

@@ -723,11 +723,11 @@ std::vector<std::string> getMatrixMultiSubstationSvgAndMetadata(const JavaHandle
 }
 
 void writeNetworkAreaDiagramSvg(const JavaHandle& network, const std::string& svgFile, const std::string& metadataFile, const std::vector<std::string>& voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters, dataframe* fixed_positions,
-    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions) {
+    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions, dataframe* bus_node_styles, dataframe* edge_styles, dataframe* three_wt_styles) {
     auto c_parameters = parameters.to_c_struct();
     ToCharPtrPtr voltageLevelIdPtr(voltageLevelIds);
     PowsyblCaller::get()->callJava(::writeNetworkAreaDiagramSvg, network, (char*) svgFile.data(), (char*) metadataFile.data(),
-        voltageLevelIdPtr.get(), voltageLevelIds.size(), depth, highNominalVoltageBound, lowNominalVoltageBound, c_parameters.get(), fixed_positions, branch_labels, three_wt_labels, bus_descriptions, vl_descriptions);
+        voltageLevelIdPtr.get(), voltageLevelIds.size(), depth, highNominalVoltageBound, lowNominalVoltageBound, c_parameters.get(), fixed_positions, branch_labels, three_wt_labels, bus_descriptions, vl_descriptions, bus_node_styles, edge_styles, three_wt_styles);
 }
 
 std::string getNetworkAreaDiagramSvg(const JavaHandle& network, const std::vector<std::string>&  voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters) {
@@ -737,10 +737,10 @@ std::string getNetworkAreaDiagramSvg(const JavaHandle& network, const std::vecto
 }
 
 std::vector<std::string> getNetworkAreaDiagramSvgAndMetadata(const JavaHandle& network, const std::vector<std::string>&  voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters, dataframe* fixed_positions,
-    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions) {
+    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions, dataframe* bus_node_styles, dataframe* edge_styles, dataframe* three_wt_styles) {
     auto c_parameters = parameters.to_c_struct();
     ToCharPtrPtr voltageLevelIdPtr(voltageLevelIds);
-    auto svgAndMetadataArrayPtr = PowsyblCaller::get()->callJava<array*>(::getNetworkAreaDiagramSvgAndMetadata, network, voltageLevelIdPtr.get(), voltageLevelIds.size(), depth, highNominalVoltageBound, lowNominalVoltageBound, c_parameters.get(), fixed_positions, branch_labels, three_wt_labels, bus_descriptions, vl_descriptions);
+    auto svgAndMetadataArrayPtr = PowsyblCaller::get()->callJava<array*>(::getNetworkAreaDiagramSvgAndMetadata, network, voltageLevelIdPtr.get(), voltageLevelIds.size(), depth, highNominalVoltageBound, lowNominalVoltageBound, c_parameters.get(), fixed_positions, branch_labels, three_wt_labels, bus_descriptions, vl_descriptions, bus_node_styles, edge_styles, three_wt_styles);
     ToStringVector svgAndMetadata(svgAndMetadataArrayPtr);
     return svgAndMetadata.get();
 }

cpp/powsybl-cpp/powsybl-cpp.h

@@ -581,12 +581,12 @@ std::vector<std::string> getMatrixMultiSubstationSvgAndMetadata(const JavaHandle
 std::vector<std::string> getSingleLineDiagramComponentLibraryNames();
 
 void writeNetworkAreaDiagramSvg(const JavaHandle& network, const std::string& svgFile, const std::string& metadataFile, const std::vector<std::string>& voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters, dataframe* fixed_positions,
-    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions);
+    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions, dataframe* bus_node_styles, dataframe* edge_styles, dataframe* three_wt_styles);
 
 std::string getNetworkAreaDiagramSvg(const JavaHandle& network, const std::vector<std::string>& voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters);
 
 std::vector<std::string> getNetworkAreaDiagramSvgAndMetadata(const JavaHandle& network, const std::vector<std::string>& voltageLevelIds, int depth, double highNominalVoltageBound, double lowNominalVoltageBound, const NadParameters& parameters, dataframe* fixed_positions,
-    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions);
+    dataframe* branch_labels, dataframe* three_wt_labels, dataframe* bus_descriptions, dataframe* vl_descriptions, dataframe* bus_node_styles, dataframe* edge_styles, dataframe* three_wt_styles);
 
 std::vector<std::string> getNetworkAreaDiagramDisplayedVoltageLevels(const JavaHandle& network, const std::vector<std::string>& voltageLevelIds, int depth);
 

cpp/pypowsybl-cpp/bindings.cpp

@@ -687,14 +687,15 @@ PYBIND11_MODULE(_pypowsybl, m) {
     m.def("write_network_area_diagram_svg", &pypowsybl::writeNetworkAreaDiagramSvg, "Write network area diagram SVG",
           py::arg("network"), py::arg("svg_file"), py::arg("metadata_file"), py::arg("voltage_level_ids"),
           py::arg("depth"), py::arg("high_nominal_voltage_bound"), py::arg("low_nominal_voltage_bound"), py::arg("nad_parameters"), py::arg("fixed_positions"),
-          py::arg("branch_labels"), py::arg("three_wt_labels"), py::arg("bus_descriptions"), py::arg("vl_descriptions"));
+          py::arg("branch_labels"), py::arg("three_wt_labels"), py::arg("bus_descriptions"), py::arg("vl_descriptions"),
+          py::arg("bus_node_styles"), py::arg("edge_styles"), py::arg("three_wt_styles"));
 
     m.def("get_network_area_diagram_svg", &pypowsybl::getNetworkAreaDiagramSvg, "Get network area diagram SVG as a string",
           py::arg("network"), py::arg("voltage_level_ids"), py::arg("depth"), py::arg("high_nominal_voltage_bound"), py::arg("low_nominal_voltage_bound"), py::arg("nad_parameters"));
 
     m.def("get_network_area_diagram_svg_and_metadata", &pypowsybl::getNetworkAreaDiagramSvgAndMetadata, "Get network area diagram SVG and its metadata as a list of strings",
           py::arg("network"), py::arg("voltage_level_ids"), py::arg("depth"), py::arg("high_nominal_voltage_bound"), py::arg("low_nominal_voltage_bound"), py::arg("nad_parameters"), py::arg("fixed_positions"),
-          py::arg("branch_labels"), py::arg("three_wt_labels"), py::arg("bus_descriptions"), py::arg("vl_descriptions"));
+          py::arg("branch_labels"), py::arg("three_wt_labels"), py::arg("bus_descriptions"), py::arg("vl_descriptions"), py::arg("bus_node_styles"), py::arg("edge_styles"), py::arg("three_wt_styles"));
 
     m.def("get_network_area_diagram_displayed_voltage_levels", &pypowsybl::getNetworkAreaDiagramDisplayedVoltageLevels, "Get network area diagram displayed voltage level",
           py::arg("network"), py::arg("voltage_level_ids"), py::arg("depth"));

docs/user_guide/network_visualization.rst

@@ -352,7 +352,20 @@ by using dataframes:
                                                   {'id': 'S2VL1_0', 'description': 'BUS C'},
                                                   {'id': 'S3VL1_0', 'description': 'BUS D'}
                                               ])
-    >>> diagram_profile=pp.network.NadProfile(branch_labels=labels_df, vl_descriptions=vl_descriptions_df, bus_descriptions=bus_descriptions_df)
+    >>> bus_node_style_df = pd.DataFrame.from_records(index='id', 
+                                              data=[
+                                                  {'id': 'S1VL1_0', 'fill': 'red', 'edge': 'black', 'edge-width': '4px'},
+                                                  {'id': 'S1VL2_0', 'fill': 'blue', 'edge': 'black', 'edge-width': '4px'},
+                                                  {'id': 'S2VL1_0', 'fill': 'yellow', 'edge': 'black', 'edge-width': '4px'},
+                                              ])
+    >>> edge_style_df = pd.DataFrame.from_records(index='id', 
+                                          data=[
+                                              {'id': 'LINE_S2S3', 'edge1': 'blue', 'width1': '16px', 'dash1': '12,12' ,'edge2': 'blue', 'width2': '16px', 'dash2': '12,12'},
+                                              {'id': 'LINE_S3S4', 'edge1': 'green',  'width1': '3px', 'edge2': 'green',  'width2': '3px'},
+                                              {'id': 'TWT'      , 'edge1': 'yellow', 'width1': '4px', 'edge2': 'blue',  'width2': '4px'},
+                                          ])
+    >>> diagram_profile=pp.network.NadProfile(branch_labels=labels_df, vl_descriptions=vl_descriptions_df, bus_descriptions=bus_descriptions_df,
+                                      bus_node_styles=bus_node_style_df, edge_styles=edge_style_df)
     >>> pars=pp.network.NadParameters(edge_name_displayed=True)
     >>> network.get_network_area_diagram(voltage_level_ids='S1VL1', depth=2, nad_parameters=pars, nad_profile=diagram_profile)
 
@@ -371,11 +384,30 @@ In the bus_descriptions dataframe parameter:
     - id is the BUS id
     - description define a label for the BUS
 
+In the bus_node_styles dataframe parameter:
+    - id is the BUS id
+    - fill is the fill color for the node
+    - edge is the edge color for the node
+    - width is the width of the edge for the node
+
+In the edge_styles dataframe parameter:
+    - id is the branch id
+    - edge1, width1 and dash1 is the color, the width and the dash pattern for the first branch's edge
+    - edge2, width2 and dash2 is the color, the width and the dash pattern for the second branch's edge
+
+The dash pattern string specifies the lengths of alternating dashes and gaps in the edge, separated by commas and/or spaces
+
 An additional three_wt_labels dataframe parameter can be used to set the labels and the arrows direction for three winding transformers:
     - id is the three winding transformer id
     - side1, side2, and side3 define the labels along the three winding transformer legs
     - arrow1, arrow2, and arrow3 define the direction of the arrows at the ends of the three winding transformer legs: 'IN' or 'OUT'. None (or an empty string) does not display the arrow.
 
+Similarly to the edge_styles, the three_wt_styles parameter can be used to set the style for the three winding transformers:
+    - id is the three winding transformer id
+    - edge1, width1 and dash1 is the color, the width and the dash pattern for the first transformer's leg
+    - edge2, width2 and dash2 is the color, the width and the dash pattern for the second transformer's leg
+    - edge3, width3 and dash3 is the color, the width and the dash pattern for the third transformer's leg
+
 The optional parameter nad_profile can also be set in the write_network_area_diagram function.
 
 Network area diagram using geographical data