Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
[Enhancement] Add docs (#61)
Jerome Cukierd57c73db7708
diff --git a/README.md b/README.mdindex 83bdbe9a1..f268d8115 100644--- a/README.md+++ b/README.md@@ -7,6 +7,9 @@ For what it is capable of, take a look at [kepler.gl demo app](https://uber.githKepler.gl is a redux component that uses redux reducer to store and manage state transitions.This package consists of a reducer and the UI components to render and customize the map.+## User guide+Check out [kepler.gl's user documentation here](docs/a-introduction.md)+## Links### Envdiff --git a/docs/a-introduction.md b/docs/a-introduction.mdnew file mode 100644index 000000000..fd4164d1e--- /dev/null+++ b/docs/a-introduction.md@@ -0,0 +1,81 @@+# Introduction++Kepler.gl is designed for geospatial data analysis. It allows technical and non-technical audiences to visualize trends in a city or region. With Kepler.gl, you can…++Visualize a large amount of location data in your browser.+Playback geo-temporal trends over time.+Explore, filter, and deeply engage with location data to gain insight++See the sample maps in the demo app for more examples.++++This guide will teach you how to perform data analysis in Kepler.gl by adding data to a map, creating layers, adding filters, and more.++## Table of contents:++### Introduction++### The kepler.gl workflow++[Add data to the map](./b-kepler-gl-workflow/a-add-data-to-the-map.md)++#### Add data layers++[Adding data layers](./b-kepler-gl-workflow/b-add-data-layers/a-adding-data-layers.md)++[Create a layer](./b-kepler-gl-workflow/b-add-data-layers/b-create-a-layer.md)++[Hide, edit and delete layers](./b-kepler-gl-workflow/b-add-data-layers/c-hide-edit-and-delete-layers.md)++[Blend and rearrange layers](./b-kepler-gl-workflow/b-add-data-layers/d-blend-and-rearrange-layers.md)++### Types of layers++[Point](./c-types-of-layers/a-point.md)++[Arc](./c-types-of-layers/b-arc.md)++[Line](./c-types-of-layers/c-line.md)++[Grid](./c-types-of-layers/d-grid.md)++[GeoJSON](./c-types-of-layers/e-geojson.md)++[Cluster](./c-types-of-layers/f-cluster.md)++[Icon](./c-types-of-layers/g-icon.md)++### Layer attributes++[Layer attributes](./d-layer-attributes.md)++### Filters++[Filters](./e-filters.md)++### Map styles++[Base map styles](./f-map-styles/1-base-map-styles.md)++[Map layers](./f-map-styles/2-map-layers.md)++[Custom styles](./f-map-styles/3-custom-styles.md)++[View maps in 3d](./f-map-styles/4-view-maps-in-3d.md)++[Display legend](./f-map-styles/5-display-legend.md)++[Split maps](./f-map-styles/6-split-maps.md)++### Map settings++[Map settings](./g-map-settings.md)++### Playback++[Playback](./h-playback.md)++### FAQ++[FAQ](./i-FAQ.md)diff --git a/docs/b-kepler-gl-workflow/a-add-data-to-the-map.md b/docs/b-kepler-gl-workflow/a-add-data-to-the-map.mdnew file mode 100644index 000000000..c6f81c90e--- /dev/null+++ b/docs/b-kepler-gl-workflow/a-add-data-to-the-map.md@@ -0,0 +1,80 @@+# Add Data to the Map++## Add Data to your Map+1. Open Kepler.gl. You should see the following prompt:++++2. Choose one of two ways to add data to your map: upload a CSV/GeoJSON file or use one of Kepler.gl’s sample datasets. The sample datasets include California earthquakes, New York City taxi rides, and San Francisco elevation contour lines.++3. Kepler.gl is a pure client side app. Data lives only on your machine/browser. No information or maps is sent back up to our server.++## Upload CSV or GEOJSON Files++Drag as many files as you wish into the upload box. Note that Kepler.gl looks for conventions in your spreadsheets to auto-populate layers and its settings onto your map.+Check out some [sample datasets](https://github.com/uber-web/kepler.gl-data) for Kepler.gl.++### For CSV files:++- Kepler.gl creates a point layer if your CSV has columns named `<name>_lat` and `<name>_lng` or `<name>_latitude` and `<name>_longitude`, or `<name>_lat` and `<name>_lon`. Only lower case names are recognized.++- Kepler.gl creates an arc layer if your CSV has 2 column point pairs.++- Kepler.gl draws an icon layer if your csv has a column named `icon`.++- Kepler.gl attempts to parse geometry from your CSV file if the column content contains geometry data types. Acceptable formats include [Well-Known Text](http://www.postgis.net/docs/ST_AsText.html) and [GeoJSON feature](http://geojson.org/) strings.++### For GeoJSON files:++- Kepler.gl accepts GeoJSON formatted JSON that contains a single [Feature](https://tools.ietf.org/html/rfc7946#section-3.2) object or a [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) object. Kepler.gl creates one layer per file.++- If a FeatureCollection contains different type of Features, Kepler.gl will render all features in one layer. Acceptable Feature types are [Point](https://tools.ietf.org/html/rfc7946#section-3.1.2), [MultiPoint](https://tools.ietf.org/html/rfc7946#section-3.1.3), [LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4), [MultiLineString](https://tools.ietf.org/html/rfc7946#section-3.1.5), [Polygon](https://tools.ietf.org/html/rfc7946#section-3.1.6) and [MultiPolygon]((https://tools.ietf.org/html/rfc7946#section-3.1.7).++- Kepler.gl will read styles from GeoJSON files. If you are a GeoJSON expert, you can add style declarations to feature properties. Kepler.gl will use the declarations to automatically style your feature. The acceptable style properties are: `lineColor: [130, 154, 227]`, `lineWidth: 0.5`, `fillColor: [255, 0, 0]`, `radius: 1`, `hi-precision: true`.++- See an example below:+```+{+ "type": "FeatureCollection",+ "features": [{+ "type": "Feature",+ "geometry": {+ "type": "MultiLineString",+ "coordinates": [[[-105.1547889, 39.9862516], [-105.15471672508885,+ 39.98626910199207]]+ ]},+ "properties": {+ "id": "a1398a11-d1ce-421c-bf66-a456ff525de9",+ "lineColor": [130, 154, 227],+ "hi-precision": true,+ "lineWidth": 0.1+ }+ }]+}+```++### Use Kepler.gl’s Sample Maps++The sample maps are a great option for new users to explore Kepler.gl and get a feel for how it works.++1. At the initial load prompt select “Try sample data” in the top right corner.++++2. Choose from the options to load the sample map and explore the configurations applied.++++### Add multiple datasets++To add additional datasets to your map:++1. Click __Add More Data__ in the top right corner.++++2. Choose one of the options above: upload a JSON/CSV file, or use Kepler.gl’s sample data.++3. Repeat as needed. There is no limit on the number of datasets you can add. However, adding too many might cause its performance to suffer.++[Back to table of contents](../a-introduction.md)diff --git a/docs/b-kepler-gl-workflow/b-add-data-layers/a-adding-data-layers.md b/docs/b-kepler-gl-workflow/b-add-data-layers/a-adding-data-layers.mdnew file mode 100644index 000000000..05928e152--- /dev/null+++ b/docs/b-kepler-gl-workflow/b-add-data-layers/a-adding-data-layers.md@@ -0,0 +1,13 @@+# Adding Data Layers++The term "Layer" refers to a layer of data visualization. For example, you might add a point layer to visualize all the instances where taxi trips began, as in the map of New York City below.++++Each blue dot represents the point (latitude and longitude). Layers work like paint—you can build up multiple layers to change the appearance of the canvas. You might create a second point layer to show trip drop-off locations. The map then looks like this:++++Learn more about the [types of layers] available in Kepler.gl.++[Back to table of contents](../../a-introduction.md)diff --git a/docs/b-kepler-gl-workflow/b-add-data-layers/b-create-a-layer.md b/docs/b-kepler-gl-workflow/b-add-data-layers/b-create-a-layer.mdnew file mode 100644index 000000000..028aa9f11--- /dev/null+++ b/docs/b-kepler-gl-workflow/b-add-data-layers/b-create-a-layer.md@@ -0,0 +1,18 @@+# Create a Layer++1. Click the Data Layers icon in the left navigation bar.+++2. The Layers panel displays a list of existing layers and the name of the dataset the layers belong to (Sample Trip Data, in the example below). To create a new layer, click __Add Layer__ at the bottom of the menu.+++3. If your map contains multiple datasets, you’ll be asked to select the data source for your new layer.+++4. Select a layer type. Read about the different [types of layers].+++5. Fill in the required columns and adjust the optional settings if desired.+6. Collapse the layer settings menu when finished.++[Back to table of contents](../../a-introduction.md)diff --git a/docs/b-kepler-gl-workflow/b-add-data-layers/c-hide-edit-and-delete-layers.md b/docs/b-kepler-gl-workflow/b-add-data-layers/c-hide-edit-and-delete-layers.mdnew file mode 100644index 000000000..8344c50af--- /dev/null+++ b/docs/b-kepler-gl-workflow/b-add-data-layers/c-hide-edit-and-delete-layers.md@@ -0,0 +1,10 @@+# Hide, Edit and Delete Layers++Each layer has its own tab in the __Data Layers__ menu:+++Click the __down arrow__ to open up the settings menu for that layer. Click the __trashcan__ to delete a layer. Click the __eye__ to toggle show/hide.++__Note__: The colored line on the left of each layer tab represents what dataset that layer belongs to.++[Back to table of contents](../../a-introduction.md)\ No newline at end of filediff --git a/docs/b-kepler-gl-workflow/b-add-data-layers/d-blend-and-rearrange-layers.md b/docs/b-kepler-gl-workflow/b-add-data-layers/d-blend-and-rearrange-layers.mdnew file mode 100644index 000000000..9d482a3b5--- /dev/null+++ b/docs/b-kepler-gl-workflow/b-add-data-layers/d-blend-and-rearrange-layers.md@@ -0,0 +1,21 @@+# Blend and Rearrange Layers+Rearrange layers by dragging and dropping them in the Layers panel. The layers at the top of the list will be displayed in the foreground of the map.+++Blend layers by selecting an option from the dropdown at the bottom of the Layers panel.++There are three different ways to blend layers: Normal, Additive, and Subtractive.++## Normal Blending+Normal layer blending does not alter the color values of overlapping data points.+++## Additive Blending+Additive blending adds the color values for overlapping data points. It makes layers, and particularly areas of high density, easier to visualize on a dark-colored map.+++## Subtractive Blending+Subtractive layer blending does not alter the color values of overlapping data points.+++[Back to table of contents](../../a-introduction.md)diff --git a/docs/c-types-of-layers/a-point.md b/docs/c-types-of-layers/a-point.mdnew file mode 100644index 000000000..4181ee195--- /dev/null+++ b/docs/c-types-of-layers/a-point.md@@ -0,0 +1,7 @@+# Point++++Point layers draw points for a given event or object.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/b-arc.md b/docs/c-types-of-layers/b-arc.mdnew file mode 100644index 000000000..cc9bdb50c--- /dev/null+++ b/docs/c-types-of-layers/b-arc.md@@ -0,0 +1,9 @@+# Arc++++Arc layers draw an arc between two points. They’re useful for visualizing the distance between two points as well as comparing distances in 3D. Note that arc layers don’t show routes between points, but simply the distance between the two points. The tallest arc represents the greatest distance.++To draw arcs, your dataset must contain the latitude and longitude of two different points for each arc.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/c-line.md b/docs/c-types-of-layers/c-line.mdnew file mode 100644index 000000000..e5adee741--- /dev/null+++ b/docs/c-types-of-layers/c-line.md@@ -0,0 +1,7 @@+# Line++++Line layers are the 2D version of arc layers. Both draw a line between two points to represent distance, but in a line layer, the drawing lies flat on the map.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/d-grid.md b/docs/c-types-of-layers/d-grid.mdnew file mode 100644index 000000000..c6758dec5--- /dev/null+++ b/docs/c-types-of-layers/d-grid.md@@ -0,0 +1,8 @@+# Grid+++++Grids layers are similar to heatmaps. They show the density of points. They provide visual discrepancy in a map where multiple heatmap-style layers are present.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/e-geojson.md b/docs/c-types-of-layers/e-geojson.mdnew file mode 100644index 000000000..eaac79b15--- /dev/null+++ b/docs/c-types-of-layers/e-geojson.md@@ -0,0 +1,8 @@+# GeoJSON+++++GeoJSON layers can display either paths or polygons.. For example, a path GeoJSON layer can display data like trip routes. A polygon GeoJSON layer is essentially a [choropleth](https://en.wikipedia.org/wiki/Choropleth_map) layer and works best for rendering geofences. To add a GeoJSON layer, your dataset must contain geometry data.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/f-cluster.md b/docs/c-types-of-layers/f-cluster.mdnew file mode 100644index 000000000..55b4e340e--- /dev/null+++ b/docs/c-types-of-layers/f-cluster.md@@ -0,0 +1,7 @@+# Cluster++++Cluster layers visualize aggregated data based on a geospatial radius.++[Back to table of contents](../a-introduction.md)diff --git a/docs/c-types-of-layers/g-icon.md b/docs/c-types-of-layers/g-icon.mdnew file mode 100644index 000000000..d3eafdd76--- /dev/null+++ b/docs/c-types-of-layers/g-icon.md@@ -0,0 +1,11 @@+# Icon++++Icon layers are a type of point layer. They allow you to differentiate between points by assigning icons to points based on a field. For example, you might use icons to differentiate between types of venues and points of interest.++To see the icon menu, create a new icon layer and click how to draw an icon layer:++++[Back to table of contents](../a-introduction.md)diff --git a/docs/d-layer-attributes.md b/docs/d-layer-attributes.mdnew file mode 100644index 000000000..3be7f8fc3--- /dev/null+++ b/docs/d-layer-attributes.md@@ -0,0 +1,25 @@+# Layer Attributes+| Layer Attribute | Description | Available in |+|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------|+| Color/Color based on | Choose the color of your layer or assign color based on a field from your dataset(s). | All layers |+| High-precision rendering | Activate high-precision rendering when zooming in closely on a layer. High-precision rendering sometimes results in a performance cost. | Point, Arc, Line, Icon, GeoJSON, Hexagon, Grid |+| Radius/Radius based on | Change the radius of points or assign radius values based on a field from your dataset(s). | Point, Icon, GeoJSON |+| Opacity | Change the transparency of a layer. 1 = opaque, 0 = invisible. | All layers |+| Cluster size | Change the granularity of clusters. The lower the numerical value, the smaller the geospatial radius that will be used to aggregate clusters. | Cluster |+| Radius range | Set a lower and upper threshold for projected radius size. | Point, Icon, Geojson, Cluster |+| Stroke width/stroke width based on | Change the thickness of lines and arcs, or assign a width based on a field from your dataset(s). | Arc, line, Geojson |+| Stroke width range | Set a lower and upper threshold for projected stroke width. | Arc, Line, Geojson |+| Grid size | Change the number of square kilometers covered by each grid square. | Grid |+| Color Palette | Choose from multiple, predefined color palettes to apply to your layer. Palettes are either Uber or ColorBrewer colors. | All layers |+| Color Scale | Choose either a quantile or quantized color scale. A quantile color scale is determined by rank, while a quantized color scale is determined by value. | All layers |+| Height based on | Assign grid square height based on a field from your dataset. | Grid, Hexagon |+| Filter by count percentile | Increase or decrease the number of grid squares by choosing a range of percentiles to display. | Grid, Hexagon |+| Coverage | Change what portion of each grid cell is covered by a color square. | Grid, Hexagon |+| Height Scale | Change the height of the grid squares or hexagons when in 3D mode. | Grid, Hexagon |+| Stroked | When activated, draws outlines around geoshapes. | GeoJSON, Point |+| Filled | When activated, geo shapes are filled in with colors. | GeoJSON |+| Extruded | In 3D mode, assign polygon height values based on some value from your dataset. | GeoJSON |+| Wireframe | Create outlines around extruded polygons. | GeoJSON |+| Stroke or radius based on | Control the radius/thickness of GeoJSON line and point features. | GeoJSON |++[Back to table of contents](./a-introduction.md)diff --git a/docs/e-filters.md b/docs/e-filters.mdnew file mode 100644index 000000000..1cea889b5--- /dev/null+++ b/docs/e-filters.md@@ -0,0 +1,20 @@+# Filters++Add filters to your map to limit the data that is displayed. Filters must be based on the columns in your dataset.++To add a filter:++1. Select Filters from the right navigation bar.+++2. The Filters panel displays the list of existing filters, color-coded by dataset. To create a new filter, Click __Add Filter__.++3. Choose a dataset, and then a field on which to filter your data. Filter values are defined by field data type (number, string, timestamp, etc.).+++4. Your filter is applied to your map as soon as you specify the field and value.+5. Delete a filter anytime by clicking the __trashcan__ to the right of the filter you wish to delete.++__Note__: filters apply to all layers in the same dataset on your map.++[Back to table of contents](./a-introduction.md)diff --git a/docs/f-map-styles/1-base-map-styles.md b/docs/f-map-styles/1-base-map-styles.mdnew file mode 100644index 000000000..581c28091--- /dev/null+++ b/docs/f-map-styles/1-base-map-styles.md@@ -0,0 +1,10 @@+# Base Map Styles++Open the __Base Map panel__ to modify the base map color scheme, imagery, and labeling.+++Open the __base map style__ drop down menu to change map color scheme and imagery. Options include:+- __Dark__: dark base map with light-colored text.+- __Light__: light base map with dark-colored text.++[Back to table of contents](../a-introduction.md)diff --git a/docs/f-map-styles/2-map-layers.md b/docs/f-map-styles/2-map-layers.mdnew file mode 100644index 000000000..bad5cbc00--- /dev/null+++ b/docs/f-map-styles/2-map-layers.md@@ -0,0 +1,19 @@+# Map Layers++Map Layers+Toggle water, buildings, roads, and more. Options include:+- __Labels__: shows labels for cities, neighborhoods, and so on.+- __Roads__: displays a translucent layer of road lines.+- __Borders__: shows state and continent borders.+- __Buildings__: shows building footprints.+- __Water__: displays bodies of water.+- __Land__: Shows parks, mountains, and other landscape features.+++To control the order in which map imagery layers are displayed, toggle the move to top icon: .++__TIP__: Move labels to the top on maps with colored layers to keep the labels from being concealed.++++[Back to table of contents](../a-introduction.md)diff --git a/docs/f-map-styles/3-custom-styles.md b/docs/f-map-styles/3-custom-styles.mdnew file mode 100644index 000000000..c8401e79c--- /dev/null+++ b/docs/f-map-styles/3-custom-styles.md@@ -0,0 +1,8 @@+# Add Custom Mapbox Styles+++To add a custom base map style, click the add map style button to open the custom map style modal, paste in the mapbox [style Url](https://www.mapbox.com/help/studio-manual-publish/#style-url). Note that you need to paste in your [mapbox access token](https://www.mapbox.com/account/) if your style is not [published](https://www.mapbox.com/help/studio-manual-publish/#style-url).++++[Back to table of contents](../a-introduction.md)diff --git a/docs/f-map-styles/4-view-maps-in-3d.md b/docs/f-map-styles/4-view-maps-in-3d.mdnew file mode 100644index 000000000..ecdb4219e--- /dev/null+++ b/docs/f-map-styles/4-view-maps-in-3d.md@@ -0,0 +1,6 @@+# View Maps in 3D+View your map in 3D by clicking the 3D icon in the top right corner of your map:++++[Back to table of contents](../a-introduction.md)diff --git a/docs/f-map-styles/5-display-legend.md b/docs/f-map-styles/5-display-legend.mdnew file mode 100644index 000000000..87a181c2e--- /dev/null+++ b/docs/f-map-styles/5-display-legend.md@@ -0,0 +1,8 @@+# Display Legend+View your map in 3D by clicking the 3D icon in the top right corner of your map:++++++[Back to table of contents](../a-introduction.md)diff --git a/docs/f-map-styles/6-split-maps.md b/docs/f-map-styles/6-split-maps.mdnew file mode 100644index 000000000..fe27afbd2--- /dev/null+++ b/docs/f-map-styles/6-split-maps.md@@ -0,0 +1,16 @@+# Split Maps++You can display a side-by-side comparison of the same map area with different layers with the Split Map functionality.++++1. Enable this by clicking the Split Map icon in the top right corner of your map:+++2. Toggle the layers visible in each map with the layer icon in the top right corner of each map.++++3. Zoom in and out on each map and the other will automatically mimic.++[Back to table of contents](../a-introduction.md)diff --git a/docs/g-map-settings.md b/docs/g-map-settings.mdnew file mode 100644index 000000000..30d131322--- /dev/null+++ b/docs/g-map-settings.md@@ -0,0 +1,25 @@+# Map Settings++You can toggle customization options on your map, including tooltips, brush highlighting, map imagery (water, parks, etc.), and more.++## Tooltips and Highlighting++To toggle customization options on your map:+1. Open the Interactions menu by clicking the Interactions icon:++2. Click the switch next to the options you wish to activate/deactivate.+++There are two types of interactions to choose from: Tooltips and Brush. Note that only one can be on at a time.+- __Tooltip__: tooltip displays metrics when hovering over a data point. You can choose which fields are displayed from the tooltip config menu.++++Tip: click a point to pin the tooltip info. To unpin the tooltip, press the blue pin icon.+++- __Brush__: Brush allows you to highlight areas with the cursor. When brush is turned on, all layers darken. Only the portion you hover over with the cursor is illuminated. Brush works well with arc layers in particular.++++[Back to table of contents](./a-introduction.md)diff --git a/docs/h-playback.md b/docs/h-playback.mdnew file mode 100644index 000000000..d70a37b97--- /dev/null+++ b/docs/h-playback.md@@ -0,0 +1,9 @@+# Playback++Follow these steps to create a playback video of an event:+1. Add a filter based on a time-related field, like timestamp.+2. The playback window will appear on the bottom of the map. Select the desired rolling time window:++3. Press play to start the video. Click the forward and backward arrows to change the playback speed.++[Back to table of contents](./a-introduction.md)diff --git a/docs/i-FAQ.md b/docs/i-FAQ.mdnew file mode 100644index 000000000..d78a4da6a--- /dev/null+++ b/docs/i-FAQ.md@@ -0,0 +1,21 @@+# FAQ++## Can I export my map to a video file?+Kepler.gl does not have built-in functionality for exporting video. It only allows you to export maps as an image. However, you can use screen capture softwares such as Quicktime Player, LICEcap, Giffy, and others to export your map.++## How can I get data from my back-end service into Kepler.gl?+You can create a react redux app with kepler.gl as your map display component, requesting data with any kind of server-side calls. The kepler.gl demo app uses simple AJAX calls to load data from a URL.++## Is there a limit on the number of datasets that can be added to a map?+There is no limit, but the more datasets you add, the more likely it is that performance will suffer.++## What is the maximum file upload size?+Kepler.gl accepts files no larger than 250mb in chrome. You can load bigger files in safari, but performance will be limited.++## How many layers can I add to a map?+There is no limit on the amount of layers you can add. However, note that the more layers you have on your map, the more likely it is that performance will suffer.++## Why does my layer color change during filtering?+When layer color is based on a numerical value (e.g, trip fare, distance, ETA), Kepler.gl recalculates the color scale based on filtered data. This is not the case for categorical values such as vehicle_name, cuisine_type and app version.++[Back to table of contents](./a-introduction.md)