Filter Image Using Gaussian Blur

SUMMARY

Filter Image Using Gaussian Blur smooths an image using a Gaussian-weighted kernel.

It convolves the image with a kernel_size x kernel_size Gaussian kernel that weights nearby pixels more heavily than distant ones, giving a more natural-looking blur than the uniform averaging of filter_image_using_blur/filter_image_using_box, while remaining faster than filter_image_using_bilateral. When sigma_x/sigma_y are left at 0 (default), the standard deviation is derived automatically from kernel_size. It is also a common pre-processing step before gradient/edge filters (filter_image_using_sobel, filter_image_using_laplacian) to suppress noise-driven false edges.

Use this Skill when you want to smooth an image with a natural-looking blur and reduce noise before further processing.

The Skill

from telekinesis import pupil

filtered_image = pupil.filter_image_using_gaussian_blur(
    image=image,
    kernel_size=19,
    sigma_x=2.0,
    sigma_y=3.0,
    border_type="default",
)

API Reference

Full parameter and return type documentation for filter_image_using_gaussian_blur.

View Reference →

Example

Input Image

Original noisy image

Filtered Image

Blurred image with kernel_size=19, sigma_x=2.0, sigma_y=3.0

The Code

"""Demonstrates filter_image_using_gaussian_blur operation."""

from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def filter_image_using_gaussian_blur_example():
    """Applies filter_image_using_gaussian_blur operation."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/nuts_scattered_noised.jpg"
    image = datatypes.Image.from_url(image_url)

    # ===================== Run Skill ==========================================
    filtered_image = pupil.filter_image_using_gaussian_blur(
        image=image,
        kernel_size=19,
        sigma_x=2.0,
        sigma_y=3.0,
        border_type="default",
    )

    # ===================== Log ================================================
    logger.success(f"Applied filter_image_using_gaussian_blur on {image}")
    logger.success(f"Result: {filtered_image}")

    # ===================== Visualization  (Optional) ======================
    rr.init("filter_image_using_gaussian_blur_example", spawn=True)
    datatypes.visualize(image, entity_path="1-Original")
    datatypes.visualize(filtered_image, entity_path="2-Filtered")

if __name__ == "__main__":
    filter_image_using_gaussian_blur_example()

Runnable examples are available in the Telekinesis examples repository.

Follow the README in that repository to set up the environment, run this specific example with:

cd telekinesis-examples
python examples/image_processing/filter_image_using_gaussian_blur.py

Parameter Configuration

Key	Type	Default	Description
image	datatypes.Image | np.ndarray	required	The input image to filter, shape (H, W) or (H, W, C)
kernel_size	datatypes.Int | int	3	Size of the Gaussian kernel. Must be odd
sigma_x	datatypes.Float | float | int	0.0	Standard deviation in the X direction. When 0, computed from kernel_size
sigma_y	datatypes.Float | float | int	0.0	Standard deviation in the Y direction. When 0, computed from kernel_size
border_type	datatypes.String | str	"default"	Border handling mode: "default", "constant", "replicate", "reflect", "reflect 101"

Returns

Type	Description
datatypes.Image	The blurred image, same shape as the input

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
ValueError	kernel_size is not odd, or border_type is not one of the supported border modes
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, or the response failed to deserialize
RequestTimeoutError	The request to the Pupil service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Pupil service rejected the request due to invalid input, invalid data, or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired
AuthenticationServiceError	The authentication service was unavailable
ServerError	The Pupil service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

The filter_image_using_gaussian_blur Skill exposes four parameters that control the kernel size, its spread, and border handling.

kernel_size

• Controls: The spatial extent of the Gaussian kernel.
• Units: Pixels
• Default: 3
• Increase → more blur, considers more distant pixels, slower
• Decrease → less blur, faster
• Typical range: 3-31. Use 3-7 for light blur, 7-15 for moderate, 15-31 for heavy

sigma_x

• Controls: The standard deviation of the Gaussian kernel along X.
• Units: Pixels
• Default: 0.0 (auto-computed from kernel_size)
• Increase → more horizontal blur
• Decrease → less horizontal blur
• Typical range: 0.0-10.0. Use 0.0 for auto, 1.0-3.0 for light, 3.0-7.0 for moderate, 7.0-10.0 for heavy

sigma_y

• Controls: The standard deviation of the Gaussian kernel along Y.
• Units: Pixels
• Default: 0.0 (auto-computed from kernel_size)
• Increase → more vertical blur
• Decrease → less vertical blur
• Typical range: 0.0-10.0. Use 0.0 for auto, 1.0-3.0 for light, 3.0-7.0 for moderate, 7.0-10.0 for heavy

border_type

• Controls: How pixels beyond the image boundary are synthesized when the kernel extends past the edge.
• Default: "default"
• Options:
  • default – library default (same as reflect 101)
  • constant – pads with a fixed value
  • replicate – repeats the edge pixel
  • reflect – mirrors without repeating the edge pixel
  • reflect 101 – mirrors with the edge pixel repeated, avoiding dark borders

TIP

Best practice: Leave sigma_x/sigma_y at 0.0 and control blur strength through kernel_size unless you need an isotropic blur with an explicit sigma or a directional blur (unequal sigma_x/sigma_y).

Where to Use the Skill

Common pipelines include:

• Noise reduction – Suppress Gaussian-like sensor noise before analysis
• Pre-processing for edge/gradient detection – Reduce noise-driven false edges before filter_image_using_sobel or filter_image_using_laplacian
• Scale-space / pyramid construction – Smooth before downsampling with transform_image_using_pyramid_downsampling
• General smoothing before segmentation – Reduce fine-detail noise before thresholding or clustering

Alternative Skills

Skill	vs. Filter Image Using Gaussian Blur
filter_image_using_blur	Uniform box average instead of Gaussian weighting. Faster but less natural-looking.
filter_image_using_box	Same uniform box averaging, with extra control over normalization and output bit depth.
filter_image_using_bilateral	Also weights on color similarity, preserving edges. Slower than Gaussian blur.
filter_image_using_median_blur	Targets salt-and-pepper/impulse noise rather than general Gaussian-like noise.

When Not to Use the Skill

Do not use Filter Image Using Gaussian Blur when:

• You need to preserve sharp edges (use filter_image_using_bilateral instead)
• You're removing salt-and-pepper noise (use filter_image_using_median_blur instead)
• You need the fastest possible smoothing (use filter_image_using_blur or filter_image_using_box)
• You need directional/oriented texture filtering (use filter_image_using_gabor instead)

TIP

For isotropic (circular) blur, keep sigma_x equal to sigma_y; use unequal values only when you deliberately want directional (e.g. motion-like) blur.