├── .eslintrc.js
├── .gitignore
├── .jsbeautifyrc
├── LICENSE
├── README.md
├── docs
├── class-breaks-symbology
│ └── index.html
├── comparison
│ ├── css
│ │ ├── normalize.css
│ │ └── skeleton.css
│ └── index.html
├── csv-data
│ ├── Flowmap_Cities.csv
│ ├── Flowmap_Cities_many_to_one.csv
│ ├── Flowmap_Cities_one_to_many.csv
│ └── Flowmap_Cities_one_to_one.csv
└── main
│ └── index.html
├── img
└── img_01.png
└── src
└── CanvasFlowmapLayer.js
/.eslintrc.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | "env": {
3 | "browser": true
4 | },
5 | "globals": {
6 | "define": false,
7 | "require": false,
8 | "module": false,
9 | "L": false,
10 | "TWEEN": false,
11 | "Papa": false
12 | },
13 | "rules": {
14 | "no-debugger": "error",
15 | "no-bitwise": "error",
16 | "curly": "error",
17 | "eqeqeq": "error",
18 | "guard-for-in": "error",
19 | "block-scoped-var": "off",
20 | "no-use-before-define": "warn",
21 | "max-params": "off",
22 | "no-caller": "error",
23 | "no-new": "error",
24 | "no-shadow": "error",
25 | "strict": "off",
26 | "no-undef": "error",
27 | "no-unused-vars": "error",
28 | "no-eval": "off",
29 | "indent": ["error", 2, {
30 | "SwitchCase": 1
31 | }],
32 | "quotes": ["error", "single"]
33 | }
34 | };
35 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jwasilgeo/Leaflet.Canvas-Flowmap-Layer/7ae3238d3bbe11512eeda5ce47b5593c172b23e6/.gitignore
--------------------------------------------------------------------------------
/.jsbeautifyrc:
--------------------------------------------------------------------------------
1 | {
2 | "indent_size": 2,
3 | "indent_char": " ",
4 | "other": "",
5 | "indent_level": 0,
6 | "indent_with_tabs": false,
7 | "preserve_newlines": true,
8 | "max_preserve_newlines": 2,
9 | "indent_handlebars": true
10 | }
11 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2017 Jacob Wasilkowski
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Leaflet.Canvas-Flowmap-Layer
2 |
3 | The `Leaflet.Canvas-Flowmap-Layer` is a custom layer plugin for [LeafletJS](http://leafletjs.com/) to map the flow of objects from an origin point to a destination point by using a Bezier curve. GeoJSON point feature coordinates are translated to pixel space so that rendering for the points and curves are mapped to an [HTMLCanvasElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement).
4 |
5 | **Demos:**
6 |
7 | - [Simple](https://jwasilgeo.github.io/Leaflet.Canvas-Flowmap-Layer/docs/main)
8 | - [Feature comparison](https://jwasilgeo.github.io/Leaflet.Canvas-Flowmap-Layer/docs/comparison) (aka: kitchen sink, sandbox)
9 | - [Advanced symbology: class breaks of flowlines](https://jwasilgeo.github.io/Leaflet.Canvas-Flowmap-Layer/docs/class-breaks-symbology)
10 |
11 | **Important!**
12 |
13 | This is a LeafletJS port of [sarahbellum/Canvas-Flowmap-Layer](https://www.github.com/sarahbellum/Canvas-Flowmap-Layer), which was originally written for the ArcGIS API for JavaScript. Go there to learn more!
14 |
15 | View our [**presentation at NACIS 2017**](https://www.youtube.com/watch?v=cRPx-BfBtv0).
16 |
17 | **Table of Contents:**
18 |
19 | - [Purpose and Background](#purpose-and-background)
20 | - [Options and More Information for Developers](#options-and-more-information-for-developers)
21 | - [Data Relationships](#data-relationships)
22 | - [Animation](#animation)
23 | - [Interaction](#interaction)
24 | - [Symbology](#symbology)
25 | - [API](#api)
26 | - [Constructor Summary](#constructor-summary)
27 | - [Options and Property Summary](#options-and-property-summary)
28 | - [Method Summary](#method-summary)
29 | - [Event Summary](#event-summary)
30 | - [Licensing](#licensing)
31 |
32 | [](https://jwasilgeo.github.io/Leaflet.Canvas-Flowmap-Layer/docs/main)
33 |
34 | ## Purpose and Background
35 |
36 | Please see [sarahbellum/Canvas-Flowmap-Layer#purpose](https://github.com/sarahbellum/Canvas-Flowmap-Layer#purpose) for more detailed information.
37 |
38 | ## Options and More Information for Developers
39 |
40 | ### Data Relationships
41 |
42 | "One-to-many", "many-to-one" and "one-to-one" origin-to-destination relationships are supported by this custom layer.
43 |
44 | **Important:** The developer must format and provide a GeoJSON point feature collection in a specific format. This layer expects that _both_ origin and destination attributes and spatial coordinates are available in each GeoJSON point feature's properties.
45 |
46 | Example of a single GeoJSON point feature within a feature collection that includes _both_ origin and destination info:
47 |
48 | ```json
49 | {
50 | "type": "Feature",
51 | "geometry": {
52 | "type": "Point",
53 | "coordinates":[109.6091129, 23.09653465]
54 | },
55 | "properties": {
56 | "origin_id": 238,
57 | "origin_city": "Hechi",
58 | "origin_country": "China",
59 | "origin_lon": 109.6091129,
60 | "origin_lat": 23.09653465,
61 | "destination_id": 1,
62 | "destination_city": "Sarh",
63 | "destination_country": "Chad",
64 | "destination_lon": 18.39002966,
65 | "destination_lat": 9.149969909
66 | }
67 | }
68 | ```
69 |
70 | Please see [sarahbellum/Canvas-Flowmap-Layer#data-relationships](https://github.com/sarahbellum/Canvas-Flowmap-Layer#data-relationships) for more details.
71 |
72 | ### Animation
73 |
74 | The animations rely on the [tween.js library](https://github.com/tweenjs/tween.js) to assist with changing the underlying line property values as well as providing many different easing functions and durations. See the `setAnimationDuration()` and `setAnimationEasing()` method descriptions below for more information.
75 |
76 | **Important:** If animations are going to be used, then the developer must first load the tween.js library.
77 |
78 | ```html
79 |
80 |
81 |
82 |
83 |
84 | ```
85 |
86 | ### Interaction
87 |
88 | You can change how users interact with the `Leaflet.CanvasFlowmapLayer` by controlling which Bezier curves appear and disappear at any time. The demos we provide show how to do this in several ways with LeafletJS `click` and `mouseover` events, coupled with using this layer's `selectFeaturesForPathDisplay()` method.
89 |
90 | For example, you could listen for a `click` event on an origin point feature—which is displayed on the map as an `L.CircleMarker`—and then choose to either **add** to your selection of displayed Bezier curves, **subtract** from your selection, or establish a brand **new** selection.
91 |
92 | Alternatively, you could set the `pathDisplayMode` option to `'all'` when constructing the layer to display every Bezier curve at once.
93 |
94 | ### Symbology
95 |
96 | The `Leaflet.Canvas-Flowmap-Layer` has default symbol styles established for origin and destination point `L.CircleMarker`s, canvas Bezier curves, and animated canvas Bezier curves.
97 |
98 | The default symbol styles for **origin and destination point** `L.CircleMarker`s can be changed by using the layer constructor option `style()` method, since this layer extends from `L.GeoJSON`.
99 |
100 | The default symbol styles for **canvas Bezier paths and animations** can be changed by overriding the layer constructor options for `canvasBezierStyle` and `animatedCanvasBezierStyle`, specifically using HTMLCanvasElement stroke and line style property names (instead of LeafletJS marker style properties).
101 |
102 | The caveat here is that this Leaflet version of the Canvas-Flowmap-Layer **and** the [Esri-compatible Canvas-Flowmap-Layer](https://github.com/sarahbellum/Canvas-Flowmap-Layer) both rely on symbol configurations that are defined using property objects inspired by the ArcGIS REST API renderer objects specification. Simple, unique value, and class breaks are all supported but instead use canvas stroke and line style property names. Specifically for this, read about the [ArcGIS REST API renderer objects specification](http://resources.arcgis.com/en/help/arcgis-rest-api/#/Renderer_objects/02r30000019t000000/).
103 |
104 | See the developer API section below and also [sarahbellum/Canvas-Flowmap-Layer#symbology](https://github.com/sarahbellum/Canvas-Flowmap-Layer#symbology) for more details. We have provided a demo page of how to set class breaks symbology for Bezier curves.
105 |
106 | ## API
107 |
108 | This extends the LeafletJS v1 [`L.GeoJSON` layer](http://leafletjs.com/reference-1.3.0.html#geojson). All properties, methods, and events provided by the `L.GeoJSON` layer are available in the `Leaflet.CanvasFlowmapLayer`, with additional custom features described below.
109 |
110 | ### Constructor Summary
111 |
112 | ```javascript
113 | var geoJsonFeatureCollection = {
114 | // collection of GeoJSON point features
115 | // with origin and destination attribute properties
116 |
117 | // see discussion above, demos, and CSV example data sources
118 | };
119 |
120 | var exampleFlowmapLayer = L.canvasFlowmapLayer(geoJsonFeatureCollection, {
121 | // required property for this custom layer,
122 | // which relies on the property names of your own data
123 | originAndDestinationFieldIds: {
124 | // all kinds of important stuff here...see docs below
125 |
126 | // however, this isn't required if your own data
127 | // is in the same format as the layer source code
128 | },
129 |
130 | // some custom options
131 | pathDisplayMode: 'selection',
132 | animationStarted: true,
133 | animationEasingFamily: 'Cubic',
134 | animationEasingType: 'In',
135 | animationDuration: 2000
136 | }).addTo(map);
137 | ```
138 |
139 | ### Options and Property Summary
140 |
141 | | Property | Description |
142 | | --- | --- |
143 | | `originAndDestinationFieldIds` | **Required if your data does not have the same property field names as the layer source code.** `Object`. This object informs the layer of your unique origin and destination attributes (fields). Both origins and destinations need to have their own unique ID attribute and geometry definition. [See example below](#originanddestinationfieldids-example) which includes minimum required object properties. |
144 | | `style` | _Optional_. `Function`. This function defines the symbol style properties of the origin and destination `L.CircleMarker`. [See example below](#style-example). |
145 | | `canvasBezierStyle` | _Optional_. `Object`. This object defines the symbol properties of the non-animated Bezier curve that is drawn on the canvas connecting an origin point to a destination point. [See Symbology discussion above](#symbology). |
146 | | `animatedCanvasBezierStyle` | _Optional_. `Object`. This defines the symbol properties of the animated Bezier curve that is drawn on the canvas directly on top of the non-animated Bezier curve. [See Symbology discussion above](#symbology). |
147 | | `pathDisplayMode` | _Optional_. `String`. Valid values: `'selection'` or `'all'`. Defaults to `'all'`. |
148 | | `wrapAroundCanvas` | _Optional_. `Boolean`. Defaults to `true`. Ensures that canvas features will be drawn beyond +/-180 longitude. |
149 | | `animationStarted` | _Optional_. `Boolean`. Defaults to `false`. This can be set during construction, but you should use the `playAnimation()` and `stopAnimation()` methods to control animations after layer construction. |
150 | | `animationDuration` | See `setAnimationDuration()` method description below. |
151 | | `animationEasingFamily` | See `setAnimationEasing()` method description below. |
152 | | `animationEasingType` | See `setAnimationEasing()` method description below. |
153 |
154 | **`originAndDestinationFieldIds` example:**
155 |
156 | (This is also the default in the layer source code.)
157 |
158 | ```javascript
159 | // this is only a default option example,
160 | // developers will most likely need to provide this
161 | // options object with values unique to their data
162 | originAndDestinationFieldIds: {
163 | originUniqueIdField: 'origin_id',
164 | originGeometry: {
165 | x: 'origin_lon',
166 | y: 'origin_lat'
167 | },
168 | destinationUniqueIdField: 'destination_id',
169 | destinationGeometry: {
170 | x: 'destination_lon',
171 | y: 'destination_lat'
172 | }
173 | }
174 | ```
175 |
176 | **`style` example:**
177 |
178 | (This is also the default in the layer source code.)
179 |
180 | ```javascript
181 | style: function(geoJsonFeature) {
182 | // use leaflet's path styling options
183 |
184 | // since the GeoJSON feature properties are modified by the layer,
185 | // developers can rely on the "isOrigin" property to set different
186 | // symbols for origin vs destination CircleMarker stylings
187 |
188 | if (geoJsonFeature.properties.isOrigin) {
189 | return {
190 | renderer: canvasRenderer, // recommended to use your own L.canvas()
191 | radius: 5,
192 | weight: 1,
193 | color: 'rgb(195, 255, 62)',
194 | fillColor: 'rgba(195, 255, 62, 0.6)',
195 | fillOpacity: 0.6
196 | };
197 | } else {
198 | return {
199 | renderer: canvasRenderer,
200 | radius: 2.5,
201 | weight: 0.25,
202 | color: 'rgb(17, 142, 170)',
203 | fillColor: 'rgb(17, 142, 170)',
204 | fillOpacity: 0.7
205 | };
206 | }
207 | }
208 | ```
209 |
210 | ### Method Summary
211 |
212 | | Method | Arguments | Description |
213 | | --- | --- | --- |
214 | | `selectFeaturesForPathDisplay( selectionFeatures, selectionMode )` | `selectionFeatures`: `Array` of origin or destination features already managed and displayed by the layer.
`selectionMode`: `String`. Valid values: `'SELECTION_NEW'`, `'SELECTION_ADD'`, or `'SELECTION_SUBTRACT'`. | This informs the layer which Bezier curves should be drawn on the map.
For example, you can most easily use this in conjunction with a `click` or `mouseover` event listener. |
215 | | `selectFeaturesForPathDisplayById( uniqueOriginOrDestinationIdField, idValue, originBoolean, selectionMode )` | | This is a convenience method if the unique origin or destination ID value is already known and you do not wish to rely on a `click` or `mouseover` event listener. |
216 | | `selectAllFeaturesForPathDisplay()` | | This informs the layer to select (and thus show) all Bezier curves. |
217 | | `clearAllPathSelections()` | | This informs the layer to unselect (and thus hide) all Bezier curves. |
218 | | `playAnimation()` | | This starts and shows Bezier curve animations. |
219 | | `stopAnimation()` | | This stops and hides any Bezier curve animations. |
220 | | `setAnimationDuration( duration )` | `duration`: _Optional_. `Number` in milliseconds. | This changes the animation duration. |
221 | | `setAnimationEasing( easingFamily, easingType )` | `easingFamily`: `String`.
`easingType`: `String`.
See `getAnimationEasingOptions()` method for info on valid values. | This changes the animation easing function with the help of the [tween.js library](https://github.com/tweenjs/tween.js). |
222 | | `getAnimationEasingOptions()` | | Returns information on valid `easingFamily` and `easingType` values based on the [tween.js library](https://github.com/tweenjs/tween.js). |
223 |
224 | ### Event Summary
225 |
226 | | Event | Description |
227 | | --- | --- |
228 | | `click` | Extends [layer `click`](http://leafletjs.com/reference-1.3.0.html#interactive-layer-click) and adds the following properties to the event object:
`isOriginFeature`: `true` if an origin point has been clicked, but `false` if a destination point has been clicked.
`sharedOriginFeatures`: `Array` of features that share the same origin.
`sharedDestinationFeatures`: `Array` of features that share the same destination. |
229 | | `mouseover` | Extends [layer `mouseover`](http://leafletjs.com/reference-1.3.0.html#interactive-layer-mouseover) and adds the following properties to the event object:
`isOriginFeature`: `true` when the mouse first entered an origin point, but `false` when the mouse first entered a destination point.
`sharedOriginFeatures`: `Array` of features that share the same origin.