Add BirdNET-Geomodel 3.0

.github/workflows/ci.yml

@@ -96,3 +96,15 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: birdnet-team/birdnet
+
+      - name: Extract log path
+        run: |
+          LOG_PATH=$(grep -o '/var/folders[^ ]*\.log' output.log | head -n1)
+          echo "LOG_PATH=$LOG_PATH" >> $GITHUB_ENV
+
+      - name: Upload log file
+        if: failure() && env.LOG_PATH != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: birdnet-log
+          path: ${{ env.LOG_PATH }}

docs/birdnet.geo_models.v3_0.rst

@@ -0,0 +1,37 @@
+birdnet.geo\_models.v3\_0 package
+=================================
+
+Submodules
+----------
+
+birdnet.geo\_models.v3\_0.model module
+--------------------------------------
+
+.. automodule:: birdnet.geo_models.v3_0.model
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+birdnet.geo\_models.v3\_0.tf module
+------------------------------------
+
+.. automodule:: birdnet.geo_models.v3_0.tf
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+birdnet.geo\_models.v3\_0.pb module
+------------------------------------
+
+.. automodule:: birdnet.geo_models.v3_0.pb
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: birdnet.geo_models.v3_0
+   :members:
+   :show-inheritance:
+   :undoc-members:

src/birdnet/core/backends.py

@@ -181,10 +181,21 @@ def prediction_out_idx(cls) -> int: ...
   @abstractmethod
   def encoding_out_idx(cls) -> int | None: ...
 
+  @classmethod
+  def requires_flex_delegate(cls) -> bool:
+    return False
+
   def load(self) -> None:
     assert self._interp is None
+    if self.requires_flex_delegate():
+      # Flex ops (Select TF ops) need the full TF op registry to be populated
+      # before the interpreter tries to prepare flex kernels.
+      import_tf()
     self._interp = load_tf_model(
-      self._model_path, self._inference_library, allocate_tensors=True
+      self._model_path,
+      self._inference_library,
+      allocate_tensors=True,
+      use_flex_delegate=self.requires_flex_delegate(),
     )
 
   def unload(self) -> None:
@@ -709,31 +720,39 @@ def load_tf_model(
   model_path: Path,
   library: Literal["tflite"],
   allocate_tensors: bool = False,
+  use_flex_delegate: bool = False,
 ) -> TFInterpreter: ...
 @overload
 def load_tf_model(
   model_path: Path,
   library: Literal["litert"],
   allocate_tensors: bool = False,
+  use_flex_delegate: bool = False,
 ) -> LiteRTInterpreter: ...
 
 
 def load_tf_model(
   model_path: Path,
   library: LIBRARY_TYPES,
   allocate_tensors: bool = False,
+  use_flex_delegate: bool = False,
 ):
   if library == LIBRARY_TFLITE:
-    return load_lib_tf_model(model_path, allocate_tensors=allocate_tensors)
+    return load_lib_tf_model(
+      model_path, allocate_tensors=allocate_tensors, use_flex_delegate=use_flex_delegate
+    )
   elif library == LIBRARY_LITERT:
-    return load_lib_litert_model(model_path, allocate_tensors=allocate_tensors)
+    return load_lib_litert_model(
+      model_path, allocate_tensors=allocate_tensors, use_flex_delegate=use_flex_delegate
+    )
   else:
     raise AssertionError()
 
 
 def load_lib_tf_model(
   model_path: Path,
   allocate_tensors: bool = False,
+  use_flex_delegate: bool = False,
 ) -> TFInterpreter:
   assert model_path.is_file()
   assert tf_installed()
@@ -781,12 +800,18 @@ def load_lib_tf_model(
       module="tensorflow.lite.python.interpreter",
     )
     try:
-      interp = tflite.Interpreter(
-        str(model_path.absolute()),
-        num_threads=1,
-        experimental_op_resolver_type=tflite.OpResolverType.BUILTIN_WITHOUT_DEFAULT_DELEGATES,
-        # tensor#187 is a dynamic-sized tensor # type: ignore
-      )
+      if use_flex_delegate:
+        interp = tflite.Interpreter(
+          str(model_path.absolute()),
+          num_threads=1,
+        )
+      else:
+        interp = tflite.Interpreter(
+          str(model_path.absolute()),
+          num_threads=1,
+          experimental_op_resolver_type=tflite.OpResolverType.BUILTIN_WITHOUT_DEFAULT_DELEGATES,
+          # tensor#187 is a dynamic-sized tensor # type: ignore
+        )
     except ValueError as e:
       raise ValueError(
         f"Failed to load model '{model_path.absolute()}' using 'tensorflow'. "
@@ -816,6 +841,7 @@ def load_lib_tf_model(
 def load_lib_litert_model(
   model_path: Path,
   allocate_tensors: bool = False,
+  use_flex_delegate: bool = False,
 ) -> LiteRTInterpreter:
   assert model_path.is_file()
   assert litert_installed()
@@ -824,12 +850,18 @@ def load_lib_litert_model(
 
   start = time.perf_counter()
   try:
-    interp = tflite.Interpreter(
-      str(model_path.absolute()),
-      num_threads=1,
-      experimental_op_resolver_type=tflite.OpResolverType.BUILTIN_WITHOUT_DEFAULT_DELEGATES,
-      # tensor#187 is a dynamic-sized tensor # type: ignore
-    )
+    if use_flex_delegate:
+      interp = tflite.Interpreter(
+        str(model_path.absolute()),
+        num_threads=1,
+      )
+    else:
+      interp = tflite.Interpreter(
+        str(model_path.absolute()),
+        num_threads=1,
+        experimental_op_resolver_type=tflite.OpResolverType.BUILTIN_WITHOUT_DEFAULT_DELEGATES,
+        # tensor#187 is a dynamic-sized tensor # type: ignore
+      )
   except ValueError as e:
     raise ValueError(
       f"Failed to load model '{model_path.absolute()}' using 'ai_edge_litert'. "

src/birdnet/geo/inference/configs.py

@@ -5,7 +5,11 @@
 from ordered_set import OrderedSet
 
 from birdnet.core.backends import VersionedBackendProtocol
-from birdnet.globals import GEO_MODEL_VERSIONS
+from birdnet.globals import (
+  GEO_MODEL_VERSIONS,
+  GEO_YEAR_ROUND_AGGREGATIONS,
+  VALID_GEO_YEAR_ROUND_AGGREGATIONS,
+)
 
 
 @dataclass(frozen=True)
@@ -63,7 +67,8 @@ def validate_min_confidence(cls, min_confidence: Any) -> float:  # noqa: ANN401
 class RunConfig:
   latitude: float
   longitude: float
-  week: int
+  week: int | None
+  year_round_aggregation: GEO_YEAR_ROUND_AGGREGATIONS
 
   @classmethod
   def validate_latitude(cls, latitude: Any) -> float:  # noqa: ANN401
@@ -86,20 +91,32 @@ def validate_longitude(cls, longitude: Any) -> float:  # noqa: ANN401
     return float(longitude)
 
   @classmethod
-  def validate_week(cls, week: Any) -> int:  # noqa: ANN401
+  def validate_week(cls, week: Any) -> int | None:  # noqa: ANN401
     if week is None:
-      return -1
+      return None
 
     if not isinstance(week, int):
       raise TypeError("Value for 'week' is invalid! It must be an integer.")
 
-    if week is not None and not (1 <= week <= 48):
+    if not (1 <= week <= 48):
       raise ValueError(
-        "Value for 'week' is invalid! It needs to be either None or in interval [1, 48]."
+        "Value for 'week' is invalid! It needs to be either None or in"
+        " interval [1, 48]."
       )
 
     return week
 
+  @classmethod
+  def validate_year_round_aggregation(
+    cls, year_round_aggregation: Any  # noqa: ANN401
+  ) -> GEO_YEAR_ROUND_AGGREGATIONS:
+    if year_round_aggregation not in VALID_GEO_YEAR_ROUND_AGGREGATIONS:
+      raise ValueError(
+        "Value for 'year_round_aggregation' is invalid!"
+        " It must be either 'max' or 'average'."
+      )
+    return year_round_aggregation
+
 
 @dataclass(frozen=True)
 class InferenceConfig:

src/birdnet/geo/inference/prediction_result.py

@@ -146,7 +146,7 @@ def to_structured_array(
 
     n_predictions = len(unmasked_species)
 
-    max_len = max(map(len, unmasked_species))
+    max_len = max(map(len, unmasked_species), default=1)
     dtype = [
       (VAR_SPECIES_NAME, f"<U{max_len}"),
       (VAR_CONFIDENCE, self._species_probs.dtype),

src/birdnet/geo/inference/session.py

@@ -20,7 +20,12 @@
   RunConfig,
 )
 from birdnet.geo.inference.prediction_result import GeoPredictionResult
-from birdnet.globals import GEO_MODEL_VERSIONS
+from birdnet.globals import (
+  GEO_MODEL_VERSION_V2_4,
+  GEO_MODEL_VERSIONS,
+  GEO_YEAR_ROUND_AGGREGATION_MAX,
+  GEO_YEAR_ROUND_AGGREGATIONS,
+)
 from birdnet.utils.helper import get_uint_dtype
 
 
@@ -56,17 +61,44 @@ def _run(self, run_config: RunConfig) -> GeoPredictionResult:
     assert self._is_initialized
     assert self._backend is not None
 
-    sample = np.expand_dims(
-      np.array(
-        [run_config.latitude, run_config.longitude, run_config.week],
-        dtype=np.float32,
-      ),
-      0,
-    )
-
-    res = self._backend.predict(sample)
-
-    res = np.squeeze(res, axis=0)
+    if run_config.week is None:
+      if self._conf.model_conf.version == GEO_MODEL_VERSION_V2_4:
+        # v2.4 was trained with -1 as the year-round sentinel
+        sample = np.expand_dims(
+          np.array(
+            [run_config.latitude, run_config.longitude, -1.0],
+            dtype=np.float32,
+          ),
+          0,
+        )
+        res = self._backend.predict(sample)
+        res = np.squeeze(res, axis=0)
+      else:
+        # v3.0+: feed all 48 weeks as a batch and aggregate
+        samples = np.array(
+          [
+            [run_config.latitude, run_config.longitude, float(w)]
+            for w in range(1, 49)
+          ],
+          dtype=np.float32,
+        )  # shape: (48, 3)
+        res_batch = self._backend.predict(samples)  # shape: (48, n_species)
+        if run_config.year_round_aggregation == GEO_YEAR_ROUND_AGGREGATION_MAX:
+          res = np.max(res_batch, axis=0)
+        else:
+          res = np.mean(res_batch, axis=0)
+      result_week = -1
+    else:
+      sample = np.expand_dims(
+        np.array(
+          [run_config.latitude, run_config.longitude, run_config.week],
+          dtype=np.float32,
+        ),
+        0,
+      )
+      res = self._backend.predict(sample)
+      res = np.squeeze(res, axis=0)
+      result_week = run_config.week
 
     n_species = self._conf.model_conf.n_species
     species_ids = np.arange(
@@ -83,7 +115,7 @@ def _run(self, run_config: RunConfig) -> GeoPredictionResult:
       model_precision=self._backend.precision(),
       latitude=run_config.latitude,
       longitude=run_config.longitude,
-      week=run_config.week,
+      week=result_week,
       species_list=self._conf.model_conf.species_list,
       species_probs=res,
       species_ids=species_ids,
@@ -150,15 +182,20 @@ def run(
     /,
     *,
     week: int | None = None,
+    year_round_aggregation: GEO_YEAR_ROUND_AGGREGATIONS = GEO_YEAR_ROUND_AGGREGATION_MAX,  # noqa: E501
   ) -> GeoPredictionResult:
     latitude = RunConfig.validate_latitude(latitude)
     longitude = RunConfig.validate_longitude(longitude)
     week = RunConfig.validate_week(week)
+    year_round_aggregation = RunConfig.validate_year_round_aggregation(
+      year_round_aggregation
+    )
 
     return self._run(
       RunConfig(
         latitude=latitude,
         longitude=longitude,
         week=week,
+        year_round_aggregation=year_round_aggregation,
       ),
     )

src/birdnet/geo/models/v2_4/model.py

@@ -15,6 +15,8 @@
 from birdnet.globals import (
   GEO_MODEL_VERSION_V2_4,
   GEO_MODEL_VERSIONS,
+  GEO_YEAR_ROUND_AGGREGATION_MAX,
+  GEO_YEAR_ROUND_AGGREGATIONS,
   MODEL_TYPE_GEO,
   MODEL_TYPES,
 )
@@ -157,6 +159,7 @@ def predict(
     /,
     *,
     week: int | None = None,
+    year_round_aggregation: GEO_YEAR_ROUND_AGGREGATIONS = GEO_YEAR_ROUND_AGGREGATION_MAX,  # noqa: E501
     min_confidence: float = 0.03,
     half_precision: bool = False,
     device: str = "CPU",
@@ -170,4 +173,5 @@ def predict(
         latitude,
         longitude,
         week=week,
+        year_round_aggregation=year_round_aggregation,
       )

src/birdnet/geo/models/v2_4/pb.py

@@ -38,8 +38,8 @@ def _check_geo_model_available(cls) -> bool:
     model_is_downloaded = True
     model_is_downloaded &= model_path.is_dir()
     model_is_downloaded &= check_protobuf_model_files_exist(model_path)
-
     model_is_downloaded &= lang_dir.is_dir()
+
     for lang in cls.AVAILABLE_LANGUAGES:
       model_is_downloaded &= (lang_dir / f"{lang}.txt").is_file()
 

src/birdnet/geo/models/v3_0/__init__.py

@@ -0,0 +1 @@
+#