Estimate Car Speed from Video with Python, YOLO and OpenCV

Can you estimate how fast a vehicle moves using a video? In this Python example, YOLO detects vehicles, a tracker connects detections between frames, and we divide a tracked point’s image displacement by the elapsed video time.

The output in this demonstration is the magnitude of average image-plane velocity in pixels per second (px/s), not road speed in km/h. It is computed from net image displacement, not the distance travelled along the full path. The source is a synthetic traffic video. It has no established real-world scale, so a physical speed cannot be recovered from it just by naming a conversion factor.

Watch the tutorial

Watch the complete Python and YOLO tutorial or see the Short demonstration.

Output from frame 96 of the sample: the yellow box surrounds the selected track, while red points trace its detected box centers. The displayed value is the magnitude of net image displacement divided by four seconds.

From video to a measurable result

1. Open the video and read its frame rate. A frame is one image in a sequence, and FPS is the number of frames per second.
2. Detect vehicles and associate detections across frames. The tracker assigns an ID to an association; it is not a permanent identity or a guarantee of correct tracking.
3. For one continuous track, find the chosen point at the start and end of the measurement interval. In this example the point is the center of its bounding box.
4. Divide the distance in image pixels by the elapsed video time. Label the answer in px/s.

The sample is 1280 × 720 pixels at 24 frames per second. We use the vehicle associated with track ID 2 in frames 0–96. The straight-line screen displacement of its box center is about 302.85 pixels in 4 seconds, or 75.7 px/s. The calculation and output concern this track and interval, not every vehicle in the scene.

How is speed calculated?

For two observations from the same tracked object at frame indices f0 and f1, a constant-frame-rate video gives elapsed_seconds = (f1 - f0) / fps. The two image positions are (x0, y0) and (x1, y1). This example uses the straight-line displacement sqrt((x1 - x0)² + (y1 - y0)²). Dividing it by elapsed seconds gives the magnitude of average image-plane velocity in pixels per second over that interval.

This is net displacement, not total path length, and it is not an instantaneous speed. A curved or back-and-forth path can yield a smaller result than summing every successive movement. FPS must describe the source video correctly; variable-frame-rate footage needs appropriate presentation timestamps rather than assuming constant spacing.

What you need

Use Python and a permitted traffic video. The demonstration ran on Windows, Python 3.13.9, Ultralytics 8.4.24, OpenCV 4.13.0, NumPy 2.3.5, PyTorch 2.10.0+cpu and lap 0.5.13. Other versions, input videos and hardware may change detections and IDs. Install the required packages in a virtual environment; downloading packages and model weights needs an internet connection unless they are already available locally.

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install ultralytics==8.4.24 lap==0.5.13

This command pins two direct packages, not the complete dependency tree. A clean online install of this exact command has not been independently tested; platform, version and hardware differences can affect compatibility and results.

Place an input video and the official yolov8n.pt checkpoint where the script expects them. Course students can find the sample traffic_counter_highway_clip.mp4 in 04_zasoby and yolov8n.pt in 02_praktyka of the lesson 51 practice ZIP. Copy them into the project folder as input.mp4 and yolov8n.pt, respectively; do not assume the video is otherwise licensed for public redistribution. Use your own permitted video if the sample is unavailable: exact tracks and speeds will differ.

Complete Python example

