====== Team #6 ======


=== MEMBERS ===

  * Nizar BOUSSARSAR (bn509988)
  * Raed CHAMMAM (cr510004)
  * Asma DHANE (da508872)
== Equipments ==

  * Phone : Smartphone HTC 8S
  * IMEI : 358721050411346

=== PROJECT ===

== Title of the Project : ==

**TrailBuddies**

== Content of the Project ==

===== Short project description =====

Hiking buddy suggestion influenced by the users' common trail habits.

===== Detailed project description =====

This app logs the different hiking activities of the user, and then compares them to the activities of different users.
The users' activities are clustered depending on the level of difficulty of their regular hiking.
The difficulty is calculated based on three factors : trail circuit length, trail circuit duration, trail circuit max altitude.
When a user is looking for a hiking buddy, the app tries to suggest one or many that have a certain compatibility depending on their habits.

===== How it works =====

==== Data manipulation ====

After collecting sensors raw data which are a set of latitude and longitude couple called Geopoints, it is time to calculate the length of the trail circuit. 
To do so, the application's algorithm takes each couple of Geopoints as input, with the measure unit of latitude and longitude, and returns the distance between these two points. As for the measure of trail's duration, the algorithm stores two times: the trail's starting and anytime which are system's timestamp at the beginning of the trail and the end of the trail. These steps are done in a background-task.
==== Machine learning and clustering ====

Based on trails information (distance and duration) the next step is to build a dataset, the database. K-Means is the unsupervised machine learning algorithm, or simply clustering algorithm, implemented in this solution to ensure grouping similar users together. There are three clusters which are: easyTrails, mediumTrails and hardTrails. 
The first step is to initialize the input which is a bi-dimensional array of distance and duration, choosing the appropriate distance measure mechanism and fixing the number of clusters. After that, the algorithm chooses randomly n centroids based on the number of clusters, which is called k, and calculates the distance between a given centroid and all the other points based on Euclidean distance. After initializing the clusters, the algorithm finds the nearest point in the centre of the cluster and call it centroid by calculating intra-cluster distance (distance between points in the same cluster). It also calculates the inter-cluster distance to identify which point belongs to which cluster (distance between the centroid of each cluster and points of other clusters). The system repeats these instructions until the stability of cluster centroids or reaching the iterations limit.

==== User matching ====


The main goal of this application is to give the users the possibility to find people, trail buddies, based on their hiking activities similarity. The user matching algorithm is quite simple, it relies on comparing the connected user with all application users. 
The comparison mechanism is based on two conditions; two trail buddies are similar, if the number of trails of the connected user is equal or lesser than 5% another one and if the connected users percentage of trails per cluster is equal or lesser than 5% another one. A set of similar trail buddies is then listed to the connected user with their phone number so he can contact them and organise a trail together.

=== Developped SOFTWARE ===

== Screenshots and GUI description == 
Left to right:
  * Splash-screen
  * Login screen 
  * Main menu [start a trail or find a partner]

{{ :projets:plim:20152016:ss-01.png |}}


Left: Tracking screen [Start or Stop tracking]

Right: Find-a-buddy screen, where a list of matching users and their phone numbers gets displayed. 

{{ :projets:plim:20152016:ss-02.png |}}

== SOFTWARE PACKAGES of the Project ==
  * [[https://github.com/RaedsLab/PLIM-TrailBuddies|Github]]
  * {{:projets:plim:20152016:plim-trailbuddies.rar|RAR file}}

== Required SOFTWARE Environment ==
  - Microsoft Visual Studio 2015 Community 
  - Windows Phone 8.1 SDK
  - Parse [[https://www.parse.com/docs/dotnet/guide|.Net + Xamarin SDK]] >v1.6.1 (Requires sign-up)
  - [[https://www.nuget.org/packages/newtonsoft.json/|Newtonsoft.Json]] JSON framework for .NET


== How To build solution from project sources ==

You can build and test the solution from within Visual Studio.
The project has been tested on both emulator and real device.

An account has been created for the purpose of the demo:
  * Username: **Demo**
  * Password: **1234**

We are using [[https://www.parse.com|Parse]] to store the collected data and the users, so you will need to have internet access for this to work. 


== F.A.Q ==

If you're going to use the //emulator//, make sure to provide the app with a number of locations so it could measure the traveled distance.

For this demo an "//application Key//" and a "//.NET Key//" have been provided in the code. These keys are required when using the Parse SDK in order to store and retrieve data.

If you're going to fork this project, you should locate '**ParseClient.Initialize**' in the code and change the previously mentioned keys.

Documentation about the Parse SDK and a getting started guide are available [[https://www.parse.com/docs/dotnet/guide|here]].


=== HOW TO USE IT and RESULTS ===

== Tutorial video ==


{{http://www.youtube.com/v/RFEtDAr7iHc?.swf?400×333}}