Esper

Esper is a tool for exploratory analysis of large video collections.

Setup

If you have a GPU and are running on Linux:

Install nvidia-docker.
pip install nvidia-docker-compose
For any command below that uses docker-compose, use nvidia-docker-compose instead.

If you do not have a GPU or are not running Linux: pip install docker-compose

export MYSQL_PASSWORD=<pick a password, save it to your shell .rc>
alias dc=docker-compose
dc build
dc up -d nginx
dc exec esper ./scripts/setup.sh

Then visit http://yourserver.com.

Accessing the local database

The default Esper build comes with a local MySQL database, saved to mysql-db inside the Esper repository. It is exposed on the default port (3306) and comes with a root user whose password is what you specified in MYSQL_PASSWORD. Connect to the database with:

mysql -h <your server> -u root -p${MYSQL_PASSWORD} esper

Note: that the root password will be set for good after the first time you run dc up -d nginx, so you need to either reset the database or run the ALTER PASSWORD SQL command to change the root password again.

Using the cloud database

To use the Google Cloud SQL database, first install git-crypt. Get the secret esper.key from Will and inside the repository run:

git-crypt unlock /path/to/esper.key

Then in docker-compose.yml under the esper service, uncomment db-cloud under depends_on. Re-run dc down && dc up -d nginx.

If you want to continue using your local MySQL database but just pull all the data from the cloud, then go into the esper container and run:

./scripts/load-cloud-db.sh

If you want to use the cloud database as the actual backend for your Django server, then go to docker-compose.yml and modify the appropriate environment settings. Re-run dc down && dc up -d nginx.

Using a proxy

If you're behind a proxy (e.g. the CMU PDL cluster), configure the Docker proxy. Make sure https_proxy is set in your environment as well.

Use docker-compose for any network operations like pulling or pushing (nvidia-docker-compose doesn't properly use a proxy yet). Make sure http_proxy is NOT set when you do dc up -d nginx.

You can then use an SSH tunnel to access the webserver from your local machine:

ssh -L 8080:127.0.0.1:80 <your_server>

Then go to http://localhost:8080 in your browser.

Processing videos

To add videos to the database, add them somewhere in the esper directory (the directory containing manage.py) and create a file paths that contains a newline-separated list of relative paths to your videos. Open a shell in the Docker container by running docker-compose exec esper bash and then run:

python manage.py ingest paths
python manage.py face_detect paths
python manage.py face_cluster paths

Using Tableau

Ask Will about getting permissions on the Esper project in Google Cloud. Then, install the Google Cloud SDK. After that, run:

gcloud auth login
gcloud config set project visualdb-1046
gcloud auth application-default login

This sets up your machine for accessing any of the Google Cloud services. Then, download the Google Cloud proxy tool and run:

./cloud_sql_proxy -instances=visualdb-1046:us-central1:esper=tcp:3306

Then download the Esper workbook with:

gsutil cp gs://esper/Esper.twb .

Open up Tableau (download), do File -> Open and open the Esper.twb file. Replace the prompted user name with your own SQL user and click Sign in.

To use your own MySQL database:

Click Data Source in the bottom left.
Click the dropdown arrow in box labeled 127.0.0.1 in the top left underneath Connections.
Select Edit connection....
Change the server to wherever your local instance is located.
Change the username to root.
Change the password to the value of your $MYSQL_PASSWORD.
Click Sign in.
Click Update now in the middle-bottom box.

Development

While editing the SASS or JSX files, use the Webpack watcher:

./scripts/build-frontend.sh

This will automatically rebuild all the frontend files into assets/bundles when you change a relevant file.

sdulloor / esper