上接Gio.js – 一个基于 Three.js 的 Web3D 地球数据可视化库（一）
Gio.js使用记录

颜色风格类API

设置输出颜色

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

默认的输出线颜色是 0xDD380C：

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

设置输入颜色

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

默认的输入线颜色是 0x154492：

// 颜色的参数可以是字符串 "#00FF00" 或者是十六进制数值 0x00FF00
controller.setImportColor("#00FF00");
//controller.setImportColor(0x00FF00);

设置光晕颜色

通过RGB值设置光晕的颜色。

光晕的默认颜色是 0xFFFFFF:

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

设置背景颜色

通过RGB值设置背景的颜色。 默认的颜色是 0x000000：

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

设置海洋亮度

您可以设置海洋的亮度。亮度的数值范围是 [0, 1] ，默认的亮度数值是0.5：

controller.adjustOceanBrightness(0.8);

设置相关国家亮度

您可以设置相关国家的亮度。 亮度的数值范围是 [0, 1] ，默认的亮度数值是0.5：

controller.adjustRelatedBrightness(0.8);

设置被提到国家亮度

您可以设置提到国家的亮度。 亮度的数值范围是 [0, 1] ，默认的亮度数值是0.5：

默认设置中，提到国家并不会被高亮。被提到国家并不会被高亮。要更改被提到国家的亮度，首先需要按如下方法启用该功能lightenMentioned(true)：

controller.lightenMentioned(true);
controller.adjustMentionedBrightness(0.8);

数据

Gio.js拥有多种设置数据的方式。最基本的方式是使用 addData API。如果需要异步加载数据，可以使用 addDataAsync。 API如果需要周期性加载数据，可以使用 liveLoad API。如果需要清除数据，可以使用 clearData API。 为了让数据更具有观赏性，Gio.js会对数据进行预处理。在添加数据时，你可以同时设置数据展示时的颜色。可以同时向Controller添加多个数据集，然后使用 dataSwitchSet API来切换使用不同的数据集。除了输出数据到国家以外，Gio.js同时支持输出数据到大洲。

• 添加（更新）数据
• 清除数据
• 切换数据集
• 输入数据到洲
• 异步添加数据
• 周期性加载
• 设置单条线条颜色
• 数据预处理

添加数据

参数：
data（一个数据集） 或者 data group（多个数据集） – JSON格式数据

1. 载入一个数据集
   将数据加载到Gio的控制器并同步覆盖以前的数据。用于可视化的数据集采用JSON格式。数组中的每一个元素都包含一个输入国家(i)，一个输出国家(e)和一个数值(v)。

[
	{
		"e": "CN",
		"i": "US",
		"v": 3300000
	},
	{
		"e": "CN",
		"i": "RU",
		"v": 10000
	}
]

说明：连接线连接两个国家并具有方向性，运动粒子将在该方向上生成动画，连线方向由“e” -> “i”定义。“e”和“i”分别表示两个国家， “e”表示连线输出的国家，“i”表示连线输入的国家。“v”表示这两个国家之间的数值，如果数值较小，则粒子的大小和数量会比较小， 并且在连线上的移动速度相对缓慢；如果数值较大，则粒子的大小和数量会比较大，并且在连线上的移动速度相对较快。从Gio.js 2.0开始，"i"支持大洲了，查看文档输入数据到洲了解更多信息。
2. 载入多个数据集
将多个数据集加载到Gio的控制器并同步覆盖以前的数据。所有的数据集一次载入控制器，并且可以通过 switchDataSet() API来控制将哪个数据集的数据呈现出来。具体的数据格式定义如下所示：

{
        dataSetKeys: [key1, key2, ......],
        initDataSet: key1,
        key1: dataSet,
        key2: dataSet,
        ...
}

说明：每个数据集都有一个唯一的"key"，所有使用到的"key"都要在"dataSetKeys"属性中申明，"initDataSet"属性指定哪个数据集作为初始的数据集呈现在地球上。"dataSet"的数据格式和载入一个数据集中定义的相同。

清除数据

清除地球上添加的数据，同时有将数据线和数据点清除的效果。

// 使用 clearData API 来清除数据
controller.clearData();

切换数据集

参数:
dataSet key -- string

switchDataSet API可以切换地球表面呈现的数据集，该API只有通过addData API添加了一个data group之后才能生效。

// "large" 是一个数据集的"key"
controller.switchDataSet("large");

输入数据到洲

在输入数据中，“i"可以被定义成"洲”（比如输入"Asia"，代表亚洲），这样定义代表着从一个国家输出到一个"洲"。当"i"被设置成一个"洲"时，当相应的输出国家（即相对应的"e"中的国家）被选中时，整一个洲都会被点亮。洲名的输入参数如洲 - 参数表中所示。

使用方法：

[
        {
                // "e"不能设置成洲，输出必须是国家
                e: "CN",
                // 可以将"i"设置成欧洲，"Europe"为输入参数
                i: "Europe",
                v: 5000000
        }
]

