tessl/pypi-dlib
A modern C++ toolkit containing machine learning algorithms and tools for creating complex software to solve real world problems
—
Pending
image-processing.mddocs/
Image Processing
Comprehensive image filtering, transformations, morphological operations, and computer vision preprocessing functions for image analysis and manipulation.
Capabilities
Image I/O Functions
Core functions for loading and saving images in various formats with automatic format detection.
def load_rgb_image(filename: str):
"""
Load RGB image from file as numpy array.
Args:
filename: Path to image file
Returns:
RGB image as numpy array with shape (height, width, 3)
"""
def load_rgb_alpha_image(filename: str):
"""
Load RGBA image with alpha channel.
Args:
filename: Path to image file with alpha channel
Returns:
RGBA image as numpy array with shape (height, width, 4)
"""
def load_grayscale_image(filename: str):
"""
Load image as 8-bit grayscale.
Args:
filename: Path to image file
Returns:
Grayscale image as numpy array
"""
def save_image(img, filename: str, quality: int = 75):
"""
Save image with automatic format detection from extension.
Args:
img: Input image array
filename: Output filename (supports .bmp, .png, .jpg, .jpeg, .webp, .jxl, .dng)
quality: JPEG quality (1-100, only for JPEG files)
"""
def save_png(img, filename: str):
"""Save image as PNG format."""
def save_jpeg(img, filename: str):
"""Save image as JPEG format."""
def save_bmp(img, filename: str):
"""Save image as BMP format."""
def save_dng(img, filename: str):
"""Save image as DNG format."""
def save_webp(img, filename: str):
"""Save image as WebP format."""
def save_jxl(img, filename: str):
"""Save image as JPEG XL format."""Usage Example:
import dlib
# Load images in different formats
rgb_img = dlib.load_rgb_image("photo.jpg")
rgba_img = dlib.load_rgb_alpha_image("logo.png")
gray_img = dlib.load_grayscale_image("document.tiff")
print(f"RGB image shape: {rgb_img.shape}")
print(f"RGBA image shape: {rgba_img.shape}")
print(f"Grayscale image shape: {gray_img.shape}")
# Save in different formats
dlib.save_image(rgb_img, "output.png") # Auto-detect PNG
dlib.save_image(rgb_img, "output.jpg", quality=95) # High quality JPEG
dlib.save_png(gray_img, "grayscale.png")
dlib.save_jpeg(rgb_img, "compressed.jpg")Basic Image Types
Core image representation and pixel types for image processing operations.
class rgb_pixel:
"""RGB color pixel representation."""
def __init__(self, red: int, green: int, blue: int):
"""
Create RGB pixel.
Args:
red: Red channel value (0-255)
green: Green channel value (0-255)
blue: Blue channel value (0-255)
"""
red: int # Red channel (0-255)
green: int # Green channel (0-255)
blue: int # Blue channel (0-255)Image Gradients and Derivatives
Gradient computation tools for edge detection and image analysis.
class image_gradients:
"""Gradient computation tool for images."""
def __init__(self, scale: int = 1):
"""
Initialize gradient computer.
Args:
scale: Scale parameter controlling filter window size
"""
def get_scale(self) -> int:
"""Get current scale parameter."""
def gradient_x(self, img):
"""
Compute X gradient (first derivative in X direction).
Args:
img: Input image
Returns:
X gradient image
"""
def gradient_y(self, img):
"""
Compute Y gradient (first derivative in Y direction).
Args:
img: Input image
Returns:
Y gradient image
"""
def gradient_xx(self, img):
"""
Compute XX gradient (second derivative in X direction).
Args:
img: Input image
Returns:
XX gradient image
"""
def gradient_xy(self, img):
"""
Compute XY gradient (mixed second derivative).
Args:
img: Input image
Returns:
XY gradient image
"""
def gradient_yy(self, img):
"""
Compute YY gradient (second derivative in Y direction).
Args:
img: Input image
Returns:
YY gradient image
"""
def get_x_filter(self):
"""Get X gradient filter kernel."""
def get_y_filter(self):
"""Get Y gradient filter kernel."""Usage Example:
import dlib
import cv2
# Load image
img = cv2.imread("image.jpg", cv2.IMREAD_GRAYSCALE)
# Create gradient computer
gradients = dlib.image_gradients(scale=2)
# Compute gradients
grad_x = gradients.gradient_x(img)
grad_y = gradients.gradient_y(img)
# Compute magnitude
import numpy as np
magnitude = np.sqrt(grad_x**2 + grad_y**2)Image Thresholding and Segmentation
Functions for image binarization and automatic threshold selection.
def threshold_image(img):
"""
Threshold image using automatic threshold selection.
Args:
img: Input grayscale image
Returns:
Binary image
"""
def threshold_image(img, threshold: float):
"""
Threshold image using specified threshold.
Args:
img: Input grayscale image
threshold: Threshold value
Returns:
Binary image
"""
def partition_pixels(img):
"""
Find optimal thresholds for image segmentation.
Args:
img: Input grayscale image
Returns:
List of optimal threshold values
"""
def partition_pixels(img, num_thresholds: int):
"""
Find specified number of optimal thresholds.
Args:
img: Input grayscale image
num_thresholds: Number of thresholds to find
Returns:
List of optimal threshold values
"""Image Filtering and Enhancement
Filtering operations for noise reduction and enhancement.
def gaussian_blur(img, sigma: float, max_size: int = 1000):
"""
Apply Gaussian filtering to image.
Args:
img: Input image
sigma: Standard deviation of Gaussian kernel
max_size: Maximum kernel size limit
Returns:
Filtered image
"""Usage Example:
import dlib
import cv2
# Load image
img = cv2.imread("noisy_image.jpg", cv2.IMREAD_GRAYSCALE)
# Apply Gaussian blur
blurred = dlib.gaussian_blur(img, sigma=2.0)
# Automatic thresholding
binary = dlib.threshold_image(blurred)
# Find optimal thresholds
thresholds = dlib.partition_pixels(img, num_thresholds=3)
print(f"Optimal thresholds: {thresholds}")Morphological Operations
Binary image morphological processing and shape analysis.
def skeleton(img):
"""
Skeletonization of binary image.
Args:
img: Input binary image
Returns:
Skeletonized image
"""
def find_line_endpoints(img):
"""
Find endpoints in binary line image.
Args:
img: Input binary image containing lines
Returns:
Image with endpoint locations marked
"""Connected Component Analysis
Connected component labeling and analysis functions.
def label_connected_blobs(
img,
zero_pixels_are_background: bool = True,
neighborhood_connectivity: int = 8,
connected_if_both_not_zero: bool = False
):
"""
Label connected components in binary image.
Args:
img: Input binary image
zero_pixels_are_background: Whether zero pixels are background
neighborhood_connectivity: 4 or 8 connectivity
connected_if_both_not_zero: Alternative connectivity rule
Returns:
Labeled image with component IDs
"""
def label_connected_blobs_watershed(
img,
background_thresh: float,
smoothing: float = 0.0
):
"""
Watershed-based connected component segmentation.
Args:
img: Input grayscale image
background_thresh: Background threshold value
smoothing: Smoothing parameter for preprocessing
Returns:
Labeled image with component IDs
"""Usage Example:
import dlib
import cv2
# Load binary image
img = cv2.imread("binary_shapes.jpg", cv2.IMREAD_GRAYSCALE)
# Label connected components
labeled = dlib.label_connected_blobs(img, neighborhood_connectivity=8)
# Watershed segmentation
grayscale = cv2.imread("cells.jpg", cv2.IMREAD_GRAYSCALE)
watershed_labels = dlib.label_connected_blobs_watershed(
grayscale,
background_thresh=100,
smoothing=1.0
)
# Skeletonization
skeleton_img = dlib.skeleton(img)
endpoints = dlib.find_line_endpoints(skeleton_img)Image Conversion and Color Mapping
Functions for image format conversion and visualization.
def convert_image(img, dtype):
"""
Convert image pixel type.
Args:
img: Input image
dtype: Target data type
Returns:
Converted image
"""
def as_grayscale(img):
"""
Convert image to grayscale.
Args:
img: Input color image
Returns:
Grayscale image
"""
def jet(img):
"""
Convert grayscale image to jet colormap.
Args:
img: Input grayscale image
Returns:
Color-mapped image using jet colormap
"""
def randomly_color_image(img):
"""
Apply random color mapping to labeled image.
Args:
img: Input labeled image
Returns:
Randomly colored image for visualization
"""
def get_rect(img) -> rectangle:
"""
Get bounding rectangle of image.
Args:
img: Input image
Returns:
Rectangle representing image bounds
"""Usage Example:
import dlib
import cv2
# Load color image
color_img = cv2.imread("color_image.jpg")
# Convert to grayscale
gray = dlib.as_grayscale(color_img)
# Apply jet colormap for visualization
jet_colored = dlib.jet(gray)
# Get image bounds
bounds = dlib.get_rect(gray)
print(f"Image size: {bounds.width()} x {bounds.height()}")
# Random coloring for labeled images
labeled_img = dlib.label_connected_blobs(gray > 128)
colored_labels = dlib.randomly_color_image(labeled_img)Edge Detection and Feature Processing
Comprehensive edge detection and feature extraction tools using gradient analysis.
def sobel_edge_detector(img):
"""
Sobel edge detection returning horizontal and vertical gradients.
Args:
img: Input grayscale image
Returns:
Tuple of (horizontal_gradient, vertical_gradient)
"""
def find_bright_lines(gradient_xx, gradient_xy, gradient_yy):
"""
Detect bright lines using Hessian matrix analysis.
Args:
gradient_xx: Second derivative in X direction
gradient_xy: Mixed second derivative
gradient_yy: Second derivative in Y direction
Returns:
Image with detected bright lines
"""
def find_dark_lines(gradient_xx, gradient_xy, gradient_yy):
"""
Detect dark lines using Hessian matrix analysis.
Args:
gradient_xx: Second derivative in X direction
gradient_xy: Mixed second derivative
gradient_yy: Second derivative in Y direction
Returns:
Image with detected dark lines
"""
def find_bright_keypoints(gradient_xx, gradient_xy, gradient_yy):
"""
Detect bright blob-like features using Hessian analysis.
Args:
gradient_xx: Second derivative in X direction
gradient_xy: Mixed second derivative
gradient_yy: Second derivative in Y direction
Returns:
Image with detected bright keypoints
"""
def find_dark_keypoints(gradient_xx, gradient_xy, gradient_yy):
"""
Detect dark blob-like features using Hessian analysis.
Args:
gradient_xx: Second derivative in X direction
gradient_xy: Mixed second derivative
gradient_yy: Second derivative in Y direction
Returns:
Image with detected dark keypoints
"""
def suppress_non_maximum_edges(horizontal_gradient, vertical_gradient):
"""
Apply non-maximum suppression to edge gradients.
Args:
horizontal_gradient: Horizontal gradient image
vertical_gradient: Vertical gradient image
Returns:
Suppressed edge image
"""
def find_peaks(img, non_max_suppression_radius: int, threshold: float = None):
"""
Find local peaks with non-maximum suppression.
Args:
img: Input image
non_max_suppression_radius: Radius for peak suppression
threshold: Minimum peak value (auto-detected if None)
Returns:
List of peak locations as points
"""
def hysteresis_threshold(img, lower_threshold: float = None, upper_threshold: float = None):
"""
Apply hysteresis thresholding for edge linking.
Args:
img: Input edge magnitude image
lower_threshold: Lower threshold (auto-detected if None)
upper_threshold: Upper threshold (auto-detected if None)
Returns:
Hysteresis thresholded binary image
"""Image Resizing and Transformation
Functions for geometric image transformations and resizing operations.
def resize_image(img, rows: int, cols: int):
"""
Resize image to specific dimensions using bilinear interpolation.
Args:
img: Input image
rows: Target height
cols: Target width
Returns:
Resized image
"""
def resize_image(img, scale: float):
"""
Resize image by scale factor.
Args:
img: Input image
scale: Scale factor (>1 for upsampling, <1 for downsampling)
Returns:
Resized image
"""
def transform_image(img, transform_function, rows: int, cols: int):
"""
Apply arbitrary geometric transformation to image.
Args:
img: Input image
transform_function: Function mapping output coordinates to input coordinates
rows: Output image height
cols: Output image width
Returns:
Transformed image
"""
def extract_image_4points(img, corners: list, rows: int, cols: int):
"""
Extract rectified image patch from four corner points.
Args:
img: Input image
corners: List of 4 corner points defining source quadrilateral
rows: Output patch height
cols: Output patch width
Returns:
Rectified image patch
"""
class chip_details:
"""Image chip extraction parameters."""
def __init__(self, rect: rectangle, dims: tuple, angle: float = 0):
"""
Initialize chip details.
Args:
rect: Source rectangle in image
dims: Output dimensions (rows, cols)
angle: Rotation angle in radians
"""
@property
def rect(self) -> rectangle:
"""Source rectangle."""
@property
def rows(self) -> int:
"""Output height."""
@property
def cols(self) -> int:
"""Output width."""
@property
def angle(self) -> float:
"""Rotation angle."""
def extract_image_chip(img, chip_location: chip_details):
"""
Extract single image chip with geometric transformation.
Args:
img: Input image
chip_location: Chip extraction parameters
Returns:
Extracted and transformed image chip
"""
def extract_image_chips(img, chip_locations: list):
"""
Extract multiple image chips with transformations.
Args:
img: Input image
chip_locations: List of chip_details objects
Returns:
List of extracted image chips
"""
def insert_image_chip(img, chip, chip_location: chip_details):
"""
Insert transformed chip back into image.
Args:
img: Target image to modify
chip: Chip image to insert
chip_location: Insertion location and transformation
"""Histogram and Intensity Processing
Functions for histogram analysis and intensity transformations.
def equalize_histogram(img):
"""
Apply histogram equalization for contrast enhancement.
Args:
img: Input grayscale image
Returns:
Histogram-equalized image
"""
def get_histogram(img, hist_size: int):
"""
Compute image histogram.
Args:
img: Input grayscale image
hist_size: Number of histogram bins
Returns:
Histogram array
"""
def convert_image_scaled(img, dtype, threshold: float = 4):
"""
Convert image type with automatic scaling.
Args:
img: Input image
dtype: Target data type
threshold: Scaling threshold parameter
Returns:
Converted and scaled image
"""Advanced Image Analysis
Higher-level image analysis and feature extraction functions.
def max_point(img):
"""
Find pixel location with maximum value.
Args:
img: Input image
Returns:
Point with maximum value
"""
def max_point_interpolated(img):
"""
Find sub-pixel maximum location using interpolation.
Args:
img: Input image
Returns:
Sub-pixel point with interpolated maximum
"""
def zero_border_pixels(img, x_border_size: int, y_border_size: int):
"""
Set image border pixels to zero.
Args:
img: Input image to modify in-place
x_border_size: Horizontal border size
y_border_size: Vertical border size
"""
def sub_image(img, rect: rectangle):
"""
Extract rectangular sub-region from image.
Args:
img: Input image
rect: Rectangle defining sub-region
Returns:
Sub-image as view or copy
"""
def tile_images(images: list):
"""
Tile multiple images into a single grid image.
Args:
images: List of input images to tile
Returns:
Tiled image containing all input images
"""
def min_barrier_distance(img, iterations: int = 10, do_left_right_scans: bool = True):
"""
Compute minimum barrier distance for salient object detection.
Args:
img: Input grayscale image
iterations: Number of diffusion iterations
do_left_right_scans: Enable bidirectional scanning
Returns:
Distance map highlighting salient regions
"""
def normalize_image_gradients(img1, img2):
"""
Normalize gradient vectors between two images.
Args:
img1: First gradient component image
img2: Second gradient component image
Returns:
Tuple of normalized gradient images
"""
def remove_incoherent_edge_pixels(line, horizontal_gradient, vertical_gradient, angle_threshold: float):
"""
Remove edge pixels inconsistent with gradient direction.
Args:
line: Input line/edge image
horizontal_gradient: X gradient image
vertical_gradient: Y gradient image
angle_threshold: Maximum angle deviation in radians
Returns:
Filtered edge image
"""
class pyramid_down:
"""Image pyramid downsampling class."""
def __init__(self, N: int = 2):
"""
Initialize pyramid with downsampling factor.
Args:
N: Downsampling factor
"""
def __call__(self, img):
"""
Apply pyramid downsampling to image.
Args:
img: Input image
Returns:
Downsampled image
"""
class hough_transform:
"""Hough transform for line detection."""
def __init__(self, size: int):
"""
Initialize Hough transform.
Args:
size: Size of Hough space
"""
def __call__(self, img):
"""
Apply Hough transform to detect lines.
Args:
img: Input binary edge image
Returns:
Hough space accumulator
"""
def get_line(self, hough_point):
"""Get line from Hough space point."""
def get_line_angle_in_degrees(self, hough_point) -> float:
"""Get line angle in degrees."""
def get_line_properties(self, hough_point):
"""Get complete line properties."""
def find_pixels_voting_for_lines(self, img, lines: list):
"""Find pixels contributing to detected lines."""
def find_strong_hough_points(self, hough_img, max_lines: int):
"""Find strongest peaks in Hough space."""
def jitter_image(img, num_jitters: int = 1, disturb_colors: bool = False):
"""
Generate jittered versions of image for data augmentation.
Args:
img: Input image
num_jitters: Number of jittered versions to generate
disturb_colors: Whether to apply color distortions
Returns:
List of jittered images
"""
def spatially_filter_image(img, filter_kernel):
"""
Apply spatial filtering with custom kernel.
Args:
img: Input image
filter_kernel: Convolution kernel
Returns:
Filtered image
"""
def spatially_filter_image_separable(img, row_filter, col_filter):
"""
Apply separable spatial filtering.
Args:
img: Input image
row_filter: Row-wise filter kernel
col_filter: Column-wise filter kernel
Returns:
Filtered image
"""Complete Image Processing Pipeline Example:
import dlib
import cv2
import numpy as np
# Load and preprocess image
img = cv2.imread("document.jpg")
gray = dlib.as_grayscale(img)
# Noise reduction
denoised = dlib.gaussian_blur(gray, sigma=1.0)
# Edge detection using gradients
gradients = dlib.image_gradients(scale=1)
grad_x = gradients.gradient_x(denoised)
grad_y = gradients.gradient_y(denoised)
edges = np.sqrt(grad_x**2 + grad_y**2)
# Thresholding
binary = dlib.threshold_image(edges)
# Morphological processing
skeleton_img = dlib.skeleton(binary)
endpoints = dlib.find_line_endpoints(skeleton_img)
# Connected component analysis
labeled = dlib.label_connected_blobs(binary)
colored_result = dlib.randomly_color_image(labeled)
# Final visualization
jet_result = dlib.jet(gray)This comprehensive image processing capability provides the foundation for computer vision applications, preprocessing for machine learning, and advanced image analysis tasks.
Install with Tessl CLI
npx tessl i tessl/pypi-dlib