ultralytics 8.3.126__py3-none-any.whl → 8.3.127__py3-none-any.whl

tests/test_solutions.py

@@ -174,3 +174,14 @@ def test_solution(name, solution_class, needs_frame_count, video, kwargs):
         video_path=str(TMP / video),
         needs_frame_count=needs_frame_count,
     )
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(checks.IS_PYTHON_3_8, reason="Disabled due to unsupported CLIP dependencies.")
+@pytest.mark.skipif(IS_RASPBERRYPI, reason="Disabled due to slow performance on Raspberry Pi.")
+def test_similarity_search():
+    """Test similarity search solution."""
+    from ultralytics import solutions
+
+    searcher = solutions.VisualAISearch()
+    _ = searcher("a dog sitting on a bench")  # Returns the results in format "- img name | similarity score"

ultralytics/__init__.py

@@ -1,6 +1,6 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-__version__ = "8.3.126"
+__version__ = "8.3.127"
 
 import os
 

ultralytics/solutions/__init__.py

@@ -12,6 +12,7 @@ from .parking_management import ParkingManagement, ParkingPtsSelection
 from .queue_management import QueueManager
 from .region_counter import RegionCounter
 from .security_alarm import SecurityAlarm
+from .similarity_search import SearchApp, VisualAISearch
 from .speed_estimation import SpeedEstimator
 from .streamlit_inference import Inference
 from .trackzone import TrackZone
@@ -35,4 +36,6 @@ __all__ = (
     "Analytics",
     "Inference",
     "TrackZone",
+    "SearchApp",
+    "VisualAISearch",
 )

ultralytics/solutions/config.py

@@ -48,6 +48,7 @@ class SolutionConfig:
         half (bool): Whether to use FP16 precision (requires a supported CUDA device).
         tracker (str): Path to tracking configuration YAML file (e.g., 'botsort.yaml').
         verbose (bool): Enable verbose logging output for debugging or diagnostics.
+        data (str): Path to image directory used for similarity search.
 
     Methods:
         update: Update the configuration with user-defined keyword arguments and raise error on invalid keys.
@@ -91,6 +92,7 @@ class SolutionConfig:
     half: bool = False
     tracker: str = "botsort.yaml"
     verbose: bool = True
+    data: str = "images"
 
     def update(self, **kwargs):
         """Update configuration parameters with new values provided as keyword arguments."""

ultralytics/solutions/similarity_search.py

