GraphViz is not good enough

+14 votes
asked Aug 16, 2016 in Wanted features by fredizzimo (260 points)
edited Aug 17, 2016 by fredizzimo

Hi,

I love the, idea of PlantUML, to be able to define UML diagrams in a textual form. The diagrams are really fast to write that way. But the problem is that the generated visual representation is far from what one would expect, they are almost useful as a tool for communicatng.

This has been brought up here for example https://github.com/plantuml/plantuml/issues/13. There's also several questions and suggestions here regarding better manual control of the layouts.

While it's possible to somewhat control the layout, by changing the direction of arrows, using hidden arrows and using Hidden groups, I don't think that's a good idea.Once you start doing tricks like that you can easily waste more time, than what you would have, by using a visual tool. It's certainly more annoying, and mostly a question of trial and error. Things could get better by giving more control, but I don't want more control, I want it to "just work".

Therefore I really wish that the automatic layout generation was much better. And I believe it's possible by switching to the Open Graph Drawing Framework instead of GraphViz. I did some experiments by adding "!pragma svek_trace on" to a relatively simple diagram. That generates a dot file, which I modified a little bit to allow a really simple program made with OGDF to open it, generate a layout and save it as svg. I also tried to use neato instead of dot for the generation, which was possible by just running dot.exe with different parameters, and adding "overlap=false" to the dot file. So it seams that integrating neato into the existing svek architecture should be really easy.

So let's do some comparison, first the original dot generated diagram

Then the same diagram with neato, as you can see it's still very far from good. It also loses the nice propery of the arrows going in one direction, which is good for class diagrams. However for state machines this could be a better format

 

Then let's look at the Sugiyama layout of OGDF (with OptimalRanking, MedianHeuristic, and OptimalHierarchyLayout). This layout have most of the same properties of the GraphViz dot layout, but is considerable easier to read. The arrows are not drawn, but it doesn't matter for this example.

There's another very similar one UpwardPlanarizationLayout, with OptimalRanking and OptimalHierarchyLayout. But produces a slightly taller graph, but with less crossings. So it's much better

 

For state machines, and why not for class diagrams too, if you don't care that much of which direction the arrow points. Then a PlanarizationLayout(with VariableEmbeddingInserter, EmbedderMinDeptMaxFaxLayers and OrthoLayout) could be used.

This generates a layout without any crossings whatsovever. 

I didn't import these diagrams back into PlantUML, mostly since OGDF, doesn't export the svg files in the right format for PlantUML.

I checked the svek code, and it seems like support for this would be fairly easy to implement. Instead of generating dot files and importing svg files, you could generate a GML files (specifications), which an ogdf program can easilly read and write without losing any information.

The actual graph generation program (using OGDF) could be a separate project, which just takes a GML file, and converts it according to the commandline options given.

For PlantUML, you would need to add some syntax to specify that the target is that instead of GraphViz. For example by specifying this "ogdf -paramter1 -paramter2=value", at the top of the PlantUML file. The paramters could be anything, and PlantUML would not need to care. Which would help for developing these parts separately. Otherwise PlantUML would have to change each time we add some new way of generating layouts, either new algorithms or parameters for existing ones.

I can implement the external OGDF program, but I wish that you could implement the PlantUML part. Would that be possible? If not, then I will probably be forced to fork my own version of PlantUML, and do it myself, since these quick tests really shows that it would be worth it. The other option I have is to just ignore PlantUML and use a good visual tool.

Edit: Fixed the display of the Planarization diagram

1 Answer

+1 vote
answered Aug 19, 2016 by plantuml (188,280 points)
Thanks for your detail message.

