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.
.github/workflows/: GitHub Actions workflows for CIassets/:assets/examples.md: Screenshots and screencasts of visualizing example program tracesassets/traces/: Prepared serialized program traces of different Squeak programs (seedocs/traces.md)
docs/: Documentational artifactsdocs/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 resultsdocs/experience-report.md: Instructions and results of our experience reportdocs/traces.md: Descriptions of the provided traces
packages/: Sources of the trace4d prototypepackages/BaselineOfTrace4D.package/: Metacello baseline for loading the trace4d backend in Squeakpackages/Trace4D.package/: Squeak backend (serialization of traces)packages/frontend/: Browser visualization (three.js)
- 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
Trace4Dpackage
- via Metacello:
See packages/frontend/README.md.
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.
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.jsonorhttps://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 intraceMap.stats.logs(default: not set, requirescountFPS)measureStartTime: flag to display the start-up time after loading (default: not set)- obsolete:
style:flatFDG(default) orhierarchical(package/class organization, no longer fully supported)
Examples:
- https://linqlover.github.io/trace4d/app.html
- https://linqlover.github.io/trace4d/app.html?trace=traces/regexMatch.json&countFPS
- http://localhost:5173/app.html?trace=https://raw.githubusercontent.com/LinqLover/trace4d/main/assets/traces/displayScanner.json?measureStartTime
If you have an own trace file, you can select it on the landing page.
- 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.
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 = 100For the full protocol, please rely on the autocompletion or dig into the the FlatFDGEntityBuilder implementation.
See IDEAS.md.
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!
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}
}