Keycube Heatmap 3D

Interactive 3D visualization of Keycube study data.

This repository is the autonomous child project for Heatmap 3D. The official parent site is keycube.github.io, but this project should not render the parent site's global header or footer. The Heatmap 3D experience is served as its own focused GitHub Pages site.

Public demo: https://keycube.github.io/heatmap3d/

Available Pages

• / - Heatmap 3D landing page
• /preference/ - English preference visualization
• /reachability/ - English reachability visualization
• /preference-fr/ - French preference visualization
• /reachability-fr/ - French reachability visualization

With the configured baseurl: "/heatmap3d", the deployed URLs are under:

https://keycube.github.io/heatmap3d/

Project Overview

heatmap3d is a static Jekyll site that maps Keycube study data directly onto a 3D model of the device.

Current stack:

• Jekyll layouts and includes
• Vanilla JavaScript
• Three.js loaded in the browser from unpkg.com
• CSV datasets in _data/
• Liquid templates that inject CSV-derived data into JavaScript globals
• GitHub Pages deployment from main

Features

• Preference view with individual participants and aggregate results
• Reachability view with per-finger, per-hand, total, and preferred-finger modes
• Shared interactive 3D Keycube viewer
• English and French variants
• Autonomous Heatmap 3D shell without the parent keycube.io header/footer

Project Structure

heatmap3d/
├── index.markdown                  # Landing page entry
├── preference.markdown             # Preference page entry
├── reachability.markdown           # Reachability page entry
├── preference-fr.markdown          # French Preference entry
├── reachability-fr.markdown        # French Reachability entry
├── _layouts/
│   ├── landing.html                # Autonomous landing shell
│   ├── dataviz.html                # Autonomous 3D visualization shell
│   ├── heatmap-home.html           # Landing content
│   ├── heatmap-preference.html     # Preference content
│   ├── heatmap-preference-fr.html
│   ├── heatmap-reachability.html   # Reachability content
│   └── heatmap-reachability-fr.html
├── _includes/
│   ├── model-viewer.html           # Main Three.js viewer
│   ├── model-viewer-static.html    # Landing page static viewer
│   └── dataviz-data.html           # CSV-to-JS data injection
├── _data/
│   ├── preferences.csv
│   └── reachability.csv
├── assets/
│   ├── css/
│   ├── js/
│   └── img/
├── scripts/build_local_site.py     # Optional Python static fallback
├── Gemfile
├── Gemfile.lock
└── _site/                          # Generated Jekyll output

Key Files

• assets/js/dataviz.js - UI state, controls, preference and reachability interaction logic
• assets/css/dataviz.css - visualization page styling
• assets/css/landing.css - landing page styling
• _includes/model-viewer.html - Three.js scene and window.updateModel(...)
• _includes/dataviz-data.html - generated frontend data from CSV files
• _data/preferences.csv - preference study data
• _data/reachability.csv - reachability study data

Run Locally

Install dependencies:

bundle install

Start Jekyll:

bundle exec jekyll serve

Open:

http://127.0.0.1:4000/heatmap3d/
http://127.0.0.1:4000/heatmap3d/preference/
http://127.0.0.1:4000/heatmap3d/reachability/

Build only:

bundle exec jekyll build

The generated site is written to _site/.

Runtime Requirements

Browser requirements:

• ES modules
• import maps
• WebGL
• runtime access to unpkg.com

The 3D viewer loads:

https://unpkg.com/three@0.160.0/build/three.module.js
https://unpkg.com/three@0.160.0/examples/jsm/

Bundler Note

Gemfile.lock currently records:

BUNDLED WITH
  4.0.10

If bundle exec jekyll build fails because Bundler 4.0.10 is missing, install the matching Bundler version or regenerate the lockfile intentionally.

Optional Python Static Build

The repository includes a fallback static builder:

python3 scripts/build_local_site.py
python3 -m http.server 4000 --directory .local_site

This is useful when Jekyll is unavailable, but the recommended workflow remains Jekyll.

Maintenance Workflow

When the official parent site receives Heatmap 3D updates, copy only the Heatmap-specific changes into this child repository.

Typical source mapping from the parent site:

• assets/js/heatmap3d-dataviz.js -> assets/js/dataviz.js
• assets/css/heatmap3d-dataviz.css -> assets/css/dataviz.css
• assets/css/heatmap3d-landing.css -> assets/css/landing.css
• _includes/heatmap3d-model-viewer.html -> _includes/model-viewer.html
• _includes/heatmap3d-model-viewer-static.html -> _includes/model-viewer-static.html
• _includes/heatmap3d-dataviz-data.html -> _includes/dataviz-data.html
• _layouts/heatmap3d-* -> _layouts/heatmap-*

After copying from the parent:

• keep local routes as /, /preference/, /reachability/, /preference-fr/, and /reachability-fr/
• keep layout: landing and layout: dataviz in the child layouts
• do not reintroduce the parent site's global header or footer
• keep keycube.github.io/ and keycube.github.io-1/ excluded from Jekyll

Deployment

Deployment target:

https://keycube.github.io/heatmap3d/

Typical flow:

git status
bundle exec jekyll build
git add .
git commit -m "Update heatmap3d"
git push origin main

Troubleshooting

If local changes are not visible:

• confirm the URL includes /heatmap3d/
• rerun bundle exec jekyll build
• hard refresh the browser

If the 3D cube does not render:

• check the browser console
• confirm WebGL is enabled
• confirm unpkg.com is reachable

If data looks wrong:

• check CSV column names in _data/
• check _includes/dataviz-data.html
• check assets/js/dataviz.js

License

See the LICENCE

Credits

Guy Junior Calvet