OpenCV Basics Explained — Images, Pixels and Real-World CV Patterns

import cv2
import numpy as np

# --- Load an image from disk ---
# cv2.IMREAD_COLOR loads as a 3-channel BGR image (the default)
# cv2.IMREAD_GRAYSCALE loads as a single-channel image
bgr_image = cv2.imread("street_scene.jpg", cv2.IMREAD_COLOR)

# Always check — imread returns None silently if the path is wrong
if bgr_image is None:
    raise FileNotFoundError("Could not load street_scene.jpg — check the file path")

# --- Inspect what we actually have ---
print("Type  :", type(bgr_image))          # numpy.ndarray
print("Shape :", bgr_image.shape)          # (height, width, channels)
print("Dtype :", bgr_image.dtype)          # uint8  (values 0-255)
print("Size  :", bgr_image.size)           # total number of pixel values

height, width, num_channels = bgr_image.shape
print(f"\nImage is {width}px wide × {height}px tall with {num_channels} colour channels")

# --- Access a single pixel (row=100, col=200) ---
# Returns [Blue, Green, Red] — remember, BGR not RGB!
bgr_pixel = bgr_image[100, 200]
print(f"\nPixel at (100,200) — B:{bgr_pixel[0]}  G:{bgr_pixel[1]}  R:{bgr_pixel[2]}")

# --- Convert BGR → RGB so other libraries see colours correctly ---
rgb_image = cv2.cvtColor(bgr_image, cv2.COLOR_BGR2RGB)
rgb_pixel = rgb_image[100, 200]
print(f"Same pixel in RGB  — R:{rgb_pixel[0]}  G:{rgb_pixel[1]}  B:{rgb_pixel[2]}")

# --- Cropping is just NumPy slicing: array[y_start:y_end, x_start:x_end] ---
# Crop a 200×200 region from the top-left corner
top_left_crop = bgr_image[0:200, 0:200]
print(f"\nCropped shape: {top_left_crop.shape}")  # (200, 200, 3)

# --- Darken the image by halving every pixel value ---
# .astype(float) prevents uint8 overflow wrapping (255+1 = 0)
darkened_image = (bgr_image.astype(np.float32) * 0.5).astype(np.uint8)

# --- Save results to disk ---
cv2.imwrite("cropped_top_left.jpg", top_left_crop)
cv2.imwrite("darkened_scene.jpg", darkened_image)
print("\nSaved cropped_top_left.jpg and darkened_scene.jpg")

import cv2
import numpy as np

# --- Load the source image ---
bgr_frame = cv2.imread("traffic_intersection.jpg", cv2.IMREAD_COLOR)
if bgr_frame is None:
    raise FileNotFoundError("traffic_intersection.jpg not found")

# ── GRAYSCALE ────────────────────────────────────────────────────────────────
# Single channel — perfect for edge detection, thresholding, template matching
gray_frame = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2GRAY)
print("Grayscale shape:", gray_frame.shape)  # (height, width) — no channel dim

# ── HSV — COLOUR-BASED OBJECT DETECTION ──────────────────────────────────────
# Convert BGR → HSV so we can isolate colours regardless of brightness
hsv_frame = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2HSV)

# Define the HSV range for detecting RED traffic lights
# Red wraps around 0° on the hue wheel, so we need TWO ranges
red_lower_1 = np.array([0,   120, 70])   # lower bound of first red range
red_upper_1 = np.array([10,  255, 255])  # upper bound of first red range
red_lower_2 = np.array([170, 120, 70])   # lower bound of second red range (wraps)
red_upper_2 = np.array([180, 255, 255])  # upper bound of second red range

# cv2.inRange creates a binary mask: 255 where colour is in range, 0 elsewhere
mask_red_1 = cv2.inRange(hsv_frame, red_lower_1, red_upper_1)
mask_red_2 = cv2.inRange(hsv_frame, red_lower_2, red_upper_2)

# Combine both red masks with bitwise OR
red_mask = cv2.bitwise_or(mask_red_1, mask_red_2)

# Apply the mask to isolate only red regions in the original image
red_regions_only = cv2.bitwise_and(bgr_frame, bgr_frame, mask=red_mask)

# Count how many red pixels were detected
red_pixel_count = cv2.countNonZero(red_mask)
print(f"Red pixels detected: {red_pixel_count}")

if red_pixel_count > 500:   # threshold tuned to filter out small noise
    print("⚠  Red traffic light likely detected — stopping recommended")
else:
    print("✓  No significant red light detected")