效果：（从中国输出到欧洲）

洲 - 参数表

洲 - 参数（无视大小写）	洲 - 中文名	百度百科解释
“Oceania”	大洋洲	戳我
“North America”	北美洲	戳我
“South America”	南美洲	戳我
“Europe”	欧洲	戳我
“Asia”	亚洲	戳我
“Africa”	非洲	戳我

异步添加数据

参数：
url - 返回JSON格式数据，数据格式与添加（更新）数据定义的data相同
asyncLoadCallback - 当加载完成时执行的回调函数

从一个数据源异步加载数据。用法：

var url = "sampleData.json";

// 使用addDataAsync() API异步加载URL中的数据。
// 回调将在完成数据加载后执行。

controller.addDataAsync( url, asyncLoadCallback );

function asyncLoadCallback () {
        controller.init();
}

周期性加载数据/关闭周期性加载

参数：
url - 返回JSON格式数据，数据格式与添加（更新）数据定义的data相同
liveLoadCallback - 当加载完成时执行的回调函数
duration - 周期性数据加载时间（以毫秒为单位）

周期性地从一个数据源加载数据，用法：

var url = "dynamicallyAPI/data";

// 使用liveLoad() API加载URL中的数据。
// 设置回调。
// 指定加载时间。

controller.liveLoad( url, liveLoadCallback, 50000 );

function liveLoadCallback () {
	console.log("Load data event happens.");
}

// 使用 closeLiveLoader API 来关闭周期性加载功能
// controller.closeLiveLoader();

设置单条线条颜色

正如连接线章节所述，连接线分为两种类型：输入线和输出线。 与这两种类型的连接线相对应的颜色称为输入颜色和输出颜色。通过指定输入数据内容可以为这条数据指定一个唯一的颜色，如下所示：

[
        {
                "e": "CN",
                "i": "US",
                "v": 100000,
                "inColor": "#0000FF",
                "outColor": "#00FF00"
        },
        {
                "e": "CN",
                "i": "RU",
                "v": 3000000,
                "inColor": "#EE0E00",
                "outColor": "#FFFF00"
        }
]

备注：e，i，v与添加数据中的定义相同。

数据预处理

在输入的JSON数据中，v的值越高，粒子越亮，并且它们从出发国家到目的国家的运行越快。 （请查阅Michael Chang的文章来 了解他是如何提出这个想法的）。Gio.js库会自动缩放输入数据的范围以便于更好的数据可视化。作为开发人员，您还可以定义自己的预处理数据的方式。

回调函数

目前Gio只有一个回调函数。不过我们正在努力开发更多的回调函数，希望可以使用这些回调函数来开发更具有交互性的应用。

当国家被选中时

当被选中的国家改变时被调用。

会向回调函数传递两个参数：被选中的国家和相关国家列表。被选中的国家指的是一个CountryObject对象，这个对象表示新的被选中的国家；相关国家列表是CountryObject对象的列表，这个列表中储存了所有与新的被选中国家相关的国家。
使用方法：

 // 使用onCountryPicked() API来设置回调函数
controller.onCountryPicked( callback );

// 定义一个回调函数，这个函数作为一个例子，简单地在console里输出selectedCountry和relatedCountries这两个参数
function callback ( selectedCountry, relatedCountries ) {

        console.log(selectedCountry);
        console.log(relatedCountries);

}

CountryObject
{
        ISOCode: "AU"
        center: THREE.vector
        lat: -27
        lon: 133
        name: "AUSTRALIA"
}

参数表：

参数	描述
ISOCode	国家的ISO代码
center	国家的中心，用THREE.vector对象来表示
lat	国家的纬度
lon	国家的经度
name	国家的名称

高级功能

使用Gio高级功能，可以更容易地开发更具有交互性的应用。

• 方法链
• 切换选中国家

方法链

方法链是Javascript中常用的编程模式，Giojs也支持使用方法链对参数进行配置。使用方法链，参数的设置会更加清晰可读。 以下的例子展示了如何使用Giojs方法链。（你也可以点击在线演示，然后查看例子的源码来详细了解方法链是如何应用在实际场景中的）

不使用方法链的API调用:

controller.setSurfaceColor( "#00FF00" );
controller.setSelectedColor( "#FF0000" );
controller.disableUnmentioned( true );
使用方法链的API调用:
controller.setSurfaceColor( "#00FF00" )
        .setSelectedColor( "#FF0000" )
        .disableUnmentioned( true );

切换选中国家

除了通过用户点击地球表面的国家来进行切换以外，Giojs还支持使用switchCountry() API来直接切换 被选中的国家 ，开发者可以使用这个API来开发具有交互性的应用。 （您也可以点击在线演示，查看应用该API的示例）
参数：countryCode - 在 ISO 3166 标准中的国家代码

// 切换选中国家到 "US"
controller.switchCountry("US");