ultralytics 8.3.126__tar.gz → 8.3.127__tar.gz

{ultralytics-8.3.126/ultralytics.egg-info → ultralytics-8.3.127}/PKG-INFO

@@ -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 → ultralytics-8.3.127}/pyproject.toml

@@ -105,6 +105,7 @@ export = [
 solutions = [
     "shapely>=2.0.0",    # shapely for point and polygon data matching
     "streamlit>=1.29.0",    # for live inference on web browser, i.e `yolo streamlit-predict`
+    "flask",  # for similarity search solution
 ]
 logging = [
     "wandb", # https://docs.ultralytics.com/integrations/weights-biases/

{ultralytics-8.3.126 → ultralytics-8.3.127}/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-8.3.126 → ultralytics-8.3.127}/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-8.3.126 → ultralytics-8.3.127}/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-8.3.126 → ultralytics-8.3.127}/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-8.3.127/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-8.3.126 → ultralytics-8.3.127}/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 → ultralytics-8.3.127/ultralytics.egg-info}/PKG-INFO

@@ -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 → ultralytics-8.3.127}/ultralytics.egg-info/SOURCES.txt

@@ -232,6 +232,7 @@ ultralytics/solutions/parking_management.py
 ultralytics/solutions/queue_management.py
 ultralytics/solutions/region_counter.py
 ultralytics/solutions/security_alarm.py
+ultralytics/solutions/similarity_search.py
 ultralytics/solutions/solutions.py
 ultralytics/solutions/speed_estimation.py
 ultralytics/solutions/streamlit_inference.py

{ultralytics-8.3.126 → ultralytics-8.3.127}/ultralytics.egg-info/requires.txt

@@ -58,3 +58,4 @@ mlflow
 [solutions]
 shapely>=2.0.0
 streamlit>=1.29.0
+flask