README

此文档的荷兰语版本在此。

PHP库，用于创建荷兰地方行政区的等高图（默认：2007年的边界，443个行政区）。区域可以分配颜色，通常用于表示某种现象的相对频率。

其他可用数据：佛兰德地区的行政区（308个行政区）、荷兰的四十个COROP区域、荷兰的十二个省份或Daan/Blok（1969年）的二十八方言区，这些方言区被映射到行政区边界。

1.1版本中的新功能

从O.W.A. Boonstra博士的数据集NLGis shapefiles中纳入了历史行政区和省份边界。1812-1997年的边界可用，可以通过可选的year参数使用。请注意，没有year参数将导致1.0版本中的2007年边界。使用NLGis数据集创建的地图使用Amsterdam codes作为市镇的代码（参见Van der Meer & Boonstra 2011），而1.0版本的地图使用CBS代码。

输出格式为：SVG（默认）、PNG、GIF、JPEG、KML、GeoJSON。

入门

要从GitHub作为库安装，在您的composer.json中使用以下内容

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/janpieterk/gemeentekaart-core"
        }
    ],
    "require": {
    "janpieterk/gemeentekaart-core": "1.1.0"
    }
}

要从packagist.org作为库安装，请省略repositories

{
    "require": {
    "janpieterk/gemeentekaart-core": "1.1.0"
    }
}

使用composer从GitHub作为项目安装

$  composer create-project janpieterk/gemeentekaart-core --repository='{"type":"vcs","url":"https://github.com/janpieterk/gemeentekaart-core"}'

要从packagist.org作为项目安装，请省略--repository

$  composer create-project janpieterk/gemeentekaart-core

运行gemeentekaart-core的PHPUnit测试

• 运行shell脚本test/run_tests.sh。

基本用法

用红色和绿色分别着色2007年的阿姆斯特丹和鹿特丹的行政区，并创建一个SVG图像

$municipalities = array('g_0363' => '#FF0000', 'g_0599' => '#00FF00');

$kaart = new Kaart('municipalities');
$kaart->addData($municipalities);
$kaart->show('svg');

市镇的代码是官方荷兰市镇代码，可在www.cbs.nl找到，以g_为前缀，以便它们可以作为HTML或XMD id属性的值。可以通过在创建不带year参数的Kaart对象上调用getPossibleMunicipalities()方法来请求可能的代码。

着色1821年今天被称为“大都市”的四个“大城市”的区域