@@ -0,0 +1,176 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+from PIL import Image
+
+from ultralytics.data.utils import IMG_FORMATS
+from ultralytics.solutions.solutions import BaseSolution
+from ultralytics.utils.checks import check_requirements
+from ultralytics.utils.torch_utils import select_device
+
+os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"  # Avoid OpenMP conflict on some systems
+
+
+class VisualAISearch(BaseSolution):
+    """
+    VisualAISearch leverages OpenCLIP to generate high-quality image and text embeddings, aligning them in a shared
+    semantic space. It then uses FAISS to perform fast and scalable similarity-based retrieval, allowing users to search
+    large collections of images using natural language queries with high accuracy and speed.
+
+    Attributes:
+        data (str): Directory containing images.
+        device (str): Computation device, e.g., 'cpu' or 'cuda'.
+    """
+
+    def __init__(self, **kwargs):
+        """Initializes the VisualAISearch class with the FAISS index file and CLIP model."""
+        super().__init__(**kwargs)
+        check_requirements(["open-clip-torch", "faiss-cpu"])
+        import faiss
+        import open_clip
+
+        self.faiss = faiss
+        self.open_clip = open_clip
+
+        self.faiss_index = "faiss.index"
+        self.data_path_npy = "paths.npy"
+        self.model_name = "ViT-B-32-quickgelu"
+        self.data_dir = Path(self.CFG["data"])
+        self.device = select_device(self.CFG["device"])
+
+        if not self.data_dir.exists():
+            from ultralytics.utils import ASSETS_URL
+
+            self.LOGGER.warning(f"{self.data_dir} not found. Downloading images.zip from {ASSETS_URL}/images.zip")
+            from ultralytics.utils.downloads import safe_download
+
+            safe_download(url=f"{ASSETS_URL}/images.zip", unzip=True, retry=3)
+            self.data_dir = Path("images")
+
+        self.clip_model, _, self.preprocess = self.open_clip.create_model_and_transforms(
+            self.model_name, pretrained="openai"
+        )
+        self.clip_model = self.clip_model.to(self.device).eval()
+        self.tokenizer = self.open_clip.get_tokenizer(self.model_name)
+
+        self.index = None
+        self.image_paths = []
+
+        self.load_or_build_index()
+
+    def extract_image_feature(self, path):
+        """Extract CLIP image embedding."""
+        image = Image.open(path)
+        tensor = self.preprocess(image).unsqueeze(0).to(self.device)
+        with torch.no_grad():
+            return self.clip_model.encode_image(tensor).cpu().numpy()
+
+    def extract_text_feature(self, text):
+        """Extract CLIP text embedding."""
+        tokens = self.tokenizer([text]).to(self.device)
+        with torch.no_grad():
+            return self.clip_model.encode_text(tokens).cpu().numpy()
+
+    def load_or_build_index(self):
+        """Loads FAISS index or builds a new one from image features."""
+        # Check if the FAISS index and corresponding image paths already exist
+        if Path(self.faiss_index).exists() and Path(self.data_path_npy).exists():
+            self.LOGGER.info("Loading existing FAISS index...")
+            self.index = self.faiss.read_index(self.faiss_index)  # Load the FAISS index from disk
+            self.image_paths = np.load(self.data_path_npy)  # Load the saved image path list
+            return  # Exit the function as the index is successfully loaded
+
+        # If the index doesn't exist, start building it from scratch
+        self.LOGGER.info("Building FAISS index from images...")
+        vectors = []  # List to store feature vectors of images
+
+        # Iterate over all image files in the data directory
+        for file in self.data_dir.iterdir():
+            # Skip files that are not valid image formats
+            if file.suffix.lower().lstrip(".") not in IMG_FORMATS:
+                continue
+            try:
+                # Extract feature vector for the image and add to the list
+                vectors.append(self.extract_image_feature(file))
+                self.image_paths.append(file.name)  # Store the corresponding image name
+            except Exception as e:
+                self.LOGGER.warning(f"Skipping {file.name}: {e}")
+
+        # If no vectors were successfully created, raise an error
+        if not vectors:
+            raise RuntimeError("No image embeddings could be generated.")
+
+        vectors = np.vstack(vectors).astype("float32")  # Stack all vectors into a NumPy array and convert to float32
+        self.faiss.normalize_L2(vectors)  # Normalize vectors to unit length for cosine similarity
+
+        self.index = self.faiss.IndexFlatIP(vectors.shape[1])  # Create a new FAISS index using inner product
+        self.index.add(vectors)  # Add the normalized vectors to the FAISS index
+        self.faiss.write_index(self.index, self.faiss_index)  # Save the newly built FAISS index to disk
+        np.save(self.data_path_npy, np.array(self.image_paths))  # Save the list of image paths to disk
+
+        self.LOGGER.info(f"Indexed {len(self.image_paths)} images.")
+
+    def search(self, query, k=30, similarity_thresh=0.1):
+        """Returns top-k semantically similar images to the given query."""
+        text_feat = self.extract_text_feature(query).astype("float32")
+        self.faiss.normalize_L2(text_feat)
+
+        D, index = self.index.search(text_feat, k)
+        results = [
+            (self.image_paths[i], float(D[0][idx])) for idx, i in enumerate(index[0]) if D[0][idx] >= similarity_thresh
+        ]
+        results.sort(key=lambda x: x[1], reverse=True)
+
+        self.LOGGER.info("\nRanked Results:")
+        for name, score in results:
+            self.LOGGER.info(f"  - {name} | Similarity: {score:.4f}")
+
+        return [r[0] for r in results]
+
+    def __call__(self, query):
+        """Direct call for search function."""
+        return self.search(query)
+
+
+class SearchApp:
+    """
+    A Flask-based web interface powers the semantic image search experience, enabling users to input natural language
+    queries and instantly view the most relevant images retrieved from the indexed database—all through a clean,
+    responsive, and easily customizable frontend.
+
+    Args:
+        data (str): Path to images to index and search.
+        device (str): Device to run inference on (e.g. 'cpu', 'cuda').
+    """
+
+    def __init__(self, data="images", device=None):
+        """Initialization of the VisualAISearch class for performing semantic image search."""
+        check_requirements("flask")
+        from flask import Flask, render_template, request
+
+        self.render_template = render_template
+        self.request = request
+        self.searcher = VisualAISearch(data=data, device=device)
+        self.app = Flask(
+            __name__,
+            template_folder="templates",
+            static_folder=Path(data).resolve(),  # Absolute path to serve images
+            static_url_path="/images",  # URL prefix for images
+        )
+        self.app.add_url_rule("/", view_func=self.index, methods=["GET", "POST"])
+
+    def index(self):
+        """Function to process the user query and display output."""
+        results = []
+        if self.request.method == "POST":
+            query = self.request.form.get("query", "").strip()
+            results = self.searcher(query)
+        return self.render_template("similarity-search.html", results=results)
+
+    def run(self, debug=False):
+        """Runs the Flask web app."""
+        self.app.run(debug=debug)

