Project Submission Instructions

=========================
===== Project Setup =====
=========================

This section describes how to set up your development environment for this class, and how to setup your project for later submission.

=== Development Environment Setup ===
There are two different ways to setup environment.

Option 1. Conda (recommended)

For those who have installed, or plan to install anaconda or miniconda, install anaconda/miniconda and run commands below:

	conda create -n cs445 python=3.6
	conda activate cs445
	conda install -y numpy scipy opencv matplotlib jupyter

Note that you don't have to use cs445 as your environment name.

Option 2. pip

For those who don't want to use anaconda or miniconda based python, we also provide requirements.txt for pip based packages. Those choosing this option need to install OpenCV 3+/4.

To install dependent python packages, run:
	pip install -r requirements.txt


=== Project Webpage Setup ===

You can create your project setup in two ways. 

Option 1: Through Web Management Site
1) Go to your project page management site: https://web.illinois.edu/. Web pages created here will appear at http://netid.web.illinois.edu.  
2) Click on "file manager" and go to "public_html". Create a folder called "cs445". Within that, create a folder called "proj1" for your first project.
3) Create or place a blank or test page called "index.html" in "proj1" and make sure that you can access it at http://netid.web.illinois.edu/cs445/proj1/, where "netid" is your netid.

Option 2: SFTP
You can also access your website through SFTP.  For example, I use WinSCP with SFTP to access web.illinois.edu (port 22), username dhoiem.  

Working on Project with Jupyter Notebook

We extensively use Jupyter Notebook (https://jupyter.org/) for our projects. For more information about Jupyter, please refer to the documentation and tutorial page of the Jupyter Webpage.


=== Running Jupyter Notebook Local Server ===

To use Jupyter notebook use your favorite terminal to run:

	cd YOUR_PROJECT_DIRECTORY
	jupyter notebook

Then, your default browser will open up a page that contains files in that directory. Typically, the page will be opened on localhost:8888/tree.


=== Understanding Notebook Kernel ===

Each notebook in Jupyter Notebook Local Server is associated with a Kernel.  Whenever a new Notebook is created or opened, the Kernel, a python subprocess is created that contains variables and functions that the Notebook will evaluate.  

For instance, running

	foo = 3

makes variable foo to be stored in the subprocess memory.

Each Kernel can be shutdown, freeing the subprocess and making the Notebook inactive. You can always reactivate Kernels by using Kernels => Restart button on the notebook menu. If there are multiple connections to same notebook, there can be collision of kernel processes. It is generally not recommended to run multiple instances of same notebook.


=== Creating new Notebook ===

You can click New button on right top corner of the opened page, and click Python 3 to create new notebook. If you go back to localhost:8888/tree, you will notice that there is a new file created, with Green Book icon. Green indicates that the notebook kernel is active. Each Notebook file has the "ipynb" extension.

** Opening Existing Notebook **
To open existing notebook, click on ipynb files under localhost:8888/tree. If the notebook kernel was not active, it will be active as you open it. If the notebook kernel was already active, it will connect to the existing kernel.

** Clearing / Resetting notebook **
You can clear notebook kernel by pressing restart button or Kernel => Restart button. This will wipe out varibles stored in memory in Kernel, and start new subprocess.

** Running code on Notebook **
To run active code block on Jupyter Notebook, you can simply do Ctrl + Enter (CMD + Enter for mac). To run and select next code block, you can click on Run button or do shift + Enter. Code under Code block will be evaluated, and variables at the top level scope will be kept in memory.

** Closing Notebook Local Server **
You can prompt shutdown notebook server by pressing ctrl + c in terminal that is running Jupyter Notebook Local Server.

** Visualizing Images on Notebook **
We recommend using matplotlib (https://matplotlib.org/) for visualizing your results on notebook. Matplotlib can show OpenCV (https://docs.opencv.org/master/) and PIL (https://www.pythonware.com/products/pil/) images on the browser. This is very useful for debugging purposes.

	import matplotlib.pyplot as plt
	%matplotlib inline # or `%matplotlib notebook` for interactive plotting

	from PIL import Image
	import cv2

	# read image using PIL and OpenCV library
	image_1 = Image.open(PATH_TO_IMAGE)
	image_2 = cv2.imread(PATH_TO_OTHER_IMAGE)
	...

	# Display image on notebook
	fig, axes = plt.subplots(2, 2)
	axes[0, 0].imshow(image_1)
	axes[0, 1].imshow(image_2)
	axes[1, 0].imshow(image_3)
	axes[1, 1].imshow(image_4)

==============================
===== Project Submission =====
==============================

To submit, you must: (1) update your project page; AND (2) submit files through compass.

(1) Updating Project Page 

Project description and results should be described in a file called 'index.html' and posted to the appropriate projects directory with any supporting media files.
 -This does not need to be a comprehensive report.
 -Include your results and any parameters or special things that you tried.
 -The page should be sufficiently clear so that the professor, TAs, and other students can easily understand what your results mean and how you got them.
 -You don't need to include a lengthy introduction or detailed description.

Post your project web page to NETID.web.illinois.edu/cs445/proj#/index.html where "#" is replaced by "1", "2", "3", "4", or "5", depending on the project.
 -Try to keep each project page under 10MB so that people can see the page in a reasonable amount of time.
 -You can use '.jpg' compression and web-scale resolutions to keep image size down and post large videos via YouTube for streaming.
 -Be sure to check that the page is working and complete. If not, we will consider it late.

Include a thumbnail image at NETID.web.illinois.edu/cs445/proj#/thumbnail.jpg.
 -Typically, the thumbnail should be your favorite result, something that is unique to your project, as it will be used on the class results page. The thumbnail does not need to be displayed within your project page.

Because this page will be available to everyone, ***DO NOT POST ANY SOURCE CODE***.


(2) Submission to Compass

Submit code/text via Compass. Projects will be mainly done in Jupyter Notebook (https://jupyter.org/) using Python3 kernels. Once finished, re-run all the cells to make sure they work and print your notebook to .pdf. We recommend you run Kernel => Restart Kernel and Run All Cells function before submission.

Code: Zip the code and images in a file called NETID_proj#.zip, where NETID is your net id. You need to submit both the .zip file and the associated notebook NETID_proj#.pdf file. Do not include large result files in this zip.

Text: In text with the submission, say how many points you expect to receive for the regular assignment (up to 100) and any extra points from bells and whistles. This will help to avoid misunderstandings.

=== Additional Notes ===

Reminder:
 Core projects worth total of 500 points, “bells and whistles” for additional points:
 – Undergrads are graded out of 500, grads out of 600.

Tips and tricks from TA
- For Windows users, we recommend using 'cmder', which contains prebuilt bash compliant command prompt.