Drake: Need a Way to Visualize Diagram

[liangfok]

It would be nice to have a visual representation of a Diagram. Perhaps we can add a Diagram::DrawDiagram() method that returns a Graphviz .dot ~file~ string for visualizing it. This'll be similar to RigidBodyTree::drawKinematicTree().

[jwnimmer-tri]

:+1: to a Diagram method that returns a dot string; :-1: to a Diagram method that opens and writes to a file.

[patmarion]

It would nice if classes could export their input and output port documentation. Most of this information has been carefully documented within code comments, but it could be formalized, so that you could extract this information either programmatically or via a doxygen mechanism would be awesome. Programmers could give each input and output port a:

• short descriptive name
• longer documentation

[david-german-tri]

Both @liangfok and @patmarion's requests make sense to me, and I'd be happy to review, and/or get to it myself eventually. (In the case of @patmarion's request, a few more sentences of design might be a good idea before code.)

[patmarion]

I'll leave it to you to design, but I'll offer an example:

Current code found in kuka_simulation.cc:

// This system has two input ports.  Input port zero is for the
// current state of the plant and input port one for the most recently
// received command.
class IiwaStatusSender : public systems::LeafSystem {
 public:
  IiwaStatusSender() {
    this->DeclareInputPort(systems::kVectorValued, kNumJoints * 2,
                           systems::kContinuousSampling);
    this->DeclareInputPort(systems::kVectorValued, kNumJoints,
                           systems::kContinuousSampling);
    ....

Note, in the above code, the input port documentation is presented in the comments above the class declaration. The input ports are declared in the constructor. Here is a straw man proposal for an alternate form:

class IiwaStatusSender : public systems::LeafSystem {
 public:
  IiwaStatusSender() {
    this->DocumentInputPorts(R"(
    @input_port_0_name State input
    @input_port_0_desc Input port zero is for the current state
    of the plant.
    @input_port_1_name Command input
    @input_port_1_desc Input port one is for the most recently
    received command.
    )");

    this->DeclareInputPort(systems::kVectorValued, kNumJoints * 2,
                           systems::kContinuousSampling);
    this->DeclareInputPort(systems::kVectorValued, kNumJoints,
                           systems::kContinuousSampling);
    ....

In this proposal, there is nothing enforcing that the port numbers in the docs match the order that the ports are declared below, except for peer code review. The doc could be passed to the DeclareInputPort() method, but then I worry it looks messier.

A completely different method might be to put the port documentation in doxygen in the class header. Then a build tool could parse it out of doxygen and generate some c++ code to make it programmatically available like:

DocumentationQuery<IiwaStatusSender>()->GetInputPortDocumentation();

[patmarion]

Just to clarify the motivation for having a formalized method to document input/output ports: it would be so that when you draw the diagram you could have human readable labels attached to the ports. Also, doxygen documentation could have a custom section that details the ports.

[sherm1]

Could the necessary label & description just be stored in the C++ Diagram object and then retrieved by introspection?

[liangfok]

I prefer providing the port documentation through System::DeclareInputPort() and System::DeclareOutputPort() since it explicitly relates the documentation with the port and seems less brittle against changes in port numbers when ports are added and removed.

[david-german-tri]

I've taken this as a Q1 KR, so upping the priority to medium.

[david-german-tri]

5545 fixed this.