Image Caption Overlay System

Build a Python program that overlays multi-line text captions onto images. The system should handle text with line breaks and provide both regular and centered text placement options.

Requirements

Input

Your program should accept:

• An input image file path
• Caption text that may contain newline characters (\n)
• Text position coordinates (x, y) for regular placement
• Font parameters (font face, font scale, color, thickness)
• Placement mode: "regular" or "centered"

Output

The program should:

• Load the input image
• Render the multi-line caption onto the image with proper line spacing
• For "regular" mode: place text starting at the specified (x, y) position
• For "centered" mode: center the text block both horizontally and vertically on the image
• Save the result to an output file path

Constraints

• Text must support multiple lines separated by \n characters
• Line spacing should be calculated automatically and appropriately
• Centered text should be positioned in the middle of the image canvas
• The solution should modify the image in-place before saving

Implementation Details

Create a Python module that provides a function with the following signature:

def add_caption(input_path: str, output_path: str, text: str,
                position: tuple, font_face: int, font_scale: float,
                color: tuple, thickness: int = 1, mode: str = "regular") -> None:
    """
    Adds a multi-line text caption to an image.

    Args:
        input_path: Path to the input image file
        output_path: Path where the output image will be saved
        text: Caption text (may contain \\n for line breaks)
        position: (x, y) tuple for text position (used in regular mode)
        font_face: OpenCV font face constant (e.g., cv2.FONT_HERSHEY_SIMPLEX)
        font_scale: Font scale factor
        color: RGB tuple for text color (e.g., (255, 255, 255))
        thickness: Text thickness in pixels
        mode: "regular" for positioned text, "centered" for centered text
    """
    pass

Test Cases

• Given an image and single-line text "Hello World" with position (10, 30), the text should appear at coordinates (10, 30). @test

• Given an image and multi-line text "Line 1\nLine 2\nLine 3" with position (10, 30), all three lines should be rendered with proper spacing starting at (10, 30). @test

• Given an image and text "Centered\nCaption" with mode="centered", the text block should be positioned in the center of the image both horizontally and vertically. @test

Dependencies { .dependencies }

imutils { .dependency }

Provides image processing convenience functions including multi-line text rendering.

opencv-python { .dependency }

Provides core image processing capabilities for reading, writing, and manipulating images.

numpy { .dependency }

Provides array operations for image data manipulation.