Image Translate

This function block shifts an image horizontally and/or vertically by a specified number of pixels. The vacated area is filled with a chosen background color. X, Y and background color inputs are optional — empty values leave the image unchanged or use defaults.

📥 Inputs

Input Image A grayscale or color image to be translated (image socket).

X displacement Horizontal shift in pixels (number socket). Positive moves the image to the right, negative to the left. Optional — when empty treated as 0.

Y displacement Vertical shift in pixels (number socket). Positive moves the image down, negative moves it up. Optional — when empty treated as 0.

Background Color Fill color for exposed background areas (pixel socket). Optional — defaults to black when not provided.

📤 Outputs

Translated Image The resulting image after translation (image socket). The output image has the same dimensions as the input; content shifted and edges filled with the chosen color.

🕹️ Controls

X displacement Enter the horizontal displacement in pixels. Use negative values to shift left.

Y displacement Enter the vertical displacement in pixels. Use negative values to shift up.

Background Color Pick a background color to fill new empty regions (use Pixel style input or a color-producing block).

✨ Features

• Optional inputs: leave X displacement or Y displacement empty to keep that axis unchanged.

• Preserves input image size; translated content is cropped to the original canvas.

• Works with both grayscale and RGB images.

• Background fill accepts single-channel or RGB values depending on the input image.

📝 Usage Instructions

1. Connect an image-producing block to Input Image.

2. Provide pixel values to X displacement and/or Y displacement to move the image.

3. Optionally provide Background Color to control the fill for exposed areas.

4. Use the Translated Image output as input for downstream blocks (display, analysis, saving).

Examples:

• Move an image 50 pixels right and 20 pixels down by setting X displacement = 50 and Y displacement = 20.

• Shift only vertically by supplying a value to Y displacement and leaving X displacement empty.

📊 Running Behavior

When the block runs it reads the input image and displacement values, shifts pixels by the requested amount, fills uncovered regions with the chosen color, and returns the translated image on the Translated Image socket. Missing displacement values are treated as zero.

💡 Tips and Tricks

• To avoid important image content being cropped after translation, add empty canvas around the image first using Image Padding or increase canvas size with Image Resize and Make Image to create a background, then translate inside the larger canvas.

• Use Pixel or a small Make Image block to create a precise background color and feed it into Background Color.

• Combine with Image ROI or Image ROI Select to translate only a cropped area, then Image Concatenate or Collage Images to reassemble/visualize results.

• If you need to flip or rotate content after translation, chain Flip Image or Rotate Image Angle after this block.

• For tiled layouts or composition, translate multiple slices and merge them back using Image Concatenate or Merge Channels as needed.

🛠️ Troubleshooting

• Issue: Important parts of the image are cut off after translation. Solution: Add margin before translating with Image Padding or increase canvas size using Image Resize / Make Image, then translate.

• Issue: Background color does not match expected result. Solution: Ensure the Background Color input provides the correct channel format (single value for grayscale, RGB triple for color). Use Pixel to supply exact color.

• Issue: No change after providing displacements. Solution: Check that displacement inputs are connected and not empty; empty values default to zero.

• Issue: Need to preserve image quality when shifting many pixels. Solution: Consider translating on a larger canvas first and avoid multiple successive crops; use downstream blocks such as Show Image to verify results.