Save the following as measure_screen_speed.py. The source is the same file used for the demonstration. Check the paths and parameters before running.

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Measure image-plane displacement of one tracked car; no real-world calibration."""
import argparse
import json
import math
import os
from pathlib import Path

import cv2


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--video', type=Path, required=True)
    parser.add_argument('--weights', type=Path, required=True)
    parser.add_argument('--output', type=Path, default=Path('speed_output'))
    parser.add_argument('--track-id', type=int, default=2)
    parser.add_argument('--end-frame', type=int, default=96)
    args = parser.parse_args()
    for name, path in [('Video', args.video), ('Weights', args.weights)]:
        if not path.is_file():
            raise FileNotFoundError(f'{name} not found: {path}')
    args.output.mkdir(parents=True, exist_ok=True)
    (args.output / 'config').mkdir(exist_ok=True)
    os.environ.setdefault('YOLO_CONFIG_DIR', str((args.output / 'config').resolve()))
    os.environ.setdefault('YOLO_OFFLINE', 'true')
    os.environ.setdefault('YOLO_AUTOINSTALL', 'false')
    from ultralytics import YOLO
    import torch
    torch.set_num_threads(4)
    model = YOLO(str(args.weights))
    cap = cv2.VideoCapture(str(args.video))
    if not cap.isOpened():
        raise RuntimeError('Could not open video')
    fps = cap.get(cv2.CAP_PROP_FPS)
    if not math.isfinite(fps) or fps <= 0:
        raise ValueError('Invalid video frame rate')
    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
    writer = cv2.VideoWriter(str(args.output / 'annotated.mp4'),
                             cv2.VideoWriter_fourcc(*'mp4v'), fps, (width, height))
    if not writer.isOpened():
        raise RuntimeError('Could not create output video')
    start = None
    path = []
    result = None
    try:
        for frame_number in range(args.end_frame + 1):
            ok, frame = cap.read()
            if not ok:
                raise RuntimeError(f'Video ended at frame {frame_number}')
            prediction = model.track(frame, persist=True, device='cpu', imgsz=640,
                conf=0.20, classes=[2, 3, 5, 7], tracker='bytetrack.yaml',
                verbose=False)[0]
            boxes = prediction.boxes
            matches = [] if boxes.id is None else [box for box in boxes
                       if box.id is not None and int(box.id.item()) == args.track_id]
            if len(matches) != 1:
                raise ValueError(f'Expected one track ID {args.track_id} in frame {frame_number}; got {len(matches)}')
            xyxy = [float(v) for v in matches[0].xyxy[0].tolist()]
            center = ((xyxy[0]+xyxy[2])/2, (xyxy[1]+xyxy[3])/2)
            if start is None:
                start = center
            path.append(tuple(round(x) for x in center))
            elapsed = frame_number / fps
            displacement = math.dist(start, center)
            mean_px_s = displacement / elapsed if elapsed else None
            cv2.rectangle(frame, (round(xyxy[0]),round(xyxy[1])),
                          (round(xyxy[2]),round(xyxy[3])), (0,220,255), 2)
            for pt in path:
                cv2.circle(frame, pt, 2, (0,0,255), -1)
            cv2.circle(frame, path[-1], 6, (0,0,255), -1)
            cv2.rectangle(frame, (10,18), (710,102), (30,30,30), -1)
            cv2.putText(frame, f'Track ID {args.track_id} | frame {frame_number} | {elapsed:.2f} s',
                        (25,55), cv2.FONT_HERSHEY_SIMPLEX, .8, (255,255,255), 2)
            label = 'Screen displacement / elapsed time: ' + (f'{mean_px_s:.1f} px/s' if mean_px_s is not None else 'N/A')
            cv2.putText(frame, label, (25,88), cv2.FONT_HERSHEY_SIMPLEX, .72, (255,255,255), 2)
            writer.write(frame)
            if frame_number in (0, 48, args.end_frame):
                if not cv2.imwrite(str(args.output / f'frame_{frame_number:03d}.png'), frame):
                    raise RuntimeError('Could not write frame')
            if frame_number == args.end_frame:
                result = {'track_id': args.track_id, 'first_frame': 0, 'last_frame': frame_number,
                          'fps': fps, 'width': width, 'height': height, 'elapsed_s': elapsed,
                          'start_xy': start, 'end_xy': center, 'displacement_px': displacement,
                          'mean_screen_displacement_px_per_s': mean_px_s,
                          'definition': 'straight-line image-plane displacement divided by elapsed time',
                          'not_kmh': True}
    finally:
        writer.release()
        cap.release()
    (args.output/'result.json').write_text(json.dumps(result, indent=2), encoding='utf-8')
    print(json.dumps(result, indent=2))


if __name__ == '__main__':
    main()

From the project directory run:

.venv\Scripts\python.exe measure_screen_speed.py --video input.mp4 --weights yolov8n.pt --output speed_output

The defaults select track ID 2 from frames 0 through 96 for this specific example. The script produces speed_output/annotated.mp4, sample annotated PNG frames and speed_output/result.json. It raises an error if the chosen ID is missing in any frame rather than silently guessing an association.

Follow the code

1. Read the source. cv2.VideoCapture opens the input and reads the recorded FPS, width and height. The loop uses zero-based frame numbers and stops at the requested end frame.
2. Detect and associate. model.track(..., persist=True, tracker='bytetrack.yaml') detects the selected vehicle classes and retains tracker state across frames. The code requires exactly one match for the selected ID in every frame; if an association is absent, it stops instead of filling gaps.
3. Pick a point. For each matching box, the midpoint between its left and right coordinates and between its top and bottom coordinates is the box center. The first center becomes the starting position; subsequent centers add visible points to the red trail.
4. Calculate and save. For each later frame, math.dist(start, center) returns the straight-line pixel distance from the starting center. Dividing by elapsed source-video time gives the running net displacement per second; the script saves an annotated MP4 and the final coordinates and numbers in JSON.

The defaults are chosen for this particular clip: ID 2 must be present already in frame 0 and remain present through frame 96. For another video, inspect its tracks and set --track-id and --end-frame to an association that satisfies that condition. The same numeric ID in another run is not necessarily the same physical object. This small script is deliberately strict; it does not automatically find an arbitrary new car later in a clip.

How to check the number

Compare the same vehicle at both endpoints. Check that the displayed ID remains associated with that vehicle throughout the measured interval. Read the endpoint coordinates, frame indices and source FPS; calculate the displacement and elapsed time independently. A different track, box jitter, occlusion or camera movement can change the answer. An ID switch can make an apparently precise calculation describe the wrong association.

For this run, frame 0 gives center approximately (692.45, 306.86), and frame 96 gives (966.27, 436.23). The elapsed time is (96 − 0) / 24 = 4 seconds; sqrt((966.27 − 692.45)² + (436.23 − 306.86)²) is approximately 302.85 pixels. Thus net displacement per second is about 302.85 / 4 = 75.7 px/s. These rounded coordinates are for illustration; the program computes with full precision. We visually inspected sampled frames of the association; this is not a ground-truth accuracy measurement.

Why this is not a speedometer

A pixel is a location in the image, not a fixed distance on the road. Perspective means the same road distance can occupy a different number of pixels in different parts of the image. A moving camera, distortion, an inaccurate frame rate and a box center that shifts as the view changes introduce further errors.

A physical speed estimate requires a calibrated mapping between image and ground-plane positions, a valid time base and a suitable known reference. A single global meters-per-pixel factor is valid only under suitable geometric conditions and assumptions. Even after calibration, compare estimates with independently measured ground truth across representative cases. The Ultralytics speed-estimation guide also describes FPS and scale as inputs and calls the output an estimate.

This demonstration is educational; it is not a validated instrument for enforcement or safety-critical decisions.

Explore further

For a related application, read Count Cars with YOLO: Why Track IDs Are Not Vehicle Counts. For more practical computer vision projects, see my Computer Vision: OpenCV, Machine Learning and YOLO course on Udemy.

Code and component licenses

The example script is © 2026 ARTSCI - Author of the AI/ML/CV course materials, licensed under GNU AGPL-3.0 only, without warranty. Keep applicable notices and provide corresponding source when sharing covered modifications. This notice does not automatically license the source video or other media.

Ultralytics software and model weights have their own terms; review the Ultralytics assets license and Ultralytics licensing information for your intended use. Other dependencies and media may have separate terms.

Remove an Image Background with Python and YOLO Segmentation

How can you remove the background around one object without cutting it out by hand? In this Python tutorial, a pretrained YOLO segmentation model predicts a bus mask on a synthetic city image. We turn that mask into an alpha channel and save a PNG with a transparent background.

Our example selects one predicted bus on a 1024 × 1024 image and runs locally on a Windows CPU. In this run the model returned 12 predictions; those are model outputs, not a verified count of physical objects. A cyclist partly blocks the bus, and the predicted mask does not reconstruct the hidden part.

Watch the Python and YOLO tutorial

Watch the full tutorial or see the short demonstration.

Actual selected instance from the demonstration. The yellow rectangle and green mask are different outputs of the same segmentation prediction.

Box versus mask versus alpha

A bounding box gives a rectangular region. It can contain background or another object, as the cyclist in this image illustrates. An instance segmentation mask marks pixels assigned to one predicted object. That boundary is an estimate; inspect it around occlusion, fine details and similar colors. See the Ultralytics instance segmentation documentation.

A PNG alpha channel controls transparency. In this binary example, an alpha value of 0 means transparent and 255 means opaque. A checkerboard is only a way to visualize transparent pixels: it is not the content of the alpha channel. This code keeps the image's full canvas size instead of cropping to the box.

What you need

The demonstrated run used Windows, Python 3.13.9, Ultralytics 8.4.24, PyTorch 2.10.0+cpu, OpenCV 4.13.0 and NumPy 2.3.5. Other versions or hardware can produce different results. Create a project folder and a virtual environment using Windows Command Prompt:

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install ultralytics==8.4.24

The command pins Ultralytics, not the full set of transitive dependencies; the exact fresh online installation has not been independently tested. Package installation and obtaining the checkpoint require an internet connection unless you already have suitable local files. Once the tested environment and inputs were present, the prediction and export were repeated with network access blocked.

Put an image and a segmentation checkpoint beside the script

Place a permitted color image as image.png and the official YOLOv8n-seg checkpoint as yolov8n-seg.pt alongside the Python file. This example image is included in lesson 37 of my Computer Vision course. For a different permitted input, predictions and output will differ.

background-demo/
├── remove_background.py
├── image.png
└── yolov8n-seg.pt

The tested checkpoint has SHA-256 a7cd8f929e1903d78a12a48efecab430209f18dc46cb96c3599a5980c63c423c. A hash identifies file bytes; it does not by itself grant usage rights. The model file is not hosted by this article.

Complete runnable example

Save the following as remove_background.py in the project folder. The script checks that the local files exist, selects the highest-scoring bus prediction and stops with an explicit message if there is no usable mask or no bus. The target class is an intentional choice for this image; change it deliberately for another object.

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Isolate the highest-scoring bus prediction as a transparent PNG."""
from pathlib import Path
import os

ROOT = Path(__file__).resolve().parent
config_dir = ROOT / 'config'
config_dir.mkdir(exist_ok=True)
os.environ['YOLO_CONFIG_DIR'] = str(config_dir)
os.environ['YOLO_OFFLINE'] = 'true'

import cv2
import numpy as np
import torch
from ultralytics import YOLO


def save_png(path, image):
    if not cv2.imwrite(str(path), image):
        raise OSError(f'Could not save {path}')


