hijiangtao/glmaps

Data visualization examples and tutorials from scratch. 数据可视化示例代码集与新手学习教程。

glmaps

Spatio-temporal data visualization example codes and tutorials from scratch.

README

English | Chinese

What is glmaps?

glmaps is a project full of bunch of earth and map visualization examples based on Three.js and Deck.gl, as well as some tutorials for visualization beginners. Easy to learn and use.

Watch online demo video at YouTube or Tencent Video.

A brief introduction of thie project is now available at Meidum, Zhihu and my blog.

Table of Contents

1. Overview - Check all visualization types that glmaps contains.
2. ZERO - Some thoughts from me that you may pay attention before have future reading.
3. Demo - Open browser and enter https://localhost:8080 to check the demo locally.
4. Tutorials - A series of tutorials that guide you how to code these visualization examples step by step. TBD.
5. Install - Installation guide for developers. Just have a try, glmaps has not get ready for industry applications.
6. Usage - Usage for how to include glmaps in your application.
7. Documents - API document for glmaps. TBD.
8. Stories - Stories behind this repositry.
9. Resources - Resources for further learning in Spatio-temporal Data Visualization, WebGL, etc.

Overview

Check all visualization types that glmaps contains, 2.5D means you can draw 3D geometries on a 2D map, 3D means a total 3D data visualization approach.

Type	Description	Demo	Animation	Cluster
3D / Curve	THREE.BufferGeometry()		Yes	No
3D / Mover	THREE.SphereGeometry()		Yes	No
3D / Cube	THREE.BoxGeometry()		No	No
2.5D / Icon	No modification from deck		No	Yes
2.5D / Brush	Support OD Arc Animation		Yes	No
2.5D / Scatter	Support Fade-out Animation		Yes	No
2.5D / Hexagon	Support Coverage Filter Conditions		Yes	Yes
2.5D / Grid	Support Coverage Filter Conditions		No	Yes
2.5D / Trip	No modification from deck		Yes	No
2.5D / Cube	No modification from deck		No	No
Other / Segment	The same as curve animation		No	No
Other / Moon	Earth-Moon System		No	No

ZERO

Thanks for your attention in this project, there are some thoughts from me that you may pay attention before have future reading.

Q: What frameworks are used in glmaps?

React Hooks is ready in 16.8.0, and glmaps get benefits from it at once, if you are not familiar with it, please check Introducing Hooks first; On the other hand, deck.gl is WebGL2 powered geospatial visualization layers, so please make sure your browser support WebGL2. To find out if WebGL(2) is enabled in your browser, go to http://get.webgl.org/ or https://get.webgl.org/webgl2/.

Besides, if you meet any errors when depoly it locally, you can describe your problem with issues, because that's most likely a problem of glmaps rather than yourself, since glmaps organizes local development environment from scratch, such as webpack, babel, etc.

Q: Guidance for visualization beginners?

I highly recommend you follows these steps in using glmaps:

• Learn how to install three.js and deck.gl from scratch, and code your first "Hello World" with them;
• Run official demos and get familiar with their API;
• Follow the tutorials step by step to make your visualization examples more powerful, or check glmaps codes in src folder directly;
• (Optional) Use glmaps in your demo application, start with npm install glmaps --save;
• Rewrite glmaps example with your own codes;
• Congratulations on mastering basics of spatio-temporal visualization, you can use three.js and deck.gl to draw a more fantastic world with spatio-temporal data!

Q: How to participate in glmaps project?

glmaps is still at the very beginning period of my thoughts, you are welcome to oepn ISSUE, PR or email me, if you have any ideas on how to make glmaps better for visualization beginners:

• Participate in implementing tutorials together;
• Contribute codes to glmaps with PR (such as imporve mover animation in Globe);
• Speak out your doubts in learning data visualization with issues;
• Tell me your advice on how to make glmaps better with issues;
• Other aspects not included yet.

Demo

Open browser and enter https://localhost:8080 to check the demo locally. Please enjoy the power of three.js and deck.gl.

