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.6,
weight_b=0.4,
)Example
Image A

Bin of gears and spacers (structured-light camera gray image)
Image B

Colour instance mask of the same view, one colour per part
Blended Image

Weighted overlay with weight_a = 0.6, weight_b = 0.4: each part is tinted with its instance colour while the part texture stays visible
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/xyzibd_gear_bin_photoneo.jpg"
image_a = datatypes.Image.from_url(image_url)
# ===================== Load Second Image (colorized instance mask) ==========================================
mask_url = "https://assets.telekinesis.ai/examples/v1/images/xyzibd_gear_bin_instances.png"
image_b = datatypes.Image.from_url(mask_url)
# ===================== Run Skill ==========================================
filtered_image = pupil.overlay_images_using_weighted_overlay(
image_a=image_a,
image_b=image_b,
weight_a=0.6,
weight_b=0.4,
)
# ===================== 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.pyParameter Configuration
| Parameter | 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, the response was not returned as an Arrow stream, 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 or malformed input (HTTP 400/422), an unrecognized endpoint (HTTP 404), or another unexpected 4xx response |
AuthenticationError | The API key was rejected as invalid or expired (HTTP 401) |
AuthenticationServiceError | The authentication service returned an invalid response, was temporarily unavailable, or timed out (HTTP 502/503/504) |
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_acontributes 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_bcontributes 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, orbitwise_xor_imagesinstead) - You need to highlight differences rather than blend them away (use
bitwise_difference_imagesinstead) image_aandimage_bhave different sizes (resize one to match first, e.g. withresize_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)