Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

[Docs] Add save and export section to docs (#148)

Shan He870c2883ecdb
diff --git a/.gitignore b/.gitignore
index 48bdaff37..77c597679 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,9 +11,10 @@ package-lock.json
.DS_Store
.idea
+.vscode/
/bundle*.js
/favicon.png
/index.html
-npm-debug.log
\ No newline at end of file
+npm-debug.log
diff --git a/docs/a-introduction.md b/docs/a-introduction.md
index 7723beec4..b93af71a4 100644
--- a/docs/a-introduction.md
+++ b/docs/a-introduction.md
@@ -14,70 +14,41 @@ This guide will teach you how to perform data analysis in Kepler.gl by adding da
## Table of contents:
-### Get Started
+#### [Get Started](./j-get-started.md)
-[Get Started](./j-get-started.md)
+#### The kepler.gl workflow
+* [Add data to the map](./b-kepler-gl-workflow/a-add-data-to-the-map.md)
+* [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)
-### The kepler.gl workflow
+#### Types of layers
-[Add data to the map](./b-kepler-gl-workflow/a-add-data-to-the-map.md)
+* [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)
-#### Add data layers
+#### [Layer attributes](./d-layer-attributes.md)
-[Adding data layers](./b-kepler-gl-workflow/b-add-data-layers/a-adding-data-layers.md)
+#### [Filters](./e-filters.md)
-[Create a layer](./b-kepler-gl-workflow/b-add-data-layers/b-create-a-layer.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)
-[Hide, edit and delete layers](./b-kepler-gl-workflow/b-add-data-layers/c-hide-edit-and-delete-layers.md)
+#### [Map settings](./g-map-settings.md)
-[Blend and rearrange layers](./b-kepler-gl-workflow/b-add-data-layers/d-blend-and-rearrange-layers.md)
+#### [Time Playback](./h-playback.md)
-### Types of layers
+#### [Save and Export](./k-save-and-export.md)
-[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)
+#### [FAQ](./i-FAQ.md)
diff --git a/docs/h-playback.md b/docs/h-playback.md
index d70a37b97..8fe51f9bc 100644
--- a/docs/h-playback.md
+++ b/docs/h-playback.md
@@ -1,9 +1,17 @@
# 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:
+1. Add a filter based on a time-related field, like timestamp.
+
+2. The playback window will appear on the bottom of the map. The bars are distribution graphs of all data points by time. Select the desired rolling time window:
+
![select filters](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/image23.png "select filters")
-3. Press play to start the video. Click the forward and backward arrows to change the playback speed.
+
+3. Press play to start the video. Click _1x_, _2x_, _4x_ on the top right to change the playback speed.
+
+4. Choose custom y axis. You can click __Select Y Axis__ to change the default distribution graph to a timesieries of selected column. An example use of this function is to show a speed vs. time graph of a given trip.
+
+![custome y axis](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/h-playback-2.png "select filters")
+
[Back to table of contents](./a-introduction.md)
diff --git a/docs/j-get-started.md b/docs/j-get-started.md
index c2f0d5e9d..c06fadac8 100644
--- a/docs/j-get-started.md
+++ b/docs/j-get-started.md
@@ -15,7 +15,7 @@ Read more about adding [Add data to the map](./b-kepler-gl-workflow/a-add-data-t
## 2) Add Layers
-![Add layer](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/image16.png "Add layer")
+![Add layer](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/j-get-started-layers.png "Add layer")
Open the Data Layers menu to start building your visualization. Layers are simply data visualizations that can be built on top of one another. The map pictured above contains a GeoJSON path layer showing trip routes.
@@ -26,7 +26,7 @@ Learn more about [adding data layers](./b-kepler-gl-workflow/b-add-data-layers/a
## 3) Add Filters
-![choose a dataset](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/image29.png "choose a dataset")
+![choose a dataset](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/add-filter.png "choose a dataset")
Add filters to your map to limit the data that is displayed. Filters must be based on the columns in your dataset. To create a new filter, open the Filter menu and click Add Filter. Note that filters apply to all layers and cannot be toggled on and off.
@@ -34,8 +34,14 @@ Learn more about [filters](./e-filters.md).
## 4) Customize Map Settings
-![activate interactions](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/image32.png "activate interactions")
+![Customize Map Settings](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/interactions.png "Customize Map Settings")
Change the settings on your map in the Interactions and Base Map menus. Customization options include tooltips, brush highlighting, base map style, map imagery toggles (water, parks, satellite image, etc.), and many more.
Read about [base map styles](./f-map-styles/1-base-map-styles.md) and [map settings](./g-map-settings.md).
+
+## 5) Save and Export
+![Save and Export](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/export-save.png "Save and Export")
+Save your map as an image, export current map data, export current map as a json file to be load back into kepler.gl.
+
+Read about [Save and export](./k-save-and-export.md).
diff --git a/docs/k-save-and-export.md b/docs/k-save-and-export.md
new file mode 100644
index 000000000..d25c9d4ac
--- /dev/null
+++ b/docs/k-save-and-export.md
@@ -0,0 +1,38 @@
+# Save and Export
+
+![Save and Export](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/k-save-and-export-1.png "activate interactions")
+
+kepler.gl is a client-side only application. In the demo app, the data you uploaded stays in your browser. Uber doesn't send or store any user data to any backends. This rule poses an limitation on how you can save and share your maps.
+
+However, in the demo app, you can:
+
+- [Export map as an iamge](#export-image).
+- [Export filtered or unfiltered data as a csv](#export-data).
+- [Export current map configuration as a `json` file](#export-config), this file does not contain any map data.
+- [Export current map configuration __AND__ map data as a `json` file](#export-config), which can be loaded back to kepler.gl to reproduce the current map.
+
+## <a href="#export-image">Export Image</a>
+
+![Export Image](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/k-save-and-export-2.png "activate interactions")
+
+You can export current map as an image. The export window will use the current map viewport, and the preview will show the entire exported map area. To adjust the viewport, you will have to close the export dialog. You can choose different export ratio, resolution, and add map legend.
+
+## <a href="#export-data">Export Data</a>
+
+![Export Data](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/k-save-and-export-3.png "activate interactions")
+
+You can export map data as a csv file, with the option to export ONLY the filtered data or the entire dataset.
+
+## <a href="#export-config">Export Map Configuration</a>
+
+![Export Map Configuration](https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/documentation/k-save-and-export-4.png "activate interactions")
+
+#### 1.Export Current Config
+
+You can export current map configuration as a `json` file. This is useful when you are running your own kepler.gl application, and want to load data with a specific preset configuration. The map config includes current layer, filter, map style and interaction settings.
+
+**Note:** kepler.gl map config is coupled with loaded datasets. The __`dataId`__ key is used to bind layers, filters and tooltip settings to a specific dataset. If you try to upload a configuration with a dataset in your own kepler.gl app, you also need to make sure your dataset __`id`__ match the __`dataId`__ in the config.
+
+#### 2.Save and Export Current Map
+
+To Save and share your current map, click the __Export Current Map__ check box to export current configuration __AND__ uploaded data in a single `json` file. **You can load this json file back to kepler.gl by simply drag and drop it in the __Add Data to Map__ dialog.**
diff --git a/src/reducers/composers.js b/src/reducers/composers.js
index d9fa71b14..d048bea50 100644
--- a/src/reducers/composers.js
+++ b/src/reducers/composers.js
@@ -30,9 +30,13 @@ import KeplerGlSchema from 'schemas';
// compose action to apply result multiple reducers, with the output of one
/**
- * Apply map bounds to mapState from received vis data
- * @param state
- * @param action {options, config: {}}
+ * Apply data and config to visState reducer
+ * @param {object} state
+ * @param {object} action
+ * @param {object} action.options
+ * @param {Boolean} action.options.centerMap
+ * @param {Boolean} action.options.readOnly
+ * @param {object} action.config
* @returns state new reducer state
*/
export const updateVisDataComposed = (state, action) => {