def main():
    image_path = ROOT / 'image.png'
    weights_path = ROOT / 'yolov8n-seg.pt'
    for path in (image_path, weights_path):
        if not path.is_file():
            raise FileNotFoundError(f'Required local file: {path}')

    image = cv2.imread(str(image_path), cv2.IMREAD_COLOR)
    if image is None:
        raise ValueError(f'Cannot decode image: {image_path}')
    torch.set_num_threads(4)
    model = YOLO(str(weights_path))
    result = model.predict(
        source=image, conf=0.25, iou=0.70, imgsz=640, device='cpu',
        retina_masks=True, max_det=300, verbose=False,
    )[0]
    if result.masks is None or result.boxes is None:
        raise ValueError('No segmentation masks were returned for this image.')

    candidates = [i for i, box in enumerate(result.boxes)
                  if result.names[int(box.cls.item())] == 'bus']
    if not candidates:
        raise ValueError('No bus prediction passed the confidence threshold.')
    selected = max(candidates, key=lambda i: float(result.boxes[i].conf.item()))
    box = result.boxes[selected]
    mask = result.masks.data[selected].cpu().numpy().astype(np.uint8)
    if mask.shape != image.shape[:2]:
        raise ValueError(f'Mask shape {mask.shape} differs from image {image.shape[:2]}.')

    alpha = mask * 255
    isolated = cv2.cvtColor(image, cv2.COLOR_BGR2BGRA)
    isolated[:, :, 3] = alpha
    isolated[mask == 0, :3] = 0  # Do not keep hidden background pixels.
    output = ROOT / 'output'
    output.mkdir(exist_ok=True)
    save_png(output / 'isolated_bus.png', isolated)
    save_png(output / 'mask.png', alpha)

    highlighted = image.copy()
    highlighted[mask == 1] = (
        image[mask == 1].astype(np.float32) * 0.55
        + np.array([45, 190, 70], dtype=np.float32) * 0.45
    ).astype(np.uint8)
    left, top, right, bottom = [round(float(v)) for v in box.xyxy[0].tolist()]
    cv2.rectangle(highlighted, (left, top), (right, bottom), (40, 220, 255), 3)
    save_png(output / 'selected_mask_and_box.png', highlighted)

    print('Image width x height:', image.shape[1], 'x', image.shape[0])
    print('Total returned predictions:', len(result.boxes))
    print('Selected class:', result.names[int(box.cls.item())])
    print('Selected confidence score:', round(float(box.conf.item()), 4))
    print('Selected box xyxy:', [round(float(v), 1) for v in box.xyxy[0].tolist()])
    print('Foreground pixels:', int(mask.sum()))
    print('Background pixels:', int(mask.size - mask.sum()))
    print('Saved:', output / 'isolated_bus.png')


if __name__ == '__main__':
    main()

From the project directory, run:

.venv\Scripts\python.exe remove_background.py

The script writes output/isolated_bus.png with four BGRA channels, output/mask.png as the alpha mask and output/selected_mask_and_box.png for inspection. The rectangle and colored mask are diagnostic overlays; they are not drawn onto the transparent PNG.

Follow the image through the code

1. Read and predict. OpenCV reads a color image, then the local segmentation model runs on the CPU. The example fixes conf=0.25, iou=0.70 and imgsz=640. retina_masks=True requests masks at the original image resolution; the explicit shape check rejects a mismatch instead of silently combining misaligned arrays.
2. Select one instance. The script filters predictions labelled bus, then chooses the highest confidence among those candidates. It uses the same selected index for the box and mask. Confidence is a model score, not a calibrated guarantee that the label or every mask pixel is correct.
3. Make transparency. The returned mask in this run contains 0 and 1. Multiplying it by 255 creates the alpha plane. OpenCV adds an alpha channel to its BGR image to make BGRA; the code assigns the alpha values and clears hidden background color pixels. It then saves PNG, which preserves transparency.

Actual transparent PNG displayed over a page-provided checkerboard. The image keeps its original 1024 × 1024 canvas. The bicycle rider occludes part of the bus; the script does not invent the unseen portion.

Read and verify the result

The recorded run returned 12 predictions in total. The selected bus had score approximately 0.9458 and box [48.2, 412.2, 476.4, 716.6] in original-image coordinates. Its binary mask produced 98,828 opaque pixels and 949,748 transparent pixels on a 1024 × 1024 canvas. These are measurements of this output, not a pixel-accuracy evaluation against a ground-truth mask.

To check your saved file instead of relying on the checkerboard display, save this separate snippet as verify_alpha.py in the project folder. It reads the PNG with its alpha channel intact and reports its shape and distinct alpha values:

import cv2
import numpy as np

image = cv2.imread("output/isolated_bus.png", cv2.IMREAD_UNCHANGED)
if image is None or image.ndim != 3 or image.shape[2] != 4:
    raise ValueError("Expected a readable image with four BGRA channels")
print("Shape:", image.shape)
print("Alpha values:", np.unique(image[:, :, 3]).tolist())

From the project folder, run .venv\Scripts\python.exe verify_alpha.py.

For the demonstrated output it reports a shape of (1024, 1024, 4) and alpha values [0, 255]. A different image or mask can produce different dimensions and counts. A viewer with a solid background may not make transparency obvious; verify the alpha channel or place the image on a contrasting background.

What this example does not do

Segmentation predicts the visible instance; it does not recover bus pixels hidden behind the cyclist. The binary alpha can also produce rough edges, and the model can include background or miss the object. If there is no suitable bus, inspect the input and class label; lowering the threshold may expose weaker candidates but does not guarantee a correct mask. Validate with representative images and an appropriate reference before relying on the output in a real application.

For another practical view of model outputs, see detecting objects from text labels with YOLO-World. The Ultralytics object-isolation guide discusses segmentation masks and transparent PNG export.

Code and component licenses

The complete example script on this page is © 2026 ARTSCI - Author of the AI/ML/CV course materials, licensed under GNU AGPL-3.0 only, without warranty. Preserve applicable notices and provide corresponding source when sharing covered modifications. This code notice does not automatically license the course image, narration or video.

Ultralytics software and model weights retain their own terms; review the Ultralytics assets license and licensing information for your use. Other dependencies have their own licenses. My full course covers more practical applications: Computer Vision: OpenCV, Machine Learning and YOLO.

YOLO-World in Python: Detect Objects with Text Prompts

Can an object detector look for categories you describe in words? In this Python tutorial we use a pretrained YOLO-World model and an image, choose text labels, and inspect the bounding boxes it returns. We then change the label list and run the model again.

Our example uses a synthetic office image from my course and a local Windows CPU run. With one list the model returned four predictions; with an expanded list it returned nine predictions. Those counts are model outputs, not verified counts of real objects or proof of accuracy.

Watch the YOLO-World tutorial

Watch the full Python tutorial or see the short demonstration.

Actual focused-list detections from the recorded run. This picture is a synthetic teaching example.

What does “no training needed” mean?

YOLO-World is an open-vocabulary object detector: it can accept text class names before prediction. Here we load pretrained YOLO-World and CLIP components and do not train them again. They were trained earlier; “no additional training” does not mean that the model learned from nothing. It also does not guarantee detection of every item or phrase. See the Ultralytics YOLO-World documentation and the original research paper.

What you need

The demonstrated run used Windows 11, Python 3.13.9, Ultralytics 8.4.116, PyTorch 2.13.0+cpu, OpenCV 4.14.0 and NumPy 2.5.1. It used the local YOLOv8s-World checkpoint and the OpenAI CLIP ViT-B/32 text encoder. The installation commands pin Ultralytics and the CLIP fork, not every transitive dependency. Other software versions or devices can change the results. Git is needed for the command that installs the fork from its repository.

From a Windows Command Prompt, create a project folder, then create and install into its virtual environment:

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install ultralytics==8.4.116
.venv\Scripts\python.exe -m pip install "git+https://github.com/ultralytics/CLIP.git@488e81a6711eea7346872b46ea928b367da8889d"

The tested course package includes an already built source-bound wheel for the CLIP fork. The Git-based installation above is an alternative way to get the identified source; this exact fresh online installation was not part of the offline replay. Installing packages and obtaining the files requires a network connection unless you have them available locally.

Prepare the local image and weights

Save the two scripts below next to a permitted image called image.png. The shown image is supplied with lesson 47 of my Computer Vision course. For your own image, the detections and numbers will differ. Download the official Ultralytics YOLOv8s-World checkpoint and the OpenAI CLIP ViT-B/32 checkpoint separately. The latter URL appears in the OpenAI CLIP model registry. Place them as follows:

yolo-world-demo/
├── setup_local.py
├── world_demo.py
├── image.png
├── yolov8s-world.pt
└── weights/
    └── clip/
        └── ViT-B-32.pt

The tested detector checkpoint SHA-256 is 095f5266bb9b654bd5ad9e21e9cdeda78e0f2c8460f5d652eaf04bab7ee251cf; the CLIP file SHA-256 is 40d365715913c9da98579312b702a82c18be219cc2a73407c4526f58eba950af. A hash identifies bytes; it does not itself establish usage rights. Model files are not hosted by this article.

Configure a project-local weights folder

The text encoder must find its local CLIP checkpoint when the class names are set. Run the following small setup script once, as a separate process. It places Ultralytics settings in this project’s config folder and sets its weights directory to this project’s weights folder. This avoids editing your user-wide Ultralytics settings for the demonstration.

