Translate Image

SUMMARY

Translate Image shifts an image by dx and dy pixels.

Translates (shifts) the image horizontally and vertically. Supports configurable border handling (constant, replicate, reflect, wrap) and fill value for regions outside the original bounds. Useful for data augmentation, alignment correction, or sliding-window preprocessing.

Use this Skill when you want to shift an image by a fixed pixel offset.

The Skill

from telekinesis import pupil

translated_image = pupil.translate_image(
    image=image,
    dx=50,
    dy=-30,
    border_type="constant",
    fill_value=0,
    interpolation_method="linear",
)

API Reference

Example

Input Image

Original image

Translated Image

Translated by dx=50, dy=-30

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

# Translate (shift) image by dx and dy pixels
translated_image = pupil.translate_image(
    image=image,
    dx=100,
    dy=50,
    border_type="constant",
    border_value=0,
    interpolation_method="linear",
)

# Access results
translated_image_np = translated_image.to_numpy()
logger.success("Translated image. Output shape: {}", translated_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 .jpg file using the io.load_image function.

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

# Load image
filepath = str(DATA_DIR / "images" / "checkerboard.jpg")
image = io.load_image(filepath=filepath)

The main operation uses the translate_image Skill from the pupil module. This Skill shifts an image by dx and dy pixels with configurable border handling. The parameters can be tuned to control shift amount, border type, fill value, and interpolation method depending on the characteristics of the input image.

translated_image = pupil.translate_image(
    image=image,
    dx=100,
    dy=50,
    border_type="constant",
    border_value=0,
    interpolation_method="linear",
)

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

translated_image_np = translated_image.to_numpy()
logger.success(f"Output image shape: {translated_image_np.shape}")

This operation is particularly useful in robotics and vision pipelines for data augmentation, alignment correction, and sliding-window preprocessing, where shifting an image by a fixed pixel offset 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 translate_image

How to Tune the Parameters

The translate_image Skill has 5 parameters:

dx (no default—required):

• Horizontal shift in pixels (positive = right)
• Units: Pixels
• Typical range: -image_width to image_width
• Use for horizontal alignment or augmentation

dy (no default—required):

• Vertical shift in pixels (positive = down)
• Units: Pixels
• Typical range: -image_height to image_height
• Use for vertical alignment or augmentation

border_type (default: "constant"):

• How to fill regions outside the original image bounds
• Options: "default", "constant", "replicate", "reflect", "reflect 101"
• "constant" uses border_value; "replicate" extends edge pixels; "reflect" mirrors
• Use "constant" for black padding; "replicate" to avoid artificial edges; "reflect" for seamless tiling

border_value (default: 0):

• Fill value for "constant" border. Scalar or [r, g, b] for color images
• Units: Intensity (0–255 for uint8)
• Use 0 for black; 255 for white; [r, g, b] for colored padding

interpolation_method (default: "linear"):

• Interpolation method for resampling during translation
• Options: "nearest", "linear", "cubic", "area", "lanczos4"
• Use "linear" for most cases; "nearest" for speed; "cubic" for highest quality

TIP

Best practice: Use "constant" with border_value=0 for data augmentation. Use "replicate" when you want to avoid visible borders in the output.

Where to Use the Skill in a Pipeline

Translate Image is commonly used in the following pipelines:

• Data augmentation - Random shifts for training
• Alignment - Correct small misalignments
• Sliding window - Shift for patch extraction

Related skills to build such a pipeline:

• rotate_image: Combine with rotation for augmentation
• pad_image: Pad before translation to avoid cropping
• crop_image_center: Crop to fixed size after translation

Alternative Skills

Skill	vs. Translate Image
pad_image	Use when you need to add padding on specific sides without shifting content.
rotate_image	Use when you need rotation instead of pure translation.

When Not to Use the Skill

Do not use Translate Image when:

• You need rotation (Use rotate_image)
• You need to add padding (Use pad_image)
• dx and dy are both 0 (No-op; skip for efficiency)