Installing PixPlot

Intro

This Docker container allows a user to run PixPlot to create outputs and then visualize them. It creates an API end point to send commands to pixplot as well as to browse your application folder where output PixPlots have been created and view them.

Install w/ Docker

Docker Desktop

1. Install Docker Desktop

2. Search for the DMI PixPlot image `digitalmethodsinitiative/dmi_pix_plot

3. Click the Run button and be sure to enter "Optional Settings"

• A Host port is required to use the web interface; use 80 if available or otherwise any available port such as 4000
• Container name will be helpful in starting and stopping PixPlot in the future

4. Wait for Docker to download and start the image and got to http://localhost, if you used 80 above, otherwise http://localhost:4000 (or other port)

You can start and stop the PixPlot container with the Docker Desktop application. Just find the PixPlot container (on the "Containers" tab) and use the start/stop buttons. Docker Desktop will have to be running for you to use PixPlot.

Docker via command line

1. Install Docker Desktop

2. Pull the latest docker image from Docker Hub

• No AVX version: docker pull digitalmethodsinitiative/dmi_pix_plot:no_AVX (for older hardware that Tensorflow doesn't like)

3. Start container for first time sudo docker run --publish 127.0.0.1:4000:4000 -v ./data/:/app/data/ --name pix_plot -d digitalmethodsinitiative/dmi_pix_plot:no_AVX `

• --name pix_plot will allow you to start the container again later with docker start pix_plot
• --publish 127.0.0.1:4000:4000 tells Docker what host port connects to the container port :
  • You can set the host port as you wish
  • 127.0.0.1:4000:4000 means that only localhost can access your container
  • 4000:4000 will expose your container to outside connections (via your_ip:4000)
• -v ./data/:/app/data/ mounts the data folder in your current directory to /app/data/ inside the container; all images and plots are saved here
  • You can also use a Docker volume by name e.g., my_docker_volume:/app/data/ and Docker will save your data for you
  • Leaving off this attribute can cause lose of data in the event you remove the pix_plot container
• -d starts the container in the background

4. You are now running! View pixplot at http://localhost:4000 in your browser

5. Afterwards you can stop and start your container as you wish

• docker stop pix_plot stops the container
• docker start pix_plot starts the container
  • docker start -a pix_plot will start the container and allow you to connect interactively (to view logs, change config.yml, etc.)
• docker exec -it pix_plot /bin/bash will allow you connect to a running container via command prompt to run commands as you wish

Usage of PixPlot container

Uploading and viewing images

• A simple web interface will start with the container by default on localhost

  • http://localhost:4000/upload/ will allow you to upload images
  • http://localhost:4000/uploads/ will allow you to browse uploaded images
    • Uploaded images will be located at /usr/src/app/data/uploads/user_defined_folder_name/
  • http://localhost:4000/create/ will allow you to use one of the folders to create a PixPlot
  • http://localhost:4000/plots/ will allow you to navigate to a created PixPlot

• You can also use docker to copy any image files with docker cp path/to/name_of_folder pix_plot:/usr/src/app/name_of_folder

  • Run this from host machine, not inside docker container

Using API to create PixPlots

• Post via curl or python requests commands to pixplot
  • pixplot commands found at PixPlot's github
  • API requests can be sent like so:

# This is equivalent to "python pixplot/pixplot.py --images "path/to/images/*.jpg" --metadata "path/to/metadata.csv"
import requests
data = {"args" : ['--images', "/usr/src/app/data/uploads/user_defined_folder_name/*.jpg", '--metadata', "/usr/src/app/data/uploads/user_defined_folder_name/metadata.csv"]}
resp = requests.post("http://localhost:4000/api/pixplot", json=data)

• You can check the status of your command like so:

result = requests.get(resp.json()['result_url'])
print(result.json())

• It is also possible to run commands directly while the docker container is running via docker exec -it pix_plot "/bin/bash"

• Navigate your browser to http://localhost:4000/plots/ to view your output PixPlots

  • Navigate to output directory (default output directory name is output and can be changed with the arg --out_dir /usr/src/app/data/plots/whatever_you_want)
  • Click on index.html

Advanced Usage

Build your own Docker image (say if you are developing)

1. Install Docker

2. Clone DMI PixPlot Repo

3. In repo directory, run docker build -t pix_plot .

4. Start and connect to container docker container run --publish 4000:4000 --name pix_plot -it pix_plot

• --name pix_plot will allow you to start the container again later with docker start pix_plot
• --publish 4000:4000 allows container to publish outside of container (i.e., your localhost)
• Ctl+c will close and stop the container

5. Afterwards you can start the docker container in the background with docker start pix_plot. You will need to use docker stop pix_plot to stop it from running.

• docker start -a pix_plot will allow you to connect interactively and view output similar to run, however you will need to run docker stop pix_plot to end it as opposed to Ctl+c
• docker exec -it pix_plot /bin/bash will allow you connect to the container via command prompt to run commands as you wish