Gio.js -- 一个基于 Three.js 的 Web3D 地球数据可视化库（一）-CSDN博客

本文链接：https://blog.csdn.net/baozi141990/article/details/120782030

Gio.js 是一个基于Three.js的web 3D地球数据可视化的开源组件库。使用Gio.js的网页应用开发者，可以快速地以申明的方式创建自定义的Web3D数据可视化模型，添加数据，并且将其作为一个组件整合到自己的应用中。

开始使用

系统要求
Gio.js仅依赖于Three.js。

经过测试，Gio.js在Three.js R90版本下可以很好地运行和使用。
Gio.js可以运行在以下的浏览器环境中:

浏览器	版本
Chrome	64.0.3282.167+
Firefox	58.0.2+
Safari	10.0.1+

安装

你可以通过以下两种途径来安装Gio.js:
途径1: <script>标签
在HTML页面的部分引入依赖，如下所示：

<script src="three.min.js"></script>
<script src="gio.min.js"></script>

注意: 请将 three.js 在 Gio.js 之前引入。

也可以使用cnd引入

    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r112/three.min.js"></script>
    <script src="https://raw.githack.com/syt123450/giojs/master/build/gio.min.js"></script>

注意一下版本，r112亲测可以使用

途径2: JavaScript包管理工具
NPM

安装Gio.js并保存到package.json

npm install giojs --save

引入Gio.js模块

var Gio = require('giojs');

Yarn
使用Yarn添加giojs依赖

yarn add giojs

引入Gio.js模块

var Gio = require('giojs');

现在你已经下载了Giojs，并且可以开始基于Giojs开发你的3D应用了！

使用

在HTML页面中添加了Threejs和Giojs依赖之后，您就可以基于Giojs开发您的应用了。我们将展示如何创建一个具有基础样式的Gio地球。

创建一个 <div> 标签，您的Gio地球将会被渲染在这个标签中。

<div id="globeArea" style="width: 200px; height: 200px"></div>

在您的页面中添加以下Javascript代码：

<script>
        $(function () {

                // 获得用来来承载您的IO地球的容器
                var container = document.getElementById( "globalArea" );

                // 创建Gio控制器
                var controller = new GIO.Controller( container );

                // 添加数据
                controller.addData( data );

                // 初始化并渲染地球
                controller.init();
        });
</script>

小贴士：我们在示例代码中使用了JQuery来让代码在页面加载完后执行。
3. 如果一切顺利，在浏览器中打开您的HTML页面你将会看到以下3D地球：点我

完整代码如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Hello World (Simplest Usage) / Gio.js</title>
    <!-- JQuery is not necessary, it is used for AJAX in this demo -->
    <script src="js/jquery.min.js"></script>
    <!-- must include Three.js library before Gio.js-->
    <script src="js/three.min.js"></script>
    <!-- must include the Gio.js library-->
    <script src="../build/gio.min.js"></script>
    <link rel="stylesheet" href="css/common.css">
    <style>
        #globalArea {
            height: 100%;
            width: 100%;
            margin: 0;
            padding: 0;
        }
    </style>
</head>
<body>
<header>A demo showing the simplest usage of Gio.js</header>
<div id="globalArea"></div>
<script>
    // get the container to hold the IO globe
    var container = document.getElementById( "globalArea" );
    // create controller for the IO globe, input the container as the parameter
    var controller = new GIO.Controller( container );
    // ask a file for the JSON data, using AJAX to load the data
    $.ajax( {
        url: "https://giojs.org/examples/data/sampleData.json",
        type: "GET",
        contentType: "application/json; charset=utf-8",
        async: true,
        dataType: "json",
        success: function ( inputData ) {
            // if received the data, use addData() API to add the the data to the controller
            controller.addData( inputData );
            // call the init() API to show the IO globe in the browser
            controller.init();
        }
    } );
</script>

</body>
</html>

基础元素

简介

为了更好地创建Gio地球，让我们先来看看Gio地球中有什么。以下图片中标注了Gio地球中的重要元素，在本章中我们会对这些元素进行具体介绍。
在这里插入图片描述