git clone [email protected]:hijiangtao/glmaps.git
cd glmaps
npm install
touch devconfigs.js

To use any of Mapbox's APIs, you'll need a Mapbox access token. Mapbox uses access tokens to associate requests to API resources with your account. Since TOKEN is a private key, glmaps doesn't provide it in codes, you need to specify it in file devconfigs.js.

Here's what an access token looks like (focus on the string starts with pk., replace it with your own token. You can create your mapbox Token here) and the devconfigs.js file format:

// devconfigs.js
const MAPBOX_TOKEN = 'pk.eyJ1IjoiaGlqaWFuZ3RhbyIsImEiOiJjampxcjFnb3E2NTB5M3BvM253ZHV5YjhjIn0.WneUon5qFigfJRJ3oaZ3Ow';

export {
  MAPBOX_TOKEN,  
}

Tips: You can utilize Search engine to get other's mapbox tokens if you don't want to create a new one, here's one token I got from GitHub Search: 'pk.eyJ1IjoiY3NuIiwiYSI6ImNpdnRvam1qeDAwMXgyenRlZjZiZWc1a2wifQ.Gr5pLJzG-1tucwY4h-rGdA', though it's not recommend to "steal" other's token…

Save changes in devconfigs.js and go on:

npm run start

When glmaps is ready, it will open browser automatically, and render demos for you.

Tutorials

A series of spatio-temporal data visualization tutorials that guide you how to code these visualization examples step by step. TBD.

• Visualization Tutorials from scratch (I) - Introduction of data visualization with three.js
• Visualization Tutorials from scratch (II) - Introduction of data visualization with deck.gl
• Visualization Tutorials from scratch (III) - Manage your three.js application with React
• Visualization Tutorials from scratch (IV) - Draw a earth-moon system with three.js from scratch
• Visualization Tutorials from scratch (V) - How to draw curve, mover and cube with three.js
• Visualization Tutorials from scratch (VI) - Animate your layers with props and transitions
• Visualization Tutorials from scratch (VII) - Animate your deck.gl with customized shaders
• Visualization Tutorials from scratch (VIII) - Some tips in data visualization with deck.gl and three.js

Install

The installation is for developers who wants to use glmaps in their demos.

cd YOUR_REPO
npm install glmaps --save

Usage

This is a package mainly designed for visualization lovers in learning Three.js and Deck.gl, however, you can use them as a normal package as other packages in npm.

import React from 'react';
import {Globe} from 'glmaps';

/**
 * Data format:
 * [
 *   [
 *      source.lat,
 *      source.lng,
 *      target.lat,
 *      target.lng,
 *   ],
 *   ...
 * ]
 */
const Demo = (props) => {
  return (
    <Globe
      data={props.data}
      id={YOUR_MOUNT_DOM_ID}
      animate={true}
      moon={true}
      visType={'curve'}
    />
  )
};

More examples and detailed usage guidances can be found in documents.

Documents

This part is still under constructing, however, you can access full codes in src folder right now.

• Layers (2.5D Map)
  1. ArcLayer
  2. HexagonLayer
  3. IconLayer
  4. ScatterplotLayer
  5. ScreenGridLayer
  6. TripLayer
• Globe (3D Space)
  1. Curve
  2. Mover
  3. Cube
  4. Moon

src
├── globe
│   ├── CubeMesh.js
│   ├── Curve.js
│   ├── Mover.js
│   ├── README.md
│   ├── SceneManager.js
│   ├── Tube.js
│   ├── constants.js
│   ├── index.js
│   ├── index.less
│   └── utils.js
├── index.js
└── layers
    ├── AnimationLayer
    │   └── index.js
    ├── ArcLayer
    │   ├── animate.js
    │   └── index.js
    ├── HexagonLayer
    │   └── index.js
    ├── IconLayer
    │   ├── cluster.js
    │   ├── icon-mapping.js
    │   └── index.js
    ├── README.md
    ├── ScatterplotLayer
    │   └── index.js
    ├── ScreenGridLayer
    │   └── index.js
    └── TripLayer
        └── index.js

Resources

