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

Input Image

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

Upsampled Image 1

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

Upsampled Image 2

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

The Code

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

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

# Load image
filepath = str(DATA_DIR / "images" / "buttons_arranged_downsampled.webp")
image = io.load_image(filepath=filepath)
logger.success("Loaded image shape: {}", image.to_numpy().shape)

# Apply pyramid upsampling transformation
filtered_image = pupil.transform_image_using_pyramid_upsampling(
    image=image,
    scale_factor=2.0,
)

# Access results
filtered_image_np = filtered_image.to_numpy()
logger.success("Applied pyramid upsampling. Transformed output image shape: {}", filtered_image_np.shape)

The Explanation of the Code

The code begins by importing the necessary modules: pupil for image processing operations, io for data handling, pathlib for path management, and loguru for logging.

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

Next, an image is loaded from a .png file using the io.load_image function. The input image may be either grayscale or color.

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

# Load image
filepath = str(DATA_DIR / "images" / "buttons_arranged_downsampled.webp")
image = io.load_image(filepath=filepath)

The main operation uses the transform_image_using_pyramid_upsampling Skill from the pupil module. This Skill upsamples an image using Gaussian pyramid by interpolating and smoothing to increase resolution. The parameters can be tuned to control the scale factor depending on the characteristics of the input image.

filtered_image = pupil.transform_image_using_pyramid_upsampling(
    image=image,
    scale_factor=2.0,
)

Finally, the upsampled image is converted to a NumPy array using to_numpy() for further processing, visualization, or downstream tasks.

filtered_image_np = filtered_image.to_numpy()
logger.success(f"Output image shape: {filtered_image_np.shape}")

This operation is particularly useful in robotics and vision pipelines for image enlargement, multi-scale reconstruction, and pyramid representation, where increasing image resolution using pyramid upsampling is required.

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. Must be greater than 1
• Units: Dimensionless (multiplier)
• Increase to create larger output
• Decrease to create smaller output (closer to original size)
• Typical range: 1.1–4.0 (min: 1.1, max: 4.0)
• Use 2.0 for standard pyramid upsampling (double size); 4.0 for quadruple size

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

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)