Welcome to The NUS Statistics Society Facemask Detector Workshop!

View the workshop video here!

Note: if you attended the workshop or cloned this repo before 18 September 2020, please type git pull while in the project folder to pull the latest code in which the backend is completed and everything should be working!

The purpose of this repo is to help you get started with the basic tools 🔨 and code 💻 needed to follow along in the workshop. It will also serve as the single source of truth, hosting the latest version of our facemask 😷 detector workshop material 📚.

We hope that you will find great joy and meaning in our workshop! 😂 Consider giving this repo a star ⭐ if you found it helpful!

Table of contents:

• Workshop video
• Pre-workshop installation guide
  • Windows
  • Mac
  • Linux
• Project structure
• Project setup
  • Cloning this repo
  • Launching jupyter notebook
  • Running the website
  • Running the FastAPI server
• Credits

Workshop video

View the workshop video here!

Pre-workshop installation guide

This guide covers the installation of:

• Anaconda - a distribution of python which comes with a lot of data science packages 📦.
• jupyter notebook - a live python execution environment typically used for exploratory 🔍 data analysis.
• nodejs and npm - nodejs is a js (javascript) runtime built on chrome's V8 engine 🚗 and npm is a package manager for nodejs.

You may find the detailed installation instructions for your operating system (Linux/Mac/Windows) via the links below. We know the instructions might look pretty lengthy but it won't take more than 20 minutes! 🙏🙏🙏

If you use a Windows machine, click here.

If you use a Mac, click here.

If you use Linux, click here.

Please only follow ONE of the installation guides e.g. if you're using Mac please don't follow the Linux guide by accident. We can't help you with troubleshooting issues otherwise.

I have problem 😭😭. What do?

Please post a GitHub issue on this repo if you encounter any difficulties!

We'd love to help you, so do include as much information that could help us such as:

• error logs,
• your operating system (Windows/Mac/Linux),
• your python3 --version,
• the exact steps you took that led to the issue,
• etc.

Thank you 🙏

Project structure

This is how the project is 🏘️🏗️structured🏢🏬. Do have a read to orient:angel: yourself.

From the project root

.
├── backend/  <--- contains FastAPI server code
├── frontend/ <--- contains website server code (nextjs)
├── notebook/ <--- contains jupyter notebook code
├── linux.md
├── mac.md
├── README.md
└── windows.md

Notebook

.
├── notebook/
    ├── data/ <--- contains our train and test data and labels
    │   ├── test/
    │   ├── test.csv
    │   ├── train/
    │   └── train.csv
    ├── facemask_workshop_participants.ipynb <--- the jupyter notebook you'll play with
    ├── history.pickle <--- our saved model training history
    └── model/         <--- our saved keras model (facemask detector)
        ├── assets/
        ├── saved_model.pb
        └── variables/

Backend

.
├── backend/
    ├── detector/
    │   ├── config/
    │   │   ├── classifiers  <--- weights for non-DL face detector
    │   │   ├── facenet      <--- weights for DL face detector
    │   │   └── keras_model/ <--- our saved keras model (facemask detector)
    │   ├── detector.py      <--- our detector class that utilizes the model
    │   └── __init__.py
    ├── __init__.py
    ├── main.py          <--- FastAPI server entrypoint
    ├── requirements.txt <--- specifies the project dependencies
    └── run.sh           <--- simple script to help run the FastAPI server

Frontend

.
├── frontend/
    ├── components/
    │   ├── cardDetectionLog/
    │   ├── cardVideoFeed/
    │   │   ├── Canvas.js        <--- draws bounding box around your face
    │   │   └── CardVideoFeed.js <--- video component
    │   └── footerContent/
    ├── config.js    <--- lets you configure the detection interval (fps)
    ├── package.json <--- specifies the project dependencies
    ├── pages/
    │   ├── _app.js
    │   └── index.js <--- website entrypoint
    ├── styles/
    └── utils/
        └── detector.js <--- contains functions to send API requests to backend

Project setup

Follow the instructions below to get familiarized with the project repo. You may make reference to this section during the workshop itself to perform certain tasks 📖.

If you wish to access the incomplete pre-workshop code, type git checkout workshop to switch to the workshop branch (while in the project folder). To revert back to the master branch containing the working code, type git checkout master.

Cloning this repo

1. Ensure you have the latest system packages.
   1. (For Windows/Linux) Open up terminal (wsl terminal for Windows) and type sudo apt update && sudo apt upgrade.
   2. (For Mac) Open up terminal and type brew update && brew upgrade.
2. Run git clone --depth 1 https://github.com/geoboom/facemask-workshop.git to clone this repo.
   • Troubleshooting: if you get a git command not found error, run sudo apt install git first then try cloning the repo again.
3. Run ls and you should see a folder called facemask-workshop.

Launching jupyter notebook

1. In terminal, type cd facemask-workshop to navigate to the project's root folder.
2. In the root folder, navigate to the notebook subdirectory by typing cd notebook.
3. Type conda activate base to activate Anaconda's base environment. You should see (base) beside your name in terminal.
4. Now run jupyter notebook (jupyter notebook --no-browser if you're on windows) and this notebook folder should open in Jupyter Notebook on your browser.
   • If you're on windows, copy the url that looks like http://127.0.0.1..token=.. OR http://localhost..token=..displayed in the terminal and paste it in your browser. This is the url to your Jupyter Notebook.
   • Troubleshooting: if for some reason Jupyter Notebook in the browser does not show the files in notebook/ folder, then go back to terminal and hit CTRL+C to stop the server. Once the server has stopped, run jupyter notebook --no-browser --notebook-dir=. and try accessing it on the browser again.

Running the frontend (website)

1. Open up a new terminal and type cd facemask-workshop to navigate to the project's root folder.
2. In the root folder, navigate to the frontend subdirectory by typing cd frontend.
3. Type npm install to install the frontend project dependencies specified in package.json. This might take a while so grab a coffee ☕.
4. Once the dependencies have finished installing, type npm run dev to run the website's server (nextjs).
5. Visit localhost:3000 in your browser to see the website live!

Running the backend (FastAPI server)

1. Open up a new terminal and type cd facemask-workshop to navigate to the project's root folder.
2. In the root folder, navigate to the backend subdirectory by typing cd backend.
3. Type python3 -m venv venv to create a python3 virtual environment in the backend directory.
   • Troubleshooting: if you get an error regarding pip/ensurepip/venv, you most likely do not have python3-venv installed. To resolve this, run sudo apt install python3-venv.
4. Type source venv/bin/activate to activate this virtual environment. You should see (venv) beside your name, indicating that the venv environment is activated.
5. Run pip install -r requirements.txt to install the dependencies to this virtual environment, specified by requirements.txt. This might take a while so grab a coffee ☕. It is strongly advised that you run pip install --upgrade pip first.
   • Troubleshooting: if you get "ERROR: Could not find a version that satisfies the requirement opencv-contrib-python=4.4.0.42..." attempting this step, fret not. Just run git pull to fetch the latest changes (I most likely updated the repo after you cloned it) and re-do step 5.
6. Once dependencies have finished installing, type ./run.sh to run the FastAPI server and hit enter.

Credits

Name	Role	Github
Jet	NUS Statistics Society Workshop Director	https://github.com/jetnew
Rama	Presenter, guide writing, and material prep	https://github.com/ramaven
Georgie	Presenter, guide writing, and material prep	https://github.com/geoboom

Dataset for masked/no-masked.