LabelBOT

app/Http/Controllers/Api/ImageAnnotationController.php

@@ -232,12 +232,13 @@ public function store(StoreImageAnnotation $request)
         if (is_null($labelId) && $request->has('feature_vector')) {
             // Get label tree id(s).
             $trees = $this->getLabelTreeIds($request->user(), $image->volume_id);
-            // Perform ANN search.
-            $topNLabels = $this->performAnnSearch($request->input('feature_vector'), $trees);
-            // Perform KNN search as a fallback if ANN search returns no results.
-            if (empty($topNLabels)) {
-                $topNLabels = $this->performKnnSearch($request->input('feature_vector'), $trees);
-            }
+
+            // Convert the feature vector into a Vector object for compatibility with the query.
+            $featureVector = new Vector($request->input('feature_vector'));
+
+            // Perform vector search.
+            $topNLabels = $this->performVectorSearch($featureVector, $trees, $topNLabels);
+
             // Set labelId to top 1 label.
             $labelId = $topNLabels[0];
         }
@@ -259,7 +260,7 @@ public function store(StoreImageAnnotation $request)
 
         // Attach the other two labels if they exist.
         for ($i = 1; $i < count($topNLabels); $i++) {
-            $annotation->labelBOTLabels[] = $topNLabels[$i];
+            $annotation->labelBOTLabels[] = Label::findOrFail($topNLabels[$i]);
         }
 
         return $annotation;
@@ -396,27 +397,52 @@ protected function getLabelTreeIds($user, $volumeId)
     }
 
     /**
-     * Perform ANN search (HNSW + Post-Subquery-Filtering).
+     * Perform vector search using the Dynamic Index Switching (DIS) technique.
      *
-     * @param vector $featureVector
-     * @param int[] $trees
+     * The search process first attempts to retrieve results using an Approximate Nearest Neighbor (ANN) search
+     * via the HNSW index. If the ANN search returns no results, it falls back to an exact KNN search using the
+     * B-Tree index for filtering, ensuring that results are always returned.
      *
-     * @return array
+     * @param vector $featureVector The input feature vector to search for nearest neighbors.
+     * @param int[] $trees The label tree IDs to filter the data by.
+     * @param int[] $topNLabels The array to store the top N labels based on the search results.
+     *
+     * @return array The array of top N labels that are the closest to the input feature vector.
      */