Save as setup_local.py:

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Store an isolated Ultralytics weights-directory setting for this example."""
from pathlib import Path
import os

ROOT = Path(__file__).resolve().parent
config_dir = ROOT / 'config'
config_dir.mkdir(exist_ok=True)
os.environ['YOLO_CONFIG_DIR'] = str(config_dir)
import cv2  # Import first in the demonstrated Windows environment.
from ultralytics import settings

settings.update({'weights_dir': str(ROOT / 'weights'), 'sync': False})
print('Project weights directory:', ROOT / 'weights')
print('Run world_demo.py as a separate process after this one exits.')

Run it from the project directory:

.venv\Scripts\python.exe setup_local.py

Then start the following script as a new process so the weights-directory setting is read during initialization. If you move the project folder later, run the setup script again before prediction.

Complete runnable example

Save the following as world_demo.py:

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Compare two text vocabularies with a local pretrained YOLO-World model."""
from pathlib import Path
import os

ROOT = Path(__file__).resolve().parent
# Keep Ultralytics settings in this project, not in your user-wide profile.
config_dir = ROOT / 'config'
config_dir.mkdir(exist_ok=True)
os.environ['YOLO_CONFIG_DIR'] = str(config_dir)
os.environ['YOLO_OFFLINE'] = 'true'

import cv2  # Import first in the demonstrated Windows environment.
import torch
from ultralytics import YOLOWorld
from ultralytics.utils import WEIGHTS_DIR


def main():
    image = ROOT / 'image.png'
    model_file = ROOT / 'yolov8s-world.pt'
    clip_file = ROOT / 'weights' / 'clip' / 'ViT-B-32.pt'
    if Path(WEIGHTS_DIR).resolve() != (ROOT / 'weights').resolve():
        raise RuntimeError('Configure this project weights directory first; see the setup command.')
    for path in (image, model_file, clip_file):
        if not path.is_file():
            raise FileNotFoundError(f'Required local file: {path}')

    torch.set_num_threads(4)
    model = YOLOWorld(str(model_file))
    groups = {
        'focused': ['person', 'backpack', 'laptop', 'cup'],
        'broad': ['person', 'backpack', 'laptop', 'cup', 'chair', 'desk'],
        'single_cup': ['cup'],
        'single_coffee_cup': ['coffee cup'],
    }
    output = ROOT / 'output'
    output.mkdir(exist_ok=True)
    for name, classes in groups.items():
        model.set_classes(classes)
        result = model.predict(
            source=str(image), conf=0.25, iou=0.70, imgsz=640, device='cpu',
            half=False, rect=True, augment=False, agnostic_nms=False,
            max_det=300, verbose=False,
        )[0]
        print(f'\n{name}: {classes} -> {len(result.boxes)} predictions')
        for box in result.boxes:
            label = result.names[int(box.cls.item())]
            score = float(box.conf.item())
            coords = [round(float(v), 1) for v in box.xyxy[0].tolist()]
            print(f'  {label}: score={score:.3f} xyxy={coords}')
        annotated = result.plot()
        if not cv2.imwrite(str(output / f'{name}.png'), annotated):
            raise OSError(f'Could not save output for {name}')
    print(f'\nSaved annotated images in {output}')


if __name__ == '__main__':
    main()

From the project directory, run:

.venv\Scripts\python.exe world_demo.py

For each vocabulary, model.set_classes(classes) configures the class names with the CLIP text encoder. model.predict(...)[0] then runs a new prediction on the image; the subsequent loop reads its boxes. The code saves an annotated image per vocabulary to output/. The illustrations on this page are the actual saved outputs from the demonstrated execution, using Ultralytics’ plotting style.

All four runs use the same input image and checkpoint, conf=0.25, iou=0.70, imgsz=640 and CPU. The two standalone prompts are separate one-class vocabularies; the focused and broad lists are separate runs too. Changing the list can change predictions and scores for shared classes, so the broad result should not be treated as simply appending new boxes to an unchanged prior result. Confidence is a model score, not a calibrated probability that a particular box is correct.

Read the result: focused versus broad

The focused list asks for person, backpack, laptop and cup. In the recorded execution it returned four predictions. The broad list retains those words and adds chair and desk; it returned nine predictions. The change in count does not establish that every additional prediction is correct.

Actual broad-list output. Inspect overlaps and questionable boxes rather than equating nine predictions with nine objects.

For example, the expanded run includes a desk box scoring approximately 0.286 over a region that appears to contain a chair. Another nearby chair prediction overlaps the region. This is a reason to inspect the image and outputs, not evidence that every overlap is a duplicate. Changing the vocabulary also changed the laptop score from about 0.924 to 0.909 in this particular run.

Does wording matter?

We also tried two separate one-class runs on the same image. With ["cup"] the model returned one prediction with score approximately 0.917. With ["coffee cup"] it returned one prediction around the same visible item with score approximately 0.830. These two scores and boxes are observations for this image and these prompts; they do not prove that either phrase is generally better or measure accuracy. Inspect the predictions before relying on them.

Try it yourself

1. Choose an image you have permission to use and predict which objects you expect the model to find.
2. Change just one class name or list in groups, run the script again, and inspect the saved image and printed rows.
3. Compare false positives, missed objects and scores. Keep the input and other settings fixed if you want an interpretable comparison.

For a real application, test a representative labelled set covering the relevant objects, viewpoints and conditions. This single synthetic scene is not an accuracy benchmark, a validated real-time system or a surveillance application. The OpenAI CLIP model card discusses research scope, limitations and potential bias.

Troubleshooting

• “Configure this project weights directory first”: run setup_local.py from the same project and then start world_demo.py in a separate process. Re-run setup after moving the project.
• Missing checkpoint or image: inspect the file paths shown above; the script checks them before model initialization.
• CLIP import or installation problem: verify that the tested Ultralytics CLIP fork is installed in this virtual environment, and that the correct kernel or Python executable is used. The separately named PyPI clip project is not a substitute for the specified fork.
• No detection or an unexpected box: check the input, class wording, visible output and threshold. A lower threshold may show additional weak candidates, but does not automatically improve correctness.

Sources and license

Both complete example scripts on this page are © 2026 ARTSCI - Author of the AI/ML/CV course materials, licensed under GNU AGPL-3.0 only, without warranty. Preserve applicable notices and provide corresponding source when sharing covered modifications. This code notice does not automatically license the course image, narration or video.

Ultralytics software and models retain their own terms; see the Ultralytics assets license and licensing information. Ultralytics states that its YOLO-World weights were migrated from the original YOLO-World project, which describes its own code as GPL-3.0. The Ultralytics CLIP fork and original OpenAI CLIP code have separate license texts; consult the upstream sources and model card for the specific components and your use.

To compare this prompt-based approach with adapting a model on labelled images, see how to fine-tune YOLO on your own images. The full English course covers these ideas and other projects: Computer Vision: OpenCV, Machine Learning and YOLO.

How to Train YOLO on Your Own Images: A Step-by-Step Python Tutorial

How can you make an object detector recognize classes from your own labelled images? In this guide we fine-tune a pretrained YOLOv8n model on a small dataset, then inspect a prediction with Python.

Our example uses 12 synthetic training images and 4 synthetic validation images containing boats and buoys. In one local CPU run, the model predicted two boats and one buoy on the selected validation image. This is an educational example: the validation set helped select the checkpoint, and the result does not establish accuracy on independent real-world data.

Watch the tutorial

Watch the full Python and YOLO tutorial, or see the short demonstration.

Actual prediction from the recorded CPU run on val_02.png. This is a validation image, not an independent final test.

What you will build

1. Organize labelled images into training and validation folders.
2. Understand the normalized YOLO bounding-box format.
3. Point a dataset configuration at those folders.
4. Fine-tune a local pretrained model and load the saved checkpoint.
5. Run a prediction and interpret its limitations.

This is fine-tuning: it starts from pretrained weights, rather than initializing a detector from scratch. You can use your own appropriately licensed images and annotations. The particular synthetic fixture shown here is supplied with lesson 29 of my Computer Vision: OpenCV, Machine Learning and YOLO course.

1. Install the dependencies

