Add the user manual

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
 

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 <>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:ACLineSegment');} }>ACLineSegment</button>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:EnergyConsumer');} }>EnergyConsumer</button>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:PowerTransformer');} }>PowerTransformer</button>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:SynchronousMachine');} }>SynchronousMachine</button>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:TopologicalNode');} }>TopologicalNode</button>
+            <button className="component-type-name button wide-button" onClick={ () => { this.props.getCimsvg().addComponent('cim:Terminal');} }>Terminal</button>
+        </>;
+    }
+}
+```
+
+#### 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,
+    },
+};
+```

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)
+

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)

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
+<!DOCTYPE html>
+<html>
+        <head>
+                <meta charset="UTF-8">
+                <title>Simple Pintura Integration</title>
+        </head>
+        <body>
+                <style>
+                        .grid {
+                                display: none;
+                        }
+                        .backing {
+                                fill: transparent;
+                        }
+                </style>
+                <div id=svg-panel>
+                        <svg id="cim" width="800" height="600">
+                                <rect class="backing" />
+                                <g class="grid" />
+                                <g class="diagrams" />
+                        </svg>
+                </div>
+                <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.7.6/handlebars.runtime.min.js"> </script>
+                <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.2.0/jszip.min.js"> </script>
+                <script type="text/javascript" src="https://sogno.energy/pintura/dist/libcimsvg.js"></script>
+                <script language="javascript" type="text/javascript">
+                        var currentCimsvg = libcimsvg.currentCimsvg;
+                        var svg = document.getElementById("svg-panel");
+                        var cimsvg = libcimsvg.cimsvg;
+                        var cimsvgInstance = new cimsvg(svg);
+                        cimsvgInstance.downloadUri("http://localhost:8082/example.zip");
+                        cimsvgInstance.fit();
+                </script>
+        </body>
+</html>
+```
+
+#### What will it look like?
+
+The grid and the backing colour are disabled in the <style> tags.
+While it is not possible to show the attributes without the menu, hovering over
+a component will reveal the component's name.
+
+![Picture of the small example](pintura.png)