trace4d

This project aims to improve program comprehension by visualizing traces of object-oriented programs through animated 2.5D object maps. Program traces are created in Squeak using the TraceDebugger and visualized in the browser using three.js.

View more examples here.

Repository Structure

.github/workflows/: GitHub Actions workflows for CI
assets/:
- assets/examples.md: Screenshots and screencasts of visualizing example program traces
- assets/traces/: Prepared serialized program traces of different Squeak programs (see docs/traces.md)
docs/: Documentational artifacts
- docs/paper/: LaTeX sources of our paper preprint (older version)
- docs/exposé/: LaTeX sources of our original exposé
- docs/benchmarking.md: Instructions for reproducing our benchmarking results
- docs/experience-report.md: Instructions and results of our experience report
- docs/traces.md: Descriptions of the provided traces
packages/: Sources of the trace4d prototype
- packages/BaselineOfTrace4D.package/: Metacello baseline for loading the trace4d backend in Squeak
- packages/Trace4D.package/: Squeak backend (serialization of traces)
- packages/frontend/: Browser visualization (three.js)

Setup

Backend (Squeak)

Get Squeak (tested on Squeak 6.1Alpha #22599, but should technically work in Squeak 6.0)
Load the trace4d backend:
- via Metacello:
```
Metacello new
	baseline: 'Trace4D';
	repository: 'github://LinqLover/trace4d/packages';
	load.
```
- or manually:
  - Install the TraceDebugger
  - Open the Git Browser (Tools in the world main docking bar)
  - Clone this repository and check out the Trace4D package

Frontend (JavaScript)

See packages/frontend/README.md.

Usage

Creating a Program Trace

For example, open a workspace and execute the following code (Cmd + A, Cmd + D):

trace := T4DTrace forBlock:
	['\d|\w+' asRegex].
trace storeJsonInFileNamed: 'parseRegex.json'.

Find more inspiration in docs/traces.md and in the class comment and examples of the T4DTrace class.

Visualization

Open the visualization: self-hosted or on GitHub Pages.

You can customize much of it through optional URL parameters:

trace: path or URL to a trace file (e.g., traces/regexParse.json or https://raw.githubusercontent.com/LinqLover/trace4d/main/assets/traces/regexParse.json)
autoStart: flag to automatically start the animation (default: not set)
countFPS: flag to turn on FPS/MS/MB display (default: not set)
measureFPS: flag to log FPS/MS/MB in traceMap.stats.logs (default: not set, requires countFPS)
measureStartTime: flag to display the start-up time after loading (default: not set)
obsolete:
- style: flatFDG (default) or hierarchical (package/class organization, no longer fully supported)

Examples:

If you have an own trace file, you can select it on the landing page.

Navigation

Navigate through the scene using the mouse (drag to move, Ctrl + drag to rotate, scroll to zoom) or the keyboard (arrow keys to move, Ctrl + arrow keys to rotate).
Inspect an object/field by clicking on it.
Override the layout by moving objects around (Shift + drag) or unpin objects again (Ctrl + click).
Press Esc to stop the layout simulation (recommended before starting the animation for performance reasons!).
To control the animation, use the play/pause button in the timeline at the bottom, click on the timeline to jump to a specific point in time, or use the keyboard shortcuts (Space to play/pause, Home to reset the animation).
To explore the call tree of the program trace, expand the flame graph by resizing the timeline and click/hover interesting frames.

Configuration

You can customize the visualization dynamically to change the visible objects and the layout. To this end, open the Chrome DevTools (F12) and use the traceMap object in the console like this:

// force layout:
traceMap.entityBuilder.forceWeights.references = 0.5
traceMap.entityBuilder.forceWeights.organization.sameClass = 0.1
traceMap.entityBuilder.forceWeights.globalFactor = 0.5
traceMap.entityBuilder.forceWeights.repulsion = 0.3
// object filtering:
traceMap.entityBuilder.excludedObjectNames.push("'an Object'")
traceMap.entityBuilder.excludedClassNames.push('ByteString')
traceMap.entityBuilder.excludeClasses = false
traceMap.reloadTrace()

traceMap.player.stepsPerSecond = 100

For the full protocol, please rely on the autocompletion or dig into the the FlatFDGEntityBuilder implementation.

Future Work and Issues

See IDEAS.md.

Acknowledgments

This project was conducted in the Methods & Techniques for Visual Analytics seminar offered by the Computer Graphics Systems Group at the Hasso Plattner Institute. Thanks to Willy Scheibel (@scheibel) for supervising this project and providing countless ideas and feedback!

Citing

If you would like to cite this project or learn more about the research behind it, please refer to the following publication:

Christoph Thiede, Willy Scheibel, and Jürgen Döllner: Bringing Objects to Life: Supporting Program Comprehension through Animated 2.5D Object Maps from Program Traces. In Proceedings of the 15th International Conference on Information Visualization Theory and Applications (IVAPP 2024), February 27–29, Rome, Italy. SciTePress, 9 pages. DOI: 10.5220/0012393900003660. 🔗 Preprint 🔗 Poster 🔗 Slides

BibTeX

@inproceedings{thiede2024bringing,
  author = {Thiede, Christoph and Scheibel, Willy and D{\"o}llner, J{\"u}rgen},
  title = {Bringing Objects to Life: Supporting Program Comprehension through Animated 2.5D Object Maps from Program Traces},
  booktitle = {Proceedings of the 19th International Joint Conference on Computer Vision, Imaging and Computer Graphics Theory and Applications -- Volume 1: GRAPP, HUCAPP and IVAPP},
  year = {2024},
  series = {IVAPP '24},
  month = {2},
  days = {27--29},
  publisher = {SciTePress},
  organization = {INSTICC},
  isbn = {978-989-758-679-8},
  issn = {2184-4321},
  doi = {10.5220/0012393900003660},
  pages = {661--669},
  location = {Rome, Italy}
}

LinqLover/trace4d