Petnow LogoPetnow

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 returns false and does nothing when initialize() has not run.
  • Omit species unless 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, engineReused in onPerformanceStats is true when 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.

PetnowCameraErrorCodeMeaning
notInitializedinitialize() has not run
invalidConfigThe config is unusable, e.g. a capture session id that is not a UUID
permissionDeniedThe camera permission is missing
invalidLicenseThe server refused the key
networkThe licence check could not reach the server (no network, a timeout, a server error)
cameraUnavailableThe camera could not be opened
multipleApiKeysA second, different key in the same process; restart the app
unknownAnything 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);

On this page