Сопоставление объектов с помощью VisionEye View и Ultralytics YOLO26
Что такое сопоставление объектов VisionEye?#
VisionEye в Ultralytics YOLO26 позволяет компьютерам распознавать объекты и определять их местоположение, имитируя точность наблюдения человеческого глаза. Эта функция позволяет компьютерам различать объекты и фокусироваться на конкретных из них так же, как человеческий глаз замечает детали с определённой точки обзора.
Сопоставляй объекты с помощью YOLO26#
VisionEye задаёт в кадре фиксированную точку наблюдения и проводит от неё луч к каждому отслеживаемому объекту, позволяя визуализировать сцену с одной точки обзора. Задай vision_point как пиксельные координаты наблюдателя, а затем запусти решение на видео с помощью Python API или CLI.
# Monitor objects position with visioneye
yolo solutions visioneye show=True
# Pass a source video
yolo solutions visioneye source="path/to/video.mp4"
# Monitor the specific classes
yolo solutions visioneye classes="[0, 5]"Аргументы VisionEye#
Вот таблица с аргументами VisionEye:
| Аргумент | Тип | По умолчанию | Описание |
|---|---|---|---|
model | str | None | Путь к файлу модели Ultralytics YOLO. |
vision_point | tuple[int, int] | (20, 20) | Точка, в которой Vision отслеживает объекты и рисует траектории с помощью решения VisionEye. |
line_width | int | 2 | Толщина линий рамок, ключевых точек и счётчиков, которые рисует решение. |
verbose | bool | True | Включает журнал решения для каждого кадра с указанием формы входных данных, количества объектов по классам и скорости обработки. Сам вызов отслеживания всегда выполняется без вывода сообщений. |
В решении VisionEye также можно использовать различные аргументы track:
| Аргумент | Тип | По умолчанию | Описание |
|---|---|---|---|
tracker | str | 'tracktrack.yaml' | Задаёт алгоритм отслеживания. Встроенные варианты: botsort.yaml, bytetrack.yaml, ocsort.yaml, deepocsort.yaml, fasttrack.yaml, tracktrack.yaml. |
conf | float | 0.25 | Задаёт порог уверенности для обнаружений: при более низких значениях можно отслеживать больше объектов, но возрастает вероятность ложноположительных срабатываний. |
iou | float | 0.5 | Задаёт порог пересечения над объединением (IoU) для фильтрации перекрывающихся обнаружений. |
classes | list | None | Фильтрует результаты по индексу класса. Например, classes=[0, 2, 3] отслеживает только указанные классы. |
device | str | None | Задаёт устройство для инференса (например, cpu, cuda:0 или 0). Позволяет выбрать CPU, определённый GPU или другое вычислительное устройство для выполнения модели. |
imgsz | int or tuple | 640 | Целевой размер изображения для инференса: целое число для квадратного изображения или пара (height, width). Размеры корректируются с учётом шага модели. |
max_det | int | 300 | Максимальное количество обнаружений, сохраняемых в каждом кадре перед отслеживанием; ограничивает число объектов, обрабатываемых решением в насыщенных сценах. |
quantize | int or str | None | Точность инференса: 16 (FP16) или 32/unset (FP32) для моделей PyTorch и TorchScript не на CPU; для других форматов точность определяется артефактом модели и средой выполнения. Заменяет устаревший аргумент half. |
Кроме того, поддерживаются некоторые аргументы визуализации, перечисленные ниже:
| Аргумент | Тип | По умолчанию | Описание |
|---|---|---|---|
show | bool | False | Если True, показывает аннотированные изображения или видео в окне. Полезно для мгновенной визуальной проверки во время разработки или тестирования. |
show_conf | bool | True | Показывает оценку уверенности каждой детекции рядом с меткой. Позволяет оценить уверенность модели в каждой детекции. |
show_labels | bool | True | Показывает метки каждой детекции на визуализации. Помогает сразу понять, какие объекты обнаружены. |
Как работает VisionEye#
VisionEye задаёт в кадре фиксированную точку наблюдения и проводит от неё линии к обнаруженным объектам. Это имитирует способность человеческого зрения фокусироваться на нескольких объектах с одной точки обзора. Решение использует отслеживание объектов, чтобы сохранять их идентификацию от кадра к кадру и наглядно показывать пространственные отношения между наблюдателем (точкой обзора) и объектами в сцене.
Метод process класса VisionEye выполняет несколько основных операций:
- Извлекает треки (ограничивающие рамки, классы и идентификаторы треков) из входного изображения
- Создаёт аннотатор для отрисовки ограничивающих рамок и меток
- Для каждого обнаруженного объекта рисует рамку с меткой и проводит линию от точки обзора
- Возвращает аннотированное изображение со статистикой отслеживания
Этот подход особенно полезен в приложениях, которым важно учитывать пространственное окружение и визуализировать взаимосвязи объектов, например в системах видеонаблюдения, автономной навигации и интерактивных инсталляциях.
Применение VisionEye#
Сопоставление объектов с помощью VisionEye находит множество практических применений в различных отраслях:
- Безопасность и видеонаблюдение: отслеживание нескольких интересующих объектов с фиксированной позиции камеры
- Аналитика розничной торговли: отслеживание перемещений покупателей относительно витрин и выкладки товаров
- Спортивная аналитика: анализ расположения и перемещений игроков с точки зрения тренера
- Автономные транспортные средства: визуализация того, как транспортное средство «видит» объекты вокруг себя и определяет их приоритет
- Взаимодействие человека с компьютером: создание более интуитивных интерфейсов, учитывающих пространственные взаимосвязи
Сочетая VisionEye с другими решениями Ultralytics, например с расчётом расстояния или оценкой скорости, ты можешь создавать комплексные системы, которые не только отслеживают объекты, но и распознают их пространственные взаимосвязи и поведение.
Часто задаваемые вопросы#
Чтобы начать использовать VisionEye Object Mapping с Ultralytics YOLO26, сначала установи пакет Ultralytics с помощью pip. Затем используй пример кода из документации, чтобы настроить обнаружение объектов с VisionEye. Вот простой пример для начала:
import cv2 from ultralytics import solutions cap = cv2.VideoCapture("path/to/video.mp4") assert cap.isOpened(), "Error reading video file" # Запись видео w, h, fps = (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) video_writer = cv2.VideoWriter("vision-eye-mapping.avi", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h)) # Инициализация объекта VisionEye visioneye = solutions.VisionEye( show=True, # отобразить результат model="yolo26n.pt", # используй любую модель, поддерживаемую Ultralytics, например yolo26s.pt classes=[0, 2], # создание представления VisionEye для выбранных классов ) # Обработка видео while cap.isOpened(): success, im0 = cap.read() if not success: print("Video frame is empty or video processing has been successfully completed.") break results = visioneye(im0) print(results) # доступ к результату video_writer.write(results.plot_im) # запись видеофайла cap.release() video_writer.release() cv2.destroyAllWindows() # закрытие всех открытых оконUltralytics YOLO26 сочетает скорость, точность и простоту интеграции, поэтому отлично подходит для картирования и отслеживания объектов. Ключевые преимущества:
- Производительность в реальном времени: обеспечивает высокую точность обнаружения объектов в реальном времени.
- Гибкость: обнаружение объектов, отслеживание и расчёт расстояния в рамках одного конвейера.
- Сообщество и поддержка: подробная документация и активное сообщество GitHub, где можно получить помощь в устранении неполадок и улучшении решения.
- Простота использования: интуитивно понятный API упрощает сложные задачи и позволяет быстро развёртывать и дорабатывать решение.
Подробнее о применении и преимуществах читай в документации Ultralytics YOLO26.
Ultralytics YOLO26 интегрируется с различными инструментами машинного обучения, такими как Comet и ClearML, для отслеживания экспериментов, совместной работы и воспроизводимости. Чтобы начать, следуй подробным руководствам по интеграции YOLO26 с Comet и интеграции YOLO26 с ClearML.
Дополнительные материалы и примеры интеграции смотри в руководстве по интеграциям Ultralytics.
Комментарии60
Задай вопрос, поделись результатами или помоги кому-нибудь.
TranDHoa
Hey, you can adjust the viewing angle of the eyes and make it measure the distance from the center of an object instead of from the edge.
Glenn JocherUltralyticsVisionEye already draws the ray from
vision_pointto the bounding-box centroid (not the edge) viaSolutionAnnotator.visioneye()as shown in the VisionEye guide and the SolutionAnnotatorvisioneye()reference; there isn’t a separate “viewing angle” parameter today since it’s a 2D overlay, so the intended control is movingvision_point, and if you need an actual distance value (vs just a line), please use the Distance Calculation solution and share your desired behavior here (plus a short clip/frame +vision_point) so the team can advise the cleanest extension.
dixroby
What dependencies are included in the requirements.txt file?
Glenn JocherUltralytics@dixroby the
requirements.txtfile typically includes dependencies liketorch,opencv-python, and other libraries necessary for running Ultralytics YOLO models. For a detailed list, please check the file directly in the repository.
FarrelCulbert
Hi, I would like to know if this is only compatible with YOLOv8, or can I use it with all models?
Glenn JocherUltralytics(изменено)@FarrelCulbert VisionEye Object Mapping is not limited to YOLOv8: it works with the tracking-capable Ultralytics models you pass via
model=, including YOLO26 (recommended) and YOLO11. For more detailed information and examples, you can refer to the VisionEye documentation at https://docs.ultralytics.com/guides/vision-eye/.
skp4595
rather than taking video as input fro testing, I want to test for an image, how can I do that? guide me on this.
Glenn JocherUltralytics(изменено)Hi there!
Great question! If you want to test an image instead of a video using Ultralytics YOLO, it's quite straightforward. Below is a simple example to guide you through the process:
Testing on an Image
First, ensure you have the latest versions of
torchandultralyticsinstalled. If not, please update them:pip install --upgrade torch ultralyticsNext, you can use the following code to test an image:
import cv2 from ultralytics import YOLO from ultralytics.utils.plotting import Annotator, colors # Load the model model = YOLO("yolo26n.pt") # Load the image image_path = "path/to/your/image.jpg" im0 = cv2.imread(image_path) # Perform prediction results = model.predict(im0) boxes = results[0].boxes.xyxy.cpu() clss = results[0].boxes.cls.cpu().tolist() # Annotate the image annotator = Annotator(im0, line_width=2) names = model.model.names for box, cls in zip(boxes, clss): annotator.box_label(box, label=names[int(cls)], color=colors(int(cls))) # Display the annotated image cv2.imshow("YOLO Image Prediction", im0) cv2.waitKey(0) cv2.destroyAllWindows()Explanation
- Load the Model: We load the YOLO model.
- Load the Image: Read the image using OpenCV.
- Perform Prediction: Use the model to predict objects in the image.
- Annotate the Image: Draw bounding boxes and labels on the image.
- Display the Image: Show the annotated image using OpenCV.
This should help you get started with testing images. If you encounter any issues or have further questions, feel free to ask! 😊
For more detailed information, you can refer to the VisionEye Object Mapping Guide.
Happy coding! 🚀
skp4595
I want to run VisionEye Object Mapping using YOLOv8 code on KITTI data set. the KITTI dataset is labeled as <class_name1, truncation, occlusion, observation angle alpha, bbox cordinantes, Dimension of object, Location, rotation_y, score > for each image. While model training, I'm getting this error train: WARNING ⚠️ /content/dataset/train/images/005936.png: ignoring corrupt image/label: could not convert string to float: 'Car' train: WARNING ⚠️ /content/dataset/train/images/005937.png: ignoring corrupt image/label: could not convert string to float: 'Pedestrian' train: WARNING ⚠️ /content/dataset/train/images/005938.png: ignoring corrupt image/label: could not convert string to float: 'Truck'
with these args { EPOCHS = 5 !yolo
task=detect
mode=train
model=yolov8s.pt
imgsz=640
data=depth_estimation_using_YOLOv8.yaml
epochs={EPOCHS}
batch=16
name=yolov8s
exist_ok=True
amp=False } how do I fix this?skp4595
how is this model trained? some details on dataset would be great help
Paula DerrengerUltralytics(изменено)Hi! The model is trained using the YOLOv8 framework. You can train it on custom datasets like KITTI by converting the dataset to the YOLO format. The dataset should have labels in the format
<class_id> <x_center> <y_center> <width> <height>.For more details on VisionEye Object Mapping, check out the Ultralytics VisionEye guide. If you have any specific questions, feel free to ask! 🚀
Here's a sample training command:
yolo task=detect mode=train model=yolo26s.pt data=your_dataset.yaml epochs=5 batch=16Happy training! 😊
1
skp4595
what does this mean "It calculates this distance by analyzing the size and position of the object within the frame, using the camera's field of view and other calibration parameters if available"? what do you mean by 'other calibration parameter if possible'? The model is not a blackbox. Is it? there must be some calibration, some ground truth from where model must have learned. please explain this.
Glenn JocherUltralytics(изменено)Hello! Great questions about the VisionEye Object Mapping using Ultralytics YOLOv8.
-
Distance Calculation: The phrase "It calculates this distance by analyzing the size and position of the object within the frame, using the camera's field of view and other calibration parameters if available" was inaccurate. The VisionEye distance example does not estimate camera-to-object distance from object size or field of view. It computes the pixel distance between the vision point and the bounding-box centroid and divides it by the
pixel_per_metervalue you set, so you calibrate that scale yourself. -
Other Calibration Parameters: The example uses none of these. You would need data such as camera intrinsic parameters (focal length, optical centers), extrinsic parameters (orientation and position of the camera), object size references, or a depth sensor only if you build a true camera-to-object distance estimate yourself.
-
Model Transparency: YOLOv8 models are not black boxes in the sense that their architecture and training processes are open for examination and modification. They learn from labeled data (ground truth) where objects are manually annotated in images, teaching the model how to recognize similar objects in new images.
For further details or specific implementations, feel free to check out our guide on VisionEye Object Mapping at Ultralytics VisionEye Guide. If you have more questions or need clarification, don't hesitate to reach out! 😊
-
mirhasnainsiba
i am getting version incompatiblity issues, tell me your system's python version
Paula DerrengerUltralytics(изменено)Hey there! 😊 It sounds like you're encountering some version compatibility issues. For Ultralytics YOLOv8, we generally recommend using Python 3.8 or newer as it strikes a good balance between being up-to-date and maintaining compatibility with most dependencies.
If you're using a Python version older than 3.7, you might run into issues, and it's a good idea to update to at least version 3.7 or newer if possible. Here's a quick way to check your current Python version from your terminal:
python --version # or if you have Python 3 installed as 'python3' python3 --versionAnd if you need to update Python, the official Python Downloads page is a great place to start.
If you're still facing issues after checking your Python version, could you please provide more details about the error messages you're seeing? This information can help us pinpoint the problem more accurately. Thanks!
mirhasnainsiba
it is telling distance 61m while object is almost 1 m far
Paula DerrengerUltralytics@mirhasnainsiba hi there! 👋 It seems there might be a discrepancy with the distance calculation in your setup. Typically, the distance calculated by the model would depend on the scale set in your system (for example,
pixel_per_meterin the example). If the object is being reported as 61m away while it's actually about 1m away, you might want to adjust this scale factor accordingly. Here's a brief example:pixel_per_meter = 100 # Adjust this value based on your actual scaleThis adjustment helps calibrate the distance calculation to more accurately reflect real-world distances. If you continue to experience issues, double-check the calibration process or consider revisiting the portion of your code responsible for calculating distances. If further assistance is needed, feel free to reach out! 🛠️
mirhasnainsiba
thanks
Paula DerrengerUltralyticsHey there! 😊 Thanks for reaching out. If you're observing an object distance as 61m while it's almost 1m away, you might want to adjust the
pixel_per_meterscaling factor in your VisionEye implementation. This adjustment is crucial for accurate distance calculation.Here's a simplified approach:
pixel_per_meter = 100 # This is just an example value. # You'll need to calibrate this based on your specific setup and camera properties.By fine-tuning this variable, you can achieve more accurate distance measurements. Calibration involves comparing known distances with the pixel distances detected by your model to find the most suitable
pixel_per_metervalue. 🛠️Hope this helps! Let us know if you have any further questions or if there are more details you'd like to dive into.
magickoo
where is the dataset(video file)?
Paula DerrengerUltralyticsHey there! 🌟
The video files used in our examples are not provided in the repository. You can use any video file that you have access to by placing it in an accessible directory and then modifying the
"path/to/video/file.mp4"placeholder in the code snippets to point to your video file's location.For example:
cap = cv2.VideoCapture("your/video/path/here.mp4")Just replace
"your/video/path/here.mp4"with the actual path to your video. If you're looking for sample videos, online resources like Pexels Video or Pixabay Videos offer free footage that you might find useful for your projects.If you have any more questions or need further assistance, don't hesitate to reach out. Happy coding! 🚀
1magickoo
Okay thankyou!
Paula DerrengerUltralyticsHey! Thank you for checking out the VisionEye Object Mapping with Ultralytics YOLOv8. 🚀 If you're keen to dive into VisionEye Object Mapping for pinpoint precision or even integrate object tracking and distance calculation, the provided Python examples can guide you seamlessly through the process.
Just remember to replace
"path/to/video/file.mp4"with the specific path to your video file, and you’re all set to explore the amazing capabilities of YOLOv8 with VisionEye!For pinpoint object mapping:
model = YOLO("yolov8n.pt") # Adjust model as needed cap = cv2.VideoCapture("your/video/path.mp4") # Your video path hereFor any additional queries or discussions, feel free to drop a message in our GitHub Issue Section. Happy coding! 🎉
AdadAlShabab
Hi, I just wanted to know about "VisionEye View with Distance". What does this 'Distance' means? I mean does it measure the distance from the camera to object? Please let me know. TIA.
Paula DerrengerUltralytics(изменено)@AdadAlShabab hey there! 👋
No, the "Distance" in the VisionEye example is not a camera-to-object distance. It is the pixel distance between the vision point and the detected object's bounding-box centroid, divided by a
pixel_per_meterscale that you set and calibrate yourself. Here's a simplified example of how you might calculate distance in a custom script:import cv2 import math from ultralytics import YOLO model = YOLO("yolo26s.pt") cap = cv2.VideoCapture("path/to/video.mp4") while True: ret, im0 = cap.read() if not ret: break results = model.track(im0, persist=True) for box in results[0].boxes.xyxy.cpu(): # Example: Calculate distance based on object size or position here # This is a placeholder for actual distance calculation logic distance = calculate_distance(box) print(f"Distance: {distance} meters")In this example,
calculate_distancewould be a function you define based on your specific distance estimation method. Keep in mind, accurate distance measurement might require camera calibration and knowing the actual size of the object or using depth sensors in conjunction with the camera.Hope this helps! Let us know if you have any more questions. 😊
AdadAlShabab
Hi @pderrenger. Thanks a lot for your reply. I just wanted to know how can I divide the results by 10 ( ex: distance/10)? I'm dropping the code, please let me know in which line/lines I should make the changes? TIA.
Code:
if results[0].boxes.id is not None: track_ids = results[0].boxes.id.int().cpu().tolist() for box, track_id in zip(boxes, track_ids): annotator.box_label(box, label=str(track_id), color=bbox_clr) annotator.visioneye(box, center_point) x1, y1 = int((box[0] + box[2]) // 2), int((box[1] + box[3]) // 2) # Bounding box centroid distance = (math.sqrt((x1 - center_point[0]) ** 2 + (y1 - center_point[1]) ** 2))/pixel_per_meter text_size, _ = cv2.getTextSize(f"Distance: {distance:.2f} m", cv2.FONT_HERSHEY_SIMPLEX,1.2, 3) cv2.rectangle(im0, (x1, y1 - text_size[1] - 10),(x1 + text_size[0] + 10, y1), txt_background, -1) cv2.putText(im0, f"Distance: {distance:.2f} m",(x1, y1 - 5), cv2.FONT_HERSHEY_SIMPLEX, 1.2,txt_color, 3)
Paula DerrengerUltralyticsHi @AdadAlShabab! 👋
To divide the calculated distance by 10, you can adjust the line where
distanceis calculated. Here's how you can modify it:distance = (math.sqrt((x1 - center_point[0]) ** 2 + (y1 - center_point[1]) ** 2)) / pixel_per_meter / 10This change will effectively scale down the calculated distance by a factor of 10. Just add
/ 10at the end of the existing distance calculation line in your code.Hope this helps! Let me know if there's anything else you need. 😊
skp4595
what does this mean "It calculates this distance by analyzing the size and position of the object within the frame, using the camera's field of view and other calibration parameters if available"? what do you mean by 'other calibration parameter if possible'? The model is not a blackbox. Is it? there must be some calibration, some ground truth from where model must have learned. please explain this.
skp4595
why are we dividing "distance " by 'pixel_per_meter' ? what is the logic or explaination for this ?
Paula DerrengerUltralyticsHey there! 👋
The division by
pixel_per_meteris used to convert the measured pixel distance into real-world units like meters. This conversion factor helps translate the scale of the image to actual distances based on how many pixels represent one meter in the image. It's essential for applications where you need to know the physical separation between objects or from the camera to an object, not just the distance in pixels.If you have more questions or need further clarification, feel free to ask! 😊
skp4595
you mean to say, if there's 1 unit Euclidean distance between two pixels in an image, than it'd be 10m in real world scenarios? And this scale can be adjusted according to our will as per "pixel_per_meter = 10" this code. Isn't it?
if so, how is this calibration done? where's the ground truth?
Paula DerrengerUltralyticsHey there! 👋
Yes, exactly! If the
pixel_per_meteris set to 10, it means that 1 pixel in the image corresponds to 0.1 meters in the real world. You can adjust this scale to fit the specific context or calibration of your camera setup.Calibration is typically done by measuring known distances in the real world and adjusting the
pixel_per_metervalue so that the distances in the image accurately reflect these measurements. Ground truth data for calibration might come from physical measurements or known dimensions within the scene.If you have any more questions or need further clarification, feel free to ask! 😊
skp4595
Thank you @pderrenger
Paula DerrengerUltralytics(изменено)You're welcome! 😊
The "VisionEye View with Distance" feature calculates the pixel distance between a reference point and the detected object's centroid, not a true camera-to-object distance. The
pixel_per_metervalue is used to convert pixel measurements to real-world distances. Calibration involves setting this value based on known distances in your scene.To divide the distance by 10, modify the distance calculation line like this:
distance = (math.sqrt((x1 - center_point[0]) ** 2 + (y1 - center_point[1]) ** 2)) / pixel_per_meter / 10For more details, check out the VisionEye guide.
1
leongjy2005
Traceback (most recent call last): File "d:\Random_YOLO8_Tutorials\Human_Detection\visioneye.py", line 28, in annotator.visioneye(box, center_point) ^^^^^^^^^^^^^^^^^^^ AttributeError: 'Annotator' object has no attribute 'visioneye'
leongjy2005
I'm facing this issue, PLEASE HELP. Much Appreciated
Glenn JocherUltralytics(изменено)@leongjy2005
visioneyeis not a method of the baseAnnotator; it lives onSolutionAnnotator. Usefrom ultralytics.solutions.solutions import SolutionAnnotatorandannotator = SolutionAnnotator(im0, line_width=2), or use thesolutions.VisionEyesolution from the VisionEye guide.1leongjy2005
Problem Solved! Thanks!