表面
整个3D地球的表面。
国家
地球表面上的特定区域，表示具体的某个国家。
连接线
连接两个国家之间的曲线，同时以流动的闪光点来体现数据数值的大小。
背景
3D场景的背景。
光晕
在地球周围的光圈。
海洋
地球表面上的特定区域，表示海洋区域。
性能监控
左上角的小窗口，用于监控应用性能。

表面

在这里插入图片描述
表面包括了国家和海洋。默认的表面颜色是0xffff。
可以通过configure()API来设置表面颜色，具体设置方法如下所示：

controller:configure({
		color:{
			surface:0xff0000
		}	
})

也可以通过 setSurfaceColor() API来动态修改表面颜色。

国家

在这里插入图片描述
每个国家都有一个特定的 ISO 3166代码。
根据输入数据和用户的交互行为，在Gio地球表面的国家可以有以下几种状态：

被选中的国家
当用户点击Gio地球表面某个国家的区域时，这个国家会以“被选中”的状态点亮。此时这个国家被称为"被选中的国家"。
可以通过 configure() API来设置被选中国家的颜色，具体设置方法如下所示：
```
controller.configure({
        color: {
                selected:0xff0000
        }
});
```
也可以通过 setSelectedColor() 来动态改变被选中国家的颜色。
有关的国家
当一个国家被选中时，Gio地球会显示该国家的数据，这些数据会以"连接线"的形式呈现，被连接线连接的国家被称为"有关的国家"（不包括"选中的国家"）。
可以通过 configure() API来设置"有关的国家"的亮度，默认的亮度是0.5，具体设置方法如下所示：
```
controller.configure({
        brightness: {
                related:0.8
        }
});
```
或者可以通过 adjustRelatedBrightness() 来动态改变有关的国家的亮度。
被提到的国家
除了"被选中的国家"和"有关的国家"之外，其余所有在数据集中提到的国家被定义为"提到过的国家"。
可以通过 ligtenMentioned(true) 设置"被提到的国家"的亮度，使其比地球表面的亮度略高，可以使用 ligtenMentioned(false) 来关闭该功能，默认设置下该功能不开启。
可以通过 configure() API来设置"被提到国家"的亮度，默认的亮度是0.5，具体设置方法如下所示：
```
controller.configure({
        color: {
                mentioned:0.8
        }
});
```
也可以通过 adjustMentionedBrightness() 来动态设置"被提到国家"的亮度。需要注意的是只有使用 ligtenMentioned(true) 后才可以设置"被提到国家"的亮度。
未被提到的国家
那些在数据集中未被提到的国家被称为"未被提到的国家"。
不可点击的国家
可以设置一个国家成为"不可点击的"状态，当用户点击"不可点击的国家"时，这个国家不会被点亮，同时也不会造成地球旋转。（在默认情况下，当一个国家被点击时，Gio地球会旋转，使该国家朝向正前方）
可以通过 disableUnmentioned(true) API来将未在数据集中提到的数据设置为"不可点击的"，也可以通过调用 disableUnmentioned(false) API来关闭该设置。

连接线

在这里插入图片描述
连接线是Gio地球数据可视化的重要部分，两个国家之间的数据会通过数据线以流动的方式按照一定的方向移动。对于被选中的国家，表示流入数据的线条称为"输入线"，表示流出数据的线条称为"输出线"。 "输入线"的默认颜色是0x154492，"输出线"的默认颜色是0xdd380c。
可以通过 configure API来设置连接线的颜色，具体设置方法如下所示：

controller.configure({
        color: {
                in:0xff0000,
                out:0x00ff00
        }
});

也可以通过 setInLineColor() API和 setOutLineColor() API来动态改变"输入线"和"输出线"的颜色。
那可不可以设置特定某条连接线的颜色呢？当然是可以的。可以直接修改输入json数据来设置，具体设置方法如下所示：

{
        "e": "CN",
        "i": "US",
        "v": 100000,
        "inColor": "#0000ff",
        "outColor": "#00ff00"
}

动态设置连接线的颜色需要在调用controller.init()之后才会生效。想要了解更多相关数据设置的细节，可以查看本文档的数据部分。

背景

背景是在3D场景中"地球背后"的区域。背景默认的颜色是0x000000。
背景的颜色可以通过 configure() API进行设置，如下所示：

controller.configure({
        color: {
                background:0x0000ff
        }
});

