Filter Image Using Laplacian

SUMMARY

Filter Image Using Laplacian detects edges by computing the second spatial derivative of an image.

It locates regions where intensity changes rapidly by responding to zero-crossings/sign-changes of the second derivative, which makes it isotropic (direction-independent) — unlike the directional, first-derivative filter_image_using_sobel. It is also more sensitive to noise than a first-derivative filter; pre-smooth with filter_image_using_gaussian_blur first if the input is noisy. output_format controls whether negative edge responses are preserved (signed/float formats) or clipped (unsigned formats).

Use this Skill when you want to detect edges in all directions using second-order derivatives.

The Skill

from telekinesis import pupil

filtered_image = pupil.filter_image_using_laplacian(
    image=image,
    output_format="32bit",
    kernel_size=5,
    scale=1.0,
    delta=0.0,
    border_type="default",
)

API Reference

Full parameter and return type documentation for filter_image_using_laplacian.

View Reference →

Example

Input Image

Original grayscale image

Filtered Image

Edge response with kernel_size=5, output_format="32bit" - highlights edges and fine details

The Code

"""Demonstrates filter_image_using_laplacian operation."""

from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def filter_image_using_laplacian_example():
    """Applies filter_image_using_laplacian operation."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/flat_mechanical_component_denoised.png"
    image = datatypes.Image.from_url(image_url)

    # ===================== Run Skill ==========================================
    filtered_image = pupil.filter_image_using_laplacian(
        image=image,
        output_format="32bit",
        kernel_size=5,
        scale=1.0,
        delta=0.0,
        border_type="default",
    )

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

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

if __name__ == "__main__":
    filter_image_using_laplacian_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_laplacian.py

Parameter Configuration

Key	Type	Default	Description
image	datatypes.Image | np.ndarray	required	The input image to filter. Recommended to be grayscale, shape (H, W)
kernel_size	datatypes.Int | int	1	Size of the Laplacian kernel. Must be a positive odd integer (typically 1, 3, 5, or 7)
output_format	datatypes.String | str	"same as input"	Output bit depth: "same as input", "8bit", "16bitS", "16bitU", "32bit", "64bit". Signed/float formats preserve negative edge responses; "8bit"/"16bitU" clip them
scale	datatypes.Float | float | int	1.0	Scale factor applied to the computed Laplacian values
delta	datatypes.Float | float | int	0.0	Offset added to the output, useful for visualization
border_type	datatypes.String | str	"default"	Border handling mode: "default", "constant", "replicate", "reflect", "reflect 101"

Returns

Type	Description
datatypes.Image	The second-derivative edge response, same shape as the input, in the dtype specified by output_format

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 a positive odd integer, or output_format/border_type is not one of the supported options
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_laplacian Skill exposes five parameters that control the scale of edges detected, their amplification, and how the response is represented.

kernel_size

• Controls: The spatial scale of the second-derivative approximation.
• Units: Pixels
• Default: 1
• Increase → detects larger-scale edges, more compute
• Decrease → finer edge detail, more noise-sensitive
• Typical range: 1, 3, 5, 7. Use 1 or 3 for fine details, 5 or 7 for larger edges

output_format

• Controls: The numerical bit depth/precision of the returned edge response.
• Default: "same as input"
• Options:
  • same as input – keeps the input dtype; may clip negative responses
  • 8bit – unsigned 8-bit; clips negative values, prefer a signed/float format if negative responses matter
  • 16bitS – signed 16-bit; preserves negative responses
  • 16bitU – unsigned 16-bit
  • 32bit / 64bit – float; preserves negative responses and precision

scale

• Controls: A multiplier applied to the raw Laplacian values.
• Default: 1.0
• Increase → amplifies edge responses
• Decrease → more subtle edge responses
• Typical range: 0.1-10.0. Use 0.1-1.0 for subtle edges, 1.0-5.0 for normal, 5.0-10.0 for strong emphasis

delta

• Controls: A constant offset added to every output pixel.
• Default: 0.0
• Typical range: -128.0 to 128.0. Use 0.0 for numerical processing; a positive offset (e.g. 128.0) shifts negative values into a visible range for 8-bit visualization

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: Use a signed or float output_format ("16bitS", "32bit", "64bit") for downstream numerical processing so negative edge responses aren't lost; only add a delta offset and switch to an unsigned format for direct 8-bit visualization.

Where to Use the Skill

Common pipelines include:

• Edge detection for shape analysis – Find object boundaries with omnidirectional sensitivity
• Image sharpening – Subtract the Laplacian response from the original image to enhance detail
• Zero-crossing / blob detection – Locate edges or blobs at sign changes of the second derivative
• Focus/sharpness assessment – Use response magnitude as a proxy for image sharpness

Alternative Skills

Skill	vs. Filter Image Using Laplacian
filter_image_using_sobel	Computes a directional first-order gradient instead of an isotropic second-order response; use Sobel when edge orientation matters.
filter_image_using_scharr	A first-derivative gradient filter with better rotation invariance than Sobel; still directional, unlike Laplacian.
filter_image_using_gaussian_blur	Common pre-processing step to reduce noise before applying the Laplacian.

When Not to Use the Skill

Do not use Filter Image Using Laplacian when:

• The input hasn't been denoised (the second derivative amplifies noise heavily; pre-smooth with filter_image_using_gaussian_blur first)
• You need edge orientation/direction (use filter_image_using_sobel or filter_image_using_scharr instead)
• You need thick, connected edge contours rather than a raw per-pixel response (post-process with thresholding or morphological operations)
• You need the most accurate gradient magnitude (use a first-derivative filter such as Sobel or Scharr)