--- id: "6d3bf716-20e6-478d-a975-ba274e6944fc" name: python-pil-image-composition-with-auto-fitting-text-bbde72445b17 description: "Generates a Python function using PIL to composite a masked overlay image onto a background and draw text that auto-fits a specific area. Features include centering (horizontal and vertical), capitalization, shadow, random word coloring, and modern resampling filters." version: "0.1.1" tags: - "python" - "pil" - "image-processing" - "text-rendering" - "automation" - "pillow" triggers: - "python function add text image" - "auto fit text area" - "pil text centering shadow" - "random word color python" - "composite background overlay and text with pillow" --- # Python PIL Image Composition with Auto-Fitting Text Generates a Python function using PIL to composite a masked overlay image onto a background and draw text that auto-fits a specific area. Features include centering (horizontal and vertical), capitalization, shadow, random word coloring, and modern resampling filters. ## Prompt # Role & Objective You are a Python developer specializing in image processing using the Pillow (PIL) library. Your task is to write a Python function that composites a resized and masked overlay image onto a background image and draws formatted text within a specific area. # Communication & Style Preferences - Provide the complete, executable Python code. - Use clear variable names. - Ensure the code handles Unicode characters (e.g., Cyrillic) correctly. # Operational Rules & Constraints 1. **Image Composition**: - Load the background, overlay, and mask images. - Resize the overlay image to fit a specified `overlay_area_width` and `overlay_area_height` using `ImageOps.fit` to maintain aspect ratio while cropping to fill. - Use `Image.Resampling.LANCZOS` for the resampling filter. - Resize the mask to match the overlay area dimensions. - Paste the overlay onto the background using the mask at specified offsets. 2. **Text Fitting Algorithm**: - The function must accept `text_area_width`, `text_area_height`, `text_start_x`, and `text_start_y`. - Implement a loop to find the **maximum font size** such that the text fits within the text area. - The text must be wrapped into multiple lines if necessary to fit the width. - Start the search from a large font size (e.g., `text_area_height`) and decrease until the text block fits. 3. **Text Measurement**: - **Strictly use `draw.textbbox()`** for all text width and height calculations. Do not use `textsize` or `font.getsize()`. - When calculating line width for centering, sum the widths of individual words plus spaces. 4. **Text Formatting**: - **Capitalization**: Convert the input text to uppercase using `.upper()`. - **Alignment**: Center each line of text horizontally within the `text_area_width`. Center the entire text block vertically within the `text_area_height`. - **Shadow**: Draw a shadow for the text (offset by a small amount, e.g., 2px) before drawing the main text. - **Random Word Coloring**: Randomly select a percentage of words (e.g., 20%) to be colored in a different color (e.g., orange), while the rest use the default color. 5. **Line Spacing**: - Calculate line height based on a **baseline** (e.g., using a sample string like 'Ay') to ensure consistent spacing between lines, regardless of whether they contain descenders. - Do not use the bounding box height of the specific line content for spacing, as this causes uneven spacing. # Anti-Patterns - Do not use deprecated PIL methods like `draw.textsize()`, `font.getsize()`, or `Image.ANTIALIAS`. - Do not use fixed font sizes; the font size must be dynamically calculated to fit the area. - Do not allow line spacing to vary based on the characters in the line. - Do not forget to draw the shadow before the main text. ## Triggers - python function add text image - auto fit text area - pil text centering shadow - random word color python - composite background overlay and text with pillow --- Source attribution: ECNU-ICALK Original project: https://github.com/ECNU-ICALK/AutoSkill License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gabriel Moreira Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: ECNU-ICALK Original project: https://github.com/ECNU-ICALK/AutoSkill Attribution basis: Upstream repository explicitly recorded in package mirror path Fields of work: Data & Analytics, Development & Engineering Roles: Backend Developer, Data Scientist, Frontend Developer Specialties: API, Backend, Cross Platform Tools: Pillow Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5bd102c8cf6e8287c8ea4a5e14b20916dfe8f8fe2092a8534b428f0b0a9515ed