Skip to content
Permalink
Browse files

first draft of the readme based on the brfv4 readme

  • Loading branch information
Marcel Klammer
Marcel Klammer committed Jun 18, 2019
1 parent 46d85d6 commit d3911973afb133eddfa31d6fc083ecb63d0d1887
Showing with 277 additions and 2 deletions.
  1. +201 −2 README.md
  2. +76 −0 eula.txt
  3. BIN images/readme_img.jpg
203 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.
-->
```
@@ -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.

BIN +418 KB images/readme_img.jpg
Binary file not shown.

0 comments on commit d391197

Please sign in to comment.
You can’t perform that action at this time.