{"id":16087490,"url":"https://github.com/linqlover/trace4d","last_synced_at":"2026-04-26T12:32:02.606Z","repository":{"id":162655388,"uuid":"636715535","full_name":"LinqLover/trace4d","owner":"LinqLover","description":"Visualization of program traces through animated 2.5D object maps. Research prototype.","archived":false,"fork":false,"pushed_at":"2024-04-15T19:03:11.000Z","size":30844,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-30T14:45:46.720Z","etag":null,"topics":["omniscient-debugging","program-comprehension","program-exploration","smalltalk","software-visualization","squeak","threejs","visualization"],"latest_commit_sha":null,"homepage":"https://linqlover.github.io/trace4d/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LinqLover.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-05T13:30:00.000Z","updated_at":"2025-10-09T21:57:17.000Z","dependencies_parsed_at":"2024-02-28T16:45:41.930Z","dependency_job_id":"1a481450-8209-4294-bafe-4b4cc855385e","html_url":"https://github.com/LinqLover/trace4d","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/LinqLover/trace4d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinqLover%2Ftrace4d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinqLover%2Ftrace4d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinqLover%2Ftrace4d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinqLover%2Ftrace4d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LinqLover","download_url":"https://codeload.github.com/LinqLover/trace4d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LinqLover%2Ftrace4d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32297893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["omniscient-debugging","program-comprehension","program-exploration","smalltalk","software-visualization","squeak","threejs","visualization"],"created_at":"2024-10-09T13:29:53.649Z","updated_at":"2026-04-26T12:32:02.589Z","avatar_url":"https://github.com/LinqLover.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trace4d\n\nThis project aims to improve program comprehension by visualizing traces of object-oriented programs through animated 2.5D object maps.\nProgram traces are created in [Squeak](https://squeak.org) using the [TraceDebugger](https://github.com/hpi-swa-lab/squeak-tracedebugger) and visualized in the browser using [three.js](https://threejs.org).\n\n- **[Read the paper](https://linqlover.github.io/trace4d/paper-ivapp.pdf)** [![SciTePress](https://img.shields.io/badge/SciTePress-green)](https://linqlover.github.io/trace4d/paper-ivapp.pdf) [![preprint (PDF)](https://img.shields.io/badge/preprint-PDF-red)](https://linqlover.github.io/trace4d/paper-ivapp.pdf) [![preprint (HTML)](https://img.shields.io/badge/preprint-HTML-yellow)](https://linqlover.github.io/trace4d/paper-ivapp.html)\n- **[Read the poster](https://linqlover.github.io/trace4d/poster-ivapp.pdf)** [![PDF](https://img.shields.io/badge/PDF-red)](https://linqlover.github.io/trace4d/poster-ivapp.pdf) [![HTML](https://img.shields.io/badge/HTML-yellow)](https://linqlover.github.io/trace4d/poster-ivapp.html)\n- **[Read the presentation slides](https://linqlover.github.io/trace4d/slides-ivapp.pdf)** [![PDF](https://img.shields.io/badge/PDF-red)](https://linqlover.github.io/trace4d/slides-ivapp.pdf) [![HTML](https://img.shields.io/badge/HTML-yellow)](https://linqlover.github.io/trace4d/slides-ivapp.html)\n- **[Try the demo](https://linqlover.github.io/trace4d/)**\n\n![Screenshot of trace4d](./assets/trace4d.png)\n\n[View more examples here.](./assets/examples.md)\n\n## Repository Structure\n\n- [`.github/workflows/`](./.github/workflows/): GitHub Actions workflows for CI\n- [`assets/`](./assets/traces/):\n  - [`assets/examples.md`](./assets/examples.md): Screenshots and screencasts of visualizing example program traces\n  - [`assets/traces/`](./assets/traces/): Prepared serialized program traces of different Squeak programs (see [`docs/traces.md`](./docs/traces.md))\n- [`docs/`](./docs/): Documentational artifacts\n  - [`docs/paper/`](./docs/paper/): LaTeX sources of our paper preprint (older version)\n  - [`docs/exposé/`](./docs/exposé/): LaTeX sources of our original exposé\n  - [`docs/benchmarking.md`](./docs/benchmarking.md): Instructions for reproducing our benchmarking results\n  - [`docs/experience-report.md`](./docs/experience-report.md): Instructions and results of our experience report\n  - [`docs/traces.md`](./docs/traces.md): Descriptions of the provided [traces](./assets/traces/)\n- [`packages/`](./packages/): Sources of the trace4d prototype\n  - [`packages/BaselineOfTrace4D.package/`](./packages/BaselineOfTrace4D.package/): Metacello baseline for loading the trace4d backend in Squeak\n  - [`packages/Trace4D.package/`](./packages/Trace4D.package/): Squeak backend (serialization of traces)\n  - [`packages/frontend/`](./packages/frontend/): Browser visualization (three.js)\n\n## Setup\n\n### Backend (Squeak)\n\n- Get [Squeak](https://squeak.org/downloads) (tested on Squeak 6.1Alpha #22599, but should technically work in Squeak 6.0)\n- Load the trace4d backend:\n  - via Metacello:\n    ```smalltalk\n    Metacello new\n    \tbaseline: 'Trace4D';\n    \trepository: 'github://LinqLover/trace4d/packages';\n    \tload.\n    ```\n  - or manually:\n    - Install the [TraceDebugger](https://github.com/hpi-swa-lab/squeak-tracedebugger)\n    - Open the Git Browser (\u003ckbd\u003eTools\u003c/kbd\u003e in the world main docking bar)\n\t- Clone this repository and check out the `Trace4D` package\n\n### Frontend (JavaScript)\n\nSee [packages/frontend/README.md](./packages/frontend/README.md).\n\n## Usage\n\n### Creating a Program Trace\n\nFor example, open a workspace and execute the following code (\u003ckbd\u003eCmd\u003c/kbd\u003e + \u003ckbd\u003eA\u003c/kbd\u003e, \u003ckbd\u003eCmd\u003c/kbd\u003e + \u003ckbd\u003eD\u003c/kbd\u003e):\n\n```smalltalk\ntrace := T4DTrace forBlock:\n\t['\\d|\\w+' asRegex].\ntrace storeJsonInFileNamed: 'parseRegex.json'.\n```\n\nFind more inspiration in [docs/traces.md](./docs/traces.md) and in the class comment and examples of the `T4DTrace` class.\n\n### Visualization\n\nOpen the visualization: [self-hosted](./packages/frontend/) or on [GitHub Pages](https://linqlover.github.io/trace4d/).\n\nYou can customize much of it through optional URL parameters:\n\n- `trace`: path or URL to a [trace file](./assets/traces/) (e.g., `traces/regexParse.json` or `https://raw.githubusercontent.com/LinqLover/trace4d/main/assets/traces/regexParse.json`)\n- `autoStart`: flag to automatically start the animation (default: not set)\n- `countFPS`: flag to turn on FPS/MS/MB display (default: not set)\n- `measureFPS`: flag to log FPS/MS/MB in `traceMap.stats.logs` (default: not set, requires `countFPS`)\n- `measureStartTime`: flag to display the start-up time after loading (default: not set)\n- obsolete:\n  - `style`: `flatFDG` (default) or `hierarchical` (package/class organization, no longer fully supported)\n\nExamples:\n\n- [https://linqlover.github.io/trace4d/app.html](https://linqlover.github.io/trace4d/app.html)\n- [https://linqlover.github.io/trace4d/app.html?trace=traces/regexMatch.json\u0026countFPS](https://linqlover.github.io/trace4d/app.html?trace=traces/regexMatch.json\u0026countFPS)\n- http://localhost:5173/app.html?trace=https://raw.githubusercontent.com/LinqLover/trace4d/main/assets/traces/displayScanner.json?measureStartTime\n\nIf you have an [own trace file](#creating-a-program-trace), you can select it on the [landing page](https://linqlover.github.io/trace4d/).\n\n#### Navigation\n\n- **Navigate** through the scene using the mouse (drag to move, \u003ckbd\u003eCtrl\u003c/kbd\u003e + drag to rotate, scroll to zoom) or the keyboard (arrow keys to move, \u003ckbd\u003eCtrl\u003c/kbd\u003e + arrow keys to rotate).\n- **Inspect** an object/field by clicking on it.\n- **Override the layout** by moving objects around (\u003ckbd\u003eShift\u003c/kbd\u003e + drag) or unpin objects again (\u003ckbd\u003eCtrl\u003c/kbd\u003e + click).\n- Press \u003ckbd\u003eEsc\u003c/kbd\u003e to **stop the layout simulation** (recommended before starting the animation for performance reasons!).\n- 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 (\u003ckbd\u003eSpace\u003c/kbd\u003e to play/pause, \u003ckbd\u003eHome\u003c/kbd\u003e to reset the animation).\n- To **explore the call tree** of the program trace, expand the flame graph by resizing the timeline and click/hover interesting frames.\n\n#### Configuration\n\nYou can customize the visualization dynamically to change the visible objects and the layout.\nTo this end, open the Chrome DevTools (\u003ckbd\u003eF12\u003c/kbd\u003e) and use the `traceMap` object in the console like this:\n\n```js\n// force layout:\ntraceMap.entityBuilder.forceWeights.references = 0.5\ntraceMap.entityBuilder.forceWeights.organization.sameClass = 0.1\ntraceMap.entityBuilder.forceWeights.globalFactor = 0.5\ntraceMap.entityBuilder.forceWeights.repulsion = 0.3\n// object filtering:\ntraceMap.entityBuilder.excludedObjectNames.push(\"'an Object'\")\ntraceMap.entityBuilder.excludedClassNames.push('ByteString')\ntraceMap.entityBuilder.excludeClasses = false\ntraceMap.reloadTrace()\n\ntraceMap.player.stepsPerSecond = 100\n```\n\nFor the full protocol, please rely on the autocompletion or dig into the the [`FlatFDGEntityBuilder` implementation](./packages/frontend/src/map.js).\n\n## Future Work and Issues\n\nSee [IDEAS.md](./IDEAS.md).\n\n## Acknowledgments\n\nThis project was conducted in the [*Methods \u0026 Techniques for Visual Analytics* seminar](https://hpi.de/studium/im-studium/lehrveranstaltungen/it-systems-engineering-ma/lehrveranstaltung/sose-23-3778-methods--techniques-for-visual-analytics.html) offered by the [Computer Graphics Systems Group](https://hpi3d.de) at the Hasso Plattner Institute.\nThanks to Willy Scheibel ([@scheibel](https://github.com/scheibel)) for supervising this project and providing countless ideas and feedback!\n\n## Citing\n\nIf you would like to cite this project or learn more about the research behind it, please refer to the following publication:\n\nChristoph Thiede, Willy Scheibel, and Jürgen Döllner: [Bringing Objects to Life: Supporting Program Comprehension through Animated 2.5D Object Maps from Program Traces.](https://www.researchgate.net/publication/376650904_Bringing_Objects_to_Life_Supporting_Program_Comprehension_through_Animated_25D_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](https://doi.org/10.5220/0012393900003660). [🔗 Preprint](https://linqlover.github.io/trace4d/paper-ivapp.pdf) [🔗 Poster](https://linqlover.github.io/trace4d/poster-ivapp.pdf) [🔗 Slides](https://linqlover.github.io/trace4d/slides-ivapp.pdf)\n\n\u003cdetails\u003e\n\u003csummary\u003eBibTeX\u003c/summary\u003e\n\u003cpre\u003e\u003ccode\u003e@inproceedings{thiede2024bringing,\n  author = {Thiede, Christoph and Scheibel, Willy and D{\\\"o}llner, J{\\\"u}rgen},\n  title = {Bringing Objects to Life: Supporting Program Comprehension through Animated 2.5D Object Maps from Program Traces},\n  booktitle = {Proceedings of the 19th International Joint Conference on Computer Vision, Imaging and Computer Graphics Theory and Applications -- Volume 1: GRAPP, HUCAPP and IVAPP},\n  year = {2024},\n  series = {IVAPP '24},\n  month = {2},\n  days = {27--29},\n  publisher = {SciTePress},\n  organization = {INSTICC},\n  isbn = {978-989-758-679-8},\n  issn = {2184-4321},\n  doi = {10.5220/0012393900003660},\n  pages = {661--669},\n  location = {Rome, Italy}\n}\u003c/code\u003e\u003c/pre\u003e\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinqlover%2Ftrace4d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinqlover%2Ftrace4d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinqlover%2Ftrace4d/lists"}