Bubble Diagram — Guide
Web Version 1.0.1
Guide updated 29 October 2026.
© 2026 Endy Y. Prasetyo
1. About Bubble Diagram
Bubble Diagram helps you explore spatial relationships during architectural programming. Each bubble represents a zone with a name, area, and elevation. Connections describe parent–child relationships and determine depth levels. Diagram, Depth, Matrix, Entries, and Summary are views of the same project.
2. Start a Project
The Start popup offers Open Project, Start New Project, and Return to Project. Return keeps the current workspace. Starting a new project clears its contents, selection, history, and remembered views.
Save regularly by downloading a .bbl project file. The browser version has no autosave or server-side project storage. Keep the latest download before closing or refreshing the tab.
3. Navigation and Toolbars
Use the floating navigation pill: Start | Diagram | Depth | Matrix | Entries | Summary | Guide. The current page name is black and the other names are grey. Hover enlarges the label.
Diagram tools
The vertical toolbar on the left contains creation, grouping, clipboard, history, and deletion tools. Hover over an icon to see its name. Grey tools are unavailable; for example, Copy requires a selection and Paste requires copied bubbles.
| Icon | Tool | Action |
|---|---|---|
| New bubble | Place a bubble, enter its attributes, then answer the entrance question. | |
| New connection | Choose a parent bubble and then its child. | |
| Inter-Cluster Connection | Connect a parent bubble to a child in another cluster while keeping the clusters separate. | |
| Reverse Connection | Reverse selected connections. Available when at least one connection is selected. | |
| Assign entrance | Select existing bubbles and confirm. A preselection goes directly to confirmation. | |
| Copy | Copy selected bubbles and selected connections whose endpoints are included. | |
| Paste | Insert copies with new identities and independent copied groups. | |
| Undo | Restore the previous recorded project state. | |
| Redo | Reapply an undone change. | |
| Delete selected | Remove selected objects and connections attached to deleted bubbles. |
Copy and Paste use the app’s internal clipboard. To copy a connection, select it together with both endpoint bubbles. Pasted bubbles receive new identities; copied groups move independently of their originals.
View controls and settings
Diagram has Refresh | Group Area | Background | Zoom All | Zoom at the bottom left. Refresh updates diagram visuals using the current settings and color theme. Background changes the canvas pattern. Zoom All fits the bubbles into view, and Zoom reports the scale. Depth has Refresh | Group Area | Zoom All | Zoom in the same position. The Group Area toggle shows or hides the grey rounded backdrops for grouped bubbles on both pages. In Depth, these areas reshape as you move individual bubbles; they do not lock bubble positions.
The bottom-right circle with three horizontal lines opens the shared settings panel on Diagram and Depth. Use an arrow at the top or bottom of the panel to collapse it.
4. Create Bubbles, Connections, and Entrances
Create a bubble
- Choose New bubble, or right-click Diagram and choose New Zone.
- Follow the centered instruction pill and click the bubble’s position on the canvas.
- Enter the zone name and press Enter.
- Enter the area in m² and press Enter.
- Enter the elevation in metres and press Enter.
- Answer “Assign this bubble as entrance? Yes or No” and press Enter to finish. You can type Yes, No, Y, or N.
Area must be nonnegative. Elevation can be positive, zero, or negative. The translucent input stays centered. Click empty canvas or press Escape to cancel an unfinished bubble.
Create a connection
Choose New connection, or right-click and choose New Connection. Follow the centered instructions: click the parent bubble, then the child bubble. A bubble cannot connect to itself. Click empty canvas or press Escape to cancel.
Connect separate clusters
- Choose Inter-Cluster Connection, the // icon immediately below New connection.
- Click the parent bubble in the source cluster, then the child bubble in another cluster.
A target in the same cluster is rejected with guidance; the tool stays active so you can choose another target. Click empty canvas or press Escape to cancel. Ordinary connections determine cluster membership. An inter-cluster connection bridges clusters while preserving their separate names, tables, matrices, and layout locks. Changing an ordinary line to dashed or dotted does not make it an inter-cluster connection.
Depth across clusters and floors
Both ordinary and inter-cluster connections count as one depth step per connection. The receiving cluster is recalculated outward from the bubble where the bridge arrives. Its ordinary arrows follow increasing depth, even if the arrival bubble was previously a leaf. Bridge direction stays authoritative; the source cluster keeps its existing directed depth behavior. Multiple incoming bridges are included in the calculation.
For example, if a staircase on the source floor has depth 3, its bridge arrives at depth 4 on the receiving floor. An ordinarily connected neighbour there has depth 5. Further bridges continue the depth sequence across floors. Deleting a bridge recalculates depth and restores the receiving cluster’s original ordinary directions where other bridges or entrance assignments do not still require reorientation.
Reverse a connection
Select one or more connections, then choose Reverse Connection above Assign entrance in the Diagram toolbar, or use the selection-dependent right-click action. This swaps parent and child for ordinary or inter-cluster connections, preserves their appearance and cluster membership, and recalculates depth and parent lists. The operation is recorded as one Undo action.
A manually reversed direction remains authoritative during automatic entrance and receiving-floor orientation. It is preserved by save/open and copying.
Assign existing bubbles as entrances
- Click the Assign entrance door-and-arrow icon above Copy.
- Select one or more existing bubbles. In this workflow, clicking a bubble again removes it from the selection.
- Click Confirm or press Enter. If bubbles were selected before you chose the tool, the centered pill goes directly to confirmation.
Cancel or Escape exits without assigning entrances. You can also turn entrance status on or off for one selected bubble in Individual Settings → Zone Properties → Assign as entrance.
An entrance is set to depth 1. It has its normal outline plus a thin outer outline separated by a clear gap. Ordinary incoming connections from non-entrance bubbles reverse so their arrows point away from the entrance, except where a direction was explicitly set with Reverse Connection. Inter-cluster bridge directions remain authoritative. Removing entrance status restores the original directions as permitted by other entrance assignments and recalculates depth. Recalculation uses the current color theme and retains custom bubble fills.
5. Select, Move, Group, and Ungroup
Diagram supports bubble and connection selection. Depth supports bubble selection and movement only; connections cannot be selected there, and deletion and Cut are disabled. Delete bubbles or connections on Diagram. Open settings to edit a selected bubble.
| Gesture | Result |
|---|---|
| Click a bubble or connection | Select it. Clicking an unselected object replaces the previous selection. |
| Shift-click an unselected object | Add it to the current selection. |
| Shift-click a selected bubble | Deselect only that bubble, keeping the others selected. Available on Diagram and Depth. |
| Click empty canvas | Clear the selection and close an open right-click menu. |
| Drag empty canvas left to right | Select fully enclosed bubbles, including their labels, and connections with both endpoints enclosed. |
| Drag empty canvas right to left | Select bubbles and connection segments that intersect the rectangle. |
| Shift-drag a selection rectangle | Add its hits to the selection. |
| Drag a selected bubble | Move the selected bubbles together. Dragging an unselected bubble selects it first. |
| Hold Shift during a move | Constrain the move to the dominant axis. Release Shift for free movement on Diagram. |
| Press Escape during a move or pan | Restore the starting positions or viewport. |
Selection uses a dotted outline and preserves bubble and connection colors. For an entrance, the selection ring sits outside its outer outline. Completed moves are recorded for Undo and Redo.
Group bubbles on Diagram
- Select two or more bubbles.
- Right-click and choose Group.
- Drag any member to move the group together.
A grouped set has a translucent grey, rounded backdrop that follows its circular members. It updates as bubbles move or resize. To separate the group, select a member, right-click, and choose Ungroup; the backdrop disappears. Grouping supports Undo/Redo and is saved with the project.
Moving every member of a cluster by the same amount preserves its matrix relationships and translates its layout locks. This works with a group or with all cluster members selected together. Partial moves remain subject to matrix locks. Once unlocked, moving only part of a cluster or changing its relative arrangement neutralizes the affected relationships.
How Diagram and Depth differ
Diagram allows free movement subject to matrix locks. Depth keeps bubbles on their assigned depth rows, so dragging changes horizontal position only. Diagram grouping controls joint movement on Diagram. Diagram’s matrix locks do not prevent movement in Depth, and moving a Depth bubble does not rearrange its Diagram position.
Dragging bubbles offers center-alignment snapping with dashed guides. Hold Alt/Option to bypass snapping. Shift constrains movement to one axis.
6. Pan, Zoom, and View Memory
- Wheel or trackpad scroll: pan horizontally and vertically.
- Ctrl + drag empty canvas: pan. Use Ctrl on macOS too.
- Middle-button drag: pan from the background.
- Ctrl + wheel: zoom around the pointer. Diagram uses 20–200%. Depth’s minimum follows its Zoom All fit, and its maximum is 200%. Vertical panning stops at the top and bottom of the Depth content; when all rows fit, they stay centered vertically.
- Zoom All: explicitly fit the bubbles in the current view.
Opening a project restores its current saved scene on Diagram, when one is selected. Otherwise, it runs Zoom All on Diagram. Switching pages retains each view’s last pan and zoom. Diagram, Depth, and the two Summary diagrams keep independent view positions for the current session. Custom bubble arrangements in Depth are saved in the .bbl project and restored when you reopen it. Starting a new project resets them and clears the scene list.
Save and revisit scenes
The translucent scene toolbar at the bottom center of Diagram saves named views of the canvas. Each scene stores its pan position and zoom level. Scenes share the same diagram content; they do not save separate copies of bubbles or connections. A project can contain any number of scenes.
- Pan and zoom to the view you want to keep.
- Click + in the scene toolbar, then choose Save as new scene. The view receives a name such as Scene 1.
- To update the selected scene with the current view, click + and choose Overwrite current scene. This option is available when a scene is selected. Panning and zooming alone do not overwrite a saved scene.
Switch scenes: click the scene name to open the list, then click a scene to animate the canvas to its saved position and zoom. A check mark identifies the selected scene. The rounded translucent submenu animates when opening and closing. Click outside the toolbar or press Escape to close it.
Rename: double-click the current scene name and edit it directly in the toolbar. Press Enter or click away to keep the name; press Escape to cancel. Empty names are ignored.
Delete: open the scene list and click × beside the scene you want to remove. Deleting a scene leaves the canvas content and current view unchanged. If you delete the selected scene, the toolbar shows No scene until you select or create another.
Keep scenes in your project: use Save or Save As to write the scene list, names, saved views, and current scene selection into the .bbl file. Creating, renaming, overwriting, or deleting a scene updates the open project; save the project to keep those changes on disk. Older files without scenes open with an empty scene list.
7. Individual Settings and General Settings
Diagram and Depth share one settings panel. Scrolling inside it does not pan the canvas.
Individual Settings
Select exactly one bubble to enable its settings. With no bubble or multiple bubbles selected, the bubble sections are greyed out and disabled.
- Bubble Properties: fill color, outline color, and outline weight.
- Zone Properties: Assign as entrance, zone name, area, and elevation. The small circular controls beside the attributes show or hide their labels.
- Connection Properties: select one connection to edit line color, weight, solid/dashed/dotted style, arrowhead visibility, size, and thickness.
The entrance toggle has an inset filled center when active and a hollow center when off. Object edits often preview immediately. Use the object section’s Apply button to apply its values. The Zone Properties Cancel button closes the editor; it does not undo all live edits.
General Settings
General Settings is available without selecting a bubble. Its sections are Bubble Size, Bubble Style, Bubble Attribute, Line Style, Arrowhead Style, and Depth Level Colors. Circular color swatches sit beside their labels.
Bubble Attribute: visibility, text size, and spacing
The circular Name, Area, and Elevation switches control label visibility across Diagram, Depth, Entries, and Summary. These global switches preserve each bubble’s individual visibility choices.
Each attribute has its own Text size slider and pixel value. The Vertical spacing slider below them changes the gaps between the three text rows. Text size and spacing apply to Diagram, Depth, and their Summary diagrams. Entries captions keep their compact default size and spacing. New bubbles use the current text settings, and PNG exports preserve them.
Color theme and applying settings
Under Depth Level Colors, the Theme swatch generates a light-to-dark palette for nine depth levels. You can also edit individual level colors. The active theme stays in use when entrances or depths change. Custom bubble fills and individual outline overrides are retained; use Set to Default on the selected object to restore the shared appearance.
- Reset to Default: preview the original settings.
- Cancel: restore the last applied general settings.
- Apply: commit the preview.
General Settings previews are shared between Diagram and Depth and remain in the panel when switching between those pages.
8. Matrix, Cluster Names, and Layout Locks
Matrix shows a relationship table for each cluster formed by ordinary connections. Edit the lower-triangle controls to choose neutral, mandatory, desirable, or avoid; the other half mirrors the values.
Cross-cluster bridges appear separately in the directed Inter-cluster accessibility (//) table. Each cluster’s relationship matrix keeps its ordinary within-cluster relationships.
Rename a cluster
On Matrix or Entries, hover over a cluster name for a subtle edit cue, then double-click it. Press Enter or click away to save, or Escape to cancel. Blank names are ignored. The field stays within the heading so it does not push the table down. Names appear in Entries, Matrix, Summary, and the Apply Layout for [cluster name] button, which updates immediately after renaming. Names are saved with the project and support Undo/Redo.
Apply, Re-arrange, and Clear
- Apply Layout for [cluster name]: confirm the prompt to arrange that cluster and lock its Diagram layout.
- Re-arrange: search for another arrangement for that cluster.
- Clear: release that cluster’s layout locks for manual editing while keeping its relationship values.
Zone names may repeat across clusters. Each layout button targets its own cluster, preserving other clusters’ positions and connections. Layouts favor compact arrangements and fewer crossing connection lines while respecting bubble clearances and matrix relationships. Some constraints can leave unavoidable crossings; layouts may still need manual refinement.
Reapplying a matrix refines a valid arrangement instead of rebuilding it from scratch. Layout locks survive save/open and do not constrain Depth movement. An entire cluster can be translated together without clearing its matrix or locks, as described under Select, Move, Group, and Ungroup.
9. Entries
Entries shows Zones & Clusters. Each cluster has its own table of zone names, areas, elevations, depth levels, and parent connections. Click column headings to sort that table. Double-click the cluster name to rename it.
Directly below each table is a responsive bubble grid ordered by increasing depth. It includes every zone in the table, with proportional bubble sizes, current fill colors, and entrance outlines. Bubbles have clean backgrounds and no text or connections inside them. The name, area, and elevation sit closely together below each bubble.
The number of bubbles per row adapts to their sizes and the available width. Each cluster’s table and bubble grid stay together vertically, followed by the next cluster. Sorting a table does not change the bubble grid’s depth order. Diagram and Depth text-size/spacing controls leave Entries’ default typography unchanged. Alt/Option + F opens the table font-size controls.
A display-only // marks bridge endpoints and parent references reached through an inter-cluster connection. Parent lists follow the recalculated receiving-cluster directions. The indicators do not change zone names in the project.
10. Summary and Export
Summary combines zone tables, relationship matrices, Diagram, and Depth. It uses the current cluster names, colors, and label settings. Its Diagram also includes the rounded group backdrops. Summary reports the inter-cluster connection count. The midpoint // bridge mark is retained in Diagram, Depth, their Summary views, and PNG exports.
Each embedded diagram has Zoom All, Locked/Unlocked, and Export PNG controls. Unlock it to navigate, then relock it to prevent accidental navigation. Both diagrams retain their own view positions when you return.
Use the Summary export controls to save the project or export a PDF. The web version opens the browser print dialog; choose its PDF destination to save a PDF. For a PNG of the main Diagram, choose File → Export diagram PNG from its right-click menu. PNGs respect hidden attributes and chosen text sizes. Save a .bbl project as well to continue editing later.
11. Files, Saving, and Clipboard
Right-click Diagram, or press and hold for about 600 ms, to open its menu. File provides New project, Open project…, Save download, Save download as…, Export diagram PNG, Undo, and Redo. Other actions include New Zone, New Connection, selection-dependent Reverse Connection, Group, Ungroup, and Delete Selected. Clicking outside closes the menu. Use Depth’s settings button to edit selected bubbles.
Open reads local .bbl, .bubble, and compatible .json project files. The unfiltered browser picker allows iPad Files to select custom extensions; project contents are validated before loading. Save and Save As download a .bbl file, including projects opened from legacy formats. Save As asks for another filename. Browser downloads cannot automatically overwrite the original file; repeated downloads may receive numbered names. Check your downloads for the latest copy.
Undo and Redo become available as history permits. Grouping, confirmed entrance assignments, cluster renaming, and completed Diagram moves are recorded. Inter-cluster types, original ordinary directions, and manually reversed directions survive saving, reopening, Undo/Redo, and copying. Saved scenes and custom Depth arrangements are included in the downloaded project. Older projects without these fields remain supported.
Copy and Paste use the internal graph clipboard. Use the Diagram toolbar or Cmd/Ctrl + C, X, and V; Cmd/Ctrl + A selects all in Select mode. Deletion and Cut are disabled on Depth. Text fields keep their normal editing shortcuts. New Project is available from Start or the File submenu because browsers reserve Cmd/Ctrl + N.
12. Keyboard Reference
| Action | macOS | Windows / Other |
|---|---|---|
| Open project | Cmd + O | Ctrl + O |
| Save download | Cmd + S | Ctrl + S |
| Save download as… | Cmd + Shift + S | Ctrl + Shift + S |
| Undo | Cmd + Z | Ctrl + Z |
| Redo | Cmd + Shift + Z | Ctrl + Shift + Z |
| Delete selected objects (Diagram only) | Delete / Backspace | Delete / Backspace |
| Finish a creation step or confirm entrances | Enter | Enter |
| Save / cancel a cluster name | Enter / Escape | Enter / Escape |
| Cancel an active operation | Escape | Escape |
| Table font-size controls | Alt/Option + F | Alt + F |
Text fields retain their normal editing keys. On the canvas, use Ctrl for navigation modifiers on every platform, including macOS.
13. Touch and Session Limits
Tap controls and bubbles to activate or select them. A primary-pointer drag on empty Diagram or Depth canvas draws a selection rectangle. Press-and-hold for about 600 ms can open the context menu; moving more than about 10 pixels cancels the hold. Pinch behavior depends on the device delivering Ctrl-modified wheel events.
Projects are edited in the current browser tab. There is no server-side project storage; refreshing or closing the tab discards unsaved work and session state. The app has no account-based storage, collaboration, or autosave. Save before closing the app or browser tab.
14. About the Developer
Endy Y. Prasetyo is an architect, educator, and researcher working at the intersection of architectural design, spatial programming, and computational design tools.
He is an Assistant Professor of Architecture at Institut Teknologi Sepuluh Nopember (ITS), Surabaya, Indonesia, and a PhD researcher at TU Delft, the Netherlands.
Bubble Diagram is part of his ongoing exploration of digital tools for architectural programming and spatial relationships. The application is developed as a design and research tool for exploring how spatial information can be represented, examined, and manipulated through interconnected diagrammatic views.
Contact:
endy_yudho_prasetyo@arch.its.ac.id
e.y.prasetyo@tudelft.nl
15. Version and Copyright
Bubble Diagram --- Web Version 1.0.1
Bubble Diagram Application is registered in Indonesia as a computer program under the name "Program Komputer Sebagai Alat Pemetaan Spasial dengan Nama: Bubble Diagram Application."
Creator: Endy Yudho Prasetyo, S.T., M.T.
Copyright Holder: Institut Teknologi Sepuluh Nopember (ITS)
Copyright Registration Number: 001319246
Application Number: EC002026102890
Application Date: 1 July 2026
First Publication: 26 June 2026, Surabaya, Indonesia
The copyright registration is issued by the Directorate General of Intellectual Property, Ministry of Law, Republic of Indonesia, under Law No. 28 of 2014 on Copyright. The certificate states a protection period of 50 years from the first publication of the work.
All rights reserved. This application is protected by copyright law and may not be reproduced or distributed without permission from the copyright holder.
This Guide describes Web Version 1.0.1. Interface guide updated 29 October 2026.