The recorded experiment ran on Windows 11 using Python 3.13.9, Ultralytics 8.4.116 and PyTorch 2.13.0+cpu. The commands below create a Windows environment and pin the direct Ultralytics dependency; they do not lock every transitive dependency. Other versions, operating systems and hardware may yield different results.

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install --upgrade pip
.venv\Scripts\python.exe -m pip install ultralytics==8.4.116

Installing packages and obtaining the initial checkpoint need an internet connection unless you already have the required files cached. The training demonstration itself used local images and local weights. Your environment's dependencies and model files must be available first.

2. Organize images and annotations

Create this layout next to the training script. Every image has a corresponding label file with the same base name:

custom-yolo/
├── train_yolo.py
├── yolov8n.pt
└── synthetic_harbor_dataset/
    ├── data.yaml
    ├── images/
    │   ├── train/  (e.g. train_00.png)
    │   └── val/    (e.g. val_02.png)
    └── labels/
        ├── train/  (e.g. train_00.txt)
        └── val/    (e.g. val_02.txt)

For example, train_00.png corresponds to train_00.txt. For a different dataset, change the image paths and class names to match your data. Do not place images without permission into your project or public downloads.

Read one YOLO annotation row

Each row describes one object using five values:

class_index x_center y_center width height

The index identifies a class; the remaining four numbers are normalized by the image width or height and typically range from 0 to 1. In this fixture, the first row of labels/train/train_00.txt is:

0 0.271484 0.691406 0.277344 0.187500

Class 0 means boat. The center is approximately (0.271484, 0.691406); its width and height are 0.277344 and 0.187500. The input is 256 × 256 pixels, so the x center is approximately 0.271484 × 256 = 69.5 pixels from the left edge. The rectangle below is computed from this exact row, rather than drawn by eye.

One image and the box defined by the example row. Inspect all objects, not just a single row, before training.

Create and check a label file from pixel coordinates

Here is a small, reproducible way to turn pixel coordinates into a YOLO label. This example uses the synthetic train_00.png image from the course fixture. Its four rectangles contain two boats and two buoys. For this demonstration we reconstructed their pixel corners from the fixture’s existing annotations; they are not newly measured by an annotation tool. For your own image, determine the correct rectangle for every object first—for example using a suitable annotation tool—and use its pixel corners in place of these values.

For each box, left and right are horizontal pixel positions, and top and bottom are vertical positions measured from the upper-left corner. The code divides horizontal values by the image width and vertical values by its height. Class 0 is boat; class 1 is buoy. Use the same numeric mapping in your data.yaml.

Inside the project folder from step 1, create a separate annotation-demo folder and copy the example image to annotation-demo/input/train_00.png. Save the complete script below as annotation-demo/annotate_example.py. This image is 256 × 256 pixels; adapt the dimensions check, filename, class IDs, coordinates and class names to use a different dataset.

custom-yolo/
├── .venv/
└── annotation-demo/
    ├── annotate_example.py
    └── input/
        └── train_00.png

The script uses Pillow, included in the demonstrated environment. If it is not installed in your environment, run .venv\Scripts\python.exe -m pip install pillow from the project folder. Then, still from the project folder, run:

.venv\Scripts\python.exe annotation-demo\annotate_example.py

Complete example source: copyright © 2026 ARTSCI — Author of the AI/ML/CV course materials, licensed under GNU AGPL version 3 only, without warranty. The sample image and other course media are separate assets and are not automatically licensed under this code notice.

"""Create a new YOLO label from pixel corners; never overwrite an existing label."""
from pathlib import Path
from PIL import Image, ImageDraw

image_path = Path(__file__).parent / 'input' / 'train_00.png'
output_dir = Path(__file__).parent / 'output'
image = Image.open(image_path).convert('RGB')
width, height = image.size
assert (width, height) == (256, 256)

# class_id, left, top, right, bottom in pixels. Origin: upper-left.
# These corners were reconstructed from this fixture's existing annotations.
boxes = [
    (0, 34, 153, 105, 201),
    (0, 118, 122, 181, 172),
    (1, 46, 189, 66, 209),
    (1, 186, 149, 212, 175),
]
rows = []
for class_id, left, top, right, bottom in boxes:
    assert class_id in (0, 1) and 0 <= left < right <= width and 0 <= top < bottom <= height
    x_center = (left + right) / (2 * width)
    y_center = (top + bottom) / (2 * height)
    box_width = (right - left) / width
    box_height = (bottom - top) / height
    rows.append(f'{class_id} {x_center:.6f} {y_center:.6f} {box_width:.6f} {box_height:.6f}')

output_dir.mkdir(parents=True, exist_ok=True)
label_path = output_dir / f'{image_path.stem}.txt'
with label_path.open('x', encoding='utf-8', newline='\n') as label_file:
    label_file.write('\n'.join(rows) + '\n')

# Reconstruct the saved boxes for visual verification of the written bytes.
saved_rows = label_path.read_text(encoding='utf-8').splitlines()
assert len(saved_rows) == len(boxes)
overlay = image.copy()
draw = ImageDraw.Draw(overlay)
for row in saved_rows:
    cls, xc, yc, bw, bh = row.split()
    xc, yc, bw, bh = map(float, (xc, yc, bw, bh))
    rect = ((xc-bw/2)*width, (yc-bh/2)*height, (xc+bw/2)*width, (yc+bh/2)*height)
    draw.rectangle(rect, outline='#ffdb40' if cls == '0' else '#5effac', width=2)
overlay.save(output_dir / 'train_00_saved_labels.png')
print('Input:', image_path.name, width, 'x', height)
print('New label:', label_path.name)
print('Saved rows:')
print('\n'.join(saved_rows))
print('Verified overlay:', 'train_00_saved_labels.png')

The script creates annotation-demo/output/train_00.txt with four lines and annotation-demo/output/train_00_saved_labels.png, which draws the rectangles reconstructed from the saved label file. The first line is 0 0.271484 0.691406 0.277344 0.187500. Inspect the overlay and correct any missing or misplaced boxes before using a label for training.

The file is opened in exclusive-create mode to protect existing labels. Running the same demo again with the same output path raises FileExistsError. To repeat it, use a new demo directory or a different output filename; do not overwrite a label without reviewing it. Once your annotations for the entire image are complete and checked, put the label file under the matching labels/train or labels/val directory with the same base name as the image.

3. Create the dataset configuration

For the example layout, save this as synthetic_harbor_dataset/data.yaml:

train: images/train
val: images/val
names:
  0: boat
  1: buoy

The training and validation paths identify separate groups of images. The names mapping defines the meaning of each class index in this custom dataset. Check paths and labels against your actual installed Ultralytics version and project layout; the example was run with the YAML beside these folders.

4. Obtain the starting weights

Download the official YOLOv8n checkpoint as a separate setup step and place it next to train_yolo.py. The file used in the demonstration has SHA-256 f59b3d833e2ff32e194b5bb8e08d211dc7c5bdf144b90d2c8412c47ccfc83b36. Review the model asset license and Ultralytics licensing information for your use. A checksum identifies bytes; it does not by itself grant usage rights.

5. Train and predict with the complete script

