detailed READMEs for example apps (#154)

tracyhenry · Sep 3, 2020 · f81e28b · f81e28b
1 parent a8a8305
commit f81e28b
Show file tree

Hide file tree

Showing 14 changed files with 253 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ Kyrix facilitates the creation of data visualizations with details-on-demand int
 
 1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) (must be `v1.17.0` or later). For Mac users, installing [Docker Desktop](https://docs.docker.com/docker-for-mac/install/) will install Docker Compose automatically. Ubuntu 18.04 users can also simply install with `sudo apt update; sudo apt install -y docker.io docker-compose;`.
 2. Run `sudo ./run-kyrix.sh --nba --build` in the root directory. You might need to make `run-kyrix.sh` executable, i.e. `sudo chmod +x run-kyrix.sh`.  
-3. Wait a couple minutes, then point your browser at <ip address>:8000 - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+3. Wait a couple minutes, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
 
 note that you'll need to wait for a message saying `Backend server started...` like this:
 ```

diff --git a/compiler/README.md b/compiler/README.md
diff --git a/compiler/examples/README.md b/compiler/examples/README.md
diff --git a/compiler/examples/USMap/README.md b/compiler/examples/USMap/README.md
@@ -0,0 +1,34 @@
+# US Crime Rate Map
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/ifY54Kuou1tXooFQTW/giphy.gif" width = "450"/>
+</a>
+</p>
+
+This example app has two canvases. The top-level canvas shows state-level US crime rates, where darker colors indicate higher crime crime rates per 100,000 population. The user can click on a state, and zoom into a detailed county-level crime rate map centered at the clicked state. On the county canvas, the user can pan around. 
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands:
+```
+wget https://www.dropbox.com/s/youvfap909mk1m3/usmap_db_psql.sql     # download data
+sudo ./docker-scripts/load-sql.sh usmap_db_psql.sql --dbname usmap   # load data into the database, must be run in root folder
+cp docker-scripts/compile.sh compiler/examples/USMap/compile.sh      # copy the compile script
+cd compiler/examples/USMap                                           # go to the app directory
+chmod +x compile.sh                                                  # make the compile script excutable
+sudo ./compile.sh USMap.js                                           # compile the application
+```
+Wait for about one minute, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's 
+firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!
diff --git a/compiler/examples/USMap_cmv/README.md b/compiler/examples/USMap_cmv/README.md
@@ -0,0 +1,38 @@
+# US Crime Rate Map (with two views)
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/fxYeifelHXbWiArGZR/giphy.gif" width = "800"/>
+</a>
+</p>
+
+This example app is a variant of the [USMap application]() with two coordinated views placed side by side. The view on the left shows state-level US crime rates, where darker colors indicate higher crime rates per 100,000 population. The user can click on a state, and populate the view on the right with a detailed county-level crime rate map centered at the clicked state. On the county canvas, the user can pan around. 
+
+In the [embedding API documentation](https://github.com/tracyhenry/Kyrix/wiki/Web-Embedding), we offer an example to embed this Kyrix app into a web app where more controls and a minimap are available. 
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands:
+```
+wget https://www.dropbox.com/s/youvfap909mk1m3/usmap_db_psql.sql     # download data
+sudo ./docker-scripts/load-sql.sh usmap_db_psql.sql --dbname usmap   # load data into the database, must be run in root folder
+cp docker-scripts/compile.sh compiler/examples/USMap_cmv/compile.sh  # copy the compile script
+cd compiler/examples/USMap_cmv                                       # go to the app directory
+chmod +x compile.sh                                                  # make the compile script excutable
+sudo ./compile.sh USMap_cmv.js                                       # compile the application
+```
+Wait for about one minute, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's 
+firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!
diff --git a/compiler/examples/dots-pushdown-uniform/README.md b/compiler/examples/dots-pushdown-uniform/README.md
@@ -1,3 +1,4 @@
+# For maintainers only
 This is an application used to test performance/scalability. 
 
 For dots-pushdown-uniform, the assumption is that the data is distributed evenly/randomly across the canvas.

diff --git a/compiler/examples/dots-skewed-80-20/README.md b/compiler/examples/dots-skewed-80-20/README.md
@@ -1,3 +1,4 @@
+# For maintainers only
 This is an application used to test performance/scalability. 
 
 For -skewed-80-20, the assuming is 80% of the data resides in 20% of the Euclidean space.
diff --git a/compiler/examples/dots-uniform/README.md b/compiler/examples/dots-uniform/README.md
@@ -1,11 +1,4 @@
-This is an application used to test performance/scalability. 
+# For maintainers only
+This is an application used to test performance/scalability.
 
 For dots-uniform, the assumption is that the data is distributed evenly/randomly across the canvas.
-
-## Generating data (legacy)
-As defined in `transform.js`, running this app needs a database `dots` with a relation `dots`, whose schema is `create table dots (id int, x int, y int);`.  The data generator `/datagen/gen.cpp` can generate a file which you can use to populate the `dots` relation (e.g. in Postgres, `COPY dots FROM 'absolute/path/to/data/file'`).  You can modify `num_points` in the cpp file to vary the number of total points.
-
-## Running the app
-You need to change the first line of the kyrix config file to `dots` (name of the app), restart the server, then run `node dots.js`. 
-
-You will see a scatterplot with uniformly distributed dots. There are two zoom levels (double click to zoom in, shift + double click to zoom out).  There are three parameters you can tune to adjust visual density (which greatly affects performance): `num_points` in the data generator, `topWidth` and `topHeight` in `dots.js`.If you have Trypophobia, be careful not to make it too dense....
diff --git a/compiler/examples/flare/README.md b/compiler/examples/flare/README.md
@@ -0,0 +1,35 @@
+# Flare Class Hierarchy
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/TkDRjJknUHDspwTcJV/giphy.gif" width = "450"/>
+</a>
+</p>
+
+This example app visualizes classes in the [Flare visualization library](https://blokt.com/tool/prefuse-flare) in a zoomable circle packing layout. The user can click on a class to zoom into another view showing its direct child classes. This visualization is composed of only one canvas, so the zoom object is a self-loop of this canvas.
+
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands:
+```
+wget https://www.dropbox.com/s/ugr3cx63ul3tt0k/flare_db_psql.sql     # download data
+sudo ./docker-scripts/load-sql.sh flare_db_psql.sql --dbname flare   # load data into the database, must be run in root folder
+cp docker-scripts/compile.sh compiler/examples/flare/compile.sh      # copy the compile script
+cd compiler/examples/flare                                           # go to the app directory
+chmod +x compile.sh                                                  # make the compile script excutable
+sudo ./compile.sh flare.js                                           # compile the application
+```
+Wait for a couple seconds, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's 
+firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!
diff --git a/compiler/examples/forest/README.md b/compiler/examples/forest/README.md
@@ -0,0 +1,34 @@
+# Animals in the Amazon Rainforest
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/efIVT8V355s9Ot0xqH/giphy.gif" width = "700"/>
+</a>
+</p>
+
+This example is a map of animals in the Amazon rainforest. There are three canvases, each with two layers. One shows background images. The other layer shows the animals. In the top two canvas, animals are previewed as white dots. In the bottom canvas, images of the animals are shown. The background images in the bottom canvas are higher-resolution versions of those in the top canvases.
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands:
+```
+wget https://www.dropbox.com/s/39ji04m926lfx5i/forest_db_psql.sql     # download data
+sudo ./docker-scripts/load-sql.sh forest_db_psql.sql --dbname forest  # load data into the database, must be run in root folder
+cp docker-scripts/compile.sh compiler/examples/forest/compile.sh      # copy the compile script
+cd compiler/examples/forest                                           # go to the app directory
+chmod +x compile.sh                                                   # make the compile script excutable
+sudo ./compile.sh forest.js                                           # compile the application
+```
+Wait for about half a minute, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's 
+firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!
diff --git a/compiler/examples/nba/README.md b/compiler/examples/nba/README.md
@@ -0,0 +1,33 @@
+# NBA Basketball Data Visualization
+
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/LqmgdFV6uVMT8UPezi/giphy.gif" width = "450"/>
+</a>
+</p>
+
+This example app visualizes NBA data in the season 2017~2018. There are four canvases, showing different type of entities in the dataset: teams, games, plays and boxscores. Canvases are connected via semantic zooms, allowing users to see related entities of an entity of interest. 
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, you should be able to see this application at <ip address>:8000. If later you want to switch back to this application, you can run the following commands in a separate terminal:
+
+```
+cp docker-scripts/compile.sh compiler/examples/nba/compile.sh        # copy the compile script (run in the root folder)
+cd compiler/examples/nba                                             # go to the app directory
+chmod +x compile.sh                                                  # make the compile script excutable
+sudo ./compile.sh nba.js                                             # compile the application
+```
+Wait for about one minute, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!
diff --git a/compiler/examples/nba_cmv/README.md b/compiler/examples/nba_cmv/README.md
@@ -0,0 +1,35 @@
+# NBA Basketball Data Visualization (with two views)
+
+<p align="center">
+<a href="https://github.com/tracyhenry/Kyrix/tree/master/compiler/examples/USMap">
+<img src="https://media.giphy.com/media/LSoUc3oBfbTa484WEy/giphy.gif" width = "700"/>
+</a>
+</p>
+
+This example app is a variant of the default NBA application with two coordinated views. The view on the left shows the logos of 30 NBA teams. When clicking on a team, the user can populate the view on the right with the schedule of the clicked team. This schedule is pannable, and allows the user to click on a game to zoom into the boxscore/play-by-play canvas, similar to the default NBA app. 
+
+A key functionality this variant app enables is coordinated selection. Say the view on the right is showing the schedule of the the Boston Celtics. The user can click on another team in the left view, say the Golden State Warriors, to highlight the games between the Celtics and the Warriors. 
+
+# Installation Instructions for the Impatient
+After running `sudo ./run-kyrix.sh --nba`, open another terminal tab and run the following commands:
+
+```
+cp docker-scripts/compile.sh compiler/examples/nba_cmv/compile.sh    # copy the compile script (run in the root folder)
+cd compiler/examples/nba_cmv                                         # go to the app directory
+chmod +x compile.sh                                                  # make the compile script excutable
+sudo ./compile.sh nba_cmv.js                                         # compile the application
+```
+Wait for about one minute, then point your browser at `<ip address>:8000` - remember that if you are using a cloud instance you may (probably) need to open your cloud provider's firewall for this port. If that sounds scary, you can create an SSH tunnel from your PC (e.g. Mac) using `ssh -N <server ipaddr> -L 8000:<same ipaddr>:8000` to forward your laptop's port 8000 to the server via [SSH tunneling](https://www.tecmint.com/create-ssh-tunneling-port-forwarding-in-linux/). 
+
+note that you'll need to wait for a message saying `Backend server started...` like this:
+```
+Serving /project
+New project definition coming...
+There is diff that requires recomputing indexes. Shutting down server and recomputing...
+Precomputing...
+Done precomputing!
+Completed recomputing indexes. Server restarting...
+Backend server started...
+```
+
+Please refer to the [tutorial](https://github.com/tracyhenry/Kyrix/wiki/Tutorial) for more details on how to start writing your own Kyrix application!