Overlay Images Using Weighted Overlay

SUMMARY

Overlay Images Using Weighted Overlay blends two images using a weighted (alpha) overlay.

It computes image_a * weight_a + image_b * weight_b per pixel. Both images must share the same (H, W) — resize one with resize_image_with_aspect_fit first if they differ. Setting weight_a + weight_b == 1.0 produces a standard cross-fade; weights that sum to more or less than 1.0 deliberately brighten or darken the blend.

Use this Skill when you want to blend two same-size images with configurable per-image weights.

The Skill

from telekinesis import pupil

blended_image = pupil.overlay_images_using_weighted_overlay(
    image_a=image_a,
    image_b=image_b,
    weight_a=0.5,
    weight_b=0.5,
)

API Reference

Full parameter and return type documentation for overlay_images_using_weighted_overlay.

View Reference →

Example

Image A

First input image

Image B

Second input image, a rotated copy of Image A

Blended Image

Weighted overlay with weight_a = weight_b = 0.5

The Code

"""Demonstrates weighted overlay blending of two images."""

from loguru import logger
import rerun as rr

from telekinesis import pupil, datatypes


def overlay_images_using_weighted_overlay_example():
    """Blends two images using weighted overlay."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/rusted_metal_gear.jpg"
    image_a = datatypes.Image.from_url(image_url)
    image_a = pupil.resize_image_with_aspect_fit(
        image=image_a,
        resize_width=512,
        resize_height=512,
    )

    # ===================== Create Second Image ==========================================
    image_b = pupil.rotate_image(
        image=image_a, angle_in_deg=60.0, keep_image_size=True
    )

    # ===================== Run Skill ==========================================
    filtered_image = pupil.overlay_images_using_weighted_overlay(
        image_a=image_a,
        image_b=image_b,
        weight_a=0.5,
        weight_b=0.5,
    )

    # ===================== Log ================================================
    logger.success(f"Weighted overlay between {image_a} and {image_b}")
    logger.success(f"Result: {filtered_image}")

    # ===================== Visualization  (Optional) ======================
    rr.init("overlay_images_using_weighted_overlay_example", spawn=True)
    datatypes.visualize(image_a, entity_path="1-Image A")
    datatypes.visualize(image_b, entity_path="2-Image B")
    datatypes.visualize(filtered_image, entity_path="3-Blended")

if __name__ == "__main__":
    overlay_images_using_weighted_overlay_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/overlay_images_using_weighted_overlay.py

Parameter Configuration

Key	Type	Default	Description
image_a	datatypes.Image | np.ndarray	required	First input image, shape (H, W) or (H, W, C)
image_b	datatypes.Image | np.ndarray	required	Second input image, blended with image_a. Must have the same (H, W) as image_a
weight_a	datatypes.Float | float | int	0.5	Weight applied to image_a. Increasing makes the blend look more like image_a
weight_b	datatypes.Float | float | int	0.5	Weight applied to image_b. Increasing makes the blend look more like image_b

Returns

Type	Description
datatypes.Image	Same shape as image_a, containing the weighted blend

Raises

Exception	Condition
TypeError	Any parameter has an invalid type
ValueError	image_a and image_b have different width or height
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 overlay_images_using_weighted_overlay Skill exposes two weights that control each image's contribution to the blend.

weight_a

• Controls: How strongly image_a contributes to the output.
• Units: Dimensionless
• Default: 0.5
• Increase → the blend looks more like image_a
• Decrease → the blend looks less like image_a
• Typical range: 0.0–1.0

weight_b

• Controls: How strongly image_b contributes to the output.
• Units: Dimensionless
• Default: 0.5
• Increase → the blend looks more like image_b
• Decrease → the blend looks less like image_b
• Typical range: 0.0–1.0

TIP

Best practice: Keep weight_a + weight_b == 1.0 for a standard cross-fade that preserves overall brightness. Use weights that sum to more or less than 1.0 only when you deliberately want to brighten or darken the blend, e.g. for a double-exposure effect.

Where to Use the Skill

Common pipelines include:

• Visualization overlays – Blend an annotation or heatmap over the source image
• Cross-fades – Transition smoothly between two frames or states
• Multi-exposure compositing – Combine differently exposed captures of the same scene
• Data augmentation – Blend pairs of images to synthesize training variations

Alternative Skills

Skill	vs. Overlay Images Using Weighted Overlay
bitwise_difference_images	Highlights where two images differ (absolute difference) instead of blending them together.
bitwise_and_images	Combines two binary masks with a logical AND instead of an intensity-weighted sum.
bitwise_or_images	Combines two binary masks with a logical OR instead of an intensity-weighted sum.

When Not to Use the Skill

Do not use Overlay Images Using Weighted Overlay when:

• You need logical mask combination, not intensity blending (use bitwise_and_images, bitwise_or_images, or bitwise_xor_images instead)
• You need to highlight differences rather than blend them away (use bitwise_difference_images instead)
• image_a and image_b have different sizes (resize one to match first, e.g. with resize_image_with_aspect_fit)
• You need per-pixel or per-region alpha, not a single global weight per image (this Skill applies one scalar weight to the whole image)