# ── LAB — NORMALISE BRIGHTNESS ACROSS IMAGES FROM DIFFERENT CAMERAS ──────────
lab_frame = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2LAB)

# Split into L (lightness), A (green↔red axis), B (blue↔yellow axis) channels
l_channel, a_channel, b_channel = cv2.split(lab_frame)

# Apply CLAHE (Contrast Limited Adaptive Histogram Equalisation) only to L
# This enhances local contrast without touching colour — great for dim images
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
l_equalised = clahe.apply(l_channel)

# Merge back and convert to BGR for saving
lab_equalised = cv2.merge([l_equalised, a_channel, b_channel])
bgr_enhanced = cv2.cvtColor(lab_equalised, cv2.COLOR_LAB2BGR)

# --- Save all outputs ---
cv2.imwrite("gray_frame.jpg",        gray_frame)
cv2.imwrite("red_mask.jpg",          red_mask)
cv2.imwrite("red_regions_only.jpg",  red_regions_only)
cv2.imwrite("brightness_enhanced.jpg", bgr_enhanced)
print("\nSaved gray_frame.jpg, red_mask.jpg, red_regions_only.jpg, brightness_enhanced.jpg")

import cv2
import numpy as np

# ── LOAD ──────────────────────────────────────────────────────────────────────
original_bgr = cv2.imread("product_photo.jpg", cv2.IMREAD_COLOR)
if original_bgr is None:
    raise FileNotFoundError("product_photo.jpg not found")

print(f"Original size: {original_bgr.shape[1]}×{original_bgr.shape[0]}")

# ── STEP 1: RESIZE ────────────────────────────────────────────────────────────
# Neural networks like MobileNet, ResNet etc. expect 224×224 or 640×640
# INTER_AREA is best when downscaling — avoids moiré patterns
target_size = (224, 224)   # (width, height) — note: width FIRST in cv2.resize
resized_bgr = cv2.resize(original_bgr, target_size, interpolation=cv2.INTER_AREA)
print(f"Resized to:    {resized_bgr.shape[1]}×{resized_bgr.shape[0]}")

# ── STEP 2: GRAYSCALE + BLUR ──────────────────────────────────────────────────
gray = cv2.cvtColor(resized_bgr, cv2.COLOR_BGR2GRAY)

# Gaussian blur: kernel size (5,5) must be ODD and POSITIVE
# sigmaX=0 tells OpenCV to calculate sigma automatically from kernel size
blurred_gray = cv2.GaussianBlur(gray, ksize=(5, 5), sigmaX=0)
print(f"Blur applied — kernel 5×5, sigma auto-calculated")

# ── STEP 3: CANNY EDGE DETECTION ─────────────────────────────────────────────
# threshold1: pixels BELOW this are definitely NOT edges
# threshold2: pixels ABOVE this are definitely edges
# Pixels between the two are edges only if connected to a definite edge
# A good starting ratio is 1:3 (low:high). Adjust based on image contrast.
edge_map = cv2.Canny(blurred_gray, threshold1=50, threshold2=150)

edge_pixel_count = cv2.countNonZero(edge_map)
print(f"Edge pixels found: {edge_pixel_count}")

# ── STEP 4: FIND CONTOURS AND DRAW BOUNDING BOXES ────────────────────────────
# Contours are the outlines of connected white regions in a binary image
# RETR_EXTERNAL: only outermost contours (ignore holes inside shapes)
# CHAIN_APPROX_SIMPLE: compress straight lines to just endpoints (saves memory)
contours, hierarchy = cv2.findContours(
    edge_map,
    cv2.RETR_EXTERNAL,
    cv2.CHAIN_APPROX_SIMPLE
)

print(f"Contours found: {len(contours)}")

# Draw bounding boxes around contours larger than 200 px² (filter out noise)
annotated_image = resized_bgr.copy()   # always work on a COPY — don't mutate original

for contour in contours:
    area = cv2.contourArea(contour)
    if area < 200:            # skip tiny noise blobs
        continue

    # Get the upright bounding rectangle: x, y = top-left corner
    bounding_x, bounding_y, box_width, box_height = cv2.boundingRect(contour)

    # Draw green rectangle: (image, top-left, bottom-right, BGR colour, thickness)
    cv2.rectangle(
        annotated_image,
        (bounding_x, bounding_y),
        (bounding_x + box_width, bounding_y + box_height),
        color=(0, 255, 0),    # green in BGR
        thickness=2
    )

    # Label the area in white text above each box
    cv2.putText(
        annotated_image,
        f"{int(area)}px",
        (bounding_x, bounding_y - 5),     # slightly above the top-left corner
        fontFace=cv2.FONT_HERSHEY_SIMPLEX,
        fontScale=0.4,
        color=(255, 255, 255),
        thickness=1
    )

