Skip to content

Commit 1257450

Browse files
M-Talha4M-Talha4
committed
Update openFaceCamera documentation and add Ensemble Kitchen Sink Link
1 parent a8c884f commit 1257450

4 files changed

Lines changed: 32 additions & 187 deletions

File tree

‎content/actions/directory.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ When an event is triggered (e.g. button is tapped), you can perform actions such
2828
| Property | Description |
2929
| :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
3030
| [openCamera](open-camera.md) | openCamera action allows users to access their device's camera within the app for capturing images and videos. |
31-
| [openFaceCamera](open-face-camera.md) | openFaceCamera action provides face-aware capture with alignment guidance and optional auto-capture for selfie and verification flows. |
31+
| [openFaceCamera](open-face-camera.md) | openFaceCamera action provides a camera plugin that detects face in real-time. flows. |
3232
| [getLocation](get-location.md) | getLocation action retrieves the device's current location, enabling location-based functionalities within the app. |
3333
| [requestNotificationAccess](request-notification-access.md) | requestNotificationAccess action prompts users to grant permission for the app to send notifications to their device. |
3434
| [showNotification](show-notification.md) | showNotification action displays local notifications within the app, notifying users of important events or information. |

‎content/actions/open-camera.md‎

Lines changed: 0 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@
3737
| assistSpeed | object | Show assist message whenever camera is moving faster than maxSpeed. [see properties](#values-for-optionsassistspeed) |
3838
| autoCaptureInterval | integer | If set any number n, on each n interval camera will capture |
3939
| captureOverlay | boolean | If set picture will be cropped according to overlay widget |
40-
| faceDetection | object | Enable face detection. [see properties](#values-for-optionsfacedetection) |
4140

4241
##### Values for options.assistAngle
4342

@@ -54,52 +53,8 @@
5453
| maxSpeed | number | Maximum speed in km/hr. |
5554
| assistSpeedMessage | number | Custom message to show when condition is hit. |
5655

57-
##### Values for options.faceDetection
58-
59-
| Property | Type | Description |
60-
| :------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
61-
| enabled | boolean | Enable face detection. |
62-
| message | string | use this pass a message above the camera |
63-
| messageStyle | object | style applied to the message widget |
64-
| showControls | boolean | set false to hide all controls |
65-
| showCaptureControl | boolean | set false to hide capture control icon |
66-
| showFlashControl | boolean | set false to hide flash control control icon |
67-
| showCameraLensControl | boolean | set false to hide camera lens control icon |
68-
| indicatorShape | string | use this to change the shape of the face indicator `circle`, `square` |
69-
| autoDisableCaptureControl | boolean | set true to disable capture control widget when no face is detected |
70-
| autoCapture | boolean | set true to capture image on face detected |
71-
| imageResolution | string | use this to set image resolution `low`, `medium`, `high` |
72-
| defaultFlashMode | string | use this to set initial flash mode `off`, `auto`, `always` |
73-
| performanceMode | string | Use this to set your preferred performance mode. `accurate`, `fast` |
74-
| accuracyConfig | object | Use this to set accuracy config for face detection. Accuracy config is only supported on web. [see properties](#values-for-optionsfacedetectionaccuracyconfig) |
75-
76-
##### Values for options.faceDetection.accuracyConfig
77-
78-
> [Note]
79-
> Accuracy config is only supported on web.
80-
81-
| Property | Type | Description |
82-
| :------------------------- | :----- | :--------------------------------------------------------------------------- |
83-
| detectionThreshold | number | Minimum confidence score required to consider a face detection valid. |
84-
| intersectionRatioThreshold | number | Minimum allowed overlap ratio between the detected face and expected region. |
85-
| extraHeightFactor | number | Additional height factor added to the face bounding box. |
86-
| inputSize | number | Size of the input image used for face detection. |
87-
| landmarkRatio | number | Minimum acceptable alignment accuracy for facial landmarks. |
88-
| frameMargin | number | Margin ratio to ensure face is not too close to frame edges. |
89-
| tiltAngleThreshold | number | Maximum allowed tilt angle of the detected face (in degrees). |
90-
| horizontalCenterTolerance | number | Allowed tolerance for how centered the face must be horizontally. |
91-
| earThreshold | number | Minimum Eye Aspect Ratio (EAR) to detect open eyes. |
92-
| minFaceWidthRatio | number | Minimum ratio of face width relative to the frame. |
93-
| maxFaceWidthRatio | number | Maximum ratio of face width relative to the frame. |
94-
| qualityPassThreshold | number | Minimum quality score required for a face to pass detection. |
95-
| yawLowerThreshold | number | Lower bound of acceptable yaw (left-right head rotation) ratio. |
96-
| yawUpperThreshold | number | Upper bound of acceptable yaw (left-right head rotation) ratio. |
97-
98-
9956
**Usage Examples**
10057

101-
102-
10358
```yaml
10459
View:
10560
header:
@@ -273,55 +228,4 @@ You can clear previous camera results while recapturing using `cameraId.clear()`
273228
id: captureLatest
274229
```
275230

276-
Capture image on face detected
277-
278-
```yaml
279-
- Button:
280-
label: Open Camera
281-
onTap:
282-
openCamera:
283-
id: cameraWithFaceDetection
284-
options:
285-
initialCamera: front
286-
faceDetection:
287-
enabled: true
288-
autoCapture: false
289-
performanceMode: accurate
290-
accuracyConfig: # accuracyConfig is only supported on web
291-
detectionThreshold: 0.5
292-
intersectionRatioThreshold: 0.9
293-
extraHeightFactor: 0.6
294-
inputSize: 224
295-
landmarkRatio: 0.95
296-
frameMargin: 0.05
297-
tiltAngleThreshold: 6
298-
horizontalCenterTolerance: 0.08
299-
earThreshold: 0.25
300-
minFaceWidthRatio: 0.18
301-
maxFaceWidthRatio: 0.82
302-
qualityPassThreshold: 0.8
303-
yawLowerThreshold: 0.85
304-
yawUpperThreshold: 1.15
305-
message: "Align your face in the square"
306-
messageStyle:
307-
color: "#FF0000"
308-
fontSize: 20
309-
onCapture:
310-
uploadFiles:
311-
id: uploader
312-
files: ${cameraWithFaceDetection.files[0]}
313-
uploadApi: fileUploadApi
314-
fieldName: file
315-
onComplete:
316-
showDialog:
317-
body:
318-
Column:
319-
children:
320-
- TextInput:
321-
value: ${cameraWithFaceDetection.files[0]}
322-
- Image:
323-
source: ${cameraWithFaceDetection.files[0].path}
324-
```
325-
326-
327231
To learn more about openCamera functionalities, test it out here in [Ensemble Kitchen Sink](https://studio.ensembleui.com/app/e24402cb-75e2-404c-866c-29e6c3dd7992/screen/USuOaOZApSgzE2uVrqlv) app.

‎content/actions/open-face-camera.md‎

Lines changed: 8 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,15 @@
11
# openFaceCamera
22

3-
## Overview
3+
`openFaceCamera` action opens the device camera with real-time face detection. It automatically captures an image when the face is properly aligned (position, angle, etc.), making it ideal for selfies, profile photos, or any face-detection task on mobile and web. Use the `id` property to bind the captured image result (e.g. to a variable or data binding).
44

5-
The `ensemble_face_camera` module adds real-time face detection to the Ensemble framework.
6-
It is extracted from the original `ensemble_camera` package and focused on face-based capture workflows across Mobile and Web.
5+
### Setup in Ensemble Studio
76

8-
## What It Does
7+
1. Go to https://studio.ensembleui.com/
8+
2. Open your app
9+
3. From the left sidebar, click **Build & Deploy**
10+
4. In the **Build Settings** tab, enable the **Face Camera** module/feature and update.
11+
5. If building for iOS: switch to the **iOS** tab and add the required camera usage description (e.g. "We use the camera to capture your face for verification") and any face-related privacy descriptions
912

10-
- Real-time face detection on Mobile and Web
11-
- Auto-capture when alignment conditions are met
12-
- Configurable detection options (yaw, tilt, thresholds, performance mode)
13-
- Seamless integration with Ensemble via `openFaceCamera`
14-
- Direct Flutter widget support
15-
16-
## Installation
17-
18-
Add this to `pubspec.yaml`:
19-
20-
```yaml
21-
dependencies:
22-
ensemble_face_camera:
23-
git:
24-
url: https://github.com/EnsembleUI/ensemble.git
25-
ref: main
26-
path: modules/face_camera
27-
```
28-
29-
## Required Setup
30-
31-
Register the manager during app initialization:
32-
33-
```dart
34-
import 'package:ensemble_face_camera/ensemble_face_camera.dart';
35-
36-
GetIt.I.registerSingleton<FaceCameraManager>(
37-
FaceCameraManagerImpl(),
38-
);
39-
```
40-
41-
Without this registration, the `openFaceCamera` action will not work.
42-
43-
## Action
44-
45-
Use `openFaceCamera` in YAML.
4613

4714
### Properties
4815

@@ -243,3 +210,4 @@ Use strict face detection thresholds for web capture.
243210
message: "Error capturing image: ${event.error}"
244211
```
245212
213+
To learn more about openCamera functionalities, test it out here in [Ensemble Kitchen Sink](https://studio.ensembleui.com/app/e24402cb-75e2-404c-866c-29e6c3dd7992/screen/iLJkHUPgX3ii9EdQ1D8K) app.

‎content/device-capabilities/open-face-camera.md‎

Lines changed: 23 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,54 @@
11
# openFaceCamera
22

3-
Use `openFaceCamera` when you need face-aware capture (for example selfie verification, identity checks, or attendance) instead of generic photo capture.
3+
Use `openFaceCamera` when you need **real-time** face detection — such as selfies, profile photos etc — instead of plain camera access.
44

5-
`openFaceCamera` provides guided framing, face validation, and optional auto-capture once the face qualifies.
5+
It adds face detection, alignment guidance (framing overlay), status messages, and optional **auto-capture** when the face meets quality criteria.
66

7-
## When to use this instead of openCamera
7+
### When to use this instead of `openCamera`
88

9-
- You need face alignment guidance before capture.
10-
- You need automatic capture when a valid face is detected.
11-
- You need stricter face quality checks, especially on web via `accuracyConfig`.
9+
- You want visual guidance to center and align the face before capture
10+
- You need automatic capture once a valid face is detected
11+
- You want stricter face quality rules (especially on web with `accuracyConfig`)
1212

13-
For generic photo/video capture or gallery-first flows, continue using [`openCamera`](/device-capabilities/open-camera).
13+
### Key Properties
1414

15-
## Properties
15+
| Property | Type | Description |
16+
|------------|--------|-----------------------------------------------------------------------------|
17+
| id | string | Bind captured result (access via `${yourId.files}`) |
18+
| onCapture | action | Runs after successful capture (`event.data.files` available) |
19+
| onError | action | Handles errors (`event.error` available) |
20+
| options | object | Controls camera lens, UI, auto-capture, resolution, flash, and detection |
1621

17-
| Property | Type | Description |
18-
| :-------- | :----- | :------------------------------------------------------------------------------ |
19-
| id | string | Camera ID used to bind captured results (for example `${myFaceCamera.files}`). |
20-
| onCapture | action | Executes when an image is captured. Files are available in `event.data.files`. |
21-
| onError | action | Executes on error. Error message is available via `event.error`. |
22-
| options | object | Face camera and detection configuration. |
22+
### Quick Examples
2323

24-
## options
25-
26-
| Property | Type | Description |
27-
| :------------------------ | :------ | :------------------------------------------------------------------------------ |
28-
| initialCamera | string | Which lens to start with: `front` (default), `back` |
29-
| message | string | Message shown above camera preview |
30-
| messageStyle | object | Text style for `message` |
31-
| showControls | boolean | Show/hide all camera controls. Default `true` |
32-
| showCaptureControl | boolean | Show/hide capture button. Default `true` |
33-
| showFlashControl | boolean | Show/hide flash control. Default `true` |
34-
| showCameraLensControl | boolean | Show/hide camera switch control. Default `true` |
35-
| showStatusMessage | boolean | Show/hide face detection status text. Default `true` |
36-
| indicatorShape | string | Face indicator shape: `circle`, `square` |
37-
| autoDisableCaptureControl | boolean | Disable capture while no valid face is detected. Default `false` |
38-
| autoCapture | boolean | Automatically capture when face qualifies. Default `false` |
39-
| imageResolution | string | Capture resolution: `low`, `medium`, `high`, `veryHigh`, `ultraHigh`, `max` |
40-
| defaultFlashMode | string | Initial flash mode: `off` (default), `auto`, `always` |
41-
| orientation | string | Camera orientation: `portraitUp`, `portraitDown`, `landscapeLeft`, `landscapeRight` |
42-
| performanceMode | string | Face detector mode: `fast` (default), `accurate` |
43-
| accuracyConfig | object | Fine-grained face detection thresholds. Web only. |
44-
45-
## Usage
46-
47-
### Basic
24+
**Basic face capture**
4825

4926
```yaml
5027
- Button:
5128
label: Open Face Camera
5229
onTap:
5330
openFaceCamera:
54-
id: myFaceCamera
31+
id: myFace
5532
```
56-
57-
### Auto-capture
33+
**Auto-capture verified selfie**
5834
5935
```yaml
6036
- Button:
61-
label: Capture verified selfie
37+
label: Capture Verified Selfie
6238
onTap:
6339
openFaceCamera:
6440
id: profilePhoto
6541
options:
6642
initialCamera: front
6743
autoCapture: true
44+
message: "Align your face in the frame"
6845
performanceMode: accurate
69-
message: "Align your face"
7046
onCapture:
71-
executeCode:
72-
body: |
73-
console.log('Captured face image: ' + profilePhoto.files[0].path);
47+
showToast:
48+
message: "Selfie captured!"
7449
onError:
7550
showToast:
76-
message: "Error capturing image: ${event.error}"
51+
message: "Capture failed: ${event.error}"
7752
```
7853
79-
## Full Reference
80-
81-
For complete module setup, advanced `accuracyConfig` fields, and more examples, see [`openFaceCamera` action docs](/actions/open-face-camera).
54+
To learn more about openCamera functionalities, test it out here in [Ensemble Kitchen Sink](https://studio.ensembleui.com/app/e24402cb-75e2-404c-866c-29e6c3dd7992/screen/iLJkHUPgX3ii9EdQ1D8K) app.

0 commit comments

Comments
 (0)