Filter Image Using Sobel

SUMMARY

Filter Image Using Sobel applies Sobel filter for directional edge detection.

Sobel operator computes gradients in X and Y directions, useful for detecting edges and their orientation. This first-order derivative filter is one of the most widely used edge detectors in computer vision, providing both edge magnitude and direction information. It's particularly effective for detecting edges in noisy environments when combined with appropriate preprocessing.

Use this Skill when you want to detect edges with directional information using gradient computation.

The Skill

from telekinesis import pupil

gradient_image = pupil.filter_image_using_sobel(
    image=image,
    dx=1,
    dy=1,
    kernel_size=3,
    scale=1.0,
    delta=0.0,
    output_format="64bit",
    border_type="default",
)

API Reference

Example

Input Image

Original grayscale image

Output Image

This output shows the raw Sobel response with dx=1 and dy=1, which emphasizes fine texture and diagonal intensity changes rather than clean object edges. This behavior is expected for this configuration.

The Code

from telekinesis import pupil
from datatypes import io, datatypes

import pathlib
from loguru import logger

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load the image
filepath = str(DATA_DIR / "images" / "nuts.jpg")
image = io.load_image(filepath=filepath)

# Apply Sobel filter
gradient_image = pupil.filter_image_using_sobel(
    image=image,
    dx=1,
    dy=1,
    kernel_size=9,
    scale=1.0,
    delta=0.0,
    output_format="64bit",
    border_type="default",
)
logger.success(f"Applied Sobel filter with gradient image shape as {gradient_image.to_numpy().shape}")

The Explanation of the Code

The Sobel filter computes first-order image gradients to highlight intensity changes in specific directions. Unlike second-order operators, Sobel provides both edge strength and orientation, making it useful when directional information is required.

The code begins by importing the required modules. These provide access to the Pupil SDK for filtering operations and logging utilities.

from telekinesis import pupil
from datatypes import io, datatypes

import pathlib
from loguru import logger

filepath = str(DATA_DIR / "images" / "nuts.jpg")
image = io.load_image(filepath=filepath)

dx and dy define the order of the derivative in the horizontal and vertical directions. Setting both to 1 computes gradients in both directions, producing a combined edge response.

kernel_size controls the size of the Sobel convolution kernel. Larger kernels capture broader edge structures, while smaller kernels emphasize fine details.

scale scales the computed gradient values, and delta adds an optional offset to the output, which can be useful for visualization or value shifting.

output_format specifies the numerical precision of the output image, and border_type defines how pixels near the image boundaries are handled during convolution.

The Sobel filter is then applied using the filter_image_using_sobel Skill. Internally, the image is convolved with Sobel kernels to compute spatial derivatives according to the specified parameters.

gradient_image = pupil.filter_image_using_sobel(
    image=image,
    dx=1,
    dy=1,
    kernel_size=9,
    scale=1.0,
    delta=0.0,
    output_format="64bit",
    border_type="default",
)
logger.success(f"Applied Sobel filter with gradient image shape as {gradient_image.to_numpy().shape}")

The resulting output image represents gradient intensity, where stronger values correspond to sharper intensity transitions. The original image remains unchanged, allowing the Sobel output to be combined with other processing stages if needed.

Running the Example

Runnable examples are available in the Telekinesis examples repository. Follow the README in that repository to set up the environment. Once set up, you can run this specific example with:

cd telekinesis-examples
python examples/pupil_examples.py --example filter_image_using_sobel

How to Tune the Parameters

The filter_image_using_sobel Skill has 7 parameters:

dx (default: 1):

• The order of the derivative in X direction
• 0 means no derivative, 1 means first derivative, 2 means second derivative
• Typical values: 0, 1, 2
• Use 1 for horizontal edges, 0 to ignore X direction

dy (default: 1):

• The order of the derivative in Y direction
• Typical values: 0, 1, 2
• Use 1 for vertical edges, 0 to ignore Y direction

kernel_size (default: 3):

• The size of the Sobel kernel. Must be 1, 3, 5, 7, or 9.
• Larger kernels detect larger-scale edges
• Typical values: 1, 3, 5, 7, 9
• Use 3 for standard edge detection, 5-7 for larger features

scale (default: 1.0):

• The scale factor for computed gradient values
• Increase to amplify edge responses
• Typical range: 0.1-10.0

delta (default: 0.0):

• The offset added to the output
• Typical range: -128.0 to 128.0

output_format (default: "64bit"):

• The output bit depth
• Options: "8bit", "16bit", "32bit", "64bit"

border_type (default: "default"):

• Border handling mode
• Options: "default", "constant", "replicate", "reflect", "wrap"

TIP

Best practice: Use (dx=1, dy=0) for horizontal edges, (0, 1) for vertical edges, or (1, 1) for both directions. Combine separate X and Y gradient images using: magnitude = sqrt(Gx² + Gy²).

Where to Use the Skill in a Pipeline

Filter Using Sobel is commonly used in the following pipelines:

• Edge detection - Detect edges with direction information
• Gradient computation - Calculate image gradients for feature extraction
• Image sharpening - Enhance edges using gradient information
• Flow estimation - Compute spatial gradients for optical flow
• Feature detection - Find corner and edge features

A typical pipeline for edge magnitude and direction looks as follows:

# Example pipeline using Sobel (parameters omitted).

from telekinesis import pupil
import numpy as np
from datatypes import io

# 1. Load and preprocess
image = io.load_image(filepath=...)
smoothed = pupil.filter_image_using_gaussian_blur(image=image, ...)

# 2. Compute X and Y gradients
grad_x = pupil.filter_image_using_sobel(image=smoothed, dx=1, dy=0, ...)
grad_y = pupil.filter_image_using_sobel(image=smoothed, dx=0, dy=1, ...)

# 3. Compute gradient magnitude and direction
magnitude = np.sqrt(grad_x**2 + grad_y**2)
direction = np.arctan2(grad_y, grad_x)

Related skills to build such a pipeline:

• load_image: Load images
• filter_image_using_gaussian_blur: Pre-smooth for noise reduction
• filter_image_using_scharr: Higher accuracy gradient estimation

Alternative Skills

Skill	vs. Filter Using Sobel
filter_image_using_scharr	Scharr has better rotation invariance and accuracy. Use Scharr for precise gradients, Sobel for standard edge detection.
filter_image_using_laplacian	Laplacian computes second derivatives. Use Laplacian for omnidirectional edges, Sobel for directional gradients.

When Not to Use the Skill

Do not use Filter Using Sobel when:

• You need the most accurate gradient estimation (Use Scharr instead)
• You need omnidirectional edge detection without direction (Use Laplacian instead)
• You're working with very noisy images (Pre-smooth with Gaussian blur first)
• You need connected edge contours (Use Canny edge detector instead)