web: add a Clusters panel and a cluster coloring overlay

src/web/BUILD

@@ -34,6 +34,7 @@ genrule(
         "src/coordinates.js",
         "src/ui-utils.js",
         "src/checkbox-tree-model.js",
+        "src/color-tree.js",
         "src/vis-tree.js",
         "src/websocket-manager.js",
         "src/tile-merge.js",
@@ -47,6 +48,8 @@ genrule(
         "src/label-manager.js",
         "src/tcl-completer.js",
         "src/hierarchy-browser.js",
+        "src/clusters-widget.js",
+        "src/hierarchy-panel.js",
         "src/menu-bar.js",
         "src/context-menu.js",
         "src/search-nav.js",
@@ -73,6 +76,7 @@ genrule(
           " $(location src/coordinates.js)" +
           " $(location src/ui-utils.js)" +
           " $(location src/checkbox-tree-model.js)" +
+          " $(location src/color-tree.js)" +
           " $(location src/vis-tree.js)" +
           " $(location src/websocket-manager.js)" +
           " $(location src/tile-merge.js)" +
@@ -86,6 +90,8 @@ genrule(
           " $(location src/label-manager.js)" +
           " $(location src/tcl-completer.js)" +
           " $(location src/hierarchy-browser.js)" +
+          " $(location src/clusters-widget.js)" +
+          " $(location src/hierarchy-panel.js)" +
           " $(location src/menu-bar.js)" +
           " $(location src/context-menu.js)" +
           " $(location src/search-nav.js)" +
@@ -117,6 +123,7 @@ _WEB_ASSET_FILES = [
     "src/coordinates.js",
     "src/ui-utils.js",
     "src/checkbox-tree-model.js",
+    "src/color-tree.js",
     "src/vis-tree.js",
     "src/websocket-manager.js",
     "src/websocket-tile-layer.js",
@@ -126,6 +133,8 @@ _WEB_ASSET_FILES = [
     "src/label-manager.js",
     "src/tcl-completer.js",
     "src/hierarchy-browser.js",
+    "src/clusters-widget.js",
+    "src/hierarchy-panel.js",
     "src/menu-bar.js",
     "src/context-menu.js",
     "src/search-nav.js",
@@ -169,8 +178,9 @@ cc_library(
         "src/font_data.cpp",
         "src/font_data.h",
         "src/glyph_cache.cpp",
+        "src/group_report.cpp",
+        "src/group_report.h",
         "src/hierarchy_report.cpp",
-        "src/hierarchy_report.h",
         "src/module_color_palette.h",
         "src/request_dispatcher.h",
         "src/request_handler.cpp",
@@ -205,6 +215,8 @@ cc_library(
         "src/web_viewer_hook.h",
         "src/request_handler.h",
         "src/clock_tree_report.h",
+        "src/hierarchy_report.h",
+        "src/shape_collector.h",
     ],
     copts = [
         "-DBOOST_ASIO_NO_DEPRECATED",

src/web/CMakeLists.txt

@@ -24,6 +24,7 @@ set(WEB_ASSET_FILES
     src/coordinates.js
     src/ui-utils.js
     src/checkbox-tree-model.js
+    src/color-tree.js
     src/vis-tree.js
     src/websocket-manager.js
     src/websocket-tile-layer.js
@@ -33,6 +34,8 @@ set(WEB_ASSET_FILES
     src/label-manager.js
     src/tcl-completer.js
     src/hierarchy-browser.js
+    src/clusters-widget.js
+    src/hierarchy-panel.js
     src/menu-bar.js
     src/context-menu.js
     src/search-nav.js
@@ -69,6 +72,7 @@ add_custom_command(
         ${CMAKE_CURRENT_SOURCE_DIR}/src/coordinates.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/ui-utils.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/checkbox-tree-model.js
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/color-tree.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/vis-tree.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/websocket-manager.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/tile-merge.js
@@ -82,6 +86,8 @@ add_custom_command(
         ${CMAKE_CURRENT_SOURCE_DIR}/src/label-manager.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/tcl-completer.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/hierarchy-browser.js
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/clusters-widget.js
+        ${CMAKE_CURRENT_SOURCE_DIR}/src/hierarchy-panel.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/menu-bar.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/context-menu.js
         ${CMAKE_CURRENT_SOURCE_DIR}/src/search-nav.js
@@ -120,6 +126,7 @@ target_sources(web
   PRIVATE
     src/clock_tree_report.cpp
     src/color.cpp
+    src/group_report.cpp
     src/hierarchy_report.cpp
     src/request_handler.cpp
     src/search.cpp

src/web/README.md

@@ -85,6 +85,25 @@ field and the value is `true` or `false`.
 | `rows` | false | Row outlines |
 | `tracks_pref` | false | Preferred-direction tracks |
 | `rudy` | false | Estimated congestion (RUDY) heatmap overlay |
+| `module_view` | false | Color each instance by the `dbModule` it belongs to |
+| `cluster_view` | false | Color each instance by the `dbGroup` (cluster) it belongs to |
+
+Cluster coloring reads the `dbGroup`s that
+[`rtl_macro_placer -keep_clustering_data`](../mpl/README.md) writes into the
+database, so it is only useful after MPL has run with that option. Each
+cluster gets its own palette color, and a cluster whose subtree is not
+expanded lends its color to all of its descendants — the same default the
+viewer's Instance Groups view shows. When the design has no groups the option
+warns and the image is rendered as if it were off.
+
+In the viewer both of the Hierarchy panel's views drive this coloring — Verilog
+Modules through `module_view`, Instance Groups through `cluster_view`. A row's
+checkbox decides whether that module or cluster paints, and in the Instance
+Groups view a double click takes the view to the cluster. The colors show only
+while the matching overlay is on, and the view's status line says so when it is
+off. One "Hierarchy view" checkbox in Display Controls turns on whichever
+overlay goes with the source the tab is showing; the two flags above are how the
+headless `save_image` path asks for either one directly.
 
 #### Examples
 
@@ -111,6 +130,12 @@ save_image -web -display_option {routing false} \
 
 # Save with RUDY congestion heatmap overlay
 save_image -web -display_option {rudy true} layout_rudy.png
+
+# Plot the MPL clustering result (one color per cluster)
+rtl_macro_placer -keep_clustering_data
+save_image -web -width 1200 \
+                -display_option {cluster_view true} \
+                clusters.png
 ```
 
 ### Save Animated GIF
@@ -450,7 +475,8 @@ them — something the single-window Qt GUI cannot do.
   paths, and view per-level statistics.
 - **Hierarchy browser** — Navigate the module tree with instance counts and area
   statistics. Toggle visibility and assign colors per module using a 31-color
-  palette.
+  palette. The same panel's Instance Groups view does this for the `dbGroup`s
+  MPL writes with `-keep_clustering_data`.
 - **Display controls** — Toggle visibility of cell types (stdcells, macros,
   pads), net types (signal, power, clock), and shapes (routing, pins, blockages,
   rows, tracks). The panel state can be saved to and restored from a file with

src/web/docs/server-api.md

@@ -110,7 +110,7 @@ Render a single 256×256 PNG tile of the layout.
 
 | Field            | Type     | Required | Description |
 | ---------------- | -------- | :------: | ----------- |
-| `layer`          | `string` |    ✓     | Layer name (`metal1`, `metal2`, …) or one of the synthetic layers `_instances`, `_modules`, `_pins`, or `_overlay`. |
+| `layer`          | `string` |    ✓     | Layer name (`metal1`, `metal2`, …) or one of the synthetic layers `_instances`, `_modules`, `_clusters`, `_pins`, or `_overlay`. |
 | `z`              | `int`    |    ✓     | Leaflet tile zoom level (0 = whole design). |
 | `x`              | `int`    |    ✓     | Tile column at zoom `z`. |
 | `y`              | `int`    |    ✓     | Tile row at zoom `z`. |
@@ -120,6 +120,17 @@ Render a single 256×256 PNG tile of the layout.
 
 **Response:** PNG image (frame type `1`).
 
+The `_modules` and `_clusters` layers color each instance by its `dbModule` /
+`dbGroup`, and each draws only while its own flag (`module_view` /
+`cluster_view`) is true and the session holds a color map (`set_module_colors` /
+`set_group_colors`); otherwise the tile comes back fully transparent.  Clients
+should therefore keep both layers mounted and toggle the flag, not the layer:
+making the map's layer set a second record of the flag is what let the viewer's
+hierarchy coloring checkbox get stuck until a page reload.  The viewer drives
+both flags from one "Hierarchy view" checkbox and the Hierarchy tab's active
+source, so at most one of them is ever true there; a Tcl or test client is free
+to set both.
+
 ### `bounds`
 
 Return the design's bounding box and shape-cache readiness.
@@ -514,11 +525,11 @@ Highlight a single clock-tree node's instance in the layout.
 
 ---
 
-## Module hierarchy
+## Module and cluster hierarchy
 
 ### `module_hierarchy`
 
-Return the module hierarchy tree (left sidebar).
+Return the `dbModule` tree (Verilog Modules view of the Hierarchy panel).
 
 No request fields.
 
@@ -552,6 +563,102 @@ layer).
 
 **Response (JSON):** `{"ok": 1, "count": <updated module count>}`.
 
+### `group_hierarchy`
+
+Return the `dbGroup` tree (Instance Groups view of the Hierarchy panel).  MPL writes its clustering
+hierarchy here as nested groups of type `VISUAL_DEBUG` when run as
+`rtl_macro_placer -keep_clustering_data`; power/voltage-domain groups appear
+too, distinguished by `type`.  Nodes are in DFS order, so a parent always
+precedes its children.
+
+No request fields.
+
+**Response (JSON):**
+```json
+{
+  "nodes": [
+    {
+      "id": 0, "parent_id": -1,
+      "name":  "root", "type": "VISUAL_DEBUG",
+      "odb_id": 42,
+      "insts": 1234, "macros": 2, "groups": 7,   // hierarchical
+      "area":  1.23,                              // μm², hierarchical
+      "local_insts": 100, "local_macros": 0, "local_groups": 3,
+      "bbox":  [xMin, yMin, xMax, yMax],          // members, recursive; zeros when empty
+      "color": [r, g, b]
+    },
+    ...
+  ]
+}
+```
+
+### `set_group_colors`
+
+Update the per-cluster color override map (for the `_clusters` tile layer).
+Same payload shape as `set_module_colors`, keyed by `dbGroup` id.
+
+| Field    | Type     | Required | Description                                                                                  |
+| -------- | -------- | :------: | -------------------------------------------------------------------------------------------- |
+| `colors` | `string` |    ✓     | Custom delimited form: `<id>:<r>,<g>,<b>,<a>;<id>:<r>,<g>,<b>,<a>;...`. Empty = clear all. |
+
+**Response (JSON):** `{"ok": 1, "count": <updated cluster count>}`.
+
+### `select_group`
+
+Select a cluster by `dbGroup` id, highlighting every member instance
+(including those of nested clusters), or drop it from the selection again.
+
+| Field              | Type   | Required | Description                                        |
+| ------------------ | ------ | :------: | -------------------------------------------------- |
+| `odb_id`           | `int`  |    ✓     | `dbGroup::getId()`, as returned by `group_hierarchy`. |
+| `add_to_selection` | `bool` |    —     | Default `false` (replace the selection).            |
+| `deselect`         | `bool` |    —     | Default `false`. When true, removes this group from the selection instead of selecting it; whatever else is selected keeps its highlight. Deselecting a group that is not selected is a no-op, so a client can fire it whenever a cluster is hidden. The response then carries no `name`/`properties` (nothing is being described — this is not an error). |
+| `no_highlight`     | `bool` |    —     | Default `false`. When true the group is selected (so it can be inspected) without pushing any highlight shapes onto the overlay, and `highlight_truncated` comes back `false`. For a client that shows the cluster through `set_group_colors` instead: the `_clusters` layer paints it in its own color, which the yellow selection veil would only cover. Nothing in the viewer sends this — neither of the Hierarchy panel's views selects anything, and there is no module equivalent of this request for the Verilog Modules one to use. The callers are Tcl and test clients. |
+| `use_dbu`          | `bool` |    —     | Same as `inspect`.                                  |
+
+**Response (JSON):** the inspect payload plus `selection_count`,
+`selection_index` and `highlight_truncated`.  The last is `true` when the
+cluster held too many shapes for the overlay and bounding boxes were used
+instead; the `_clusters` tile layer is the scalable way to see such a cluster
+(and what `no_highlight` clients rely on).  Errors when the id is not a group
+in the current block.
+
+### `find_objects`
+
+Batch select (and optionally highlight) every object of one type whose name
+matches a pattern — the counterpart of the Qt GUI's Find dialog and of
+`select -type ... -name ... -highlight`.
+
+| Field              | Type     | Required | Description                                                     |
+| ------------------ | -------- | :------: | --------------------------------------------------------------- |
+| `object_type`      | `string` |    ✓     | Descriptor type name: `Inst`, `Net`, `BTerm`, `Group`, ... Note it is *not* `type`, which the envelope uses. |
+| `pattern`          | `string` |    ✓     | Anchored glob (or Tcl regexp). Empty matches everything.         |
+| `is_regexp`        | `bool`   |    —     | Default `false` (glob).                                          |
+| `case_sensitive`   | `bool`   |    —     | Default `false`.                                                 |
+| `highlight_group`  | `int`    |    —     | `0..15` to also add the matches to that colored highlight group; `-1` (default) selects only. Any other value is an error, including negatives below `-1` — they are not a second spelling of `-1`. |
+| `add_to_selection` | `bool`   |    —     | Default `false` (replace the selection and the highlight group). |
+| `use_dbu`          | `bool`   |    —     | Same as `inspect`.                                               |
+
+**Response (JSON):** the inspect payload of the first match plus `found`,
+`found_truncated`, `selection_count`, `selection_index`,
+`highlight_truncated`, and `match_bbox` — the `[x0, y0, x1, y1]` union of the
+matches in DBU, for the client to zoom to.  It is absent when nothing matched
+or no match reports a box.  Note it is *not* the inspect payload's own `bbox`,
+which is the first match's box and is what the selection outline is drawn from.
+Errors on an unknown `object_type`, an out-of-range `highlight_group`, or a
+malformed regexp.
+
+### `clear_highlights`
+
+Drop the members of the colored highlight groups.  The selection is separate
+state and is left alone.
+
+| Field   | Type  | Required | Description                                                     |
+| ------- | ----- | :------: | --------------------------------------------------------------- |
+| `group` | `int` |    —     | `0..15` to clear just that group; `-1` (default) clears them all. |
+
+**Response (JSON):** `{"ok": 1, "cleared": <members removed>}`.
+
 ### `set_focus_nets`
 
 Add or remove a net from the focus-nets set (route-tracing overlay).