3D github repository visualiser
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
client
libs Allow branch to be set to get commits from GitHub API Mar 27, 2018
static/assets/images repo is public, readme pic Apr 13, 2018
.gitignore 1st pass Mar 19, 2018
CNAME Create CNAME Apr 5, 2018
README.md Update README.md Aug 1, 2018
config.js switch db May 9, 2018
package.json update packages Aug 28, 2018
server.js set currentPage to commitTotal if no commits in DB Sep 10, 2018
yarn.lock build Oct 29, 2018

README.md

WebGL Gource

WebGL Gource is a 3D git repository history visualization tool inspired by the famous Gource visualization: https://github.com/acaudwell/Gource.

It employs a custom GPGPU Force Directed Graph simulation to efficiently maintain it's structure.

This package comes with a Node JS server for populating Google Firebase Firestore from the Github API and a frontend client for running the visualization.

Gource visual

Install server dependencies with:

yarn install

Install client dependencies with:

cd client && yarn install

To start the Node server and the frontend client, run this in the root directory:

yarn dev

Firebase Firestore data storage

WebGL Gource relies on data being copied from the Github API to Google Firebase Firestore. You will need to set up a new Firebase Firestore project through your Google Console.

Once this is set up, paste the following into the Firestore Rules:

// Allow read/write access on all documents to any user signed in to the application
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      allow read: if request.auth.uid != null;
      allow write: if request.auth.uid != null;
    }
  }
}

Following this, you need to enable Anonymous authentication for the Google project. This step is to slow down a potential DDOS attack.

In order to run the Node server you will need to download your Firebase Admin SDK service account key json file and put this in /auth. Add the key filename to /config.js

Local server config

Enter the details of the Github Repository you wish to use in /config.js (these values can also be passed as query strings when running the update script):

const config = {
  GHRepo: 'REPO_NAME',
  GHBranch: 'BRANCH',
  GHOwner: 'OWNER',
  FBFilename: 'FIREBASE_ADMIN_SDK_FILENAME'
}

Github access token

Create a new Github personal access token: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ and add this as a Node JS environment variable with the key: TOKEN_GITHUB_DOT_COM

Populating Firebase Firestore

With all of the above configured you should be able to run:

yarn dev

To start populating Firebase Firestore, point your browser to:

http://localhost:5000/api/updateDB

If you hit github API rate limiting or the script is stopped for any reason, the script will automatically pick up where it left off. For a production environment as on https://cardanoroadmap.com/ you can set this script run as a cron job to keep Firebase up to date with the git repository.

It should be noted that each repository branch needs to be added separately.

Google Cloud Function for file click interaction

In order to show details about a file on click you will need to set up a Google Cloud Function to pull data from the Github API. There is an example script and package.json in /client/cloud_functions/

Running the Visualization

The following code will create a new gource instance:

window.onload = function() {
  if (gource.canRun()) {
    gource.init(config).on('ready', function() {

    }
  }
}

A detailed example implementation can be found in: /client/build/index.html

The following config settings can be passed to the Gource instance. Default values can be found in /client/src/Config.js.

config = {
          git: {
            owner: 'input-output-hk',
            repo: 'cardano-sl',
            branch: 'develop',
            commitHash: '', // hash of commit to load
            commitDate: '', // date to load (YYYY-MM-DD)
            loadLatest: true // load latest commit in db
          },
          display: {
            showUI: true,
            showSidebar: true
          },
          FDG: {
            nodeSpritePath: 'textures/dot.png', // path to node texture
            nodeUpdatedSpritePath: 'textures/dot-concentric.png', // path to node updated state texture
            fontTexturePath: 'textures/UbuntuMono.png', // path to font texture
            autoPlay: false,
            delayAmount: 1000, // time in between new commits being added to the graph
            sphereProject: 0, // project graph onto sphere? 1 == true, 0 == false
            usePicker: false, // show file commit details on click
            pickerLoadingPath: '/assets/images/loading.svg', // show file commit details on click
            sphereRadius: 500, // radius of sphere if in sphere projection mode
            showFilePaths: true, // display filepath overlay on nodes
            colorPalette: [ // colors to use if cycleColors is switched off
              '#eb2256',
              '#f69ab3',
              '#1746a0',
              '#6f9cef',
              '#652b91',
              '#0e5c8d',
              '#1fc1c3'
            ]
          },
          scene: {
            fullScreen: true,
            width: 800,
            height: 600,
            bgColor: 0x121327,
            antialias: false,
            canvasID: 'gource-stage', // ID of webgl canvas element
            autoRotate: false, // auto rotate camera around target
            autoRotateSpeed: 0.001 // speed of auto rotation
          },
          post: {
            vignette: true
          },
          camera: {
            fov: 45,
            initPos: {x: 0, y: 0, z: 1600},
            enableZoom: true // enable camera zoom on mousewheel/pinch gesture
          }
        }

TODO

  • Move external UI from https://cardanoroadmap.com/ to the react application
  • Move frontend data sorting code to webworkers to ensure smooth playback in play mode
  • Add higher visual quality setting for faster machines
  • Debug Firestore indexedDB local storage anomalies
  • Use an octree for physics calculations
  • Add UI widgets to expose more information about the repository to the user