animal_detection

Depend on flutter_litert ^3.9.0, opencv_dart ^2.2.2, and dartcv4 ^2.3.1. The direct dartcv4 constraint exists only so resolution can never keep a dartcv4 release whose iOS CMake hook hardcodes a 12.0 deployment target, which Xcode 27 rejects; no Dart source imports it.

Raise the floors to Dart 3.10 and Flutter 3.47.5. Earlier Flutter releases pin meta 1.18.0 through flutter_test, which cannot coexist with dartcv4 2.3.1.

Building for iOS with Xcode 27 needs an iOS 15 deployment target. Set the Runner target (and platform :ios in the Podfile) to 15.0 and add this to the app's pubspec.yaml; hook user-defines are only honoured from the root package, so a dependency cannot supply it for you:

hooks:
  user_defines:
    dartcv4:
      ios:
        deployment_target: '15.0'

Run flutter clean afterwards so the cached OpenCV build is regenerated.

Remove the unused direct meta dependency.

No API changes. Verified with the hosted flutter_litert 3.9.0 on macOS 27, Xcode 27, and the iOS 27 simulator.

The bundled SuperAnimal models are now correctly documented as academic/non-commercial only. The Dart source code remains Apache 2.0 and is unchanged. Nothing about the models themselves is different from 3.0.1, and this neither grants nor removes any right: it records the position accurately for the first time. assets/models/superanimal_ssdlite_float16.tflite, assets/models/superanimal_rtmpose_s_float16.tflite and the on-demand HRNet pose model are format conversions of the Mathis Laboratory's SuperAnimal-Quadruped checkpoints. Those weights are licensed for academic, non-commercial purposes only, the licence is explicitly non-transferable, and it forbids using the models to deliberately harm an animal. The README badge and LICENSE file previously implied Apache 2.0 covered everything shipped, which was wrong. See the new NOTICE.

Major version because this is material to anyone depending on the package. Nothing in the API changed, but a caret constraint on 3.x should not silently carry a consumer into a non-commercial licence statement they did not choose to read. Bumping the major forces that to be a deliberate upgrade.

Commercial use has a route, and it is not through this package. The rights holders offer commercial licensing: Prof. Mackenzie W. Mathis (mackenzie@post.harvard.edu) and the EPFL Technology Transfer Office (tto@epfl.ch).

The required SuperAnimal citation is now in the README, which it should have been from the start. Please cite Ye et al., Nature Communications 15, 5165 (2024).

Clarified that species_classifier_float16.tflite (torchvision, BSD-3-Clause) and species_mapping.json (this package, Apache 2.0) carry no such restriction.

Fixed: a cropped cv.Mat passed to detectFromMat returned no detections. Mat.data ignores row stride, so a non-continuous Mat, which is what mat.region(...) returns, was read as though its rows were tightly packed and arrived scrambled. Passing a cropped view produced zero detections or nonsense labels; the same crop with .clone() worked. Non-continuous input is now packed automatically, so no .clone() is needed at the call site. face_detection_tflite, pose_detection and hand_detection already guarded against this; this brings the remaining packages in line.

Default precision is now Precision.fp32 instead of fp16. This changes numeric output. flutter_litert 3.8.0 changed its own default for the same reason: across 29 published detection models measured on five GPUs, fp16 matched a plain-CPU reference for only about a fifth of them, while fp32 matched every model that compiled. These graphs emit pixel-space coordinates and landmark positions, and fp16 carries about three decimal digits of mantissa, so the error lands directly on output geometry. The cost is real and worth stating plainly: fp32 is a median 29.9% slower on GPU across those five GPUs, with Apple M4 the lone exception at 6.5% faster. Pass precision: Precision.fp16 explicitly to restore the previous behaviour, ideally per model and validated on your target GPU.

Pin flutter_litert to ^3.8.0. Adds an optional LiteRT Next CompiledModel backend, off by default, and pins flutter_litert to ^3.8.0.

New useCompiledModel on initializeFromBuffers. When true, every stage is initialized onto CompiledModel instead of Interpreter. Off by default, matching the same opt-in in face_detection_tflite, pose_detection and hand_detection. compiledForceCpu is accepted alongside it.

The CompiledModel backend is CPU-only, deliberately. Each stage requests {Accelerator.cpu} rather than the permissive {gpu, cpu} set. This is a correctness requirement, not a performance preference: LiteRT miscomputes two of this package's own models once the GPU accelerator is in the set, by 42.3% of the output range for the species classifier and 53.8% for the pose model, while still reporting success. Do not widen the accelerator set without measuring against a bare-CPU reference first; flutter_litert 3.7.0 ships verifyCompiledModel for exactly that check.

Whether CompiledModel is faster is per-platform and per-model. Its CPU accelerator beats the Interpreter's XNNPACK path on Apple Silicon macOS but is roughly 2x slower on iOS, so measure before enabling it.

SSD output shapes are now derived rather than assumed, so the body detector works under both backends.

Requires flutter_litert ^3.8.0, which fixes a 3x macOS CPU slowdown affecting every stage of this pipeline (ruy multithreading was inert in the previously bundled macOS dylib).

Replace the boxed nested input and output tensors in every model class with reused flat Float32Lists handed to TFLite as ByteBuffers, matching the approach in face_detection_tflite, pose_detection and hand_detection. Measured end to end on the cat_detection pipeline over a 3264x2448 photo in profile mode with PerformanceMode.auto, the full pipeline drops from 438 ms/frame to 109 ms/frame and poseOnly from about 44 ms to 15 ms. Model outputs are unchanged.

The two new helpers ImageUtils.matToFloat32Simd and matToFloat32ImageNetSimd use OpenCV's vectorized path and accept an optional caller buffer. Both are asserted equal to the per-pixel loops they replace: worst deviation 5.96e-8 (one float32 ULP) for the plain path, 7.15e-7 for the ImageNet affine. ImageUtils.matToFloat32 and matToFloat32ImageNet are retained.

Fix ImageUtils.cropAndResize returning CropMetadata built from pre-truncation floats while cropping an integral region. Callers mapped normalized coordinates against an origin up to 1px from where the crop actually began, and against a slightly too-large extent. Measured over the 311-image CatFLW holdout with real localizer boxes, this placed landmarks +0.61px right and +0.52px down of ground truth and cost 0.255 NME_IOD, rising to 1.14 at the 95th percentile, with 72% of images improved by the fix. The Python training pipelines normalize against the integer crop, so this also aligns inference with how the models were trained.

This changes returned landmark coordinates. Downstream packages should bump their own pipeline version so cached detections re-evaluate.

Fix ModelDownloader.modelHrnet, which requested superanimal_hrnet_w32_256_float16.tflite while the release publishes superanimal_hrnet_w32_float16.tflite. AnimalPoseModel.hrnet therefore failed with an HTTP 404 on first use and had never worked. The private filename constant now derives from the public one so the two cannot drift.

Reject a configured input size that disagrees with the bundled model, via the new internal assertSquareInputSize. Interpreter.resizeInputTensor accepts a shape the model was not trained for without reporting an error, and inference then returns finite but meaningless values: feeding a 256px landmark model at 384px measured NME_IOD 67.3 against a correct 3.5 while every output stayed in range. All six model classes now validate against getInputTensor(0).shape at initialization.

Stop tracking .DS_Store files, which were included in the published archive.