Save the following as train_yolo.py in the project folder. It checks for the local checkpoint, dataset YAML and selected validation image, fine-tunes the checkpoint, loads the selected best.pt file, and saves the prediction as prediction_val_02.jpg.

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Fine-tune a local YOLO checkpoint on an annotated dataset and inspect a validation image."""
from pathlib import Path

import cv2
from ultralytics import YOLO


def main():
    root = Path(__file__).resolve().parent
    dataset = root / "synthetic_harbor_dataset"
    data_yaml = dataset / "data.yaml"
    validation_image = dataset / "images" / "val" / "val_02.png"
    starting_weights = root / "yolov8n.pt"

    for file_path in (data_yaml, validation_image, starting_weights):
        if not file_path.is_file():
            raise FileNotFoundError(f"Required local file: {file_path}")

    model = YOLO(str(starting_weights))
    training = model.train(
        data=str(data_yaml), epochs=50, imgsz=256, batch=4, workers=0,
        device="cpu", project=str(root / "runs"), name="custom_yolo",
        exist_ok=False, verbose=False, plots=False, mosaic=0.0,
        seed=0, deterministic=True,
    )

    best_weights = Path(training.save_dir) / "weights" / "best.pt"
    if not best_weights.is_file():
        raise FileNotFoundError(f"Training did not produce a checkpoint: {best_weights}")
    final_model = YOLO(str(best_weights))
    result = final_model(
        str(validation_image), conf=0.25, iou=0.30, device="cpu", verbose=False,
    )[0]

    print(f"Best checkpoint: {best_weights}")
    for box in result.boxes:
        class_name = result.names[int(box.cls.item())]
        print(f"{class_name}: confidence {float(box.conf.item()):.3f}")
    output = root / "prediction_val_02.jpg"
    if not cv2.imwrite(str(output), result.plot(line_width=1, font_size=8)):
        raise OSError(f"Could not save prediction image: {output}")
    print(f"Saved validation-image prediction: {output}")


if __name__ == "__main__":
    main()

Complete sample source above: copyright © 2026 ARTSCI — Author of the AI/ML/CV course materials, licensed under GNU AGPL version 3, without warranty. Preserve applicable notices and provide corresponding source when sharing covered modifications. Ultralytics software and model weights retain their own terms. Dataset images, course media and other independent assets are not automatically licensed under this code notice.

From the project folder, run:

.venv\Scripts\python.exe train_yolo.py

data selects the YAML. epochs=50 means 50 passes through the training set; imgsz=256 selects the processing size, batch=4 controls batch size, and device="cpu" chooses the CPU. The seed and deterministic setting help reproduce this particular example, but they do not guarantee bit-identical results across every environment. Training duration depends on the computer.

6. Inspect the actual result

In the recorded run, prediction on val_02.png at conf=0.25 and iou=0.30 returned two boat boxes and one buoy box. These matched the three labelled classes in that particular image. The checkpoint and image shown in the video belong to that run; a new run can produce different confidences or boxes.

A box confidence is the model's score for that prediction, not a measurement of how often the system will be correct in real life. The four validation images were used during training and checkpoint selection. Their prediction and validation metrics are therefore not an independent final test.

7. Troubleshoot the common problems

• Required local file is missing: check the project layout and filenames, including the checkpoint and data.yaml. For your own dataset, change validation_image to an existing image.
• Images or labels are not found: check matching filename stems and whether train and val resolve to the intended folders.
• Boxes look wrong: check that the annotations use normalized center coordinates and width/height, rather than pixel corners. Draw them on the source image before training.
• No box appears: inspect your labels, classes and input, then investigate the confidence threshold and training output. Lowering a threshold changes which predictions appear; it does not guarantee correct detections.
• Training is slow: CPU runtime depends on your hardware, configuration and dataset. Reduce or adjust a test run deliberately, and report the actual settings when comparing results.

What to do next

Try adding an image you have permission to use and manually checking every annotation. For a real application, collect representative examples across cameras and lighting, prevent similar images from leaking between splits, inspect errors, and evaluate on a separate test set that was not used for training or checkpoint selection. A tiny synthetic fixture teaches the steps; it does not establish production reliability.

For another application of these ideas, read how a Parking Space Counter assigns detections to spaces. You can explore more practical projects in my Computer Vision: OpenCV, Machine Learning and YOLO course.

Parking Space Counter with Python and YOLO: From Detections to Occupancy

Finding vehicles is only half of a parking-space counter. The application must also decide which detected vehicle belongs to which monitored space.

In this Python and YOLO example, six calibrated regions produce four occupied and two free statuses. Raising one application threshold changes the result to three occupied and three free, even though the image has not changed. Following that change back to one detection makes the rule much easier to understand.

We use a synthetic 1024 × 1024 course scene and a local Windows/CPU run. This is a static-image demonstration, not a live-camera reliability or accuracy benchmark. Other partial vehicles appear outside the six monitored regions; the reported total is about those six spaces, not every vehicle in the image.

Watch the Parking Lot Monitor walkthrough

Watch the complete Python and YOLO tutorial, or see the quick parking-space demonstration.

Red regions are occupied and green regions free according to the rule. Yellow rectangles and points show accepted detector boxes and their centers. The regions approximate perspective bays rather than tracing their painted outlines.

The instructional figures include extra yellow detection boxes and centers to make the decisions inspectable. The minimal script below saves the colored region-and-ID overlays and prints the assignment rows; it does not add those extra yellow annotations to its saved images.

The pipeline: image, detections, regions, decisions

1. Load one explicit local image, checkpoint and region calibration.
2. Run YOLOv8n once with a candidate confidence floor of 0.10.
3. Keep vehicle classes: car, truck and bus.
4. Filter those fixed candidates using the parking acceptance threshold.
5. Assign accepted box centers to the calibrated rectangles.
6. Count the resulting occupied and free rows.

YOLO supplies predictions; our Python rule supplies the occupancy decision. A free row means that no accepted candidate center matched that region. It does not independently verify that the physical space is empty.

Prepare the local inputs

Save the complete script below as parking.py. Place yolov8n.pt, parking_lot_sample.png and parking_zones.json beside it. The demonstrated input and its calibration are included in lesson 50 of my course. You can instead use your own permitted image, but you must calibrate regions for that image.

The tested checkpoint matches the official YOLOv8n release asset, SHA-256 f59b3d833e2ff32e194b5bb8e08d211dc7c5bdf144b90d2c8412c47ccfc83b36. Obtain that file as a separate setup step and review the model license and Ultralytics licensing options. The script checks that the required local files exist before loading the model; it does not download missing inputs.

For Windows with Python 3.13 installed:

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install ultralytics==8.4.24 numpy==2.3.5 opencv-python==4.13.0.92
.venv\Scripts\python.exe parking.py

The measured environment used Python 3.13.9, Ultralytics 8.4.24, PyTorch 2.10.0, NumPy 2.3.5 and OpenCV 4.13.0.92. The installation command pins three direct dependencies, not the complete transitive environment. This is not a fresh-install claim for every operating system. Installation and obtaining the model may need internet access; the demonstrated processing runs offline with local files.

Calibrate regions in the input image's coordinates

Here is the demonstrated calibration. Save it as parking_zones.json. Coordinates are [left, top, right, bottom] in the original 1024 × 1024 image:

{
  "image_size": [1024, 1024],
  "zones": [
    {"spot_id": "A1", "rect": [146, 55, 399, 337]},
    {"spot_id": "A2", "rect": [402, 55, 649, 337]},
    {"spot_id": "A3", "rect": [651, 55, 856, 337]},
    {"spot_id": "B1", "rect": [72, 570, 373, 978]},
    {"spot_id": "B2", "rect": [375, 570, 696, 978]},
    {"spot_id": "B3", "rect": [698, 570, 959, 978]}
  ]
}

These coordinates belong to this image and viewpoint. Equal dimensions alone do not make them valid for another camera.

load_zones rejects a calibration with different image dimensions, an empty region list, duplicate identifiers, invalid rectangles, or overlapping regions. Those checks catch structural mistakes. They do not prove that a rectangle corresponds to the correct physical bay. Inspect the overlay, especially after changing the image or viewpoint.

Complete runnable parking-space counter

# SPDX-License-Identifier: AGPL-3.0-only
# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Assign local YOLO candidates to calibrated parking spaces; no asset downloads."""
from pathlib import Path
import json
import sys
import cv2
import numpy as np
from ultralytics import YOLO


def load_zones(path, shape):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if payload["image_size"] != [shape[1], shape[0]]:
        raise ValueError("Zone calibration dimensions differ from the selected image.")
    zones = payload["zones"]
    if not zones or len({z["spot_id"] for z in zones}) != len(zones):
        raise ValueError("Use nonempty zones with unique spot IDs.")
    for i, zone in enumerate(zones):
        x1, y1, x2, y2 = zone["rect"]
        if not 0 <= x1 < x2 <= shape[1] or not 0 <= y1 < y2 <= shape[0]:
            raise ValueError("Invalid or out-of-image zone.")
        for other in zones[:i]:
            a, b, c, d = other["rect"]
            if max(x1, a) < min(x2, c) and max(y1, b) < min(y2, d):
                raise ValueError("Overlapping zones could assign one center twice.")
    return zones


