Center Text in GIMP 3 with Python Scripting

GIMP is a powerful, free image editor. Its Python scripting engine, Python-Fu, unlocks automation. A common task is centering text on an image. Doing this manually for many files is slow. This guide shows you how to automate it with a script.

Understanding the GIMP Python Environment

GIMP 3 includes a built-in Python interpreter. It uses the gimpfu module. This module provides functions to control GIMP. You can access layers, text, and canvas properties. Scripts run from inside GIMP or from the command line.

First, ensure your script registers with GIMP. This makes it appear in the menu. The registration defines the script's parameters and main function.

Prerequisites for Scripting

You need GIMP 3 installed. Basic Python knowledge is helpful. No extra modules are required. The gimpfu module is bundled with GIMP.

Open the Python-Fu console in GIMP. Go to Filters > Python-Fu > Console. This lets you test commands. It is a great way to learn the API.

Building the Text Centering Script

The goal is to create a text layer. Then center it horizontally and vertically. The script will handle different image and text sizes.

We will use key functions. The pdb.gimp_text_fontname creates the text layer. The pdb.gimp_text_layer_get_extents gets its size. Then we calculate the position.

The Complete Script Code

Below is the full script. It creates a new image. Adds centered text. And saves the result. Read the comments to understand each step.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from gimpfu import *

def center_text_gimp3(image_width, image_height, text_string, font_size, output_path):
    """
    Creates a new image with perfectly centered text and saves it.
    
    Args:
        image_width (int): Width of the new image in pixels.
        image_height (int): Height of the new image in pixels.
        text_string (str): The text to be centered.
        font_size (int): Font size in pixels.
        output_path (str): Full path to save the final image (e.g., '/path/to/result.png').
    """
    
    # 1. Create a new RGB image with a white background.
    # The FALSE argument means the image does not have an alpha channel initially.
    image = pdb.gimp_image_new(image_width, image_height, RGB)
    background_layer = pdb.gimp_layer_new(
        image, image_width, image_height, RGB_IMAGE, "Background", 100, NORMAL_MODE
    )
    pdb.gimp_image_insert_layer(image, background_layer, None, 0)
    # Fill the background layer with white.
    white_color = (255, 255, 255)
    pdb.gimp_context_set_background(white_color)
    pdb.gimp_drawable_fill(background_layer, BACKGROUND_FILL)

    # 2. Create the text layer.
    # We use the default font available on the system.
    text_layer = pdb.gimp_text_fontname(
        image, None, 0, 0, text_string, 10, True, font_size, PIXELS, "Sans"
    )

    # 3. Get the dimensions (bounding box) of the text layer.
    # The function returns (x1, y1, x2, y2). We calculate width and height.
    x1, y1, x2, y2 = pdb.gimp_text_layer_get_extents(text_layer)
    text_width = x2 - x1
    text_height = y2 - y1

    # 4. Calculate the center position.
    # The formula: (image_dimension / 2) - (text_dimension / 2)
    text_x = (image_width / 2) - (text_width / 2)
    text_y = (image_height / 2) - (text_height / 2)

    # 5. Move the text layer to the calculated center position.
    pdb.gimp_layer_set_offsets(text_layer, int(text_x), int(text_y))

    # 6. Flatten the image (merge all layers) and save it.
    merged_layer = pdb.gimp_image_merge_visible_layers(image, CLIP_TO_IMAGE)
    pdb.file_png_save(
        image, merged_layer, output_path, output_path, FALSE, 9, FALSE, FALSE, FALSE, FALSE, FALSE
    )
    # Clean up: remove the image from GIMP's memory.
    pdb.gimp_image_delete(image)

    # Print a success message (visible in the Python-Fu console).
    print(f"Success! Image saved to: {output_path}")

# This is the mandatory registration block.
# It tells GIMP how to integrate this script into its menu.
register(
    "python_fu_center_text",          # Unique procedure name
    "Center Text on Image",           # Menu label
    "Creates a new image with centered text.", # Description
    "Your Name",                      # Author
    "Your Name",                      # Copyright
    "2024",                           # Date
    "/Filters/MyScripts/Center Text...", # Menu path
    "",                               # Image types (empty for new images)
    [
        (PF_INT, "width", "Image Width", 800),
        (PF_INT, "height", "Image Height", 600),
        (PF_STRING, "text", "Text Content", "Centered Text"),
        (PF_INT, "fontsize", "Font Size (px)", 60),
        (PF_STRING, "filepath", "Output File Path", "/tmp/centered_text.png"),
    ],
    [],
    center_text_gimp3,                # The main function to call
)

main() # This line executes the registration.

How to Install and Run the Script

Save the script with a .py extension. For example, center_text.py. Place it in your GIMP scripts folder.

On Linux, this is typically ~/.config/GIMP/3/scripts/. On Windows, it's in your user profile under AppData\Roaming\GIMP\3\scripts.

Restart GIMP. Find the script under Filters > MyScripts > Center Text.... A dialog will open. Enter your parameters and run it.

Example Output and Verification

Run the script with these values: Width=800, Height=400, Text="Hello GIMP 3!", Font Size=72, Path="/tmp/demo.png".

The script will execute. It prints a confirmation message in the console.

Success! Image saved to: /tmp/demo.png

Open the saved image. The text will be perfectly centered. This automation saves immense time for batch processing.

Advanced Usage and Customization

This script is a foundation. You can modify it for existing images. Load an image with pdb.gimp_file_load. Then find its text layers and center them.

Change the font by modifying the "Sans" string. Use functions like pdb.gimp_text_layer_set_font for more control. You can also center text within a specific region, not the whole canvas.

For related text processing, see our Python Text Extraction from Images Guide. It covers reading text from images, the opposite operation.

Common Errors and Troubleshooting

Script not appearing in menu: Check the file is in the correct scripts folder. Ensure it has a .py extension. Restart GIMP completely.

Font not found: The script uses "Sans" as a default. If it fails, change it to a font you know exists, like "Arial" on Windows.

Permission denied on save: Ensure the output directory exists. Your script has write permissions for the specified path.

For handling file paths and text data efficiently in other Python projects, our guide on Python TextIOWrapper is a great resource.

Conclusion

Centering text in GIMP 3 with Python is straightforward. The gimpfu module provides all necessary tools. You learned to create a script from scratch. This script creates images with centered text automatically.

The real power is in customization. You can adapt this script for logos, watermarks, or social media graphics. Automating repetitive tasks is a key skill. It turns a powerful editor like GIMP into an automated design powerhouse.

Start with the provided script. Experiment with its parameters. Soon you will be automating complex GIMP workflows with ease.