$municipalities = array("a_11150" => "#990000", a_10345" => "#990000", "a_11434" => "#990000", "a_10722": "#990000");

$kaart = new Kaart('municipalities', 1821);
$kaart->addData($municipalities);
$kaart->show('svg');

代码是来自Van der Meer & Boonstra 2011的Amsterdam codes，以a_为前缀，以便它们可以作为HTML或XMD id属性的值。可以通过在创建带有year参数的Kaart对象上调用getPossibleMunicipalities()方法来请求特定年份的可能的代码。

API

__construct(string $type = 'municipalities', integer $year = NULL)

默认地图类型为 municipalities。可能的地图类型有：'municipalities', 'gemeentes', 'corop','provincies', 'provinces', 'municipalities_nl_flanders', 'municipalities_flanders', 'dialectareas'。 municipalities 是 gemeentes 的同义词。 provincies 是 provinces 的同义词。当省略 $year 时，将使用版本 1.0 的默认地图，即 2007 年的市界。使用 Kaart::getAllowedYears(string $maptype) 查找给定地图类型的可用年份。

示例

$kaart = new Kaart(); // equals new Kaart('municipalities');
$kaart = new Kaart('provinces');
$kaart = new Kaart('gemeentes', 1921);

setPathsFile(string $paths_file)

路径文件是包含地图特征坐标和名称的 geoJSON 文件（2008 年规范）。请参阅 coords 目录中的示例。注意，坐标系统应该是 EPSG:28992。仅在默认路径文件不足以满足需要时才需要。警告：文件不应由用户提交，因为它将原样使用。

示例

$kaart = new Kaart();
$kaart->setPathsFile($alternative_paths_file);

setAdditionalPathsFiles(array $paths_files )

在基础地图之上添加更多图层。典型用例：将不同的面状图类型组合在一个地图中，例如，以市为基图，并在其上绘制较大区域的边界。仅限于 coords 目录中的文件。

示例

// adding dialect areas to map of municipalities
$kaart = new Kaart('gemeentes');
$kaart->setAdditionalPathsFiles(array('dialectareas.json'));

setIniFile(string $ini_file)

如果需要为地图的特征设置替代样式。可以来自 ini 目录（无需完整路径）或来自其他地方。请参阅 ini 目录中的示例。警告：文件不应由用户提交，因为它将原样使用。

示例

$kaart = new Kaart('gemeentes');
$kaart->setAdditionalPathsFiles(array('municipalities_flanders.json', 'border_nl_be.json'));
$kaart->setIniFile('municipalities_nl_flanders.ini');

setData(array $data)

$data 应该是一个数组，包含要突出显示的区域。区域代码是键，颜色是值。请参阅 coords 目录中的 geoJSON 文件以获取区域代码，或在 Kaart 对象上调用 getPossibleAreas()。颜色可以是 HTML 颜色名称、#RRGGBB 十六进制字符串或 AABBGGRR 十六进制字符串。AA（不透明度）部分仅在 KML 地图上有效。

示例

$kaart = new Kaart();
$data = array('g_0534' => '#FFC513');
$kaart->setData($data);

$kaart = new Kaart('gemeentes', 1950);
$kaart->setData(array("a_11150" => "#990000"); // note the Amsterdam code instead of the CBS code

setTitle(string $title)

设置地图的标题。在图片上方显示。

示例

$kaart = new Kaart('corop');
$kaart->setTitle('The 40 COROP areas');

setInteractive(bool $value = true)

添加 JavaScript 或 title 属性，当悬停在区域上时显示区域名称。在 SVG 地图（嵌入地图本身并使用 JavaScript 显示）中，使用具有 title 属性的 <area> 标签的列表来实现相同的效果。在调用 setInteractive() 后，使用 getImagemap() 方法请求。

示例

$kaart = new Kaart('provincies');
$kaart->setInteractive();

setPixelWidth(int $width)

设置地图的像素宽度。如果不使用，宽度是默认值，由当前地图类型的 .ini 文件定义。默认高度由 .ini 文件定义为因子。对于默认的荷兰地图，例如，高度是宽度的 1.1 倍。

示例

// set a picture width of 500 pixels
$kaart = new Kaart();
$kaart->setPixelWidth(500);

setPixelHeight(int $height)

设置地图的像素高度。如果您不想使用 .ini 文件中的默认高度（例如，荷兰默认地图的高度是宽度的 1.1 倍），则可以使用此方法使用绝对值覆盖它。不过，您可能不想这样做。注意，此方法应始终在调用 setPixelWidth() 之后调用。

示例

// create a square 500 * 500 map
$kaart = new Kaart();
$kaart->setPixelWidth(500);
$kaart->setPixelHeight(500);

setLink(string $link, mixed $target = NULL)

将相同的链接添加到所有区域。%s 占位符将被区域代码替换。对于位图地图，链接位于 <area> 元素中，可以通过调用 getImagemap() 方法获得，对于其他（文本）格式，链接嵌入在地图中。可选参数 $target 可以用于创建例如 target="_blank" 的链接属性。

示例

$kaart = new Kaart();
$kaart->setLink('https://www.example.com/?code=%s');
// now all areas have a link

setLinkHighlighted(string $link, mixed $target = NULL)

将相同的链接添加到所有突出显示的区域。%s 占位符将被区域代码替换。对于位图地图，链接位于 <area> 元素中，可以通过调用 getImagemap() 方法获得，对于其他（文本）格式，链接嵌入在地图中。可选参数 $target 可以用于创建例如 target="_blank" 的链接属性。

示例

$kaart = new Kaart();
$kaart->setData(array('g_0363' => '#FFC513'));
$kaart->setLinkHighlighted('http://www.example.com/?code=%s');
// now only area g_0363 (Amsterdam) has a link
// http://www.example.com/?code=g_0363

setLinks(array $data, mixed $target = NULL)

为区域添加链接（每个区域可能都有不同的链接）。$data 应该是一个以区域代码为键、链接为值的数组。

示例

$kaart = new Kaart();
$links = array(
    'g_0003' => 'http://www.example.com/some-path/',
    'g_0363' => 'http://www.example.net/another-path/'
    );
$kaart->setLinks($links, '_blank');

setToolTips(array $data)

为区域添加工具提示。这些成为 HTML <area> 元素或 SVG <path> 元素的 'title' 属性，KML 中的 <description> 元素，以及 GeoJSON 中的 'name' 属性。$data 应该是一个以区域代码为键、字符串为值的数组。注意，如果之前设置了 $kaart->setInteractive() 为 TRUE，则工具提示将覆盖给定区域的默认区域名称。

示例

$kaart = new Kaart();
$tooltips = array(
    'g_0003' => 'Some text',
    'g_0363' => 'Another informative text'
    );
$kaart->setLinks($tooltips);

setJavaScript(array $data, string $event = 'onclick')

为区域添加 JavaScript 代码。可能的 $event 参数值：onclick、onmouseover、onmouseout。注意（仅限 SVG 地图）：如果之前设置了 $kaart->setInteractive() 为 TRUE，则使用此方法添加的任何 onmouseover 或 onmouseout 事件将覆盖默认的 onmouseover 和 onmouseout 事件。$data 应该是一个以区域代码为键、JavaScript 代码为值的数组。

示例

$kaart = new Kaart();
$kaart->setJavaScript(array('g_0003' => "alert('g_0003');"));

array getData()

返回当前关联数组，包含地图数据（突出显示的区域）。

示例

$kaart = new Kaart();
$kaart->setData(array('g_0534' => '#FFC513'));
$data = $kaart->getData();
print_r($data);
// Array
// (
//     [g_0534] => #FFC513
// )

int getPixelWidth()

返回地图的像素宽度。

int getPixelHeight()

返回地图的像素高度。

string getTitle()

返回地图的标题。如果没有设置标题，则为空字符串。

string | boolean getImagemap()

仅适用于位图地图：返回一个包含地图特征的 <area> 元素字符串，用于 <map> HTML 元素。只能在调用 show()、fetch() 或 saveAsFile() 方法后调用！如果没有生成位图，则返回 FALSE。

array getPossibleAreas()

返回当前地图对象的关联数组（区域代码为键，区域名称为值）。

array getPossibleMunicipalities()

在类型为 'municipalities'/'gemeentes' 的地图对象上的同义词 getPossibleAreas()。

void show(string $format = 'svg')

将地图交给网络浏览器进行进一步处理。根据浏览器的功能和设置，地图将在页面上显示、交给其他应用程序或下载。可能的格式有：'svg'、'png'、'gif'、'jpeg'、'jpg'、'kml'、'json'。

string|blob fetch(string $format = 'svg')

将地图作为字符串（SVG、JSON、KML）或二进制 blob（位图图像）返回。有关可能的格式，请参阅 show()。

bool saveAsFile(string $filename, string $format = 'svg')

将地图保存为文件。有关可能的格式，请参阅 show()。如果成功，则返回 TRUE，如果失败，则返回 FALSE。

array Kaart::getAllowedMaptypes()

返回可以在构造函数中使用的可能地图类型数组。

示例

$types = Kaart::getAllowedMaptypes();
print_r($types);
// Array
// (
//    [0] => municipalities
//    [1] => gemeentes
//    [2] => corop
//    [3] => provincies
//    [4] => provinces
//    [5] => municipalities_nl_flanders
//    [6] => municipalities_flanders
//    [7] => dialectareas
// )

array Kaart::getAllowedFormats()

返回可以在 show()、fetch() 或 saveAsFile() 调用中使用的可能地图格式数组。

示例

$formats = Kaart::getAllowedFormats();
print_r($formats);
// Array
// (
//     [0] => gif
//     [1] => png
//     [2] => jpg
//     [3] => jpeg
//     [4] => svg
//     [5] => kml
//     [6] => json
// )

array Kaart::getAllowedYears(string $maptype)

返回可以在给定地图类型构造函数中使用的可能年份数组。

示例

$years = Kaart::getAllowedYears('provinces');
print_r($years);
// Array
// (
//    [0] => 1830
//    [1] => 1860
//    [2] => 1890
//    [3] => 1920
//    [4] => 1940
//    [5] => 1950
//    [6] => 1980
// )

参考文献

J. Daan 和 D.P. Blok (1969). 《从边缘城市到乡村边缘。关于地图的解释：方言和地名学。阿姆斯特丹皇家荷兰科学院方言委员会的贡献和公告 37》阿姆斯特丹，N.V. 北荷兰出版社。

Meer, Ad van der 和 Onno Boonstra (2011). 《自 1812 年以来的荷兰地方政府名录，附：阿姆斯特丹代码》。第 2 版。[海牙：DANS。] (DANS 数据指南，2)。[https://dans.knaw.nl/nl/over/organisatie-beleid/publicaties/DANSrepertoriumnederlandsegemeenten2011.pdf](https://dans.knaw.nl/nl/over/organisatie-beleid/publicaties/DANSrepertoriumnederlandsegemeenten2011.pdf)

致谢

• 此库是来自 Meertens Kaart 模块 的代码的衍生作品。
• 该库整合了略微修改过的PEAR包Image_Color和XML_SVG。
• 该库包含了以下GIS数据的GIS数据：O.W.A. Boonstra博士（2007年）：NLGis形状文件。DANS。 https://doi.org/10.17026/dans-xb9-t677
• 该库献给Ilse van Gemert（1979-2018）。