def detect_candidates(model, image):
    result = model.predict(
        source=image, conf=0.10, imgsz=640, device="cpu", iou=0.70,
        max_det=300, rect=True, half=False, classes=None,
        augment=False, agnostic_nms=False, verbose=False,
    )[0]
    detections = []
    for box in result.boxes:
        label = result.names[int(box.cls.item())]
        if label not in {"car", "truck", "bus"}:
            continue
        x1, y1, x2, y2 = box.xyxy[0].cpu().tolist()
        detections.append(dict(
            label=label, confidence=float(box.conf.item()), box=[x1, y1, x2, y2],
            center=[(x1 + x2) / 2, (y1 + y2) / 2],
        ))
    return detections


def assign_spots(detections, zones, confidence=0.20):
    accepted = [d for d in detections if d["confidence"] >= confidence]
    rows = []
    for zone in zones:
        x1, y1, x2, y2 = zone["rect"]
        matches = [d for d in accepted
                   if x1 <= d["center"][0] < x2 and y1 <= d["center"][1] < y2]
        best = max(matches, key=lambda d: d["confidence"]) if matches else None
        rows.append(dict(spot_id=zone["spot_id"], status="occupied" if best else "free",
                         confidence=round(best["confidence"], 3) if best else None,
                         center=best["center"] if best else None))
    return rows


def draw_status(image, zones, rows):
    canvas = image.copy()
    states = {row["spot_id"]: row["status"] for row in rows}
    for zone in zones:
        x1, y1, x2, y2 = zone["rect"]
        color = (70, 170, 70) if states[zone["spot_id"]] == "free" else (50, 70, 225)
        cv2.rectangle(canvas, (x1, y1), (x2, y2), color, 4)
        cv2.putText(canvas, zone["spot_id"], (x1 + 8, y1 + 32),
                    cv2.FONT_HERSHEY_SIMPLEX, 1, color, 3)
    return canvas


def main():
    root = Path(__file__).resolve().parent
    image_path = Path(sys.argv[1]) if len(sys.argv) > 1 else root / "parking_lot_sample.png"
    zones_path = Path(sys.argv[2]) if len(sys.argv) > 2 else root / "parking_zones.json"
    weights = root / "yolov8n.pt"
    for path in (image_path, zones_path, weights):
        if not path.is_file():
            raise FileNotFoundError(f"Required local file: {path}")
    image = cv2.imdecode(np.fromfile(image_path, dtype=np.uint8), cv2.IMREAD_COLOR)
    if image is None:
        raise ValueError(f"Cannot decode image: {image_path}")
    zones = load_zones(zones_path, image.shape)
    detections = detect_candidates(YOLO(str(weights)), image)
    output = root / "output"
    output.mkdir(exist_ok=True)
    for confidence in (0.20, 0.30):
        rows = assign_spots(detections, zones, confidence)
        occupied = sum(row["status"] == "occupied" for row in rows)
        print(f"threshold={confidence:.2f}: {occupied} occupied, {len(rows)-occupied} free")
        for row in rows:
            print(f"  {row['spot_id']}: {row['status']} (score={row['confidence']})")
        if not cv2.imwrite(str(output / f"parking_{confidence:.2f}.png"),
                           draw_status(image, zones, rows)):
            raise OSError("Could not save parking overlay.")


if __name__ == "__main__":
    main()

Complete sample source above: copyright © 2026 ARTSCI — Author of the AI/ML/CV course materials, licensed under GNU AGPL version 3, without warranty. Keep applicable notices and provide corresponding source when sharing covered modifications. Ultralytics software and weights retain their own terms. Independent course images, narration, slides and videos are not automatically licensed under AGPL.

The script's default paths are relative to the saved Python file. To select your own image and its matching calibration, pass both paths:

.venv\Scripts\python.exe parking.py "C:\images\my_parking.png" "C:\images\my_zones.json"

Keep detector inference separate from the parking threshold

detect_candidates runs prediction once, with conf=0.10, imgsz=640, CPU and the other shown settings fixed. In this execution it returns eight vehicle candidates. Some are outside the monitored spaces, and two predictions can describe the same region. A candidate count is not a parking-space count.

The loop in main compares application thresholds 0.20 and 0.30 by filtering that same post-NMS candidate set. It does not rerun YOLO or non-maximum suppression. This controlled comparison keeps the image, model and underlying predictions unchanged. The official prediction documentation describes confidence and overlap-suppression settings; our additional acceptance threshold belongs to the application rule.

Assign the center, then count the space

For each box, the center is ((x1+x2)/2, (y1+y2)/2). assign_spots tests that center against each region, including left/top boundaries and excluding right/bottom boundaries. With non-overlapping regions, a point cannot belong to two spaces. If several accepted centers match one space, the rule keeps the highest-scoring match and still counts only one occupied row.

This is a center-in-rectangle rule, not an intersection-over-union or segmentation calculation. A long, partly occluded or incorrectly localized vehicle may not behave as expected. Test the geometry and the detector output separately.

Inspect the actual output

threshold=0.20: 4 occupied, 2 free
  A1: occupied (score=0.771)
  A2: occupied (score=0.428)
  A3: free (score=None)
  B1: occupied (score=0.222)
  B2: occupied (score=0.501)
  B3: free (score=None)
threshold=0.30: 3 occupied, 3 free
  A1: occupied (score=0.771)
  A2: occupied (score=0.428)
  A3: free (score=None)
  B1: free (score=None)
  B2: occupied (score=0.501)
  B3: free (score=None)

At 0.20, A1, A2, B1 and B2 are occupied; A3 and B3 are free according to the rule. Seven candidate detections pass that threshold, but only four monitored spaces receive a match. The detector labels the red vehicle in B2 as bus with score about 0.501. The application accepts that class as a vehicle, so a useful occupancy result here does not establish perfect vehicle classification.

Why did B1 become free when the car stayed?

The B1 candidate has score approximately 0.22236 and center (229.74, 740.91). It passes 0.20, but fails 0.30. B1 therefore loses its accepted center and changes to free. Five candidates pass the higher threshold, while only three monitored spaces receive matches.

Inspecting one candidate explains the changed decision. The center coordinates refer to the original full image, not this crop's coordinate system.

Same pixels, same calibration and same detector candidate set. Only the application acceptance threshold changed.

A stricter threshold can remove mistakes, but it can also miss occupied spaces. A confidence score is not calibrated certainty, and a higher threshold does not automatically make a counter more accurate.

What to verify before adapting the example

Use permitted inputs, recalibrate the regions, and inspect each selected vehicle center alongside the assignment table. Test weak detections, occlusion, shadows and boundaries. Check representative labelled examples before relying on physical occupancy claims. This single synthetic scene does not measure field accuracy or live-camera performance.

For related projects, see how to read YOLO detection outputs and why track IDs are not vehicle counts. My English course, Computer Vision: OpenCV, Machine Learning and YOLO, develops the full Parking Lot Monitor application alongside other practical projects.

Python Document Scanner: Detect Corners and Correct Perspective

A tilted page can become a rectangular scan without training a neural network. The useful idea is to find a plausible page boundary, keep its four corners in a consistent order, and map them onto a rectangle.

This walkthrough builds a small Python document scanner with OpenCV. It runs locally on a CPU and saves both a color result and an optional black-and-white view. There is no model checkpoint and no OCR. The example uses an explicitly synthetic document scene from my course, so a clean result here is a demonstration of the pipeline rather than evidence that every photograph will work.

Watch the working example

Watch the complete Python and OpenCV scanner walkthrough, or see the quick before-and-after demonstration.

Same input pixels, transformed using four detected corners. The result is 740 × 523 pixels in this execution.

What does the scanner actually do?

1. Convert the image to grayscale and blur small variations.
2. Use Canny edges and morphological closing to prepare boundaries.
3. Select the largest qualifying convex four-corner contour.
4. Order those corners and calculate a perspective transform.
5. Save the flattened color image and an optional thresholded view.

