[feature] Add grouping for connectors to represent f.e. PCB with multiple connectors

[Heenne]

Currently I am documenting the cable harness for my 3D-printer. In this printer is a controller board with over 20 connectors. If I add all these connectors they are not very well grouped to visualize that these connectors are all on one single PCB. Therefore, I would like to propose the following feature:

Add possibility to create a box with a name around a list of connectors to represent and better visualize a single component with multiple connectors.

Thank you for this awesome tool, it is real fun to work with it!

[kvid]

Thank you for sharing your use case. It is possible to group several connectors and/or cables and draw a frame around them with a title text by adding an entry in the tweak section. See an example in #276 (comment) where one connector and one cable is grouped, but you can include many of each in the same group. Notice that connector/cable names need to be quoted when they contain certain characters, e.g space.

[Heenne]

Thank you very much for the quick response. The example you linked is exactly how I imagined it.
If I got time, can I make a pull request to add a simple example for this to the other examples?

[JarrettR]

Also requesting this.

The linked example is a good workaround, but not quite production ready.
The main issues are that it only groups connectors vertically, and (IMO) tweak should be avoided except in the edgiest edge cases.

Here's an example, trimmed down from a WIP of mine:

templates:
  - &molex_fan
    type: Molex KK 254
    subtype: female
    pinlabels: [GND, +12V, TACH, FAN]
    show_pincount: false
  - &ps_small
    type: Molex KK 254
    subtype: female
    pincount: 6
  - &ps_large
    type: Molex KK 254
    subtype: female
    pincount: 22
connectors:
  JB-J22:
    <<: *molex_fan
    notes: "Fan 1"
  JB-J23:
    <<: *molex_fan
    notes: "Fan 2"
  JB-J2:
    <<: *molex_fan
    notes: "Fan 3"
  JB-J24:
    <<: *molex_fan
    notes: "Fan 4"
  JB-J25:
    <<: *molex_fan
    notes: "Fan 5"
  JB-J18:
    <<: *ps_small
    notes: "PS L 1"
  PS-L-J18:
    <<: *ps_small
  JB-J19:
    <<: *ps_large
    notes: "PS L 2"
  PS-L-J19:
    <<: *ps_large
  Fan:
    type: 'Fan'
    pincount: 4
  PS-L-1:
    type: 'PS'
    pincount: 2


cables:
  W1:
    colors: [GN, BK, RD]
    gauge: 6 AWG
    show_wirenumbers: false
  W3:
    wirecount: 1
    show_wirecount: false
    show_wirenumbers: false
    length: 50 ft
  F:
    type: 'Fan Cable'
    colors: [BK, YE, GN, BU]
    show_wirecount: false
    category: bundle
  PSW-1:
    wirecount: 6
    show_wirecount: false
    show_wirenumbers: false
  PSW-2:
    wirecount: 22
    show_wirecount: false
    show_wirenumbers: false

connections:
  -
    - JB-J22: [1-4]
    - F.: [1-4]
    - Fan.: [1-4]
  -
    - JB-J23: [1-4]
    - F.: [1-4]
    - Fan.: [1-4]
  -
    - JB-J2: [1-4]
    - F.: [1-4]
    - Fan.: [1-4]
  -
    - JB-J24: [1-4]
    - F.: [1-4]
    - Fan.: [1-4]
  -
    - JB-J25: [1-4]
    - F.: [1-4]
    - Fan.: [1-4]
  -
    - PS-L-J18: [1-6]
    - PSW-1.PSW-L1:  [1-6]
    - JB-J18: [1-6]
  -
    - PS-L-J19: [1-22]
    - PSW-2.PSW-L2:  [1-22]
    - JB-J19: [1-22]
tweak:
  append: |
    subgraph cluster1 {
      label="PCB Assembly"
      style=dashed
      "JB-J22"
      "JB-J23"
      "JB-J2"
      "JB-J24"
      "JB-J25"
      "JB-J18"
      "JB-J19"
    }
    subgraph cluster2 {
      label="Power Supply Left"
      style=dashed
      "PS-L-J18"
      "PS-L-J19"
    }

Results in this:

Proposed ideal result:

The top two connectors of the PCB assembly should be moved to the left of the screen, with the dashed lines intact around the group. Excuse the poor image edit.

The syntax could be fairly simple - Something like:

groups:
  -
     - "JB-J22"
     - "JB-J23"
     - "JB-J2"
     - "JB-J24"
     - "JB-J25"
     - "JB-J18"
     - "JB-J19"
  -
     - "PS-L-J18"
     - "PS-L-J19"
   

Right after I finish this post, I'll poke around in GV and see if there are tweak settings to do what I want, but it would be good to get this mainlined!

[martinrieder]

Another idea of grouping has been suggested in #268 (comment).

The Graphviz "rankdir" is "LR", which creates WireViz diagrams with horizontal layouts. Any parts of the harness that are independent (unconnected) need to be stacked top-to-bottom, in order to achieve the least possible overall image width.

[martinrieder]

@JarrettR you can use the new connector-to-connector feature (creating arrows with "==" as a wire designator). This will cause Graphviz to align the boxes to the right. Then check the GV file what the auto-generated designators of the dashed edges are. You can hide them with a "style: invis" tweak in the overrides.

[JarrettR]

Thanks for the explanation, and that's a really good hack.

I'm having issues with figuring out the appropriate overrides, though.

For this simplified example:

connections:
  -
    - X1: [1-4]
    - ==
    - X3: [1-4]

Then the generated GraphViz section is just this, appended at the very end:

	edge [color="#000000:#000000" dir=none style=dashed]
	X1:e -- X3:w

Neither of these can be accessed through the key/value system that the tweak option checks for.

This does nothing useful, for example:

tweak:
    override:
        "X1:e -- X3:w":
            style: invis 
        edge:
            style: invis 

It actually hides all wires except for the one I want, ironically.

[kvid]

Instead of trying to override the arrow connections, I recommend adding the invisible edges you need in the tweak:append section.

[JarrettR]

Oh of course. That works perfectly.

Thanks for the tips, @martinrieder and @kvid

[martinrieder]

Instead of trying to override the arrow connections, I recommend adding the invisible edges you need in the tweak:append section.

That seems perfectly valid and allows for all kinds of nodes to be "tied together". The invisible edge can be added between two cables as well.

I would like to add that these invisible edges actually influence the ranking of nodes. The is also an attribute rank that can be set to either source or min vs. sink or max. It has a similar effect on grouping nodes, because independent nodes are stacked TB by default due to their rank=same.

[kvid]

@JarrettR wrote a couple of weeks ago:

[...]

	edge [color="#000000:#000000" dir=none style=dashed]
	X1:e -- X3:w

Neither of these can be accessed through the key/value system that the tweak option checks for.

• The edge entry can be tweaked, but then all such entries will get affected because the current tweak code doesn't see any difference between them. Please suggest how we could specify which of the edge entries to override, preferably in a new issue.
• The other entry currently cannot be tweaked unless it has a parameter section [par1=xx par2=yy ...] at the end of the line. Should this requirement be relaxed?

This does nothing useful, for example:

tweak:
    override:
        "X1:e -- X3:w":
            style: invis 
        edge:
            style: invis 

It actually hides all wires except for the one I want, ironically.

• As I wrote above, the first of these overrides does nothing due to a missing parameter section.
• As I also wrote above, the second override should affect all edge entries. The fact that it didn't affect the one you wanted, made me investigate the code, and I found a bug that will be fixed as part of PR Fix bugs in mate processing #358. Thank you for reporting this observation.