也可以通过 setBackgroundColor() API来动态改变背景颜色。

光晕

光晕是在地球周围的光圈。光晕的默认颜色是0xffffff.
可以通过 configure() API来设置光晕的颜色，具体设置方法如下所示：

controller.configure({
        color: {
                halo:0xff0000
        }
});

也可以通过 setHaloColor() API来动态修改光晕颜色。

海洋

海洋是3D地球表面表示海洋的特定区域，在Gio地球表面，海洋是最暗的区域。海洋的默认亮度是0.5。
可以通过 configure() API来设置海洋的亮度，具体设置方式如下所示：

controller.configure({
        brightness: {
                ocean:0.8
        }
});

也可以通过 adjustOceanBrightness API来动态改变海洋亮度。

性能监控

"性能监控"整合了Threejs的监控组件stats，如果你对这个组件感兴趣，你可以从它的 github 仓库中了解更多细节。如果你想要在gio场景中显示这个组件，你可以使用 enableStats() API，这个性能监控面板默认会显示在左上角。

配置

通过构造函数配置

当创建Gio controller对象时，可以将配置参数传递给controller，具体传递方式如下所示：

var configs = {
        color: {
                surface:0xFF0000
        }
};
var globe = new Gio.controller(container, configs);

通过API配置

或者可以在controller创建之后，使用configure API来配置controller，具体使用方式如下所示：

controller.configure(configs);

configure API接受的参数和通过构造函数配置配置一样，可以查看配置参数表了解各个配置参数的详细解释。

配置参数表

var configs = {
        control: {
                stats: false,
                disableUnmentioned: false,
                lightenMentioned: false,
                inOnly: false,
                outOnly: false,
                initCountry: "CN",
                halo: true
        },
        color: {
                surface: 0xFFFFFF,
                selected: null,
                in: 0x154492,
                out: 0xDD380C,
                halo: 0xFFFFFF,
                background: null
        },
        brightness: {
                ocean: 0.5,
                mentioned: 0.5,
                related: 0.5
        }
}

参数表

参数名	默认值/范围	描述
control.stats	false	True表示开启性能监控
control.disableUnmentioned	false	True表示设置"未提到的国家"不可点击
control.lightenMentioned	false	True表示设置地球表面"提到的国家"比"未提到的国家"更亮
control.inOnly	false	True表示只显示"输入线条"
control.outOnly	false	True表示只显示"输出线条"
control.initCountry	“CN”	初始"被选中国家"
control.halo	true	True表示显示光晕
color.surface	0xFFFFFF or “#FFFFFF”	大陆以及海洋颜色
color.selected	null	被选中国家颜色
color.in	0x154492 or “#154492”	"输入线条"颜色
color.out	0xDD380C or “#DD380C”	"输出线条"颜色
color.halo	0xFFFFFF or “#FFFFFF”	光晕颜色
color.background	null	背景颜色
brightness.ocean	0.5 [0.0, 1.0]	海洋亮度
brightness.mentioned	0.5 [0.0, 1.0]	被提到国家亮度
brightness.related	0.5 [0.0, 1.0]	有关国家亮度

功能设计型API

功能设计型API是一组可以控制Gio元素（呈现或隐藏）的API。除文档外，我们还提供在线演示来帮助您更好地理解这些API。点击以下链接来查看各个API详细的解释。

设置初始国家
高亮被提及国家
禁用未提及国家
显示(隐藏)输入线(输出线)
添加/删除光晕
启动/禁用性能监控
透明背景
自动旋转

设置初始国家

设置初始被选中国家。当Gio地球完成初始化之后，地球会有一个转动动画，将初始国家转至屏幕正前方。默认设置下初始国家是"CN"（中国）。

默认初始国家：
在这里插入图片描述

// 将初始国家改成"美国"
controller.setInitCountry("US");

在这里插入图片描述

高亮被提及国家

使Gio地球表面上提及国家比未提及的国家更亮。在默认情况下，提及国家和未提及国家的亮度是一样的。

controller.lightenMentioned(true);

在这里插入图片描述

controller.lightenMentioned(false);

在这里插入图片描述

禁用未提及国家