OpenCV's contour documentation explains how contours represent boundaries in a binary image. A boundary is a shape, not an understanding of the object. That distinction is the main limitation to keep in mind.

Prepare Python, OpenCV and one local image

Save the full code below as scanner.py. Place document_scene.png beside it to use the demonstrated course input, available in lesson 53. Alternatively, supply the path to an image you have permission to use. The example does not download or silently replace your image.

On Windows with Python 3.13 installed, create a separate environment and install the two demonstrated package versions:

py -3.13 -m venv .venv
.venv\Scripts\python.exe -m pip install numpy==2.3.5 opencv-python==4.13.0.92
.venv\Scripts\python.exe scanner.py

To process your own file instead of the default input:

.venv\Scripts\python.exe scanner.py "C:\images\my_page.jpg"

The measured execution used Python 3.13.9, NumPy 2.3.5 and OpenCV 4.13.0.92 on Windows. These commands describe that setup; they are not a fresh-install test of every operating system. Package installation may require internet access. Once the packages and image are present, this scanner needs no network connection, model download or GPU.

Complete runnable scanner

# Copyright (c) 2026 ARTSCI - Author of the AI/ML/CV course materials.
"""Straighten a page candidate with local OpenCV operations; no trained model."""
from pathlib import Path
import sys
import cv2
import numpy as np


def edge_map(image, low=50, high=150):
    if not 0 <= low < high:
        raise ValueError("Require 0 <= low < high.")
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
    edges = cv2.Canny(blurred, low, high)
    return cv2.morphologyEx(edges, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))


def find_page(edges):
    contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
    for contour in sorted(contours, key=cv2.contourArea, reverse=True):
        perimeter = cv2.arcLength(contour, True)
        candidate = cv2.approxPolyDP(contour, 0.02 * perimeter, True)
        large = cv2.contourArea(candidate) >= 0.10 * edges.size
        if len(candidate) == 4 and large and cv2.isContourConvex(candidate):
            return candidate.reshape(4, 2).astype(np.float32)
    return None


def order_corners(points):
    points = np.asarray(points, dtype=np.float32).reshape(4, 2)
    if not np.isfinite(points).all() or len(np.unique(points, axis=0)) != 4:
        raise ValueError("Four distinct finite corners are required.")
    center = points.mean(axis=0)
    angles = np.arctan2(points[:, 1] - center[1], points[:, 0] - center[0])
    ordered = points[np.argsort(angles)]
    if not cv2.isContourConvex(ordered) or abs(cv2.contourArea(ordered)) < 1:
        raise ValueError("Corners must form a non-degenerate convex quadrilateral.")
    start = np.argmin(ordered.sum(axis=1))
    return np.roll(ordered, -start, axis=0)


def flatten_page(image, corners):
    tl, tr, br, bl = corners
    width = max(2, round(max(np.linalg.norm(tr - tl), np.linalg.norm(br - bl))))
    height = max(2, round(max(np.linalg.norm(bl - tl), np.linalg.norm(br - tr))))
    target = np.float32([[0, 0], [width-1, 0], [width-1, height-1], [0, height-1]])
    matrix = cv2.getPerspectiveTransform(np.float32(corners), target)
    return cv2.warpPerspective(image, matrix, (width, height))


def document_mode(photo):
    gray = cv2.cvtColor(photo, cv2.COLOR_BGR2GRAY)
    blurred = cv2.GaussianBlur(gray, (3, 3), 0)
    normalized = cv2.normalize(blurred, None, 0, 255, cv2.NORM_MINMAX)
    return cv2.adaptiveThreshold(normalized, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
                                 cv2.THRESH_BINARY, 31, 15)


def main():
    root = Path(__file__).resolve().parent
    source = Path(sys.argv[1]) if len(sys.argv) > 1 else root / "document_scene.png"
    if not source.is_file():
        raise FileNotFoundError(f"Required local image: {source}")
    image = cv2.imdecode(np.fromfile(source, dtype=np.uint8), cv2.IMREAD_COLOR)
    if image is None:
        raise ValueError(f"Cannot decode image: {source}")
    edges = edge_map(image)
    candidate = find_page(edges)
    if candidate is None:
        raise ValueError("No qualifying page candidate. Check the image and thresholds.")
    corners = order_corners(candidate)
    photo = flatten_page(image, corners)
    binary = document_mode(photo)
    output = root / "output"
    output.mkdir(exist_ok=True)
    for name, pixels in [("edges", edges), ("photo", photo), ("document", binary)]:
        if not cv2.imwrite(str(output / f"{name}.png"), pixels):
            raise OSError(f"Could not save {name}.png")
    print("Corners [TL, TR, BR, BL]:", corners.astype(int).tolist())
    print(f"Scan: {photo.shape[1]} x {photo.shape[0]} pixels")
    print("Saved edges.png, photo.png and document.png in output/")


if __name__ == "__main__":
    main()

Sample code © 2026 ARTSCI — Author of the AI/ML/CV course materials. OpenCV and NumPy retain their own licenses. OpenCV 4.5 and later use Apache License 2.0; NumPy's license is documented separately. This example uses no Ultralytics software or model weights.

Why grayscale, blur and Canny come first

edge_map converts the input to grayscale and applies a 5 × 5 Gaussian blur. Canny uses thresholds 50 and 150 in this run. Closing with a 5 × 5 kernel can connect small gaps, making a boundary easier to follow. These values are starting parameters, not settings that are guaranteed to work for all lighting and backgrounds.

The edge image includes text and background details as well as the page boundary. find_page sorts contours by area, approximates each polygon with a tolerance of 2% of its perimeter, then accepts the first convex candidate with four corners and at least 10% of the image area. Always inspect that selected boundary before interpreting the output as a document scan.

Detected corners for this input: TL=(199,156), TR=(818,127), BR=(884,643), BL=(145,676). The yellow outline is the selected candidate.

Corner order controls the perspective mapping

The source and destination corners must correspond. Here the order is top left, top right, bottom right, bottom left. The code sorts points around their center and rotates that sequence so the point with the smallest x+y comes first. It also rejects duplicate, nonfinite and degenerate corner sets.

This ordering assumes a roughly upright page. It does not identify which way the text should face. Strongly rotated or ambiguous pages need additional orientation handling. Mixing corner correspondence can twist or flip the output even when all four points lie near a page.

cv2.getPerspectiveTransform calculates the mapping from the four input points to the four rectangle points. cv2.warpPerspective resamples the image using that mapping. See the official perspective transformation tutorial for the source-to-destination point relationship.

Read the actual output

Corners [TL, TR, BR, BL]: [[199, 156], [818, 127], [884, 643], [145, 676]]
Scan: 740 x 523 pixels
Saved edges.png, photo.png and document.png in output/

The printed 740 × 523 dimensions are a result of this image and the edge-length rule in flatten_page. They are not a known physical paper size. If the real page dimensions matter, supply that prior information and choose the target aspect ratio accordingly.

Flattened color output. Perspective correction does not recover blurred characters or remove a curved page's three-dimensional shape.

Black and white is an optional view, not OCR

document_mode converts the flattened image to grayscale, blurs it, normalizes its intensity range and applies adaptive Gaussian thresholding with a 31-pixel neighborhood and C=15. A local threshold can help with brightness variation, but it can also discard fine detail or amplify noise. Compare this output with the color scan before deciding which one to keep.

A document-style image. No text has been recognized or exported as characters.

When a convincing scan can still be wrong

A large picture frame, desk mat or other convex four-corner object can satisfy exactly the same rule as a page. In a separate controlled test, the algorithm accepted a plain large rectangle that was not a document. A blank image produced no candidate. Those outcomes are useful checks, but neither establishes general document-detection accuracy.

For your own input, inspect the selected outline, check all four corners and compare the output with the original. Test shadows, low-contrast borders, clutter and rotation. If the script reports no qualifying page, investigate the input and parameters; do not silently crop an arbitrary region and call it a successful scan.

This project demonstrates classical image geometry. If you want to compare it with learned detection, see my first working YOLO object-detection example. My English course, Computer Vision: OpenCV, Machine Learning and YOLO, develops these operations through notebooks and practical applications, including the complete Document Scanner project.