ultralytics/solutions/solutions.py

@@ -54,55 +54,56 @@ class BaseSolution:
             is_cli (bool): Enables CLI mode if set to True.
             **kwargs (Any): Additional configuration parameters that override defaults.
         """
-        check_requirements("shapely>=2.0.0")
-        from shapely.geometry import LineString, Point, Polygon
-        from shapely.prepared import prep
-
-        self.LineString = LineString
-        self.Polygon = Polygon
-        self.Point = Point
-        self.prep = prep
-        self.annotator = None  # Initialize annotator
-        self.tracks = None
-        self.track_data = None
-        self.boxes = []
-        self.clss = []
-        self.track_ids = []
-        self.track_line = None
-        self.masks = None
-        self.r_s = None
-
-        self.LOGGER = LOGGER  # Store logger object to be used in multiple solution classes
         self.CFG = vars(SolutionConfig().update(**kwargs))
-        self.LOGGER.info(f"Ultralytics Solutions: ✅ {self.CFG}")
-
-        self.region = self.CFG["region"]  # Store region data for other classes usage
-        self.line_width = self.CFG["line_width"]
-
-        # Load Model and store additional information (classes, show_conf, show_label)
-        if self.CFG["model"] is None:
-            self.CFG["model"] = "yolo11n.pt"
-        self.model = YOLO(self.CFG["model"])
-        self.names = self.model.names
-        self.classes = self.CFG["classes"]
-        self.show_conf = self.CFG["show_conf"]
-        self.show_labels = self.CFG["show_labels"]
-
-        self.track_add_args = {  # Tracker additional arguments for advance configuration
-            k: self.CFG[k] for k in ["iou", "conf", "device", "max_det", "half", "tracker", "device", "verbose"]
-        }  # verbose must be passed to track method; setting it False in YOLO still logs the track information.
-
-        if is_cli and self.CFG["source"] is None:
-            d_s = "solutions_ci_demo.mp4" if "-pose" not in self.CFG["model"] else "solution_ci_pose_demo.mp4"
-            self.LOGGER.warning(f"source not provided. using default source {ASSETS_URL}/{d_s}")
-            from ultralytics.utils.downloads import safe_download
-
-            safe_download(f"{ASSETS_URL}/{d_s}")  # download source from ultralytics assets
-            self.CFG["source"] = d_s  # set default source
-
-        # Initialize environment and region setup
-        self.env_check = check_imshow(warn=True)
-        self.track_history = defaultdict(list)
+        self.LOGGER = LOGGER  # Store logger object to be used in multiple solution classes
+
+        if self.__class__.__name__ != "VisualAISearch":
+            check_requirements("shapely>=2.0.0")
+            from shapely.geometry import LineString, Point, Polygon
+            from shapely.prepared import prep
+
+            self.LineString = LineString
+            self.Polygon = Polygon
+            self.Point = Point
+            self.prep = prep
+            self.annotator = None  # Initialize annotator
+            self.tracks = None
+            self.track_data = None
+            self.boxes = []
+            self.clss = []
+            self.track_ids = []
+            self.track_line = None
+            self.masks = None
+            self.r_s = None
+
+            self.LOGGER.info(f"Ultralytics Solutions: ✅ {self.CFG}")
+            self.region = self.CFG["region"]  # Store region data for other classes usage
+            self.line_width = self.CFG["line_width"]
+
+            # Load Model and store additional information (classes, show_conf, show_label)
+            if self.CFG["model"] is None:
+                self.CFG["model"] = "yolo11n.pt"
+            self.model = YOLO(self.CFG["model"])
+            self.names = self.model.names
+            self.classes = self.CFG["classes"]
+            self.show_conf = self.CFG["show_conf"]
+            self.show_labels = self.CFG["show_labels"]
+
+            self.track_add_args = {  # Tracker additional arguments for advance configuration
+                k: self.CFG[k] for k in ["iou", "conf", "device", "max_det", "half", "tracker", "device", "verbose"]
+            }  # verbose must be passed to track method; setting it False in YOLO still logs the track information.
+
+            if is_cli and self.CFG["source"] is None:
+                d_s = "solutions_ci_demo.mp4" if "-pose" not in self.CFG["model"] else "solution_ci_pose_demo.mp4"
+                self.LOGGER.warning(f"source not provided. using default source {ASSETS_URL}/{d_s}")
+                from ultralytics.utils.downloads import safe_download
+
+                safe_download(f"{ASSETS_URL}/{d_s}")  # download source from ultralytics assets
+                self.CFG["source"] = d_s  # set default source
+
+            # Initialize environment and region setup
+            self.env_check = check_imshow(warn=True)
+            self.track_history = defaultdict(list)
 
     def adjust_box_label(self, cls, conf, track_id=None):
         """