You are welcome to raise PR to add more contents of this part, let's contribute together to make it more valuable.

1. Online Book/Series

• WebGL Fundamentals
• WebGL2 Fundamentals

2. Video Tutorials

TBD

Stories

Q: Why I create this repositry?

A: I am really impressed by many open source developers when I learning how to visualize data on Web. They had contributed a lof of codes and resources in guiding beginners. This year, I want to take visualization as a serious work to do in my spare time. I will keep on record what I learned in my blog, at the same time I want to share more and hope my notes and codes can raise your interests in data visualization, too. Keep Simple and Love Visualization.

Contact

@hijiangtao

LICENSE

MIT

glmaps's Issues

[RELEASED] Visualization Tutorial One / 可视化教程（一）

EN

Tutorial One - Introduction of three.js and how to draw a simple geometry hierarchy demo with it

I just published the first chinese version tutorial of glmaps, which contains a brief introduction of three.js and how to draw a simple geometry hierarchy demo with it.

The blog address is https://hijiangtao.github.io/2019/04/03/Learn-Spatio-Temporal-Data-Visualization-with-glmaps-from-Scratch-One/.

Due to the limitation of my time, I couldn't guarantee to update english version of these tutorials in time. You are welcome to open ISSUE, PR or email me, if you have any ideas on how to make glmaps better for visualization beginners.

---

CN

从零开始学习时空数据可视化（一）

从零开始学习时空数据可视化系列教程发布了第一篇 - three.js 简介与示例教学，你可以选择以下你喜欢的方式进行阅读：

• 博客 https://hijiangtao.github.io/2019/04/03/Learn-Spatio-Temporal-Data-Visualization-with-glmaps-from-Scratch-One/
• 知乎 https://zhuanlan.zhihu.com/p/61350952

本教程涉及到的代码与示例如下：

• 本文在线 Demo https://hijiangtao.github.io/glmaps/tutorials/example_three_geometry_hierarchy.html
• 本文示例代码 https://github.com/hijiangtao/glmaps/blob/master/tutorials/example_three_geometry_hierarchy.html

「从零开始学习时空数据可视化」系列按照我的最初思路会分为八篇教程，但难免在知识面覆盖上有所偏差，如果你有任何建议或想法，欢迎新开 issue 参与讨论。

求vue代码

看文档说明，是基于react实现的，有没有基于vue实现的

Todos of v0.0.4 - Deps upgrade and demo codes rearrangement

Thanks for your support on glmaps project, there's not too much improvements since last few months ago, but with technologies moving forward, the repo itself should be reviewed again so as to get the pace of its' deps (three.js and deck.gl).

Previous release and future todos

I just release v0.0.3 of glmaps, and it will be the last version which still supports deck.gl @v6.4.x. In the next version, I should focus on following things:

1. Upgrade deps such as deck.gl to v7, so that to allow developers use glmaps with deps' new grammar (in map visualization aspect);
   • deck.gl @v7
   • three.js codes review
   • react-map-gl codes review
   • mapbox codes review
2. Rearrange the demo codes, to make current data visualization example codes clear with later added WebGL example codes, as well as building a bundle of them to let developers preview the effects online;
   • glmaps demo codes (layers)
   • glmaps demo codes (globe)
   • WebGL demo codes
   • Bundle and preview deployment
3. Other improvements such as visualization tools for people who don't know how to code, etc.
   • Map Data visualization tools (Plan to support input data format with CSV, JSON, TSV, etc)

Besides, the tutorials will be suspended since I don't have enough time in putting my thoughts from codes to articles.

Developing arrangement

I add a new project in tracking the progress of v0.0.4, and I also add a CHANGELOG of glmaps, you can find previous changes in it with details.

• master branch contains the latest stable data visualization codes and tutorials;
• dev branch is for regular development of glmaps;
• feat-deck-v7 branch is used in developing v0.0.4, and it should contains all the new features mentioned above;

If you have any ideas about glmaps' development, you can comment or open a PR to let me know it. Last, please feel freee to star glmaps if you think it‘s a cool project!