Create FPP augmentation language for tools and visualization

[timcanham]

The purpose of this discussion is to start gathering ideas for an augmented FPP specification that would allow an auxiliary file accompanying the main FPP models that would specify layouts for diagramming. Even basic diagrams of components are awkward to render automatically, and automatically rendering non-trivial topologies can turn to "spaghetti" quickly.

The concept of the FPP diagramming augmentation is that the augmentation files would exist alongside normal FPP files and provide extra metadata about how to arrange diagrams. That would allow either a human to manually arrange the diagrams via editing the extra file, or a GUI with graphical tools to arrange objects could generate it. A separate file allows the FPP model file to be "pure" FPP, uncluttered by the augmented code. The FPP spec could allow the files to be combined, but that would seem sub-optimal from a human readability perspective.

For the sake of discussion, the component file could have specifications like:

component CommandDispatcher {
   position: 12,22,50,100 # x location, y location, x size, y size
   port compCmdSend: left, 10, red # left side of component, 10 down from top left, colored red
   (so on)
}

The topology file could have specifications like:

instance cmdDisp {
   # specify locations for topology to aid clean interconnections
   position: 1000,2000, 150, 170 
   port compCmdSend: left, 10, red
      connection: right 100 then up 10 then right 10 # modeled on pic 
}

[bocchino]

I like this idea! I suggest adding a keyword in front of component, instance, etc. to distinguish the drawing info from the modeling info. It could be something like

draw component CommandDispatcher {
  ...
}

Then any symbol that is in scope could have any number of draw annotations attached to it, and they would all be aggregated and applied to the component (or instance, etc.) when drawing the topology.

[bocchino]

You could also have

draw Topology Ref {
  ...
  instance ...
}

for drawing the instances in the Ref topology.

[timcanham]

Would the draw Topology XXX be only defined in one place? If we wanted to draw multiple views in different files (perhaps), it would seem to make more sense have something like:

draw view RateGroups {
   instance cmdDisp...
}

or, maybe:

draw topology Ref {
   view RateGroups {
       instance cmdDisp...
   }
}

That way components could appear in multiple views.

[bocchino]

Yes, I agree that we would want to lay out instances separately for each named connection group.

[bocchino]

For reference, here is a link to a modern implementation of the classic pic drawing language inside of Markdown: https://pikchr.org/home/doc/trunk/homepage.md. It looks like it's not yet integrated with GitHub-flavored Markdown.

[bocchino]

Even basic diagrams of components are awkward to render automatically, and automatically rendering non-trivial topologies can turn to "spaghetti" quickly.

I actually think that it is possible to have nice-looking auto-generated diagrams. One just has to accept some limitations, e.g., breaking the diagram up into sub-diagrams to remove edges that cross or go back and forth. Here is an example of an auto-generated diagram that is simple but not entirely trivial and looks nice:

https://github.com/fprime-community/fprime-layout/blob/main/examples/ref/RateGroups/RateGroups.pdf

This diagram was generated automatically from the FPP Ref topology with the fprime-layout tool. I agree that if one is not willing to break up diagrams this way, then at some point one needs manual layout like this.