# ── SAVE OUTPUTS ─────────────────────────────────────────────────────────────
cv2.imwrite("resized_product.jpg",    resized_bgr)
cv2.imwrite("edge_map.jpg",           edge_map)
cv2.imwrite("annotated_product.jpg",  annotated_image)
print("\nSaved resized_product.jpg, edge_map.jpg, annotated_product.jpg")

import cv2
import numpy as np
from pathlib import Path
from typing import Optional

# ImageNet normalisation constants — used when loading weights pretrained on ImageNet
# Values are per-channel means and stds in RGB order, scaled to [0,1]
IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
IMAGENET_STD  = np.array([0.229, 0.224, 0.225], dtype=np.float32)


def preprocess_for_model(
    image_path: str,
    target_size: tuple = (224, 224),
    normalise_imagenet: bool = False
) -> Optional[np.ndarray]:
    """
    Load an image and return a float32 NumPy array ready for a CNN.

    Returns shape: (target_height, target_width, 3) in RGB order.
    Pixel values are in [0, 1] range (or ImageNet-normalised if requested).
    Returns None if the image cannot be loaded.
    """
    image_file = Path(image_path)

    # ── VALIDATE ──────────────────────────────────────────────────────────────
    if not image_file.exists():
        print(f"[WARN] File not found: {image_path}")
        return None

    raw_bgr = cv2.imread(str(image_file), cv2.IMREAD_COLOR)
    if raw_bgr is None:
        print(f"[WARN] OpenCV could not decode: {image_path}")
        return None

    # ── HANDLE UNEXPECTED SHAPES ──────────────────────────────────────────────
    # Some images are loaded as grayscale even with IMREAD_COLOR (rare but happens)
    if raw_bgr.ndim == 2:
        raw_bgr = cv2.cvtColor(raw_bgr, cv2.COLOR_GRAY2BGR)

    # Some PNGs have an alpha channel — strip it
    if raw_bgr.shape[2] == 4:
        raw_bgr = cv2.cvtColor(raw_bgr, cv2.COLOR_BGRA2BGR)

    # ── RESIZE ────────────────────────────────────────────────────────────────
    # INTER_AREA for shrinking, INTER_LINEAR for enlarging
    original_h, original_w = raw_bgr.shape[:2]
    interpolation = (
        cv2.INTER_AREA
        if (original_w > target_size[0] or original_h > target_size[1])
        else cv2.INTER_LINEAR
    )
    resized_bgr = cv2.resize(raw_bgr, target_size, interpolation=interpolation)

    # ── BGR → RGB ─────────────────────────────────────────────────────────────
    # Models expect RGB. This is the single most common source of silent bugs.
    resized_rgb = cv2.cvtColor(resized_bgr, cv2.COLOR_BGR2RGB)

    # ── NORMALISE TO [0, 1] ───────────────────────────────────────────────────
    # Divide by 255 and cast to float32 (float64 wastes memory, models use float32)
    normalised = resized_rgb.astype(np.float32) / 255.0

    # ── OPTIONAL: IMAGENET NORMALISATION ─────────────────────────────────────
    # Apply only when using weights pretrained on ImageNet (ResNet, VGG, etc.)
    if normalise_imagenet:
        normalised = (normalised - IMAGENET_MEAN) / IMAGENET_STD

    return normalised  # shape: (224, 224, 3), dtype: float32


# ── BATCH PROCESSING EXAMPLE ─────────────────────────────────────────────────
if __name__ == "__main__":
    image_paths = [
        "cat.jpg",
        "dog.png",
        "corrupt_file.jpg",     # intentionally bad — tests our None handling
        "high_res_landscape.jpg"
    ]

    processed_batch = []

    for path in image_paths:
        preprocessed = preprocess_for_model(
            path,
            target_size=(224, 224),
            normalise_imagenet=True
        )
        if preprocessed is not None:
            processed_batch.append(preprocessed)
            print(f"✓  {path:<30} shape={preprocessed.shape}  "
                  f"min={preprocessed.min():.3f}  max={preprocessed.max():.3f}")

    # Stack into a batch array ready for model.predict() or torch DataLoader
    if processed_batch:
        batch_array = np.stack(processed_batch, axis=0)
        print(f"\nBatch array shape: {batch_array.shape}")   # (N, 224, 224, 3)
        print(f"Batch dtype:       {batch_array.dtype}")
        print(f"Successfully processed {len(processed_batch)}/{len(image_paths)} images")