added release notes + description of the counter heuristic

4_release_notes.md

@@ -1,5 +1,6 @@
 # Release notes
 
+* [2.1.0](#2-1-0)
 * [2.0.0](#2-0-0)
 * [1.1.0](#1-1-0)
 * [1.0.3](#1-0-3)
@@ -7,6 +8,36 @@
 * [1.0.1](#1-0-1)
 * [1.0.0](#1-0-0)
 
+<a name="2-1-0"></a>
+## 2.1.0
+
+#### Web
+
+* Added PhotoSwipe for image overview (easier to browse through images). [#24](https://github.com/kerberos-io/web/issues/24)
+* Added reboot and shutdown commands. [#23](https://github.com/kerberos-io/web/issues/23)
+* Added logging view to system page. [#20](https://github.com/kerberos-io/web/issues/20)
+* Added labels to check if machinery is running. [#19](https://github.com/kerberos-io/web/issues/19)
+* Added error handling if web interface isn’t working properly. [#2](https://github.com/kerberos-io/web/issues/2)
+* Fixed Heatmap.js fail to load by ad-blocker. [#16](https://github.com/kerberos-io/web/issues/16)
+* Show additional information on the dashboard (streaming is opening or not) there is no data available. [#16](https://github.com/kerberos-io/web/issues/16)
+* Settings page is now visible on mobile (+ changed icon). [#16](https://github.com/kerberos-io/web/issues/16)
+* Fixed sorting of news articles. [#16](https://github.com/kerberos-io/web/issues/16)
+* Removed links to assets in the cloud (.css files). [#16](https://github.com/kerberos-io/web/issues/16)
+
+#### Machinery
+
+* Added configurable streaming port and quality. [#21](https://github.com/kerberos-io/machinery/issues/21)
+* Added new algorithm: Background subtraction. [#35](https://github.com/kerberos-io/machinery/issues/35)
+* Added new heuristic: Counter (for object/people counting). [#28](https://github.com/kerberos-io/machinery/issues/28)
+* Added video capture, which can be used for debugging purposes (replay a video fragment).. [#26](https://github.com/kerberos-io/machinery/issues/26)
+* It’s now possible to mark the images with a timestamp. [#24](https://github.com/kerberos-io/machinery/issues/24)
+* Fixed blocking streaming socket. [#22](https://github.com/kerberos-io/machinery/issues/22)
+
+#### Kios
+
+* Fix removal images if disk is almost full (wrong path was defined). [#1](https://github.com/kerberos-io/kios/issues/1)
+
+
 <a name="2-0-0"></a>
 ## 2.0.0
 

72_machinery/1_introduction.md

@@ -40,7 +40,7 @@ After the algorithm is executed, the expositor will determine, a region, where t
 <a name="heuristic"></a>
 ### Heuristic
 
-When the expositor detected a region where activity was detection, a **heuristic** will evaluate, the current and previous detections. The heuristic is basically some kind of memory which makes decision and tells the machinery if the detection was true or false.
+When the expositor detected a region where activity was detection, a **heuristic** will evaluate, the current and previous detections. The heuristic is basically some kind of memory which makes a decision and tells the machinery if the detection was true or false.
 
 <a name="io"></a>
 ### IO

72_machinery/83_heuristics/2_counter.md

@@ -0,0 +1,88 @@
+# Counter
+
+Counting objects forms the basis for a range of high-tech solutions, including retail analytics, queue management, building management and security applications. By using the counter heuristic **you can count incoming and outgoing objects** (e.g. people). By defining two lines, the counter heuristics can count the incoming (green line) and outgoing (red line) objects.
+
+![Counter heuristic](2_counter-heuristic.png)
+
+The quality of the Counter heuristic depends heavily on the accurancy of the chosen algorithm (Differential, Background subtraction, etc). Therefore **we recommend** to use the **Background Subtraction algorithm** as this is the most accurate one; the algorithm is used for segmentation and it will distinguish background and foreground. 
+
+After the algorithm did its magic, the segmented image is used by the Counter heuristic to calculate some features: the **center of mass** is calculated for each foreground segment, and is stored in memory together with the height and width of the segment. By using the coordinates of the center of mass a trajectory is calculated.
+
+$$ \texttt{mu} \_{ji}= \sum \_{x,y}  \left ( \texttt{array} (x,y)  \cdot (x -  \bar{x} )^j  \cdot (y -  \bar{y} )^i \right ) $$
+
+$$ \bar{x} = \frac{\texttt{m}\_{10}}{\texttt{m}\_{00}} , \; \bar{y} = \frac{\texttt{m}\_{01}}{\texttt{m}\_{00}} $$
+
+![Center of mass](2_counter-heuristic-center-of-mass.png)
+
+While the capture device is taking images, the counter heuristic will calculate the features (as mentioned before) for every subsequent frame. When calculated **the heuristic will search for the best match**: the closest, in terms of distance, center of mass is searched from the previous calculation. When the best match is found the center of mass (with its features) is added to the feature list of the best match; or if not found, a new feature list is created.
+
+
+The idea of the feature list is that it contains the trajectory of an object which is moving from one point to another (a person walking by). A feature list exists for every moving object in the viewport of the camera and each feature list contains the sequence of center of masses (the x- and y-coordinates of the object).
+
+After the center of masses are calculated, existing feature lists are expanded or new feature lists are created (the start of a new object). By using the feature lists, **the direction of the moving objects** can be calculated, as it contains the initial center of mass and the last found center of mass. 
+
+![Trajectory](2_counter-heuristic-trajectory.png)
+
+As we know the trajectory of an object (and thus its direction), the intersection is calculated with the incoming (green line) and outgoing (red line). If the trajectory intersects both incoming and outgoing lines, the direction of the trajectory is used to determine which line was interesected first (and this is an incoming or outgoing object).
+
+## Parameters
+
+The parameters of the Counter heuristic can be found in the **config/heuristic.xml** file, but you can also use the web to modify the parameters. Below you see a default configuration file.
+	
+	<heuristics>
+	    
+		<Counter>
+		    <appearance type="number">5</appearance>
+		    <maxDistance type="number">90</maxDistance>
+		    <minArea type="number">1400</minArea>
+		    <onlyTrueWhenCounted type="bool">true</onlyTrueWhenCounted>
+		    <minimumChanges type="number">20</minimumChanges>
+	        <noMotionDelayTime type="number">1000</noMotionDelayTime>
+			<markers type="twolines">100,100|100,200|200,100|200,200</markers>
+		</Counter>
+
+	</heuristics>
+
+### Appearance
+
+The appearance parameters works as a time-out value. If a feature lists hasn't been updated for x (appearance) times in a row, it's removed. The idea is that when an object has moved outside the viewport of the camera, it can't be tracked anymore.
+
+### Max Distance
+
+While calculating the center of masses, the best match is searched for each one. As the best match is calculated in function of the distance, a maximum distance is used to limit the matching process.
+
+### Min Area
+
+The center of mass is calculated for each segment which has an area which is larger than the minimum area.
+e
+### Only true when counted
+
+By default the heuristic will only return true when one or more objects are marked as incoming or outgoing. However by unchecking this option you can make the heuristic return true when something changed (same behaviour as the sequence heuristic). The idea is that one wants to track the incoming and outgoing objects, but also want to have images for every change.
+
+### Minimum changes
+
+The heuristic will only procede true if enough changes have been detected.
+
+### No motion delay time
+
+When the heuristic is not valid, the heuristic will idle for some time.
+
+### Markers
+
+The start- and en-coordinates of both the incoming and outgoing lines (delimited by the pipe symbol).
+
+## Output
+
+The whole point of the counter heuristic is counting objects. Therefore when one or more incoming or outgoing objects are detected the results are added to the JSON object which is passed along the four passway. The JSON object can be retrieved by using the [**Webhook IO device**](/machinery/Outputs/webhook).
+
+	[
+ 		'regionCoordinates' : [618, 317, 703, 493],
+  		'numberOfChanges' : 5446,
+  		'incoming' : 0,
+  		'outgoing' : 1,
+  		'timestamp' : '1465894497',
+  		'microseconds' : '5-97451',
+  		'token' : 695,
+  		'pathToImage' : '1465894497_5-97451_frontdoor_618-317-703-493_5446_695.jpg',
+  		'instanceName' : 'frontdoor',
+	]

72_machinery/84_Outputs/4_webhook.md

@@ -3,11 +3,6 @@
 Detailed information (a JSON object) is send as a POST request to a webhook. The JSON object contains the number of changes, the region, the URL of the image, etc. 
 
 **Make sure that the Webhook comes after the Disk device, otherwise the URL of the image is not included.**
-
-## Web 
-
-![Webhook io](4_webhook.png)
-
 ## Parameters
 
 The parameters of the webhook can be found in the **config/io.xml** file, but you can also use the web to modify the parameters. Below you see a default configuration file.
@@ -22,4 +17,4 @@ The parameters of the webhook can be found in the **config/io.xml** file, but yo
 
 ### Url
 
-This is the URL, to which Kerberos will send a JSON object (as a POST request).
+This is the URL, to which Kerberos.io will send a JSON object (as a POST request).

72_machinery/90_heuristic.md

@@ -1,13 +1,16 @@
 # Heuristic
 
 * [Sequence](#sequence)
+* [Counter](#counter)
 
-When the expositor detected one or more regions, a heuristic will evaluate, the current and previous evaluations. This step is less loosly coupled as the connection between algorithms and expositors, because it can require specific parameters from the expositor or algorithm.
-
-However, the main convention is that an expositor would always modify a JSON object with minimal information; as explained above, one or more regions and the number of pixels of interest. For flexibility, one can choose to add additional parameters or remove (required) parameters. Therefore it is possible that some expositors can't be used with some heuristics; we strongly disrecommend this feature.
-
-To keep things simple: a heuristic is some kind of memory which makes decision and tells Kerberos if the evaluation was true or false. 
+The heuristic is the last step in the four passway which will decide if the detection is valid or not. It will do this by using information from the previous steps (the expositor and the algorithm); e.g. number of changed pixels.
 
 <a name="sequence"></a>
 ## Sequence
-This is a trivial heuristic. The sequence heuristic returns true if the recognition was positive for x times in a row.
+In most cases motion contains a sequence of events; for example someone who walks by or a car which is parking on the street. The sequence heuristic will measure this by returning true if the recognition was positive for x times in a row. By using this heuristic most of the false-positives (invalid detections) are removed.
+
+<a name="counter"></a>
+## Counter
+Counting objects forms the basis for a range of high-tech solutions, including retail analytics, queue management, building management and security applications. By using this counter heuristic you can count incoming and outgoing objects (e.g. people).
+
+![Counter heuristic](83_heuristics/2_counter-heuristic.png)