Basic Usage
Show the Petnow camera in a Flutter app, prepare it ahead with prewarm, and handle errors.
Initialize
A PetnowCameraController holds the licence. Create it once (for example in your app's state) and call initialize() before mounting a camera.
import 'package:petnow_camera_ui/petnow_camera_ui.dart';
final camera = PetnowCameraController(
license: const LicenseInfo(apiKey: clientKey), // Client key (app)
);
await camera.initialize();initialize() stores the key; the server checks it when the camera starts. LicenseInfo(environment: PetnowEnvironment.staging) targets the staging backend for a staging-console key.
Show the camera
PetnowCameraView(
key: ValueKey(sessionId),
controller: camera,
config: PetnowCameraConfig(
species: Species.dog,
purpose: DetectionPurpose.registration,
captureSessionId: sessionId, // from your server: POST /v2/capture-sessions
),
onDetectionStatus: (status) {}, // live guidance
onDetectionProgress: (percent) {}, // 0..100
onDetectionFinished: (result) {}, // CameraResult: upload the images
onError: (PetnowCameraError e) {}, // what stops the camera
onPerformanceStats: (s) {}, // optional
)The view reads config once, when it is created. A capture session is single-use, so a retake needs a new session from your server: give the view a new key (ValueKey(config.captureSessionId)) so it is rebuilt. controller.startDetection() restarts detection on the open camera, and pauseDetection() / resumeDetection() / switchCamera() control it.
The preview appears before detection is ready
Since 1.6.0 the preview shows as soon as the camera runs, while the detection models may still be loading. Say "preparing" until CameraPerformanceStats.detectionReadyAtMs is set, or drive guidance from onDetectionStatus, rather than asking the user to aim when the preview appears.
Faster camera start (prewarm)
Call prewarm() from the screen whose button leads to the camera. The licence check, the SDK Profile and the model load then happen while the user is still on that screen.
// On the screen before the camera. Do not wait for it.
camera.prewarm();
// Leaving the capture flow (a back button to home), not on the way into the camera:
await camera.releasePrewarmed();prewarm()returns once the request is taken, not when the models are ready. It never throws; it returnsfalseand does nothing wheninitialize()has not run.- Omit
speciesunless the screen knows what will be captured. Naming the wrong one costs a rebuild on iOS. - Do not call
releasePrewarmed()from the dispose of the screen that prewarmed: that also runs on the way into the camera and destroys the engine it was about to take. - To check it worked,
engineReusedinonPerformanceStatsistruewhen the camera started on models that were already complete.
When a capture fails
onDetectionFinished is also called when the capture fails: success is false, the image lists are empty, and failureReason is the DetectionFailureReason the session's frames most often failed on. Tell the user what to change, then controller.startDetection() retries on the open camera.
onDetectionFinished: (result) {
if (!result.success) {
showRetry(result.failureReason); // e.g. tooDark -> "Find a brighter spot"
return;
}
upload(result.fingerprintImages, result.appearanceImages);
},onDetectionStatus is live guidance only — the most frequent status of each 1.5-second window while the user is aiming. It does not send the failed capture's final reason.
After the upload: getting the result
Uploading the images does not register, verify or identify the pet by itself. Your server submits that job with its Secret key and receives the outcome by polling the job or through a webhook: see Getting Results. If a request is refused or the job ends FAILED, see Why Did Registration Fail?.
Errors
onError reports what stops the camera; guidance such as "too dark" arrives on onDetectionStatus as DetectionFailed instead, and a failed capture's reason on CameraResult.failureReason.
PetnowCameraErrorCode | Meaning |
|---|---|
notInitialized | initialize() has not run |
invalidConfig | The config is unusable, e.g. a capture session id that is not a UUID |
permissionDenied | The camera permission is missing |
invalidLicense | The server refused the key |
network | The licence check could not reach the server (no network, a timeout, a server error) |
cameraUnavailable | The camera could not be opened |
multipleApiKeys | A second, different key in the same process; restart the app |
unknown | Anything else; message says what |
message is for logs and support, not for users. Branch on code.
Performance stats
onPerformanceStats arrives a few times a second when set: cameraInitMs, firstFrameMs, fps, detectorMs, inferenceTier, firstPreviewAtMs, detectionReadyAtMs and engineReused. The …AtMs values are offsets from the camera start and stay null until they happen.
Guidance sounds
PetnowSound plays the SDK's guidance sounds without a camera:
await PetnowSound.prepare();
final handle = await PetnowSound.play(GuidanceSound.random, Species.dog);
await PetnowSound.stop(handle);