Telekinesis Agentic Skill Library

Appearance

Resize Image With Aspect Fit ​

SUMMARY

Resize Image With Aspect Fit resizes an image to fit within target dimensions while preserving aspect ratio.

Scales the image to fit inside the target width and height without distortion, then pads to reach exact dimensions. Useful for model inputs that require fixed size while avoiding distortion from stretching.

Use this Skill when you want to resize to target dimensions with aspect ratio preserved.

The Skill ​

python
from telekinesis import pupil

resized_image = pupil.resize_image_with_aspect_fit(
    image=image,
    resize_width=400,
    resize_height=300,
    pad_color=(128, 128, 128),
    interpolation_method="linear",
)

API Reference

Example ​

Input Image

Input image

Original image

Resized Image

Output image

Resized to fit 400x300 with padding

The Code ​

python
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" / "gearbox.webp")
image = io.load_image(filepath=filepath)
logger.success(f"Loaded image from {filepath}")

# Resize to fit within target dimensions while preserving aspect ratio
resized_image = pupil.resize_image_with_aspect_fit(
    image=image,
    resize_width=400,
    resize_height=300,
    interpolation_method="linear",
)

# Access results
resized_image_np = resized_image.to_numpy()
logger.success("Resized image (aspect fit) from input shape: {}, to output shape: {}", image.to_numpy().shape, resized_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.

python
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.

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

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

The main operation uses the resize_image_with_aspect_fit Skill from the pupil module. This Skill resizes an image to fit within target dimensions while preserving aspect ratio, scaling to fit inside the target rectangle and padding to reach exact dimensions. The parameters can be tuned to control target size, pad color, and interpolation method depending on the characteristics of the input image.

python
resized_image = pupil.resize_image_with_aspect_fit(
    image=image,
    resize_width=400,
    resize_height=300,
    interpolation_method="linear",
)

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

python
resized_image_np = resized_image.to_numpy()
logger.success(f"Output image shape: {resized_image_np.shape}")

This operation is particularly useful in robotics and vision pipelines for fixed-size model inputs, neural network preprocessing, and dimension normalization, where resizing without distortion 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:

bash
cd telekinesis-examples
python examples/pupil_examples.py --example resize_image_with_aspect_fit

How to Tune the Parameters ​

The resize_image_with_aspect_fit Skill has 4 parameters:

resize_width (no default—required):

  • Desired output width in pixels
  • Units: Pixels
  • Typical range: 32–4096 (depends on use case)
  • Use model input size (e.g., 224, 640) for neural networks

resize_height (no default—required):

  • Desired output height in pixels
  • Units: Pixels
  • Typical range: 32–4096 (depends on use case)
  • Use model input size for neural networks

pad_color (default: (128, 128, 128)):

  • BGR tuple for padding the letterboxed regions
  • Units: BGR values (0–255)
  • Use (128, 128, 128) for neutral gray; (0, 0, 0) for black
  • Use neutral gray when feeding to models; black for dark backgrounds

interpolation_method (default: "linear"):

  • The interpolation method for resizing
  • Options: "nearest", "linear", "cubic"
  • Use "linear" for most cases; "cubic" for higher quality

TIP

Best practice: Use neutral gray (128, 128, 128) for padding when feeding to models. Use black (0, 0, 0) for dark backgrounds.

Where to Use the Skill in a Pipeline ​

Resize Image With Aspect Fit is commonly used in the following pipelines:

  • Model input - Fixed-size input without distortion
  • Batch processing - Uniform dimensions for batching
  • Display - Fit thumbnails in fixed UI slots

Related skills to build such a pipeline:

  • resize_image: Scale by factor only
  • crop_image_using_bounding_boxes: Extract regions after resize

Alternative Skills ​

Skillvs. Resize Image With Aspect Fit
resize_imageUse when scaling by factor; does not preserve aspect with padding.
crop_image_using_bounding_boxesUse when you need to extract regions without padding.

When Not to Use the Skill ​

Do not use Resize Image With Aspect Fit when:

  • You can scale by factor (Use resize_image for simpler control)
  • Stretching is acceptable (Direct resize to target size)
  • You need to crop to fit (Use crop instead of pad)