禁止点击未提及的国家，这个操作会使在数据集中未提到过的国家在3D地球上不可选。默认设置下此功能不开启。

controller.disableUnmentioned(true);

在这里插入图片描述

// 禁用此功能
controller.disableUnmentioned(false);

对于被选中的国家，只显示输入线或者输出线
只显示输入线
只显示输出线

controller.showInOnly(true);

在这里插入图片描述

controller.showInOnly(false);

在这里插入图片描述

controller.showOutOnly(true);

在这里插入图片描述

controller.showOutOnly(false);

在这里插入图片描述

添加/删除光晕

添加/删除光晕是一组API，可以控制是否在3D地球周围显示光晕。当使用addHalo() API添加光晕时，可以指定光晕颜色。默认设置下光晕是启用的。

controller.addHalo(0xFF0000);

在这里插入图片描述

controller.removeHalo();

在这里插入图片描述

启动/禁用性能监控

显示或隐藏左上角的性能监控组件。在使用这个API之前，需要先在HTML页面的 <header> 部分引入stats.min.js

<header>
        <script src="stats.min.js"></script>
</header>

controller.enableStats();

在这里插入图片描述

controller.disableStats();

在这里插入图片描述

透明背景

通过使用启用透明背景功能，可以使用自定义图片作为背景。

controller.setTransparentBackground( true );

在这里插入图片描述

自动旋转

使地球自动旋转，并控制旋转速率。地球的自动旋转功能在默认情况下是关闭的，如果启动旋转功能，默认的旋转速率是1。

// 启用自动旋转功能，将转速设置为1（同时1也是默认的转速） 
controller.setAutoRotation( true, 1 );

在这里插入图片描述

颜色风格类API

颜色风格类API用于设置Gio地球的风格（颜色和亮度）。您可以自定义几乎所有Gio地球的参数，例如表面，国家，连接线，光晕，背景，海洋等等。我们同时在文档中提供在线演示和 Codepen 在线编辑器用于帮助您理解和测试每一个API。您可以点击以下链接来了解每一个API的定义和使用详情。

设置风格
设置表面颜色
设置选中国家颜色
设置输出颜色
设置输入颜色
设置光晕颜色
设置背景颜色
设置海洋亮度
设置相关国家亮度
设置提到国家亮度
设置风格
通过设置风格名称来更改3D地球的颜色风格。Gio.js提供一些预设的色彩风格。

预设风格

这里您可以预览我们提供的预设配色模板，您可以通使用风格名称来应用所有的预设颜色风格。例如：将默认风格更改为“magic”风格：
在这里插入图片描述

controller.setStyle("magic");

在这里插入图片描述

预设风格预览

controller.setStyle("blueInk");

在这里插入图片描述

controller.setStyle("earlySpring");

在这里插入图片描述

controller.setStyle("frozenBerry");

在这里插入图片描述

controller.setStyle("gorgeousDream");

在这里插入图片描述

controller.setStyle("juicyCake");

在这里插入图片描述

controller.setStyle("lemonGate");

在这里插入图片描述

controller.setStyle("magic");

在这里插入图片描述

controller.setStyle("mint");

在这里插入图片描述

controller.setStyle("nearMoon");

在这里插入图片描述

controller.setStyle(“octoberParty”);
在这里插入图片描述

controller.setStyle("redBlue");

在这里插入图片描述

controller.setStyle("strawberry");

在这里插入图片描述

controller.setStyle("sunset");

在这里插入图片描述

设置选中国家颜色

通过RGB值设置在选中状态下的国家颜色。默认的选中国家颜色和表面颜色相同，但亮度稍高。

默认：

// 颜色的参数可以是字符串 "#FF0000" 或者是十六进制数值 0xFF0000
controller.setSelectedColor("#FF0000");
//controller.setSelectedColor(0xFF0000);

通过RGB值设置输出线的颜色。关于连接线定义，请参考这里: 连接线。

默认的输出线颜色是 0xDD380C：
在这里插入图片描述

// 颜色的参数可以是字符串 "#FEF504" 或者是十六进制数值 0xFEF504
controller.setExportColor("#FEF504");
//controller.setExportColor(0xFEF504);

在这里插入图片描述
Gio.js – 一个基于 Three.js 的 Web3D 地球数据可视化库（二）