Using OGDF could be a solution. However, we are currently working hard to have a full Java implementation of PlantUML (see http://plantuml.com/smetana02.html and http://plantuml.com/vizjs.html ). A lot of issues we usually get are indeed linked to the fact that GraphViz is an external program: either some too old version is installed, or GraphViz is not well installed or compiled...

So adding a new external program is something that we will consider as an extrem option.

However, another option might be to build a separate .jar file (let's says ogdf.jar) that would embedded native OGDF library, and that would be called by PlantUML. The API of ogdf.jar may be very simple (to be discussed, but just as an example, it could be a static method that would take a String - containing a GML file that would have been generated by PlantUML). The real difficulty here is to use to JNI (Java Native Interface), which is not that easy.

Would you be ok to take care of this ogdf.jar part ? On our side, we could modify plantuml.jar so that ogdf.jar will be used if present. Note that there are probably some important work to be done on both sides!

What do you think about it ?
Thanks again,
commented Aug 19, 2016 by fredizzimo (260 points)
Thanks for you answer.

Yes, I'm actually aware of the effort to convert GraphViz to Java. Although I didn't fully understand the reasons, until now, when you explain it that way. I have browsed through the questions and answers quite a bit, but that hasn't really popped up as a problem for me.

But anyway, in this case I think the situation would be easier, the OGDF program would contain a single executable, which wouldn't need any installation, and could just be placed in the same directory as the PlantUML jar file. The executable could be distributed along the jar file, in the same download for convenience. Also since we have control of the file ourselves, we could add some versioning check, for example PlantUML requests for minver=1.2, and then the OGDF would give an error if the version is too old.

One complication, is that executables are not cross-platform, so we would need several packages for different operating systems. Fortunately we could use the free Travis-CI on Github for compiling for the major platforms, and others supported by manually compiling from the source code. We would have the same problem with JNI too, but with some additional effort I believe that too could be handled with Travis.

Also if you still prefer the JAR approach, even to this single execuable idea, I think far easier would be to embed the executable in the jar file, and just extract it to the temp folder before running. For example like this http://stackoverflow.com/questions/600146/run-exe-which-is-packaged-inside-jar

And yes, the API should be simple, but in additional to the GML file, it should probably pass some options, which could be just another string. I don't think the plantuml.jar itself need to care what the actual options are. The output would be a string containing the GML output. And of course if the standalone exe is used instead of a jar, then we could use stdin and stdout for the GML data, and arguments for the options. Or alternatively generate temp files, like I believe the GraphViz version does.

And yes, I'm willing to take care of either the jar(with embedded exe) or the standalone exe version. However the JNI approach might be too much for me, since I have never actually done anything non-trivial in Java. This includes compiling it for as many platforms as Travis-CI can handle.

Which platform are you working on? I could compile a first version of a standalone executable tomorrow, which would read input from a file or stdin if you rather prefer that, and generate some output with one of the layout algorithms specified above. I think that's the easiest route to go, even if we later switch to embedding it in Java.
commented Aug 20, 2016 by plantuml (188,280 points)
Ok, let's have a simple try with some external .exe
We are mainly working on Windows 10. Is it fine to you?

We prefer a standalone executable (that can have optional command line flags) than read from stdin and generate data to stdout. We don't want to use intermediate temporary file (this is the way we are working with dot)

We also would like to focus first on only one kind of diagram (class, component...) so please tell us which one you'd like.

Even if you send us quickly your executable, it will take us several weeks to investigate arround GML format and to refactor our code, so please do not be too impatient!

Thanks,
commented Aug 22, 2016 by fredizzimo (260 points)
Thanks,

I will be a little bit busy myself for the next few days. But I'll try to have something to test by the end of the week.

For reading and writing the gml format, you could try
https://github.com/tinkerpop/blueprints/wiki/GML-Reader-and-Writer-Library

or

http://jgrapht.org/javadoc/org/jgrapht/ext/GmlExporter.html
commented Oct 5, 2016 by anonymous
This sounds like a great idea. ODGF is very impressive from looking at the OGDF site.

For myself, installing Graphviz is not an issue. I use homebrew on OS X, so it always makes sure the latest is installed. Other OS's would depend on their own package managers or manual installs. I would accept the same approach for installing another external program as being perfectly acceptable.

I honestly do not see the requirement that the user needs to install an external executable in order to generate the graphs as being a particularly difficult or onerous requirement.

As far as porting to a pure Java library, why not do something like a Java port of OGDF instead? If you make it a separate project, it would be useful for a much broader user base.
commented Jan 24, 2017 by Serge Wenger Work (9,890 points)
Hello,

What is the status of this "wanted feature"?
commented Aug 7, 2017 by anonymous
Me too - any progress on this?
commented Nov 22, 2017 by Taylor
Same. Any progress?
...