From 21dddc156577988e00acb094e8ee4f6a1b97eb27 Mon Sep 17 00:00:00 2001 From: Richard Marston Date: Mon, 16 Jan 2023 15:54:55 +0100 Subject: [PATCH] Add the user manual Signed-off-by: Richard Marston --- README.md | 53 ++++++++++--- docs/AddingComponent.md | 114 +++++++++++++++++++++++++++ docs/Development.md | 45 +++++++++++ docs/Manual.md | 103 ++++++++++++++++++++++++ docs/UsingLibcimsvg.md | 58 ++++++++++++++ docs/add_energy_consumer.gif | Bin 0 -> 270052 bytes docs/add_terminal_to_syncmachine.gif | Bin 0 -> 693189 bytes docs/add_topological_node.gif | Bin 0 -> 132953 bytes docs/change_terminal_name.gif | Bin 0 -> 535880 bytes docs/components.svg | 4 + docs/delete_component.gif | Bin 0 -> 126257 bytes docs/file_open.gif | Bin 0 -> 454273 bytes docs/file_save.gif | Bin 0 -> 514132 bytes docs/join_topological_nodes.gif | Bin 0 -> 384560 bytes docs/multiple_diagrams.gif | Bin 0 -> 498669 bytes docs/new_diagram.gif | Bin 0 -> 52712 bytes docs/pan_and_zoom.gif | Bin 0 -> 697792 bytes docs/pintura.arch.svg | 4 + docs/pintura.png | Bin 0 -> 51870 bytes 19 files changed, 371 insertions(+), 10 deletions(-) create mode 100644 docs/AddingComponent.md create mode 100644 docs/Development.md create mode 100644 docs/Manual.md create mode 100644 docs/UsingLibcimsvg.md create mode 100644 docs/add_energy_consumer.gif create mode 100644 docs/add_terminal_to_syncmachine.gif create mode 100644 docs/add_topological_node.gif create mode 100644 docs/change_terminal_name.gif create mode 100644 docs/components.svg create mode 100644 docs/delete_component.gif create mode 100644 docs/file_open.gif create mode 100644 docs/file_save.gif create mode 100644 docs/join_topological_nodes.gif create mode 100644 docs/multiple_diagrams.gif create mode 100644 docs/new_diagram.gif create mode 100644 docs/pan_and_zoom.gif create mode 100644 docs/pintura.arch.svg create mode 100644 docs/pintura.png diff --git a/README.md b/README.md index a9baff0..e7ba326 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,55 @@ # Pintura -## Getting Started +## What does it do? + +Pintura can make a graphical representation of CIM-formatted power grid models. +Creation, editing and exporting of the CIM files is possible. +Part of Pintura (libcimsvg) can be used as a standalone library to generate an SVG +representation of a CIM power network. -### Build Docker image +## Will my data get uploaded somewhere? -```bash -$ make -``` +No. Pintura code only runs locally in the browser and data is all handled locally. You can save to an external +link, but then you will have to arrange access to a server to upload it to and actively cause it to happen. + +## How can I use Pintura myself? + +There is an online demo available here: https://sogno.energy/pintura -### Start it up +## How can I run it on my own computer? + +#### This is easy if you have docker and make installed on your computer ```bash -$ make start +$ make && make start ``` -## Developer notes +After the scripts have finished running, they will tell you the url from which you can access Pintura. + +## How do I do anything with it? + +The user manual is [here.](docs/Manual.md) + +## How can I add support for a new component? + +This process is fairly simple and is documented [here.](docs/AddingComponent.md) + +## I just want to show the picture. How do I use libcimsvg without all the menus and stuff? + +This is described in more detail [here.](docs/UsingLibcimsvg.md) + +## How does it work? + +There is information for developers [here.](docs/Development.md) + +## Known problems -### Cimmenu +* Refreshing the browser loses your work +* There is no undo button +* If you change the unique identifier for a component, it will lose track of it +* It should be possible to specify a subclass as the value for an attribute. It would be possible +to select it, but there is no way to add the component. +* If you haven't added a diagram, you can't start adding components +* There's no way to remove a diagram once it has been added -#### Cimgen diff --git a/docs/AddingComponent.md b/docs/AddingComponent.md new file mode 100644 index 0000000..dd8eb14 --- /dev/null +++ b/docs/AddingComponent.md @@ -0,0 +1,114 @@ + +## How to add a new component type to Pintura + +Pintura currently (release 0.4.17) supports the creation of the following component types: + +| Component type | +|----------------| +| AC Line Segment | +| Energy Consumer | +| Power Transformer | +| Synchronous Machine | +| Topological Node | + + +#### Add the component type to the menu + +in cimmenu/src/react-menu.js: + +```javascript +class CreateNewComponentList extends React.Component { + + constructor(props) { + super(props); + } + + render() { + return <> + + + + + + + ; + } +} +``` + +#### Create a new icon in cimsvg/images. +The icons are svg images created using paths. If you are not interested in creating an image in this way you can use +inkscape or any other svg editor. + + +#### Create a new entry in the icon list + +in cimsvg/src/cimjson.js: + +```javascript +cimjson.imageNames = { + "cim:ACLineSegment": term, + "cim:Terminal": term, + "cim:Breaker": brea, + "cim:ConnectivityNode": conn, + "cim:EnergyConsumer": cons, + "cim:EquivalentInjection": cons, + "cim:ExternalNetworkInjection": net, + "cim:PowerTransformer": tran, + "cim:SolarGeneratingUnit": sola, + "cim:SynchronousMachine": sync, + "cim:TopologicalNode": conn, + "cim:TransformerWinding": tran, + "generic": gene +}; +``` + +If you do not create a new svg file, the generic icon will be used. The generic icon looks like a question mark. + +#### Create a new entry in the terminal and points list + +```javascript +cimedit.terminalAndPointLimits = { + "cim:ACLineSegment": { + "minTerminals" : 2, + "maxTerminals" : 2, + "points": 2, + "terminalStyle": cimedit.linePoints, + }, + "cim:Busbar": { + "minTerminals" : 2, + "maxTerminals" : 2, + "points": 2, + "terminalStyle": cimedit.linePoints, + }, + "cim:Terminal": { + "minTerminals" : 0, + "maxTerminals" : 0, + "points": 1, + }, + "cim:TopologicalNode": { + "minTerminals" : 0, + "maxTerminals" : 0, + "points": 2, + "terminalStyle": cimedit.linePoints, + }, + "cim:EnergyConsumer": { + "minTerminals" : 1, + "maxTerminals" : 4, + "points": 1, + "terminalStyle": cimedit.constellationPoints, + }, + "cim:PowerTransformer": { + "minTerminals" : 1, + "maxTerminals" : 4, + "points": 1, + "terminalStyle": cimedit.constellationPoints, + }, + "cim:SynchronousMachine": { + "minTerminals" : 1, + "maxTerminals" : 4, + "points": 1, + "terminalStyle": cimedit.constellationPoints, + }, +}; +``` diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..7654a96 --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,45 @@ + +# Developing on Pintura + +## How does it work? + +Here is a diagram of how the software components interact: + +![Pintura components](pintura.arch.svg) + +There are 3 libraries that are loaded to make pintura work: + +### Cimsvg + ++ Graphical representation of power grids (the main diagram) + ++ Selection of components in the diagram for display in the menu + ++ Changing the location of a component in the diagram + +### Cimmenu + ++ Showing a list of the components grouped by type + ++ Showing / editing attributes for each component + ++ Adding new components to the diagram + ++ Adding new diagrams and selecting which diagram to work on + ++ File actions (importing and exporting models) + + * Multi-profile zip file + + * Single XML file containing all profiles + + * Exporting to an SVG file (picture of the grid) + +### Cgmes + ++ Rendering the components as a list of attributes (when the component is selected to be displayed in the menu) + ++ Rendering the components as a member of a list of attributes (when the component is one of the attributes in a component that has been selected to be displayed in the menu) + ++ Deciding whether a component belongs in a profile or not (for file export) + diff --git a/docs/Manual.md b/docs/Manual.md new file mode 100644 index 0000000..7799b4a --- /dev/null +++ b/docs/Manual.md @@ -0,0 +1,103 @@ +# Pintura Manual + +## How do I.. + +### How do items connect? + +![Image showing how items are connected in Pintura](components.svg) + +### Create a new network diagram + +Select the diagram tab. This is the middle tab in the left hand panel. +Then click the "New Diagram" button. + +![Image of user creating a new diagram](new_diagram.gif) + +### Add a topological node to a network + +Select the components tab. This is the right hand tab in the left hand panel. +Select your diagram from the dropdown, then click on "Topological Node". +Move your pointer over the network diagram and you will see that it has changed to indicate +that a topological node will be added when you click. Click on the diagram where you want +to place it. + +![Image of user adding a topological node](add_topological_node.gif) + +### Join two topological nodes that form part of a network + +Add two topological nodes to the diagram. Then add an AC Line Segment to the diagram. +This will be used to connect the two topological nodes. In the diagram menu, open the terminal +component list and select the terminal called "cim:ACLineSegment1-terminal1". The attributes +for the terminal will de displayed in the right hand menu. Change the "TopologicalNode" +node attribute to the topologicalnode called "cim:TopologicalNode1". Then go back to the diagram +tab and select the terminal called "cim:ACLineSegment-terminal2". Change the "TopologicalNode" +attribute to "cim:TopologicalNode2". + +![Image of user joining two topological nodes](join_topological_nodes.gif) + +### Add a new component to the network and connect it to a topological node + +Select the add component tab (right-hand tab in the left-hand panel). Click on the EnergyConsumer, +PowerTransformer or SynchronousMachine buttons. When you move your pointer over the main diagram it +will show an icon of the component you chose, to indicate which type of component will be added. +Click on the diagram in the place you wish to put the component. We then need to associate the +component's terminal with the topological node that it should be connected to. Show the terminal's +attributes, either by clicking on the terminal or selecting it in the diagram menu. Select the +topological node from the "cim:TopologicalNode" attribute dropdown menu. + +![Image of user adding a component to a topological node](add_energy_consumer.gif) + +### Adding a terminal to a component + +Once you have added the component, add a terminal and place it adjacent to the component you wish +to add it to. Then find the terminal in the diagram menu and update the "ConductingEquipment" +attribute to the component you are adding the terminal to. The terminal will now follow the +component if you move the component somewhere else on the grid. + +![Image of user adding a terminal to a component](add_terminal_to_syncmachine.gif) + +### Changing the name of a component + +When the attributes for a component are displayed in the attributes (right-hand) panel, it is +possible to update them. In the example below the name of a terminal is changed to fit the +convention used for the other terminals. Do not change the mRID value, because this will corrupt +links in the CIM file. + +![Image of user changing the name of a component](change_terminal_name.gif) + +### Adding a new diagram and selecting which is visible. + +From the diagrams tab (middle of the left-hand pane) click on the "New Diagram" button. +To show or hide the diagram, click on the star next to the diagram name. + +![Image of user using multiple diagrams](multiple_diagrams.gif) + +### Pan and zoom + +The arrow keys will move the viewing field around the diagram. Holding Ctrl (Strg) and using the +up and down keys will zoom in and out. It is also possible to drag the grid using the pointer. + +![Image of user panning and zooming](pan_and_zoom.gif) + +### Deleting a component + +Right-click on a component to show the delete option. You will also need to delete the terminals +if you don't want them any more. + +![Image of user deleting a component](delete_component.gif) + +### Open an existing CIM file + +Make sure the file tab is selected and click "Open file". +Then use the file dialog to select the files you wish to open. + + +![Image of user opening a file](file_open.gif) + + +### Save the network to a multi-profile zip file + +On the file menu, select save file, then use the file dialog to choose +where to save the file. + +![Image of user saving a file](file_save.gif) diff --git a/docs/UsingLibcimsvg.md b/docs/UsingLibcimsvg.md new file mode 100644 index 0000000..8192d68 --- /dev/null +++ b/docs/UsingLibcimsvg.md @@ -0,0 +1,58 @@ + +## Using Libcimsvg in other projects + +### How do I include a diagram in my web page? +The html below is demonstration code to show how libcimsvg can be used to show a +graphical representation of a model in a web page. The easiest way to try this out is: + +```bash +$make dev && make start +``` + +Then navigate to http://localhost:8082/example.html + +```html + + + + + Simple Pintura Integration + + + +
+ + + + + +
+ + + + + + +``` + +#### What will it look like? + +The grid and the backing colour are disabled in the