Guiding the person into position
What the widget shows before the capture starts, what each cue means, and what your code receives at the same moment.
A measurement only works if the face sits correctly in the frame, at the right distance, with the upper chest visible. Rather than say it once and hope, Saphere Scan follows the face before the capture and shows, continuously, whether it sits correctly between two guides.
The direction to move in is shown, not written: it has to work the same way in ten languages and in both reading directions. And it says what to do, not what is wrong. A single line of text under the frame, in the user’s language, only gives the state: place your face in the lit area, then hold still.
Conditions for a good measurement explains why the position matters in the first place.
| What the person sees | What it means | What to do |
|---|---|---|
| Arrows pointing down at the upper guide | The face is above the usable area | Move down |
| Arrows pointing up at the lower guide | The face is below the usable area | Move up |
| The frame closing in on itself | The face is bigger than the space between the guides | Move back |
| No marker, and the line below asks for the face to be placed | No face is seen | Come into the frame |
| No marker, and a ring filling beside “Hold still” | The position is accepted | Hold still |
Two things about this guidance are worth knowing before you build around it.
The guidance and the accept-or-refuse decision are read from the same rule. Guidance can therefore never appear while the position is accepted, nor be missing while a face is seen and its position refused.
“Move back” is checked first. A face taller than the usable area will not fit by moving in any direction, so telling the person to move up or down would be advice that cannot work.
When the capture starts
An accepted position is not yet a start. The face must also hold still — two seconds by default, in one go: any movement starts the count again, and leaving the lit area clears it. Then the capture starts on its own or, if the customisation chose a manual start, a button appears and the capture waits for it. The mode and the delay are set in the workshop, under Measurement start, or through components.placement.start (mode is "auto" or "manual", delay is in seconds).
That is also the moment your code can still say no, through the beforeMeasureStart hook. Once it has let the start through, the framing is frozen and placement:accepted is reported.
What your code receives
Your code receives the same information as the screen, through the placement:guidance event. Its guidance is "up", "down" or "back", or null — when nothing needs correcting, and also when no face is seen. Beside it, stable says whether the face held still since the previous image. The event fires only when one of the two changes, never merely because an image was analysed. See Events.