{ultralytics-8.3.126.dist-info → ultralytics-8.3.127.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ultralytics
-Version: 8.3.126
+Version: 8.3.127
 Summary: Ultralytics YOLO 🚀 for SOTA object detection, multi-object tracking, instance segmentation, pose estimation and image classification.
 Author-email: Glenn Jocher <glenn.jocher@ultralytics.com>, Jing Qiu <jing.qiu@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>
@@ -70,6 +70,7 @@ Requires-Dist: h5py!=3.11.0; platform_machine == "aarch64" and extra == "export"
 Provides-Extra: solutions
 Requires-Dist: shapely>=2.0.0; extra == "solutions"
 Requires-Dist: streamlit>=1.29.0; extra == "solutions"
+Requires-Dist: flask; extra == "solutions"
 Provides-Extra: logging
 Requires-Dist: wandb; extra == "logging"
 Requires-Dist: tensorboard; extra == "logging"

{ultralytics-8.3.126.dist-info → ultralytics-8.3.127.dist-info}/RECORD

@@ -6,8 +6,8 @@ tests/test_engine.py,sha256=aGqZ8P7QO5C_nOa1b4FOyk92Ysdk5WiP-ST310Vyxys,4962
 tests/test_exports.py,sha256=dhZn86LdbapW15RthQF870LGxDjC1MUZhlGdBgPmgIQ,9716
 tests/test_integrations.py,sha256=dQteeRsRVuT_p5-T88-7jqT65Zm9iAXkyKg-KQ1_TQ8,6341
 tests/test_python.py,sha256=hkOJc0Ejin3Bywyw0BT4pPex5hwwfbmw0K5ChRtvdvw,25398
-tests/test_solutions.py,sha256=BIvg9zW0a_ggEmrPKgB_Y0MncveH-eYuN5KlqdJ6nHs,5726
-ultralytics/__init__.py,sha256=HfUbgU67v26Obhd8l6aWhYnTG8W_ycy0mBgszTdxe6E,730
+tests/test_solutions.py,sha256=IFlqyOUCvGbLe_YZqWmNCe_afg4as0p-SfAv3j7VURI,6205
+ultralytics/__init__.py,sha256=rW2L-G5wnwjbBDeXcA2NLIjdA291K6epdl33-rsgZak,730
 ultralytics/assets/bus.jpg,sha256=wCAZxJecGR63Od3ZRERe9Aja1Weayrb9Ug751DS_vGM,137419
 ultralytics/assets/zidane.jpg,sha256=Ftc4aeMmen1O0A3o6GCDO9FlfBslLpTAw0gnetx7bts,50427
 ultralytics/cfg/__init__.py,sha256=We3ti0mvUQrGRmUPcufDGboW0YAO3nSRYuoWxGagk3M,39462
@@ -202,10 +202,10 @@ ultralytics/nn/modules/conv.py,sha256=nxbfAxmvo6A9atuxY3LXTtzMXhihZapCSg1F5mI4sI
 ultralytics/nn/modules/head.py,sha256=FbFB-e44Zvxgzdfy0FqeGWUn0DDahmEZvD1W_N2olcM,38442
 ultralytics/nn/modules/transformer.py,sha256=tC80QKFaLtWZo0zVNTuORX4pOu6HVs2wS0vSM-3h5W4,28227
 ultralytics/nn/modules/utils.py,sha256=rn8yTObZGkQoqVzjbZWLaHiytppG4ffjMME4Lw60glM,6092
-ultralytics/solutions/__init__.py,sha256=pjNYva0qnw-4hf_tTLx_dgIfg24XrYLLp3kygPj95rs,1113
+ultralytics/solutions/__init__.py,sha256=ZoeAQavTLp8aClnhZ9tbl6lxy86GxofyGvZWTx2aWkI,1209
 ultralytics/solutions/ai_gym.py,sha256=QRrZGMka83NY4B9gU3N2GxTaomo0WmTMNLxkNZTxo9U,5763
 ultralytics/solutions/analytics.py,sha256=u-khRAViGupjq9mkuAFCl9G3yE8hXfXASfKZd_SQZ-8,12111
-ultralytics/solutions/config.py,sha256=ogXWpE0LhVXHz05M2ChrVu5usIxsRy2yxraHuSyc_V0,5330
+ultralytics/solutions/config.py,sha256=TLxQuZjqW-vhbS2OFmTT188-31ukHg1XP7l-BeOmqbU,5427
 ultralytics/solutions/distance_calculation.py,sha256=E13siGlQTqaGCk0xULk5Q86PwxiBAL4XWp83kQPb0YE,5751
 ultralytics/solutions/heatmap.py,sha256=lXYptA_EbypipF7YJMjsxxBzLAgsroLcdqypvNAhduA,5569
 ultralytics/solutions/instance_segmentation.py,sha256=HxzFf752PwjAjZhrf8BzI-gEey_f9mjxTOqJsLHSIB8,3498
@@ -216,7 +216,8 @@ ultralytics/solutions/parking_management.py,sha256=BV-2lpSfgmK7fib3DnPSZ5rtLdy11
 ultralytics/solutions/queue_management.py,sha256=p1-cuI_rs4ygtlBryXjE65NYG2bnZXhp3ylggFnWcRs,4344
 ultralytics/solutions/region_counter.py,sha256=Zn35YRXNzhBk27D9MLOHBYe2L1o6H2ey3mEwCXofB_E,5418
 ultralytics/solutions/security_alarm.py,sha256=cmUWvz7U9IAxlOr-QCIU_j95lc2c8eUx9wI04t1vDFU,6251
-ultralytics/solutions/solutions.py,sha256=MV2sKr0mHVMh-dT2SmiYkYLFCdoNz-2VA0z4a7fWK_8,32503
+ultralytics/solutions/similarity_search.py,sha256=joejjaw0FWfZKnkNJQhT9l7Hz9jkquLu8JY7B6Iy93g,7535
+ultralytics/solutions/solutions.py,sha256=aXU5p6zv8UPyaC8v51tsE9L_KzmnRCP4M9PP6pAYMXQ,32715
 ultralytics/solutions/speed_estimation.py,sha256=r7S5nGIx8PTV-zC4zCI36lQD2DVy5cen5cTXItfQIHo,5318
 ultralytics/solutions/streamlit_inference.py,sha256=M0ppTFInqSPrdytZBLH8x-XoA7zFc7PaRQ51wHG9ppU,9846
 ultralytics/solutions/trackzone.py,sha256=mfklnZcVRqI3bbhPiHF2iSoV6INcd10wwwGP4tlK7L0,3854
@@ -261,9 +262,9 @@ ultralytics/utils/callbacks/neptune.py,sha256=JaI95Cj2kIjUhlEEOiDN0-Drc-fDelLhNI
 ultralytics/utils/callbacks/raytune.py,sha256=A8amUGpux7dYES-L1iSeMoMXBySGWCD1aUqT7vcG-pU,1284
 ultralytics/utils/callbacks/tensorboard.py,sha256=jgYnym3cUQFAgN1GzTyO7l3jINtfAh8zhrllDvnLuVQ,5339
 ultralytics/utils/callbacks/wb.py,sha256=iDRFXI4IIDm8R5OI89DMTmjs8aHLo1HRCLkOFKdaMG4,7507
-ultralytics-8.3.126.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
-ultralytics-8.3.126.dist-info/METADATA,sha256=zkgsqHwnXIUCbSDzK_gK_HunHRJAQvvvIgix7NOzXgw,37180
-ultralytics-8.3.126.dist-info/WHEEL,sha256=GHB6lJx2juba1wDgXDNlMTyM13ckjBMKf-OnwgKOCtA,91
-ultralytics-8.3.126.dist-info/entry_points.txt,sha256=YM_wiKyTe9yRrsEfqvYolNO5ngwfoL4-NwgKzc8_7sI,93
-ultralytics-8.3.126.dist-info/top_level.txt,sha256=XP49TwiMw4QGsvTLSYiJhz1xF_k7ev5mQ8jJXaXi45Q,12
-ultralytics-8.3.126.dist-info/RECORD,,
+ultralytics-8.3.127.dist-info/licenses/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+ultralytics-8.3.127.dist-info/METADATA,sha256=bWJ0fJoFESEzhGqAO3ox4uQ5b0EnneDRxfHn3D1efDs,37223
+ultralytics-8.3.127.dist-info/WHEEL,sha256=GHB6lJx2juba1wDgXDNlMTyM13ckjBMKf-OnwgKOCtA,91
+ultralytics-8.3.127.dist-info/entry_points.txt,sha256=YM_wiKyTe9yRrsEfqvYolNO5ngwfoL4-NwgKzc8_7sI,93
+ultralytics-8.3.127.dist-info/top_level.txt,sha256=XP49TwiMw4QGsvTLSYiJhz1xF_k7ev5mQ8jJXaXi45Q,12
+ultralytics-8.3.127.dist-info/RECORD,,