first draft of the readme based on the brfv4 readme

README.md

@@ -1,2 +1,201 @@
-# brfv5-browser
-Beyond Reality Face SDK - BRFv5 - Platform: Browser
+# Beyond Reality Face SDK - v5.0.0 (BRFv5) - Platform: Browser
+
+### What is BRFv5?
+
+It is a real-time face detection and face tracking SDK. It analyses image data (eg. a camera stream, video stream or a static image) and returns facial landmarks and data to place 3d objects on a face.
+
+![alt text](images/readme_img.jpg "BRFv5")
+
+### Ready to try!
+
+Read the EULA (eula.txt) carefully before using the SDK. You can try and test the trial SDK free of charge. Before you buy a license, please test the SDK thoroughly to find out whether it fits your project's needs. Once you decide to use BRFv5 commercially, please contact us via email. You will get a separate license agreement, that you must agree to. 
+
++ http://www.tastenkunst.com/#/contact
+
+### Visit us online.
+
++ [Github (all repos)](https://github.com/Tastenkunst)
++ [Demo (platform: browser)](https://tastenkunst.github.io/brfv4_javascript_examples/)
++ [Docs / API](https://tastenkunst.github.io/brfv4_docs/)
++ [What can I do with it?](https://tastenkunst.github.io/brfv4_docs/what_can_i_do_with_it.html)
++ [Website](https://www.beyond-reality-face.com)
++ [Facebook](https://www.facebook.com/BeyondRealityFace)
++ [Twitter](https://twitter.com/tastenkunst)
+
+### Getting started.
+
+To test BRFv5 simply visit the JavaScript demo site:
+
++ https://tastenkunst.github.io/brfv4_javascript_examples/
+
+### Which platforms does it support?
+
+#### HTML5/Browser – JavaScript (works in Chrome/Firefox/Edge/Opera/Safari 11)
+Run the index.html on a local server.
+
+#### iOS - ObjectiveC/C++
+Open the Xcode project. Attach your iOS device and run the example app on your device.
+
+#### Android - Java 
+Open the Android Studio project. Attach your Android device and run the example app on your device.
+
+#### macOS - C++ utilizing OpenCV for camera access and drawing
+Have [OpenCV](http://opencv.org/) brewed (opencv3) on your system. Open the Xcode project and just run it on your Mac.
+
+#### Windows - C++ utilizing OpenCV for camera access and drawing
+Good luck in trying to compile [OpenCV](http://opencv.org/) for your Windows. Update the Visual Studio (2017) project properties that mention 
+OpenCV. Then run the Release x64 target. Fingers crossed!
+
+#### Adobe AIR - Actionscript 3 on Windows, macOS, iOS and Android 
+Use your preferred IDE. Add the src folder and the ANE itself to your class path and run the example class on your 
+desired device (not in a simulator). Unfortunately we had to discontinue Flash Player (SWF in browser) support.
+
+### Technical overview
+
+BRFv4 comes with the following components:
+
++ face detection	- Finds faces (rectangles) in an image/camera stream
++ face tracking		- Finds 68 facial landmarks/features
++ point tracking	- Tracks points in a webcam stream
+
+All available packages have roughly the same content and come with a set of examples to show SDK use cases.
+
+### What image size does BRFv4 need?
+
+You can input any image size.
+
+Internally BRFv4 uses a DYNx480 (landscape) or 480xDYN (portrait) image for the analysis. So 480px is the base size that every other input size gets scaled to, eg.
+
+landscape:
+
++  640 x  480 -> 640 x 480 // fastest, no scaling
++ 1280 x  720 -> 854 x 480
++ 1920 x 1080 -> 854 x 480
+
+portrait:
+
++  480 x  640 -> 480 x 640 // fastest, no scaling
++  720 x 1280 -> 480 x 854
++ 1080 x 1920 -> 480 x 854
+
+BRFv4 scales the results up again, so you don't have to do that yourself.
+All parameters named *size or *width are pixel values based on the actual image size.
+eg. telling BRF what face sizes to initially detect:
+
+```markdown
+brfManager.setFaceDetectionParams(int minFaceSize, int maxFaceSize, int stepSize, int minMergeNeighbors);
+```
+If you work with a 640x480 camera stream, it would be something like this:
+```markdown
+brfManager.setFaceDetectionParams(144, 432, 12, 8);
+```
+Where as if you work with a 1280x720 camera stream, you will need something like this:
+```markdown
+brfManager.setFaceDetectionParams(216, 648, 12, 8);
+```
+In the examples we generalize that a bit:
+```javascript
+// We have either a landscape area (desktop), then choose height or
+// we have a portrait area (mobile), then choose width as max face size.
+
+var maxFaceSize = _faceDetectionRoi.height;
+
+if(_faceDetectionRoi.width < _faceDetectionRoi.height) {
+ maxFaceSize = _faceDetectionRoi.width;
+}
+
+brfManager.setFaceDetectionParams(maxFaceSize * 0.30, maxFaceSize * 0.90, 12, 8);
+```
+More on that in the API, see link above.
+
+### FAQ
+
+Can I track other objects like hands or neck?
++ No, it is tracking faces only.
+
+Can you increase the performance?
++ We could remove some calculations in a commercial version, if you want to, but this comes at the price of reduced accuracy.
+
+Can you make the library smaller?
++ Usually the descriptor would be 80MB and more. It's already only 9MB for most platforms. So: We could go down in 1,5MB steps, but this will also massively decrease accuracy.
+Once you bought a license you can choose which size you want to go with.
+
+### Release notes
+
+v4.1.0 - 11th July 2018
+
++ All: Changed 3D calculation model a bit. This might result in slightly different placement and rotationX.
++ Info: We started to work on BRFv5 (yeha!)
+
+v4.0.1 - 09th November 2017
+
++ JS: Added: WASM export to JavaScript SDK.
++ JS: Fix: Found a workaround for iOS 11 (in Safari) for starting the camera.
++ JS: Updated: CreateJS to v1.0.2 (easel) and v1.0.1 (preload).
++ JS: Updated: ThreeJS to r88.
++ Minor cleanups
++ Known issue: JS SDK is slow in Chrome 63 because of this bug: https://bugs.chromium.org/p/chromium/issues/detail?id=768775
+
+v4.0.0 - 20th June 2017
+
+It's done! After over a year of development Tastenkunst is proud to announce the release of BRFv4.
+
++ Changed: Completely rewritten the C++ core: image handling, face detection and tracking algorithms etc.
++ Changed: Image data can now be of any site. BRFv4 will handle the scaling internally.
++ Changed: Point tracking and face tracking can now be done simultaneously.
++ Changed: Face tracking algorithm changed from ASM to ERT. This comes with an increased file size though (For JS up from 2MB to 10MB)
++ Added: Multi face tracking. It is now possible to track more than one face.
++ Added: Example project for native Android (Java, Android Studio project)
++ Added: Example project for macOS (C++, Xcode project, needs brewed OpenCV for camera handling and drawing)
++ Added: Example project for Windows (C++, Visual Studio 2017 project, needs OpenCV for camera handling and drawing)
++ Added: Adobe AIR native extension now supports Windows, macOS, iOS and Android.
++ Removed: Support for Flash Player (SWF in Browser).
+
+### Licenses
+
+Used Haar Cascade: haarcascade_frontalface_default.xml
+```
+<!--
+    Stump-based 24x24 discrete(?) adaboost frontal face detector.
+    Created by Rainer Lienhart.
+
+////////////////////////////////////////////////////////////////////////////////////////
+
+  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+
+  By downloading, copying, installing or using the software you agree to this license.
+  If you do not agree to this license, do not download, install,
+  copy or use the software.
+
+
+                        Intel License Agreement
+                For Open Source Computer Vision Library
+
+ Copyright (C) 2000, Intel Corporation, all rights reserved.
+ Third party copyrights are property of their respective owners.
+
+ Redistribution and use in source and binary forms, with or without modification,
+ are permitted provided that the following conditions are met:
+
+   * Redistribution's of source code must retain the above copyright notice,
+     this list of conditions and the following disclaimer.
+
+   * Redistribution's in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+
+   * The name of Intel Corporation may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+ This software is provided by the copyright holders and contributors "as is" and
+ any express or implied warranties, including, but not limited to, the implied
+ warranties of merchantability and fitness for a particular purpose are disclaimed.
+ In no event shall the Intel Corporation or contributors be liable for any direct,
+ indirect, incidental, special, exemplary, or consequential damages
+ (including, but not limited to, procurement of substitute goods or services;
+ loss of use, data, or profits; or business interruption) however caused
+ and on any theory of liability, whether in contract, strict liability,
+ or tort (including negligence or otherwise) arising in any way out of
+ the use of this software, even if advised of the possibility of such damage.
+-->
+```

eula.txt

@@ -0,0 +1,76 @@
+EULA.
+End User License Agreement.
+
+See below our terms for the trial license. For commercial licenses we will provide a different agreement.
+
+END-USER LICENSE AGREEMENT FOR "Beyond Reality Face SDK - trial version"
+IMPORTANT PLEASE READ THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT CAREFULLY BEFORE CONTINUING 
+WITH THIS DOWNLOAD: Tastenkunst End-User License Agreement ("EULA") is a legal agreement between you 
+(either an individual or a single entity) and Tastenkunst for the Tastenkunst software product(s) 
+identified above which may include associated software components, media, printed materials, and 
+"online" or electronic documentation ("SOFTWARE PRODUCT"). By downloading, copying, or otherwise 
+using the SOFTWARE PRODUCT, you agree to be bound by the terms of this EULA. This license agreement 
+represents the entire agreement concerning the program between you and Tastenkunst, (referred to as 
+"licensor"), and it supersedes any prior proposal, representation, or understanding between the parties.
+If you do not agree to the terms of this EULA, do not download or use the SOFTWARE PRODUCT. The 
+SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as other 
+intellectual property laws and treaties. The SOFTWARE PRODUCT is licensed, not sold.
+
+1. GRANT OF LICENSE.
+The SOFTWARE PRODUCT is licensed as follows:
+
+(a) Download and Use.
+Tastenkunst grants you the right to download and use copies of the SOFTWARE PRODUCT on your computer.
+
+(b) Backup Copies.
+You may also make copies of the SOFTWARE PRODUCT as may be necessary for backup and archival purposes.
+
+2. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS.
+(a) Maintenance of Copyright Notices. You must not remove or alter any copyright notices on any and 
+all copies of the SOFTWARE PRODUCT.
+(b) Distribution. You may not distribute registered copies of the SOFTWARE PRODUCT to third parties.
+Evaluation versions available for download from Tastenkunst's websites or Tastenkunst's GitHub
+repositories may be freely distributed.
+(c) Prohibition on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer,
+decompile, or disassemble the SOFTWARE PRODUCT, except and only to the extent that such activity is
+expressly permitted by applicable law notwithstanding this limitation.
+(d) Rental. You may not rent, lease, or lend the SOFTWARE PRODUCT.
+(e) Support Services. Tastenkunst may provide you with support services related to the SOFTWARE PRODUCT
+("Support Services"). Any supplemental software code provided to you as part of the Support Services shall be
+considered part of the SOFTWARE PRODUCT and subject to the terms and conditions of this EULA.
+(f) Compliance with Applicable Laws. You must comply with all applicable laws regarding use of the SOFTWARE PRODUCT.
+
+3. TERMINATION
+Without prejudice to any other rights, Tastenkunst may terminate this EULA if you fail to comply 
+with the terms and conditions of this EULA. In such event, you must destroy all copies of the 
+SOFTWARE PRODUCT in your possession.
+
+4. COPYRIGHT
+All title, including but not limited to copyrights, in and to the SOFTWARE PRODUCT and any copies 
+thereof are owned by Tastenkunst or its suppliers. All title and intellectual property rights in 
+and to the content which may be accessed through use of the SOFTWARE PRODUCT is the property of 
+the respective content owner and may be protected by applicable copyright or other intellectual 
+property laws and treaties. This EULA grants you no rights to use such content. All rights not 
+expressly granted are reserved by Tastenkunst.
+
+5. NO WARRANTIES
+Tastenkunst expressly disclaims any warranty for the SOFTWARE PRODUCT. The SOFTWARE PRODUCT is 
+provided 'As Is' without any express or implied warranty of any kind, including but not limited 
+to any warranties of merchantability, noninfringement, or fitness of a particular purpose. 
+Tastenkunst does not warrant or assume responsibility for the accuracy or completeness of any 
+information, text, graphics, links or other items contained within the SOFTWARE PRODUCT. Tastenkunst 
+makes no warranties respecting any harm that may be caused by the transmission of a computer 
+virus, worm, time bomb, logic bomb, or other such computer program. Tastenkunst further expressly 
+disclaims any warranty or representation to Authorized Users or to any third party.
+
+6. LIMITATION OF LIABILITY
+In no event shall Tastenkunst be liable for any damages (including, without limitation, lost 
+profits, business interruption, or lost information) rising out of 'Authorized Users' use of 
+or inability to use the SOFTWARE PRODUCT, even if Tastenkunst has been advised of the possibility 
+of such damages. In no event will Tastenkunst be liable for loss of data or for indirect, special, 
+incidental, consequential (including lost profit), or other damages based in contract, tort or 
+otherwise. Tastenkunst shall have no liability with respect to the content of the SOFTWARE PRODUCT 
+or any part thereof, including but not limited to errors or omissions contained therein, libel, 
+infringements of rights of publicity, privacy, trademark rights, business interruption, personal 
+injury, loss of privacy, moral rights or the disclosure of confidential information.
+