{"id":50572301,"url":"https://github.com/imbue-ai/gp-treemap","last_synced_at":"2026-06-04T19:30:58.456Z","repository":{"id":353595342,"uuid":"1215280782","full_name":"imbue-ai/gp-treemap","owner":"imbue-ai","description":"Beautiful, interactive, large-scale treemaps for the web. Visualize resource usage, budgets, tabular data — anything hierarchical.","archived":false,"fork":false,"pushed_at":"2026-05-20T20:56:34.000Z","size":99167,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-21T01:04:23.721Z","etag":null,"topics":["data-visualization","disk-usage","resource-usage","treemaps"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imbue-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-19T18:02:40.000Z","updated_at":"2026-05-20T20:56:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imbue-ai/gp-treemap","commit_stats":null,"previous_names":["imbue-ai/gp-treemap"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/imbue-ai/gp-treemap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbue-ai%2Fgp-treemap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbue-ai%2Fgp-treemap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbue-ai%2Fgp-treemap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbue-ai%2Fgp-treemap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imbue-ai","download_url":"https://codeload.github.com/imbue-ai/gp-treemap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imbue-ai%2Fgp-treemap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33917183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["data-visualization","disk-usage","resource-usage","treemaps"],"created_at":"2026-06-04T19:30:57.838Z","updated_at":"2026-06-04T19:30:58.450Z","avatar_url":"https://github.com/imbue-ai.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gp-treemap: Beautiful, interactive, large-scale treemaps for the web\n\nTreemaps are often the best way to quickly hone in on the \"mass\" in large,\nhierarchical datasets.  You can think of them as \"hierarchical pie charts\".\n\nFor example, they're great for interactive visualizions of disk usage.\n\nWith this package, you can run:\n\n```sh\n# Opens browswer with a treemap of disk usage under ~/Downloads.\nnpx -p @imbue-ai/gp-treemap gpdu ~/Downloads\n```\n\nAnd see this visualization (click for the interactive version):\n\n[![gpdu scan of the gp-treemap source tree](tests/screenshots/gallery-source-tree.png)](https://imbue-ai.github.io/gp-treemap/gallery/)\n\n\nBut it's not just for disk usage. gp-treemap is a general web component,\ngreat for any time you have hierarchical counts to wrap your head around!\n\n* Spending reports (they never looked so beautiful!)\n* Budgets\n* Profiling data\n* Resource usage (Disk, RAM, inference tokens, electricity, ...)\n\nDon't forget that lots of tabular data can be made hierarchical using GROUP BY on a list of columns.\n\nCheck out the [gallery of more examples](https://imbue-ai.github.io/gp-treemap/gallery/),\nor the [side-by-side comparison](https://imbue-ai.github.io/gp-treemap/gallery/comparison.html)\nagainst Plotly.js and D3 on the same datasets.\n\n## CLI tools\n\nEach tool runs straight from `npx`, with no install. Hover any code\nblock on GitHub for a copy-to-clipboard button. File-header comments\nin [`tools/`](tools/) document every flag in detail.\n\n### `gpdu` — disk usage\n\n[`tools/gpdu-scan.js`](tools/gpdu-scan.js). Recursive directory scan;\nwrites a single self-contained HTML file with the bundle and dataset\ninlined. Symlinks are not followed.\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu ~/Downloads\n```\n\n### `gpdu-json` — JSON / JSON5 file\n\n[`tools/gpdu-json.js`](tools/gpdu-json.js). Visualizes a JSON or JSON5\nfile as a treemap. Each cell's area is the byte size of that node's\nserialized form in the source file. Internal nodes (objects, arrays)\ncarry a synthetic `(leftover)` leaf that absorbs structural-overhead\nbytes (braces, brackets, commas, whitespace, comments), so the tree's\ntotal reconciles to the source file size exactly. Color modes: type /\ndepth / key. Pruning: `--min-bytes=N`, `--max-array-children=N`.\nAccepts JSON5 (comments, trailing commas, unquoted keys, single-quoted\nstrings).\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu-json ./package.json\n```\n\n### `gpdu-sqlite` — SQLite database\n\n[`tools/gpdu-sqlite.js`](tools/gpdu-sqlite.js). Hierarchy:\ndb → table → [column-1, ..., index-1, ...]. Per-column byte sizes are\nestimated by sampling rows (default 10 000, override with\n`--sample-rows=N`) and applying SQLite's serial-type encoding rules\nJS-side. Pass `--include-row-elements-for-all-columns` for an exact\ncount via a full table scan, with each (row, column) becoming a leaf.\nSystem tables, views, and triggers are shown alongside (views \u0026\ntriggers as 0-byte cells). Color modes: kind / parent-table /\nvalue-type. Requires `better-sqlite3` (an `optionalDependency`).\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu-sqlite ./mydatabase.db\n```\n\n### `gpdu-s3` — S3 bucket via LIST\n\n[`tools/gpdu-s3.js`](tools/gpdu-s3.js). Recursively enumerates objects\nvia `ListObjectsV2` (or `ListObjectVersions` if `--include-versions`),\nfans out by `Delimiter=/` with an async Promise pool of `--workers=16`\nworkers. Synthesizes a folder hierarchy from `/`-separated keys. Auth\nvia the default AWS credential chain; `--region` overrides; pass\n`--no-sign-request` for public buckets. Color modes: extension /\nstorage class / last-modified. Requires `@aws-sdk/client-s3` (an\n`optionalDependency`).\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu-s3 --no-sign-request s3://esa-worldcover-s2/swir/2021/\n```\n\n### `gpdu-s3-inventory` — S3 bucket via daily Inventory parquet\n\n[`tools/gpdu-s3-inventory.js`](tools/gpdu-s3-inventory.js). Way faster\nthan `gpdu-s3` for large buckets — reads the daily S3 Inventory\nparquet report via DuckDB instead of paginating through\n`ListObjectsV2`. Two-pass SQL computes the total then partitions rows\ninto \"big leaves\" (kept verbatim) and \"(N small)\" rollups (grouped by\ndirectory at `--max-depth`). `--min-fraction=F` (default 0.001%)\ncontrols the keep-vs-rollup threshold. Output can be\n`s3://bucket/key.html` to upload directly. Requires `duckdb` on\n`PATH` and `@aws-sdk/client-s3` (an `optionalDependency`).\n\nYou'll need an [S3 Inventory configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-inventory.html)\non the bucket, with [Parquet output format](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html#storage-inventory-contents)\nand a destination bucket you have read access to. Inventory reports\nland daily under\n`s3://\u003cdestination\u003e/\u003csource-bucket\u003e/\u003cconfig-id\u003e/\u003cdate\u003eT01-00Z/manifest.json`.\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu-s3-inventory \\\n  s3://my-meta-bucket/my-source-bucket/inv-config-id/2026-04-29T01-00Z/manifest.json\n```\n\n### `gpdu-llm-density` — LLM token-continuation density\n\n[`tools/gpdu-llm-density.js`](tools/gpdu-llm-density.js). Visualizes the\nprobability distribution an LLM assigns to continuations of a starter\nprompt. Each tree node is one token; cell area is the joint probability\nof the prefix from the root to that token, so sibling areas at any\nsubtree sum to that subtree's joint and the whole treemap sums to 1.0.\nAt every internal node, a synthetic `(other)` leaf carries the residual\nmass — long-tail tokens dropped by `--top-k`, `--top-p`, or\n`--prune-probability` all fold into it, so aggregates reconcile exactly\nat every level. Traversal is depth-first with a KV-cache stack: each\ndescent is one new-token forward pass, and `eraseContextTokenRanges`\npops the cache between siblings, so the cost of exploring a tree is\nO(nodes) forward passes instead of O(nodes × depth) prefix\nre-evaluations. Color modes: probability / depth / token-rank /\nsurprisal / leaf-reason. Requires `node-llama-cpp` (an\n`optionalDependency`); `--model` accepts a local `.gguf` path or\nanything `resolveModelFile` recognizes (HF repo IDs, `hf:` URIs).\nModels cache under `~/.node-llama-cpp/models/`. Pass `--backend=stub`\nfor a no-model deterministic demo distribution.\n\n```sh\nnpx -p @imbue-ai/gp-treemap gp-visualize-llm-continuation-density \\\n  --prompt \"Time flies like an arrow. Fruit flies like a\" \\\n  --model hf:HuggingFaceTB/SmolLM2-135M-Instruct-GGUF:Q4_K_M \\\n  --continuation-max-depth=20 --prune-probability=1e-5\n```\n\n### `gp-columnar-treemap` — CSV / JSONL tabular data\n\n[`tools/table-treemap.js`](tools/table-treemap.js). General-purpose\nviewer for columnar data — accepts CSV, TSV, or JSONL (NDJSON). The\ngenerated HTML lets you pick Size and Color columns and drag chips to\nreorder the Path (group-by) hierarchy on the fly; state is persisted in\nthe URL hash. Initial selection can be seeded with `--size=COL`,\n`--color=COL`, `--path=A,B,C`. Powers several of the gallery examples.\n\n```sh\nnpx -p @imbue-ai/gp-treemap gp-columnar-treemap ./spending.csv\n```\n\n### `gp-treemap-profile-load` — capture a Chrome DevTools `.cpuprofile`\n\n[`tools/profile-load.js`](tools/profile-load.js). Launches headless\nChromium, records a V8 CPU profile across page load, and writes a\nstandard Chrome DevTools `.cpuprofile`. Requires Playwright +\nChromium (`npx playwright install chromium`).\n\n```sh\nnpx -p @imbue-ai/gp-treemap gp-treemap-profile-load https://example.com/ /tmp/load.cpuprofile\n```\n\n### `gp-treemap-profile-to-html` — `.cpuprofile` → treemap\n\n[`tools/profile-to-html.js`](tools/profile-to-html.js). Renders a\n`.cpuprofile` as a self-contained treemap of CPU time, bucketed by\nthread and call stack.\n\n```sh\nnpx -p @imbue-ai/gp-treemap gp-treemap-profile-to-html /tmp/load.cpuprofile\n```\n\n## Sandboxed usage\n\nIf you'd like the scanner to only be able to read the tree you're\nscanning — no `~/.ssh`, no `/etc`, nothing else — run it under Deno's\nper-path permission sandbox:\n\n```sh\nSCAN=~/Downloads\nOUT=/tmp/disk_usage.html\n\ndeno run \\\n  --allow-read=\"$SCAN\",\"$OUT\" \\\n  --allow-write=\"$OUT\" \\\n  --deny-env \\\n  npm:@imbue-ai/gp-treemap@0.6.2/gpdu --no-open \"$SCAN\" \"$OUT\" \\\n  \u0026\u0026 open \"$OUT\"\n```\n\n* On Linux, use `xdg-open` instead of `open`.\n\n\n## Comparison with other tools\n\nWe put together a [side-by-side comparison](https://imbue-ai.github.io/gp-treemap/gallery/comparison.html)\nof gp-treemap, [Plotly.js](https://plotly.com/javascript/treemaps/), and\n[D3](https://d3js.org/d3-hierarchy/treemap) on the same datasets — toy,\ndisk usage, and a 137k-node mega-treemap — with live render times\nmeasured in your own browser.\n\n## A hat tip to GrandPerspective\n\nMost treemap implementations we've seen are boring and don't scale well\nto millions of nodes, with [GrandPerspective](https://grandperspectiv.sourceforge.net/)\nbeing a wonderful exception.\n\n`\u003cgp-treemap\u003e` is a standards-compliant Custom Element that renders interactive\ntreemaps with GrandPerspective's signature \"raised tile\" pixel shading — bright\nupper-left, dark lower-right, with a crisp diagonal seam between the two halves\nof every cell.\n\nThis project is a JavaScript/Canvas port of the treemap view from\n[GrandPerspective](https://grandperspectiv.sourceforge.net/), the macOS disk\nvisualizer by Erwin Bonsma (and contributors). GrandPerspective is released\nunder the GNU General Public License, version 2, and so is `gp-treemap`.\n\nThe upstream 3.6.4 source is bundled under `GrandPerspective-3_6_4/` for\nreference. The treemap layout, the raised-tile shader, and the HSV brightness\nramp were all translated from that source — this is a derivative work in the\nGPL sense, not a clean-room reimplementation. If you want the original tool,\nor want to see where these algorithms came from, go support that project.\n\nIf you use `gp-treemap`, please keep the attribution to Erwin Bonsma visible.\n\n## Quick start\n\nNo install required — run directly via `npx`:\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu ~/Downloads\n```\n\nScans `~/Downloads`, writes a self-contained HTML file, and opens it in your\ndefault browser. Pass a second argument to choose the output path:\n\n```sh\nnpx -p @imbue-ai/gp-treemap gpdu ~/Pictures /tmp/pictures.html\n```\n\nTo install globally instead:\n\n```sh\nnpm install -g @imbue-ai/gp-treemap\ngpdu ~/Downloads\n```\n\nFor a sandboxed run under Deno — scanner restricted to just the scan tree\nand output directory — see the `deno run` example at the top of this README.\n\n## Repo layout\n\n```\nsrc/                    component source (ES modules)\n  gp-treemap.js           custom element: canvas render + hit-testing + toolbar\n  painter.js              per-pixel raised-tile painter\n  lut.js                  brightness-ramp LUT\n  layout.js               BSP slice-and-dice\n  balancer.js             balanced-binary-tree merge\n  builder.js              tabular + tree accessor ingestion\n  color-resolver.js       palette index assignment\n  color-scale.js          linear / log / diverging / quantile\n  palettes.js             built-in palettes\n  hash.js                 FNV-1a for categorical color hashing\n  format.js               d3-format-ish value formatter\n\nsamples/                one HTML per behavior (load via \u003cscript src\u003e)\n  index.html              links to all samples\n  filesystem.html         categorical, bytes formatter\n  budget.html             diverging quantitative\n  depth.html              ~960 leaves, categorical by order\n  interactions.html       event log + zoom demo\n  gradients.html          intensity 0 / 0.5 / 1 side by side\n  min-cell.html           pruning comparison\n  located.html            highlight-node demo\n  data/                   small datasets the samples attach to window.__data\n\ndist/                   build output\n  gp-treemap.bundle.js        single-file IIFE; defines the custom element\n\ntests/                  Playwright suite (Chromium)\n  visual.spec.js          screenshots → tests/screenshots/*.png\n  units.spec.js           core module unit tests (browser-run)\n  file-url.spec.js        smoke test that file:// renders correctly\n  unit-fixture.html       loader that exposes bundle helpers on window\n  screenshots/            committed PNGs — browse offline\n\ntools/\n  build.js                concatenates src/ → dist/gp-treemap.bundle.js\n  server.js               tiny static server (used by Playwright \u0026 local dev)\n  gpdu-scan.js            recursive directory scan → self-contained treemap HTML\n  profile-load.js         Playwright+CDP CPU profile capture → .cpuprofile\n  profile-to-html.js      .cpuprofile → treemap HTML (thread / call-stack)\n\nGrandPerspective-3_6_4/ upstream source bundled for reference (GPL v2)\n```\n\n## Tests\n\n```sh\nnpm run test:install     # one-time: download Chromium\nnpm test                 # run units + visual snapshots\n```\n\n## Spec deltas from upstream GrandPerspective\n\n- **Web Component, not a Cocoa view.** Rendering is a per-pixel loop on a\n  single `\u003ccanvas\u003e`. Paint of a full 1280×720 canvas with a few thousand cells\n  takes ~10–30 ms; WASM could give 5–20× headroom for 100k+ cells or per-frame\n  animation, not needed for MVP.\n- **Plain ES modules + IIFE bundle** — no Stencil, no generated React/Vue\n  wrappers. A Stencil wrapper can be grafted on later without API churn.\n- **FLIP data-change animations** are not yet implemented; a data change\n  rerenders the whole canvas.\n- **Resize** immediately CSS-scales the canvas, then re-paints after a\n  150 ms debounce.\n- Toolbar, palettes, color scales, keyboard / wheel / double-click behavior,\n  and FNV-1a categorical hashing are all new to this port.\n\n## License\n\nGNU General Public License, version 2. See [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimbue-ai%2Fgp-treemap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimbue-ai%2Fgp-treemap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimbue-ai%2Fgp-treemap/lists"}