
################################ Installation of Python #####################################

Python version 2.6 or 2.7 are both acceptable.

How to tell if you have Python installed?
On Windows, open a Command prompt window. Try entering the command python and hitting return.
If Python is installed and configured, you should see the python version information.

On Mac, python 2.7 is pre-installed by Apple.

How to install Python on Windows?
Go to https://www.python.org/downloads/windows/
Look for python 2.7 for windows x86. (not windows x86-64).

################################ Installation of Modules related #############################

External Modules to be installed before execution: 
1. Ephem
2. openCV 
3. ffmpeg (optional) 
4. numpy, scipy, matplotlib (Are these pre-installed on mac?)
5. moviepy

#############################################################################################

How to install the module 'ephem' (mac)?

Go to: 
Finder -> Library -> Python -> 2.6 or 2.7 -> site-packages

Follow the instructions: https://pypi.python.org/pypi/pyephem/
It is reecommended that you use pip to install the ephem folder. 

Installing pip:
Follow instruction on https://pip.pypa.io/en/latest/installing/
Download the getpip.py onto Desktop and type 'cd Desktop' in terminal.
Type 'python get-pip.py' into Terminal.

Type 'cd Desktop' and 'pip install ephem' into terminal and it will indicate the path at which the ephem directory
is located. Follow the path and copy the folder ephem into site-packages 

#############################################################################################

How to install the module 'openCV' for specifically for python on mac?

https://jjyap.wordpress.com/2014/05/24/installing-opencv-2-4-9-on-mac-osx-with-python-support/

#############################################################################################

How to install the module 'ffmpeg'?

https://www.ffmpeg.org/

Save the exec files in any location, but when using it, change the FFMPEG_BIN variable in the 
extract_jpg_frm_mp4.py file

################################ read_one_run.py ############################################

Overview:
Process the data in one run (i.e. one subdirectory from the main directory containing all runs)
read_one_run processes data read from the log file and returns values as indicated in the [Index CHART]
the main function compiles all the processed data from the read_one_run function and produces a final report
It produces gps file and a weather short file, keeping record of the starting gps parameters and 
and the weather when the video was recorded. In addition, during execution, it will produce a file 
with image frames extracted from mp4 file and produce a text file indicated the sharpness of each image



[Index CHART] function read_one_run returns the following in a tuple format:
	0  - STARTseconds
	1  - ENDseconds
	2  - GPSseconds
	3  - lon
	4  - lat
	5  - STARTdate0
	6  - ACCseconds
	7  - ax
	8  - ay
	9  - az
	10 - IMseconds
	11 - IMdates
	12 - image_list_length
	13 - IMax
	14 - image_list
	15 - light_of_day
	16 - sharpness
	17 - weather_str
	18 - weather_num


This file contains four functions:
1. datetime2matlabdn
2. str2datenum
3. make_imagedate_list
4. is_Daylight_Savings
5. weather_new
6. sharpness_detection_per_image
7. sharpness_detection_main
8. read_one_run
9. main


To Run the code:
Go to the end of the file to access information on how to run the code

################################ extract_jpg_frm_mp4.py ########################################

Overview: 
Given a video in mp4 format, extract_jpg_frm_mp4 extracts frames from the video at a specified rate
The function allow images of two different resolution to be extracted. The high resolution image has sizes
of around 350KB, while the low resolution image has sizes around 80KB. In order to use ffmpeg, the path to the 
ffmpeg exec has to be specified. Since ffmpeg might not be installed, program send an error message if ffmpeg is 
not installed and automatically switches to use openCV instead. If ffmpeg is not used or installed, comment the import 'from moviepy.editor import *'. If it is to be used, ensure moviepy is installed.

Options: 
1. High resolution - single frame (openCV)
2. High resolution - multiple frames at a given rate (openCV)
3. Low resolution - single frame (ffmpeg)
4. Low resolution - multiple frames at a given rate (ffmpeg)
5. Low resolution - single frame (OpenCV)
6. Low resolution - multiple frames at a given rate (OpenCV)

################################ write_your_kml.py ########################################

Overview:
Produce one kml file that keeps track of all info of all images in each run 
write_your_kml_run returns a body for each run in the main_dir 
write_your_kml_main calls write_your_kml_run and compiles all sub-bodies into one main body, 
writing it into the kml file 
the kml file will be saved in the main_dir, same level as all the sub-run folders.
Notes that the folder 'arrows' should be saved at the same level as all the directories for the runs

Options: 
Options are based on how many images we want to display on the google earth

0. all images
1. only latest images at each location 
2. only the sharpness image every 10 meters 
3. both latest and every 10 meters (most efficient set)

#############################################################################################

How to run the entire code on one main directory?

Before you begin, please double check the following: 

1. external modules are installed (especially openCV and ephem)
2. The subdirectories has to be of the format '20150806_172541_260_CMU'
3. Ensure the log file and video files are in the sub directories. They should be named using this format 'VID_20150806_172541_260_CMU.mp4' and 'VID_20150806_172541_260_CMU.log'.
2. if extract option 3 or 4 (ffmpeg) is what you want to use, make sure it is downloaded, 
and the file path is changed in the extract_jpg_frm_mp4.py file. 
3. Inside each sub directories, there exists a log file and an mp4 file 
4. Folder named "arrows" is saved under the main directory 
5. if this is the second time running the program, please clear out all files and photos saved 
from the previous runs (i.e. images, gps.txt, sharpness.txt, kml etc) Under the main directory, 
there should only be the sub directories for each run, and a folder named arrow. And under each sub
directory, there should only be a log file and a mp4 file. This would make sure the data extracted
do not clash from previous runs and the information is most updated and consistent.

After checking the above, you should be ready to run the program:

1. The only file that needs to be altered would be the MAIN.py file. Do not change anything in the
other python files. 

2. The MAIN function takes in the following parameters: 
main_dir, frame rate, kml option, extract option

3. The parameter main dir takes in the file path to the main directory. 
An example would be : "/Users/lamwingchan/Desktop/navlab"
This is the main directory that contains all sub directories.

4.  The parameter frameRate takes in an positive integer, which is how many images needs to be extracted 
per second. For a 25 seconds video, if you want 25 images, 1 would be your frameRate. If you want 50 images
instead, 2 would be your frameRate. 

5. For the parameters kml option, extract option, you may find the following useful:

# kml option :
# 0. all images
# 1. only latest images at each location 
# 2. only the sharpness image every 10 meters 
# 3. both latest and every 10 meters (RECOMMENDED! most efficient set)

# extract_option :
# 1. High resolution - single frame (openCV)
# 2. High resolution - multiple frames at a given rate (openCV)
# 3. Low resolution - single frame (ffmpeg)
# 4. Low resolution - multiple frames at a given rate (ffmpeg)
# 5. Low resolution - single frame (OpenCV)
# 6. Low resolution - multiple frames at a given rate (OpenCV)

The above index table for these two parameters is also available at the end of the MAIN.py file.

6. After obtaining all the required parameters, you are ready to run the program.

7. At the end of the MAIN.py file, you should see the command line. There is a commented line 
"INPUT HERE!!". The line which requires your input would be the line below. Alter the parameters 
accordingly. 

After the program has completed all the runs:

1. You should be able to see the following being printed:

# Successful Run!

# You should find the following in each sub-directories:
# 1. Photos
# 2. Final Report
# 3. gps.txt
# 4. sharpness.txt
# 5. weather-short.txt

# You should find the following in the main directory:
# 1. hi-my-kml.kml