-    protected function performAnnSearch($featureVector, $trees)
+    protected function performVectorSearch($featureVector, $trees, $topNLabels)
     {
-        $featureVector = new Vector($featureVector);
+        // Perform ANN search.
+        $topNLabels = $this->performAnnSearch($featureVector, $trees);
 
+        // Perform KNN search as a fallback if ANN search returns no results.
+        if (empty($topNLabels)) {
+            $topNLabels = $this->performKnnSearch($featureVector, $trees);
+        }
+
+        return $topNLabels;
+    }
+
+    /**
+     * Perform Approximate Nearest Neighbor (ANN) search using the HNSW index with Post-Subquery Filtering (PSF).
+     *
+     * The search uses the HNSW index to find the top K nearest neighbors of the input feature vector,
+     * and then applies filtering based on the label_tree_id values. If no results are found or if the filtering
+     * removes all results, an empty array is returned.
+     *
+     * @param Vector $featureVector The input feature vector to search for nearest neighbors.
+     * @param int[] $trees The label tree IDs to filter the data by.
+     *
+     * @return array The array of label IDs representing the top nearest neighbors.
+    */
+    protected function performAnnSearch($featureVector, $trees)
+    {
         $subquery = ImageAnnotationLabelFeatureVector::select('label_id', 'label_tree_id')
             ->selectRaw('(vector <=> ?) AS distance', [$featureVector])
             ->orderBy('distance')
-            // K = 100
-            ->limit(config('labelbot.K'));
+            ->limit(config('labelbot.K')); // K = 100
 
-        return DB::table(DB::raw("({$subquery->toSql()}) as subquery"))
-            ->setBindings([$featureVector])
+        return DB::query()->fromSub($subquery, 'subquery')
             ->whereIn('label_tree_id', $trees)
-            ->select('label_id')
             ->groupBy('label_id')
             ->orderByRaw('MIN(distance)')
             ->limit(config('labelbot.N')) // N = 3
@@ -425,31 +451,29 @@ protected function performAnnSearch($featureVector, $trees)
     }
 
     /**
-     * Perform KNN search (B-Tree + Post-Filtering).
+     * Perform exact KNN search using the B-Tree index for filtering.
      *
-     * @param Vector $featureVector
-     * @param int[] $trees
+     * This search filters the data based on label_tree_id using the B-Tree index,
+     * and then performs the vector search to find the nearest neighbors of the input feature vector.
+     * This method is used as a fallback when the ANN search does not return results.
      *
-     * @return array
-     */
+     * @param Vector $featureVector The input feature vector to search for nearest neighbors.
+     * @param int[] $trees The label tree IDs to filter the data by.
+     *
+     * @return array The array of label IDs representing the top nearest neighbors.
+    */
     protected function performKnnSearch($featureVector, $trees)
     {
-        $featureVector = new Vector($featureVector);
-
         $subquery = ImageAnnotationLabelFeatureVector::select('label_id', 'label_tree_id')
             ->selectRaw('(vector <=> ?) AS distance', [$featureVector])
-            // filter by label tree id in subquery
-            // to use B-Tree index for filtering and speeding up the vector search
-            ->whereIn('label_tree_id', $trees)
+            ->whereIn('label_tree_id', $trees) // Apply label tree ID filter in the subquery to use the B-Tree index for faster filtering
             ->orderBy('distance')
             ->limit(config('labelbot.K')); // K = 100
 
         // TODO: Drop HNSW index temporary
         // DB::beginTransaction();
 
-        $topNLabels = DB::table(DB::raw("({$subquery->toSql()}) as subquery"))
-            ->setBindings(array_merge([$featureVector], $trees))
-            ->select('label_id')
+        $topNLabels = DB::query()->fromSub($subquery, 'subquery')
             ->groupBy('label_id')
             ->orderByRaw('MIN(distance)')
             ->limit(config('labelbot.N')) // N = 3

app/Http/Requests/StoreImageAnnotation.php

@@ -4,8 +4,9 @@
 
 use Biigle\Image;
 use Biigle\Shape;
+use Illuminate\Foundation\Http\FormRequest;
 
-class StoreImageAnnotation extends StoreImageAnnotationLabelFeatureVector
+class StoreImageAnnotation extends FormRequest
 {
     /**
      * The image on which the annotation should be created.
@@ -33,10 +34,13 @@ public function authorize()
      */
     public function rules()
     {
-        return array_merge(parent::rules(), [
+        return [
+            'label_id'    => 'required_without:feature_vector|integer|exists:labels,id',
+            'feature_vector' => 'required_without:label_id|array|size:384',
+            'confidence'  => 'required|numeric|between:0,1',
             'shape_id' => 'required|integer|exists:shapes,id',
             'points'   => 'required|array',
-        ]);
+        ];
     }
 
     /**

config/labelbot.php

@@ -3,12 +3,25 @@
 return [
 
     /*
-    | K for KNN
+    |--------------------------------------------------------------------------
+    | K for KNN (K-Nearest Neighbors)
+    |--------------------------------------------------------------------------
+    |
+    | The value of K determines the number of nearest neighbors to consider
+    | when performing a KNN search. This is used in both Approximate
+    | Nearest Neighbor (ANN) and Exact KNN searches.
     */
     'K' => 100,
 
     /*
-    | N for top N labels
+    |--------------------------------------------------------------------------
+    | N for Top N Labels
+    |--------------------------------------------------------------------------
+    |
+    | The value of N specifies how many top labels should be returned from
+    | the search results. After performing a KNN or ANN search, the top N
+    | labels (based on their distance to the query vector) will be selected
+    | and returned.
     */
     'N' => 3,
 ];

tests/php/Http/Controllers/Api/ImageAnnotationControllerTest.php

@@ -402,7 +402,12 @@ public function testStoreWithFeatureVectorWithoutHNSW()
         $response->assertSuccessful();
         // The feature vector of differentLabel is more similar to the input feature vector
         // than feature vector of anotherDifferentLabel, so it is ranked higher.
-        $response->assertJsonFragment(['labelBOTLabels' => [$differentLabel->id, $anotherDifferentLabel->id]]);
+        $response->assertJsonFragment([
+            'labelBOTLabels' => [
+                ['id' => $differentLabel->id],
+                ['id' => $anotherDifferentLabel->id],
+            ]
+        ]);
     }
 
     public function testStoreValidatePoints()