Transform Using Pyramid Upsampling

SUMMARY

Transform Using Pyramid Upsampling upsamples an image using Gaussian pyramid.

Pyramid up increases image resolution by upsampling and smoothing, useful for image enlargement and multi-scale reconstruction. This operation doubles the image dimensions and applies smoothing to create a larger image. It's commonly used to reconstruct images from pyramid representations or to upsample images for visualization or further processing.

Use this Skill when you want to increase image resolution using pyramid upsampling.

The Skill

from telekinesis import pupil

upsampled_image = pupil.transform_image_using_pyramid_upsampling(
    image=image,
    scale_factor=datatypes.Float(2.0),
)

API Reference

Example

Input Image

Original low-resolution image

Output Image 1

Upsampled image, Pyramid Level 1, with scale_factor=2.0 - resolution doubled

Output Image 2

Upsampled image, Pyramid Level 2, with scale_factor=2.0 - resolution doubled

Output Image 3

Upsampled image, Pyramid Level 3, with scale_factor=2.0 - resolution doubled

The Code

from telekinesis import pupil
from datatypes import io
import pathlib

# Optional for logging
from loguru import logger

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

# Load image
filepath = str(DATA_DIR / "images" / "buttons_arranged_downsampled.png")
image = io.load_image(filepath=filepath)
logger.success(f"Loaded image with shape {image.to_numpy().shape}")

# Apply pyramid upsampling
transformed_image = pupil.transform_image_using_pyramid_upsampling(
    image=image,
    scale_factor=2.0,
)
logger.success(
    f"Applied Pyramid upsampling with upsampled image shape {transformed_image.to_numpy().shape}"
)

The Explanation of the Code

Pyramid upsampling increases image resolution by interpolating new pixels and applying smoothing to produce a larger image, resulting in smooth upsampling suitable for pyramid reconstruction and multi-scale processing.

The input image is loaded from disk using io.load_image.These imports provide access to the Pupil SDK, type-safe datatypes for I/O operations, path handling utilities, and logging functionality.

from telekinesis import pupil
from datatypes import io
import pathlib

# Optional for logging
from loguru import logger

Next, the image is loaded from disk using the io.load_image function. The input image may be either grayscale (H, W) or color (H, W, C). A log message confirms successful loading and reports the image dimensions.

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

# Load image
filepath = str(DATA_DIR / "images" / "buttons_arranged_downsampled.png")
image = io.load_image(filepath=filepath)
logger.success(f"Loaded image with shape {image.to_numpy().shape}")

Pyramid up provides smooth upsampling with interpolation and can be controlled through the parameters.

scale_factor controls the scaling factor for upsampling. A value of 2.0 doubles both width and height, resulting in 4 times the total pixels. This is the standard value for pyramid upsampling and is used to reverse a pyramid downsampling operation. Finally, apply the pyramid upsampling operation.

transformed_image = pupil.transform_image_using_pyramid_upsampling(
    image=image,
    scale_factor=2.0,
)
logger.success(
    f"Applied Pyramid upsampling with upsampled image shape {transformed_image.to_numpy().shape}"
)

Pyramid upsampling doubles the image dimensions by interpolating new pixels and applying smoothing. This creates smooth upsampling that is the inverse operation of pyramid downsampling, making it ideal for reconstructing images from pyramid representations or upsampling images for visualization and further processing.

The operation returns a new image with increased resolution. The original image remains unchanged. This Skill performs a representation change (scale-space transform) rather than photometric enhancement or spatial filtering, making it commonly used for pyramid reconstruction, image enlargement, Laplacian pyramids, and multi-scale fusion.

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 transform_image_using_pyramid_upsampling

How to Tune the Parameters

The transform_image_using_pyramid_upsampling Skill has 1 parameter:

scale_factor (default: 2.0):

• The scaling factor for upsampling
• Typical value: 2.0 (doubles dimensions)
• Use 2.0 for standard pyramid upsampling

TIP

Best practice: Pyramid up is the inverse of pyramid down. Use scale_factor=2.0 to reverse a pyramid_downsampling operation.

Where to Use the Skill in a Pipeline

Transform Using Pyramid Up is commonly used in the following pipelines:

• Pyramid reconstruction - Rebuild images from pyramid representations
• Image enlargement - Increase image size for visualization
• Laplacian pyramids - Create residual images for blending
• Super-resolution preprocessing - Initial upsampling before enhancement
• Multi-scale fusion - Combine information from different scales

A typical pipeline for Laplacian pyramid looks as follows:

# Example pipeline using pyramid up (parameters omitted).

from telekinesis import pupil

# 1. Downsample
down = pupil.transform_image_using_pyramid_downsampling(image=original, ...)

# 2. Upsample back
up = pupil.transform_image_using_pyramid_upsampling(image=down, ...)

# 3. Compute Laplacian (residual)
laplacian = original - up

Related skills to build such a pipeline:

• transform_image_using_pyramid_downsampling: Downsample images
• filter_image_using_gaussian_blur: Smoothing operations

Alternate Skill

Pyramid upsampling performs fixed-factor, smooth interpolation for scale-space reconstruction. For arbitrary resizing or sharper results, use resize-based operations instead.

Skill	When to use it instead
transform_image_using_pyramid_downsampling	Use for reducing image resolution or building Gaussian / Laplacian pyramids. Pyramid up is its inverse.
filter_image_using_gaussian_blur	Use when you only need smoothing, not resolution change. Pyramid up always increases image size.

When Not to Use the Skill

Do not use Transform Using Pyramid Up when:

• You need sharp, pixelated upsampling (Use resize with NEAREST interpolation)
• You want custom interpolation methods (Use resizing instead)
• You need non-2.0 scale factors (Use resizing for arbitrary scaling)
• You're doing super-resolution (Pyramid up provides basic upsampling; use specialized super-resolution methods)