Skip to content

Commit 6210e9a

Browse files
actions-useractions-user
committed
Update merged docs via GitHub Action
1 parent d2caaa7 commit 6210e9a

2 files changed

Lines changed: 66 additions & 374 deletions

File tree

‎README.md‎

Lines changed: 33 additions & 187 deletions
Original file line numberDiff line numberDiff line change
@@ -11873,7 +11873,7 @@ When an event is triggered (e.g. button is tapped), you can perform actions such
1187311873
| Property | Description |
1187411874
| :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1187511875
| [openCamera](open-camera.md) | openCamera action allows users to access their device's camera within the app for capturing images and videos. |
11876-
| [openFaceCamera](open-face-camera.md) | openFaceCamera action provides face-aware capture with alignment guidance and optional auto-capture for selfie and verification flows. |
11876+
| [openFaceCamera](open-face-camera.md) | openFaceCamera action provides a camera plugin that detects face in real-time. flows. |
1187711877
| [getLocation](get-location.md) | getLocation action retrieves the device's current location, enabling location-based functionalities within the app. |
1187811878
| [requestNotificationAccess](request-notification-access.md) | requestNotificationAccess action prompts users to grant permission for the app to send notifications to their device. |
1187911879
| [showNotification](show-notification.md) | showNotification action displays local notifications within the app, notifying users of important events or information. |
@@ -13865,7 +13865,6 @@ Applicable on iOS/Android only. Opens the app settings page where the user can m
1386513865
| assistSpeed | object | Show assist message whenever camera is moving faster than maxSpeed. [see properties](#values-for-optionsassistspeed) |
1386613866
| autoCaptureInterval | integer | If set any number n, on each n interval camera will capture |
1386713867
| captureOverlay | boolean | If set picture will be cropped according to overlay widget |
13868-
| faceDetection | object | Enable face detection. [see properties](#values-for-optionsfacedetection) |
1386913868

1387013869
##### Values for options.assistAngle
1387113870

@@ -13882,52 +13881,8 @@ Applicable on iOS/Android only. Opens the app settings page where the user can m
1388213881
| maxSpeed | number | Maximum speed in km/hr. |
1388313882
| assistSpeedMessage | number | Custom message to show when condition is hit. |
1388413883

13885-
##### Values for options.faceDetection
13886-
13887-
| Property | Type | Description |
13888-
| :------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
13889-
| enabled | boolean | Enable face detection. |
13890-
| message | string | use this pass a message above the camera |
13891-
| messageStyle | object | style applied to the message widget |
13892-
| showControls | boolean | set false to hide all controls |
13893-
| showCaptureControl | boolean | set false to hide capture control icon |
13894-
| showFlashControl | boolean | set false to hide flash control control icon |
13895-
| showCameraLensControl | boolean | set false to hide camera lens control icon |
13896-
| indicatorShape | string | use this to change the shape of the face indicator `circle`, `square` |
13897-
| autoDisableCaptureControl | boolean | set true to disable capture control widget when no face is detected |
13898-
| autoCapture | boolean | set true to capture image on face detected |
13899-
| imageResolution | string | use this to set image resolution `low`, `medium`, `high` |
13900-
| defaultFlashMode | string | use this to set initial flash mode `off`, `auto`, `always` |
13901-
| performanceMode | string | Use this to set your preferred performance mode. `accurate`, `fast` |
13902-
| accuracyConfig | object | Use this to set accuracy config for face detection. Accuracy config is only supported on web. [see properties](#values-for-optionsfacedetectionaccuracyconfig) |
13903-
13904-
##### Values for options.faceDetection.accuracyConfig
13905-
13906-
> [Note]
13907-
> Accuracy config is only supported on web.
13908-
13909-
| Property | Type | Description |
13910-
| :------------------------- | :----- | :--------------------------------------------------------------------------- |
13911-
| detectionThreshold | number | Minimum confidence score required to consider a face detection valid. |
13912-
| intersectionRatioThreshold | number | Minimum allowed overlap ratio between the detected face and expected region. |
13913-
| extraHeightFactor | number | Additional height factor added to the face bounding box. |
13914-
| inputSize | number | Size of the input image used for face detection. |
13915-
| landmarkRatio | number | Minimum acceptable alignment accuracy for facial landmarks. |
13916-
| frameMargin | number | Margin ratio to ensure face is not too close to frame edges. |
13917-
| tiltAngleThreshold | number | Maximum allowed tilt angle of the detected face (in degrees). |
13918-
| horizontalCenterTolerance | number | Allowed tolerance for how centered the face must be horizontally. |
13919-
| earThreshold | number | Minimum Eye Aspect Ratio (EAR) to detect open eyes. |
13920-
| minFaceWidthRatio | number | Minimum ratio of face width relative to the frame. |
13921-
| maxFaceWidthRatio | number | Maximum ratio of face width relative to the frame. |
13922-
| qualityPassThreshold | number | Minimum quality score required for a face to pass detection. |
13923-
| yawLowerThreshold | number | Lower bound of acceptable yaw (left-right head rotation) ratio. |
13924-
| yawUpperThreshold | number | Upper bound of acceptable yaw (left-right head rotation) ratio. |
13925-
13926-
1392713884
**Usage Examples**
1392813885

13929-
13930-
1393113886
```yaml
1393213887
View:
1393313888
header:
@@ -14101,106 +14056,22 @@ You can clear previous camera results while recapturing using `cameraId.clear()`
1410114056
id: captureLatest
1410214057
```
1410314058

14104-
Capture image on face detected
14105-
14106-
```yaml
14107-
- Button:
14108-
label: Open Camera
14109-
onTap:
14110-
openCamera:
14111-
id: cameraWithFaceDetection
14112-
options:
14113-
initialCamera: front
14114-
faceDetection:
14115-
enabled: true
14116-
autoCapture: false
14117-
performanceMode: accurate
14118-
accuracyConfig: # accuracyConfig is only supported on web
14119-
detectionThreshold: 0.5
14120-
intersectionRatioThreshold: 0.9
14121-
extraHeightFactor: 0.6
14122-
inputSize: 224
14123-
landmarkRatio: 0.95
14124-
frameMargin: 0.05
14125-
tiltAngleThreshold: 6
14126-
horizontalCenterTolerance: 0.08
14127-
earThreshold: 0.25
14128-
minFaceWidthRatio: 0.18
14129-
maxFaceWidthRatio: 0.82
14130-
qualityPassThreshold: 0.8
14131-
yawLowerThreshold: 0.85
14132-
yawUpperThreshold: 1.15
14133-
message: "Align your face in the square"
14134-
messageStyle:
14135-
color: "#FF0000"
14136-
fontSize: 20
14137-
onCapture:
14138-
uploadFiles:
14139-
id: uploader
14140-
files: ${cameraWithFaceDetection.files[0]}
14141-
uploadApi: fileUploadApi
14142-
fieldName: file
14143-
onComplete:
14144-
showDialog:
14145-
body:
14146-
Column:
14147-
children:
14148-
- TextInput:
14149-
value: ${cameraWithFaceDetection.files[0]}
14150-
- Image:
14151-
source: ${cameraWithFaceDetection.files[0].path}
14152-
```
14153-
14154-
1415514059
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.
1415614060

1415714061
---
1415814062

1415914063
# openFaceCamera
1416014064

14161-
## Overview
14065+
`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).
1416214066

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

14166-
## What It Does
14069+
1. Go to https://studio.ensembleui.com/
14070+
2. Open your app
14071+
3. From the left sidebar, click **Build & Deploy**
14072+
4. In the **Build Settings** tab, enable the **Face Camera** module/feature and update.
14073+
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
1416714074

14168-
- Real-time face detection on Mobile and Web
14169-
- Auto-capture when alignment conditions are met
14170-
- Configurable detection options (yaw, tilt, thresholds, performance mode)
14171-
- Seamless integration with Ensemble via `openFaceCamera`
14172-
- Direct Flutter widget support
14173-
14174-
## Installation
14175-
14176-
Add this to `pubspec.yaml`:
14177-
14178-
```yaml
14179-
dependencies:
14180-
ensemble_face_camera:
14181-
git:
14182-
url: https://github.com/EnsembleUI/ensemble.git
14183-
ref: main
14184-
path: modules/face_camera
14185-
```
14186-
14187-
## Required Setup
14188-
14189-
Register the manager during app initialization:
14190-
14191-
```dart
14192-
import 'package:ensemble_face_camera/ensemble_face_camera.dart';
14193-
14194-
GetIt.I.registerSingleton<FaceCameraManager>(
14195-
FaceCameraManagerImpl(),
14196-
);
14197-
```
14198-
14199-
Without this registration, the `openFaceCamera` action will not work.
14200-
14201-
## Action
14202-
14203-
Use `openFaceCamera` in YAML.
1420414075

1420514076
### Properties
1420614077

@@ -14401,6 +14272,8 @@ Use strict face detection thresholds for web capture.
1440114272
message: "Error capturing image: ${event.error}"
1440214273
```
1440314274

14275+
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.
14276+
1440414277
---
1440514278

1440614279
# openPlaidLink
@@ -17819,85 +17692,58 @@ To learn more about openCamera functionalities, test it out here in [Ensemble Ki
1781917692

1782017693
# openFaceCamera
1782117694

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

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

17826-
## When to use this instead of openCamera
17699+
### When to use this instead of `openCamera`
1782717700

17828-
- You need face alignment guidance before capture.
17829-
- You need automatic capture when a valid face is detected.
17830-
- You need stricter face quality checks, especially on web via `accuracyConfig`.
17701+
- You want visual guidance to center and align the face before capture
17702+
- You need automatic capture once a valid face is detected
17703+
- You want stricter face quality rules (especially on web with `accuracyConfig`)
1783117704

17832-
For generic photo/video capture or gallery-first flows, continue using [`openCamera`](#opencamera).
17705+
### Key Properties
1783317706

17834-
## Properties
17707+
| Property | Type | Description |
17708+
|------------|--------|-----------------------------------------------------------------------------|
17709+
| id | string | Bind captured result (access via `${yourId.files}`) |
17710+
| onCapture | action | Runs after successful capture (`event.data.files` available) |
17711+
| onError | action | Handles errors (`event.error` available) |
17712+
| options | object | Controls camera lens, UI, auto-capture, resolution, flash, and detection |
1783517713

17836-
| Property | Type | Description |
17837-
| :-------- | :----- | :------------------------------------------------------------------------------ |
17838-
| id | string | Camera ID used to bind captured results (for example `${myFaceCamera.files}`). |
17839-
| onCapture | action | Executes when an image is captured. Files are available in `event.data.files`. |
17840-
| onError | action | Executes on error. Error message is available via `event.error`. |
17841-
| options | object | Face camera and detection configuration. |
17842-
17843-
## options
17844-
17845-
| Property | Type | Description |
17846-
| :------------------------ | :------ | :------------------------------------------------------------------------------ |
17847-
| initialCamera | string | Which lens to start with: `front` (default), `back` |
17848-
| message | string | Message shown above camera preview |
17849-
| messageStyle | object | Text style for `message` |
17850-
| showControls | boolean | Show/hide all camera controls. Default `true` |
17851-
| showCaptureControl | boolean | Show/hide capture button. Default `true` |
17852-
| showFlashControl | boolean | Show/hide flash control. Default `true` |
17853-
| showCameraLensControl | boolean | Show/hide camera switch control. Default `true` |
17854-
| showStatusMessage | boolean | Show/hide face detection status text. Default `true` |
17855-
| indicatorShape | string | Face indicator shape: `circle`, `square` |
17856-
| autoDisableCaptureControl | boolean | Disable capture while no valid face is detected. Default `false` |
17857-
| autoCapture | boolean | Automatically capture when face qualifies. Default `false` |
17858-
| imageResolution | string | Capture resolution: `low`, `medium`, `high`, `veryHigh`, `ultraHigh`, `max` |
17859-
| defaultFlashMode | string | Initial flash mode: `off` (default), `auto`, `always` |
17860-
| orientation | string | Camera orientation: `portraitUp`, `portraitDown`, `landscapeLeft`, `landscapeRight` |
17861-
| performanceMode | string | Face detector mode: `fast` (default), `accurate` |
17862-
| accuracyConfig | object | Fine-grained face detection thresholds. Web only. |
17714+
### Quick Examples
1786317715

17864-
## Usage
17865-
17866-
### Basic
17716+
**Basic face capture**
1786717717

1786817718
```yaml
1786917719
- Button:
1787017720
label: Open Face Camera
1787117721
onTap:
1787217722
openFaceCamera:
17873-
id: myFaceCamera
17723+
id: myFace
1787417724
```
17875-
17876-
### Auto-capture
17725+
**Auto-capture verified selfie**
1787717726

1787817727
```yaml
1787917728
- Button:
17880-
label: Capture verified selfie
17729+
label: Capture Verified Selfie
1788117730
onTap:
1788217731
openFaceCamera:
1788317732
id: profilePhoto
1788417733
options:
1788517734
initialCamera: front
1788617735
autoCapture: true
17736+
message: "Align your face in the frame"
1788717737
performanceMode: accurate
17888-
message: "Align your face"
1788917738
onCapture:
17890-
executeCode:
17891-
body: |
17892-
console.log('Captured face image: ' + profilePhoto.files[0].path);
17739+
showToast:
17740+
message: "Selfie captured!"
1789317741
onError:
1789417742
showToast:
17895-
message: "Error capturing image: ${event.error}"
17743+
message: "Capture failed: ${event.error}"
1789617744
```
1789717745

17898-
## Full Reference
17899-
17900-
For complete module setup, advanced `accuracyConfig` fields, and more examples, see [`openFaceCamera` action docs](#openfacecamera).
17746+
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.
1790117747

1790217748
---
1790317749

0 commit comments

Comments
 (0)