Merge branch 'dbscan' of https://github.com/asvsfs/ml5-library into dbscan

Author: asvsfs

.all-contributorsrc

@@ -1163,6 +1163,15 @@
         "code",
         "ideas"
       ]
+    },
+    {
+      "login": "RaglandCodes",
+      "name": "Ragland Asir",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/39048764?v=4",
+      "profile": "http://raglandcodes.github.io",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -248,6 +248,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
   </tr>
   <tr>
     <td align="center"><a href="https://daleonai.com"><img src="https://avatars1.githubusercontent.com/u/2328571?v=4" width="100px;" alt=""/><br /><sub><b>Dale Markowitz</b></sub></a><br /><a href="https://github.com/ml5js/ml5-library/commits?author=dalequark" title="Code">💻</a> <a href="#ideas-dalequark" title="Ideas, Planning, & Feedback">🤔</a></td>
+    <td align="center"><a href="http://raglandcodes.github.io"><img src="https://avatars3.githubusercontent.com/u/39048764?v=4" width="100px;" alt=""/><br /><sub><b>Ragland Asir</b></sub></a><br /><a href="https://github.com/ml5js/ml5-library/commits?author=RaglandCodes" title="Documentation">📖</a></td>
   </tr>
 </table>
 

docs/_media/reference__header-facemesh.jpg

@@ -38,6 +38,7 @@
     * [PoseNet](/reference/posenet.md)
     * [BodyPix](/reference/bodypix.md)
     * [UNET](/reference/unet.md)
+    * [Facemesh](/reference/facemesh.md)
     * [FaceApi](/reference/face-api.md)
     * [StyleTransfer](/reference/style-transfer.md)
     * [pix2pix](/reference/pix2pix.md)

docs/_sidebar.md

@@ -0,0 +1,186 @@
+# Facemesh
+
+
+<center>
+    <img style="display:block; max-height:20rem" alt="A screenshot of a video video feed where a person sits at their chair inside of a bedroom while green dots are drawn over different locations on their face." src="_media/reference__header-facemesh.jpg">
+</center>
+
+
+## Description
+
+Facemesh is a machine-learning model that allows for facial landmark detection in the browser. It can detect multiple faces at once and provides 486 3D facial landmarks that describe the geometry of each face. Facemesh works best when the faces in view take up a large percentage of the image or video frame and it may struggle with small/distant faces.
+
+The ml5.js Facemesh model is ported from the [TensorFlow.js Handpose implementation](https://github.com/tensorflow/tfjs-models/tree/master/facemesh#keypoints).
+
+## Quickstart
+
+```js
+let predictions = [];
+const video = document.getElementById('video');
+
+// Create a new facemesh method
+const facemesh = ml5.facemesh(video, modelLoaded);
+
+// When the model is loaded
+function modelLoaded() {
+  console.log('Model Loaded!');
+}
+
+// Listen to new 'predict' events
+facemesh.on('predict', results => {
+  predictions = results;
+});
+```
+
+
+## Usage
+
+### Initialize
+You can initialize ml5.facemesh with an optional `video`, configuration `options` object, or a `callback` function.
+```js
+const facemesh = ml5.facemesh(?video, ?options, ?callback);
+```
+
+#### Parameters
+* **video**: OPTIONAL. Optional HTMLVideoElement input to run predictions on.
+* **options**: OPTIONAL. A object that contains properties that effect the Facemesh model accuracy, results, etc. See documentation on the available options in [TensorFlow's Facemesh documentation](https://github.com/tensorflow/tfjs-models/tree/master/facemesh#parameters-for-facemeshload).
+  ```js
+  const options = {
+  flipHorizontal: false, // boolean value for if the video should be flipped, defaults to false
+  maxContinuousChecks: 5, // How many frames to go without running the bounding box detector. Only relevant if maxFaces > 1. Defaults to 5.
+  detectionConfidence: 0.9, // Threshold for discarding a prediction. Defaults to 0.9.
+  maxFaces: 10, // The maximum number of faces detected in the input. Should be set to the minimum number for performance. Defaults to 10.
+  iouThreshold: 0.3, // A float representing the threshold for deciding whether boxes overlap too much in non-maximum suppression. Must be between [0, 1]. Defaults to 0.3.
+  scoreThreshold: 0.75, // defaults to 0.75
+  }
+  ```
+
+* **callback**: OPTIONAL. A function that is called once the model has loaded.
+
+### Properties
+***
+#### .video
+> *Object*. HTMLVideoElement if given in the constructor. Otherwise it is null.
+***
+
+***
+#### .config
+> *Object*. containing all of the configuration options passed into the model. 
+***
+
+***
+#### .model
+> *Object*. The bodyPix model.
+***
+
+***
+#### .modelReady
+> *Boolean*. Truthy value indicating the model has loaded.
+***
+
+### Methods
+
+***
+#### .predict()
+> A function that returns the results of a single face detection prediction.
+
+  ```js
+  facemesh.predict(inputMedia, callback);
+  ```
+
+📥 **Inputs**
+* **inputMedia**: REQUIRED. An HMTL or p5.js image, video, or canvas element that you'd like to run a single prediction on.
+
+* **callback**: OPTIONAL.  A callback function to handle new face detection predictions. For example:
+
+  ```js
+  facemesh.predict(inputMedia, results => {
+    // do something with the results
+    console.log(results);
+  });
+  ```
+
+📤 **Outputs**
+
+* **Array**: Returns an array of objects describing each detected face. See the [Facemesh keypoints map](https://github.com/tensorflow/tfjs-models/tree/master/facemesh#keypoints) to determine how the keypoint related to facial landmarks.
+
+  ```js
+  [
+      {
+          faceInViewConfidence: 1, // The probability of a face being present.
+          boundingBox: { // The bounding box surrounding the face.
+              topLeft: [232.28, 145.26],
+              bottomRight: [449.75, 308.36],
+          },
+          mesh: [ // The 3D coordinates of each facial landmark.
+              [92.07, 119.49, -17.54],
+              [91.97, 102.52, -30.54],
+              ...
+          ],
+          scaledMesh: [ // The 3D coordinates of each facial landmark, normalized.
+              [322.32, 297.58, -17.54],
+              [322.18, 263.95, -30.54]
+          ],
+          annotations: { // Semantic groupings of the `scaledMesh` coordinates.
+              silhouette: [
+              [326.19, 124.72, -3.82],
+              [351.06, 126.30, -3.00],
+              ...
+              ],
+              ...
+          }
+      }
+  ]
+  ```
+
+***
+
+#### .on('predict', ...)
+> An event listener that returns the results when a new face detection prediction occurs.
+
+  ```js
+  facemesh.on('predict', callback);
+  ```
+
+📥 **Inputs**
+
+* **callback**: REQUIRED.  A callback function to handle new face detection predictions. For example:
+
+  ```js
+  facemesh.on('predict', results => {
+    // do something with the results
+    console.log(results);
+  });
+  ```
+
+📤 **Outputs**
+
+* **Array**: Returns an array of objects describing each detected face as an array of objects exactly like the output of the `.predict()` method described above. See the [Facemesh keypoints map](https://github.com/tensorflow/tfjs-models/tree/master/facemesh#keypoints) to determine how the keypoint related to facial landmarks.
+
+
+## Examples
+
+**p5.js**
+* [Facemesh_Image](https://github.com/ml5js/ml5-library/tree/development/examples/p5js/Facemesh/Facemesh_Image)
+* [Facemesh_Webcam](https://github.com/ml5js/ml5-library/tree/development/examples/p5js/Facemesh/Facemesh_Webcam)
+
+**p5 web editor**
+* [Facemesh_Image](https://editor.p5js.org/ml5/sketches/Facemesh_Image)
+* [Facemesh_Webcam](https://editor.p5js.org/ml5/sketches/Facemesh_Webcam)
+
+## Demo
+
+No demos yet - contribute one today!
+
+## Tutorials
+
+No tutorials yet - contribute one today!
+
+## Acknowledgements
+
+**Contributors**:
+  * Ported to ml5.js by [Bomani Oseni McClendon](https://bomani.xyz/).
+
+## Source Code
+
+* [/src/Facemesh](https://github.com/ml5js/ml5-library/tree/development/src/Facemesh)

docs/reference/facemesh.md

@@ -0,0 +1,13 @@
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Handpose with Webcam</title>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/p5.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/addons/p5.dom.min.js"></script>
+    <script src="http://localhost:8080/ml5.js" type="text/javascript"></script>
+  </head>
+  <body>
+    <h1>Handpose with single image</h1>
+    <script src="sketch.js"></script>
+  </body>
+</html>

examples/p5js/Handpose/Handpose_Image/data/hand.jpg

@@ -0,0 +1,54 @@
+let handpose;
+let predictions = [];
+let img;
+
+// load the image before the main program starts
+function preload(){
+  img = loadImage("data/hand.jpg");
+}
+
+function setup() {
+  // Create a canvas that's at least the size of the image.
+  createCanvas(400, 350);
+  // call modelReady() when it is loaded
+  handpose = ml5.handpose(modelReady);
+
+  frameRate(1); // set the frameRate to 1 since we don't need it to be running quickly in this case
+}
+
+// when poseNet is ready, do the detection
+function modelReady() {
+  console.log("Model ready!");
+  
+  // when the predict function is called, tell 
+  // handpose what to do with the results.
+  // in this case we assign the results to our global
+  // predictions variable
+  handpose.on("predict", results => {
+    predictions = results;
+  });
+
+  handpose.predict(img);
+}
+
+// draw() will not show anything until poses are found
+function draw() {
+  if (predictions.length > 0) {
+    image(img, 0, 0, width, height);
+    drawKeypoints();
+    noLoop(); // stop looping when the poses are estimated
+  }
+}
+
+// A function to draw ellipses over the detected keypoints
+function drawKeypoints() {
+  for (let i = 0; i < predictions.length; i += 1) {
+    const prediction = predictions[i];
+    for (let j = 0; j < prediction.landmarks.length; j += 1) {
+      const keypoint = prediction.landmarks[j];
+      fill(0, 255, 0);
+      noStroke();
+      ellipse(keypoint[0], keypoint[1], 10, 10);
+    }
+  }
+}

examples/p5js/Handpose/Handpose_Image/index.html

@@ -1,19 +1,13 @@
 <html>
-
-<head>
-  <meta charset="UTF-8">
-  <title>Handpose with Webcam</title>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/p5.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/addons/p5.dom.min.js"></script>
-  <script src="http://localhost:8080/ml5.js" type="text/javascript"></script>
-
-  <style></style>
-</head>
-
-<script src="sketch.js"></script>
-
-<body>
+  <head>
+    <meta charset="UTF-8" />
+    <title>Handpose with Webcam</title>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/p5.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/0.9.0/addons/p5.dom.min.js"></script>
+    <script src="http://localhost:8080/ml5.js" type="text/javascript"></script>
+  </head>
+  <body>
     <h1>Handpose with Webcam</h1>
-</body>
-
-</html>
+    <script src="sketch.js"></script>
+  </body>
+</html>