Probabilistically add background & foreground images to some of the slides

helpers/image_search.py

@@ -0,0 +1,111 @@
+"""
+Search photos using Pexels API.
+"""
+import os
+import random
+from io import BytesIO
+from typing import Union, Tuple, Optional
+from urllib.parse import urlparse, parse_qs
+
+import requests
+
+
+REQUEST_TIMEOUT = 12
+MAX_PHOTOS = 2
+
+
+def search_pexels(query: str, size: Optional[str] = 'medium', per_page: int = MAX_PHOTOS):
+    """
+    Searches for images on Pexels using the provided query.
+
+    This function sends a GET request to the Pexels API with the specified search query
+    and authorization header containing the API key. It returns the JSON response from the API.
+
+    :param query: The search query for finding images.
+    :param size: The size of the images: small, medium, or large.
+    :param per_page: No. of results to be displayed per page.
+    :return: The JSON response from the Pexels API containing search results.
+    :raises requests.exceptions.RequestException: If the request to the Pexels API fails.
+    """
+
+    url = 'https://api.pexels.com/v1/search'
+    headers = {
+        'Authorization': os.getenv('PEXEL_API_KEY')
+    }
+    params = {
+        'query': query,
+        'size': size,
+        'page': 1,
+        'per_page': per_page
+    }
+    response = requests.get(url, headers=headers, params=params, timeout=REQUEST_TIMEOUT)
+    response.raise_for_status()  # Ensure the request was successful
+
+    return response.json()
+
+
+def get_photo_url_from_api_response(
+        json_response: dict
+) -> Tuple[Union[str, None], Union[str, None]]:
+    """
+    Return a randomly chosen photo from a Pexels search API response. In addition, also return
+    the original URL of the page on Pexels.
+
+    :param json_response: The JSON response.
+    :return: The selected photo URL and page URL or `None`.
+    """
+
+    page_url = None
+    photo_url = None
+
+    if 'photos' in json_response:
+        photos = json_response['photos']
+
+        if photos:
+            photo_idx = random.choice(list(range(MAX_PHOTOS)))
+            photo = photos[photo_idx]
+
+            if 'url' in photo:
+                page_url = photo['url']
+
+            if 'src' in photo:
+                if 'large' in photo['src']:
+                    photo_url = photo['src']['large']
+                elif 'original' in photo['src']:
+                    photo_url = photo['src']['original']
+
+    return photo_url, page_url
+
+
+def get_image_from_url(url: str) -> BytesIO:
+    """
+    Fetches an image from the specified URL and returns it as a BytesIO object.
+
+    This function sends a GET request to the provided URL, retrieves the image data,
+    and wraps it in a BytesIO object, which can be used like a file.
+
+    :param url: The URL of the image to be fetched.
+    :return: A BytesIO object containing the image data.
+    :raises requests.exceptions.RequestException: If the request to the URL fails.
+    """
+
+    response = requests.get(url, stream=True, timeout=REQUEST_TIMEOUT)
+    response.raise_for_status()
+    image_data = BytesIO(response.content)
+
+    return image_data
+
+
+def extract_dimensions(url: str) -> Tuple[int, int]:
+    """
+    Extracts the height and width from the URL parameters.
+
+    :param url: The URL containing the image dimensions.
+    :return: A tuple containing the width and height as integers.
+    """
+    parsed_url = urlparse(url)
+    query_params = parse_qs(parsed_url.query)
+    width = int(query_params.get('w', [0])[0])
+    height = int(query_params.get('h', [0])[0])
+
+    return width, height

helpers/pptx_helper.py

@@ -1,17 +1,30 @@
+"""
+A set of functions to create a PowerPoint slide deck.
+"""
 import logging
 import pathlib
+import random
 import re
+import sys
 import tempfile
-
-from typing import List, Tuple
+from typing import List, Tuple, Optional
 
 import json5
 import pptx
+from dotenv import load_dotenv
 from pptx.enum.shapes import MSO_AUTO_SHAPE_TYPE
+from pptx.shapes.placeholder import PicturePlaceholder, SlidePlaceholder
+
+sys.path.append('..')
+sys.path.append('../..')
 
+import helpers.image_search as ims
 from global_config import GlobalConfig
 
 
+load_dotenv()
+
+
 # English Metric Unit (used by PowerPoint) to inches
 EMU_TO_INCH_SCALING_FACTOR = 1.0 / 914400
 INCHES_1_5 = pptx.util.Inches(1.5)
@@ -21,24 +34,10 @@ INCHES_0_4 = pptx.util.Inches(0.4)
 INCHES_0_3 = pptx.util.Inches(0.3)
 
 STEP_BY_STEP_PROCESS_MARKER = '>> '
+IMAGE_DISPLAY_PROBABILITY = 0.3
+FOREGROUND_IMAGE_PROBABILITY = 0.75
+SLIDE_NUMBER_REGEX = re.compile(r"^slide[ ]+\d+:", re.IGNORECASE)
 
-PATTERN = re.compile(r"^slide[ ]+\d+:", re.IGNORECASE)
-SAMPLE_JSON_FOR_PPTX = '''
-{
-    "title": "Understanding AI",
-    "slides": [
-        {
-            "heading": "Introduction",
-            "bullet_points": [
-                "Brief overview of AI",
-                [
-                    "Importance of understanding AI"
-                ]
-            ]
-        }
-    ]
-}
-'''
 
 logger = logging.getLogger(__name__)
 
@@ -48,9 +47,10 @@ def remove_slide_number_from_heading(header: str) -> str:
     Remove the slide number from a given slide header.
 
     :param header: The header of a slide.
+    :return: The header without slide number.
     """
 
-    if PATTERN.match(header):
+    if SLIDE_NUMBER_REGEX.match(header):
         idx = header.find(':')
         header = header[idx + 1:]
 
@@ -68,7 +68,7 @@ def generate_powerpoint_presentation(
     :param structured_data: The presentation contents as "JSON" (may contain trailing commas).
     :param slides_template: The PPTX template to use.
     :param output_file_path: The path of the PPTX file to save as.
-    :return A list of presentation title and slides headers.
+    :return: A list of presentation title and slides headers.
     """
 
     # The structured "JSON" might contain trailing commas, so using json5
@@ -166,6 +166,28 @@ def _handle_default_display(
     :param slide_height_inch: The height of the slide in inches.
     """
 
+    status = False
+
+    if random.random() < IMAGE_DISPLAY_PROBABILITY:
+        if random.random() < FOREGROUND_IMAGE_PROBABILITY:
+            status = _handle_display_image__in_foreground(
+                presentation,
+                slide_json,
+                slide_width_inch,
+                slide_height_inch
+            )
+        else:
+            status = _handle_display_image__in_background(
+                presentation,
+                slide_json,
+                slide_width_inch,
+                slide_height_inch
+            )
+
+    if status:
+        return
+
+    # Image display failed, so display only text
     bullet_slide_layout = presentation.slide_layouts[1]
     slide = presentation.slides.add_slide(bullet_slide_layout)
 
@@ -197,6 +219,181 @@ def _handle_default_display(
     )
 
 
+def _handle_display_image__in_foreground(
+        presentation: pptx.Presentation(),
+        slide_json: dict,
+        slide_width_inch: float,
+        slide_height_inch: float
+) -> bool:
+    """
+    Create a slide with text and image using a picture placeholder layout.
+
+    :param presentation: The presentation object.
+    :param slide_json: The content of the slide as JSON data.
+    :param slide_width_inch: The width of the slide in inches.
+    :param slide_height_inch: The height of the slide in inches.
+    :return: True if the side has been processed.
+    """
+
+    img_keywords = slide_json['img_keywords'].strip()
+    slide = presentation.slide_layouts[8]  # Picture with Caption
+    slide = presentation.slides.add_slide(slide)
+
+    title_placeholder = slide.shapes.title
+    title_placeholder.text = remove_slide_number_from_heading(slide_json['heading'])
+
+    pic_col: PicturePlaceholder = slide.shapes.placeholders[1]
+    text_col: SlidePlaceholder = slide.shapes.placeholders[2]
+    flat_items_list = get_flat_list_of_contents(slide_json['bullet_points'], level=0)
+
+    for idx, an_item in enumerate(flat_items_list):
+        if idx == 0:
+            text_col.text_frame.text = an_item[0].removeprefix(STEP_BY_STEP_PROCESS_MARKER)
+        else:
+            paragraph = text_col.text_frame.add_paragraph()
+            paragraph.text = an_item[0].removeprefix(STEP_BY_STEP_PROCESS_MARKER)
+            paragraph.level = an_item[1]
+
+    if not img_keywords:
+        # No keywords, so no image search and addition
+        return True
+
+    try:
+        photo_url, page_url = ims.get_photo_url_from_api_response(
+            ims.search_pexels(query=img_keywords, size='medium')
+        )
+
+        if photo_url:
+            pic_col.insert_picture(
+                ims.get_image_from_url(photo_url)
+            )
+
+            _add_text_at_bottom(
+                slide=slide,
+                slide_width_inch=slide_width_inch,
+                slide_height_inch=slide_height_inch,
+                text='Photo provided by Pexels',
+                hyperlink=page_url
+            )
+    except Exception as ex:
+        logger.error(
+            '*** Error occurred while running adding image to slide: %s',
+            str(ex)
+        )
+
+    return True
+
+
+def _handle_display_image__in_background(
+        presentation: pptx.Presentation(),
+        slide_json: dict,
+        slide_width_inch: float,
+        slide_height_inch: float
+) -> bool:
+    """
+    Add a slide with text and an image in the background. It works just like
+    `_handle_default_display()` but with a background image added.
+
+    :param presentation: The presentation object.
+    :param slide_json: The content of the slide as JSON data.
+    :param slide_width_inch: The width of the slide in inches.
+    :param slide_height_inch: The height of the slide in inches.
+    :return: True if the slide has been processed.
+    """
+
+    img_keywords = slide_json['img_keywords'].strip()
+
+    # Add a photo in the background, text in the foreground
+    slide = presentation.slides.add_slide(presentation.slide_layouts[1])
+
+    title_shape = slide.shapes.title
+    body_shape = slide.shapes.placeholders[1]
+    title_shape.text = remove_slide_number_from_heading(slide_json['heading'])
+
+    flat_items_list = get_flat_list_of_contents(slide_json['bullet_points'], level=0)
+
+    for idx, an_item in enumerate(flat_items_list):
+        if idx == 0:
+            body_shape.text_frame.text = an_item[0].removeprefix(STEP_BY_STEP_PROCESS_MARKER)
+        else:
+            paragraph = body_shape.text_frame.add_paragraph()
+            paragraph.text = an_item[0].removeprefix(STEP_BY_STEP_PROCESS_MARKER)
+            paragraph.level = an_item[1]
+
+    if not img_keywords:
+        # No keywords, so no image search and addition
+        return True
+
+    try:
+        photo_url, page_url = ims.get_photo_url_from_api_response(
+            ims.search_pexels(query=img_keywords, size='large')
+        )
+
+        if photo_url:
+            picture = slide.shapes.add_picture(
+                image_file=ims.get_image_from_url(photo_url),
+                left=0,
+                top=0,
+                width=pptx.util.Inches(slide_width_inch),
+            )
+
+            _add_text_at_bottom(
+                slide=slide,
+                slide_width_inch=slide_width_inch,
+                slide_height_inch=slide_height_inch,
+                text='Photos provided by Pexels',
+                hyperlink=page_url
+            )
+
+            # Move picture to background
+            # https://github.com/scanny/python-pptx/issues/49#issuecomment-137172836
+            slide.shapes._spTree.remove(picture._element)
+            slide.shapes._spTree.insert(2, picture._element)
+    except Exception as ex:
+        logger.error(
+            '*** Error occurred while running adding image to the slide background: %s',
+            str(ex)
+        )
+
+    return True
+
+
+def _add_text_at_bottom(
+        slide: pptx.slide.Slide,
+        slide_width_inch: float,
+        slide_height_inch: float,
+        text: str,
+        hyperlink: Optional[str] = None,
+        target_height: Optional[float] = 0.5
+):
+    """
+    Add arbitrary text to a textbox positioned near the lower left side of a slide.
+
+    :param slide: The slide.
+    :param slide_width_inch: The width of the slide.
+    :param slide_height_inch: The height of the slide.
+    :param target_height: the target height of the box in inches (optional).
+    :param text: The text to be added
+    :param hyperlink: The hyperlink to be added to the text (optional).
+    """
+
+    footer = slide.shapes.add_textbox(
+        left=INCHES_1,
+        top=pptx.util.Inches(slide_height_inch - target_height),
+        width=pptx.util.Inches(slide_width_inch),
+        height=pptx.util.Inches(target_height)
+    )
+
+    paragraph = footer.text_frame.paragraphs[0]
+    run = paragraph.add_run()
+    run.text = text
+    run.font.size = pptx.util.Pt(10)
+    run.font.underline = False
+
+    if hyperlink:
+        run.hyperlink.address = hyperlink
+
+
 def _handle_double_col_layout(
         presentation: pptx.Presentation(),
         slide_json: dict,
@@ -417,112 +614,150 @@ def _get_slide_width_height_inches(presentation: pptx.Presentation) -> Tuple[flo
     return slide_width_inch, slide_height_inch
 
 
+def print_placeholder_names(slide: pptx.slide.Slide):
+    """
+    Display the placeholder details of a given slide.
+
+    :param slide: The slide.
+    """
+
+    for shape in slide.placeholders:
+        print(f'{shape.placeholder_format.idx=}, {shape.name=}')
+
+
 if __name__ == '__main__':
     _JSON_DATA = '''
     {
-    "title": "Understanding AI",
+    "title": "Mastering PowerPoint Shapes",
     "slides": [
         {
-            "heading": "Introduction",
+            "heading": "Introduction to PowerPoint Shapes",
             "bullet_points": [
-                "Brief overview of AI",
-                [
-                    "Importance of understanding AI"
-                ]
+                "Shapes are fundamental elements in PowerPoint",
+                "Used to create diagrams, flowcharts, and visuals",
+                "Available in various types: lines, rectangles, circles, etc."
             ],
-            "key_message": ""
+            "key_message": "",
+            "img_keywords": "PowerPoint shapes, basic shapes"
         },
         {
-            "heading": "What is AI?",
+            "heading": "Types of Shapes in PowerPoint",
             "bullet_points": [
-                "Definition of AI",
+                "Lines: Connect two points",
+                "Rectangles: Four-sided figures with right angles",
                 [
-                    "Types of AI",
-                    [
-                        "Narrow or weak AI",
-                        "General or strong AI"
-                    ]
+                    "Squares: Special type of rectangle with equal sides",
+                    "Rounded Rectangles: Rectangles with rounded corners"
                 ],
-                "Differences between AI and machine learning"
+                "Circles: Round shapes with no corners",
+                "Ovals: Elliptical shapes"
             ],
-            "key_message": ""
+            "key_message": "",
+            "img_keywords": "PowerPoint shapes, types of shapes"
         },
         {
-            "heading": "How AI Works",
+            "heading": "Creating and Manipulating Shapes",
             "bullet_points": [
-                "Overview of AI algorithms",
-                [
-                    "Types of AI algorithms",
-                    [
-                        "Rule-based systems",
-                        "Decision tree systems",
-                        "Neural networks"
+                ">> Select the 'Home' tab and click on 'Shapes'",
+                ">> Choose the desired shape",
+                ">> Click and drag to create the shape",
+                ">> Resize, move, or rotate shapes using handles",
+                ">> Change shape color, fill, and outline"
+            ],
+            "key_message": "Demonstrates the process of creating and manipulating shapes",
+            "img_keywords": "PowerPoint shapes, creating shapes, manipulating shapes"
+        },
+        {
+            "heading": "Advanced Shape Manipulation",
+            "bullet_points": [
+                {
+                    "heading": "Adding Text to Shapes",
+                    "bullet_points": [
+                        "Right-click on the shape and select 'Add Text'",
+                        "Type or paste the desired text"
                     ]
-                ],
-                "How AI processes data"
+                },
+                {
+                    "heading": "Grouping and Ungrouping Shapes",
+                    "bullet_points": [
+                        "Select multiple shapes and press 'Ctrl + G' to group",
+                        "Right-click and select 'Ungroup' to separate"
+                    ]
+                }
+            ],
+            "key_message": "Explores advanced techniques for working with shapes",
+            "img_keywords": "PowerPoint shapes, advanced manipulation, grouping, text in shapes"
+        },
+        {
+            "heading": "Using the 'Format' Tab for Shapes",
+            "bullet_points": [
+                "Access advanced shape formatting options",
+                "Change shape fill, outline, and effects",
+                "Adjust shape size and position"
             ],
-            "key_message": ""
+            "key_message": "",
+            "img_keywords": "PowerPoint shapes, format tab, advanced formatting"
         },
         {
-            "heading": "Building AI Models",
+            "heading": "Example: Creating a Simple Diagram",
             "bullet_points": [
-                ">> Collect data",
-                ">> Select model or architecture to use",
-                ">> Set appropriate parameters",
-                ">> Train model with data",
-                ">> Run inference",
+                "Use rectangles to represent blocks",
+                "Use lines to connect blocks",
+                "Add text to shapes to label elements"
             ],
-            "key_message": ""
+            "key_message": "Illustrates the use of shapes to create a simple diagram",
+            "img_keywords": "PowerPoint shapes, diagram example, simple diagram"
         },
         {
-            "heading": "Pros and Cons: Deep Learning vs. Classical Machine Learning",
+            "heading": "Example: Creating a Flowchart",
+            "bullet_points": [
+                "Use different shapes to represent steps, decisions, and inputs/outputs",
+                "Use connectors to link shapes",
+                "Add text to shapes to describe each step"
+            ],
+            "key_message": "Demonstrates the use of shapes to create a flowchart",
+            "img_keywords": "PowerPoint shapes, flowchart example, creating flowchart"
+        },
+        {
+            "heading": "Double Column Layout: Shapes in Older vs. Newer PowerPoint Versions",
             "bullet_points": [
                 {
-                    "heading": "Classical Machine Learning",
+                    "heading": "Older PowerPoint Versions",
                     "bullet_points": [
-                        "Interpretability: Easy to understand the model",
-                        "Faster Training: Quicker to train models",
-                        "Scalability: Can handle large datasets"
+                        "Limited shape types and formatting options",
+                        "Less intuitive shape creation and manipulation"
                     ]
                 },
                 {
-                    "heading": "Deep Learning",
+                    "heading": "Newer PowerPoint Versions",
                     "bullet_points": [
-                        "Handling Complex Data: Can learn from raw data",
-                        "Feature Extraction: Automatically learns features",
-                        "Improved Accuracy: Achieves higher accuracy"
+                        "Expanded shape library with more types and styles",
+                        "Improved shape formatting and manipulation tools"
                     ]
                 }
             ],
-            "key_message": ""
-        },
-        {
-            "heading": "Pros of AI",
-            "bullet_points": [
-                "Increased efficiency and productivity",
-                "Improved accuracy and precision",
-                "Enhanced decision-making capabilities",
-                "Personalized experiences"
-            ],
-            "key_message": "AI can be used for many different purposes"
+            "key_message": "Compares the use of shapes in older and newer PowerPoint versions",
+            "img_keywords": "PowerPoint shapes, older versions, newer versions, comparison"
         },
         {
-            "heading": "Cons of AI",
+            "heading": "Tips for Effective Use of Shapes",
             "bullet_points": [
-                "Job displacement and loss of employment",
-                "Bias and discrimination",
-                "Privacy and security concerns",
-                "Dependence on technology"
+                "Keep shapes simple and uncluttered",
+                "Use consistent colors and styles",
+                "Avoid overusing shapes, maintain balance with text and other elements"
             ],
-            "key_message": ""
+            "key_message": "Provides best practices for using shapes in presentations",
+            "img_keywords": "PowerPoint shapes, best practices, effective use"
         },
         {
-            "heading": "Future Prospects of AI",
+            "heading": "Conclusion",
             "bullet_points": [
-                "Advancements in fields such as healthcare and finance",
-                "Increased use"
+                "Shapes are versatile tools in PowerPoint",
+                "Mastering shapes enhances presentation visuals",
+                "Practice and experimentation are key to improving shape usage"
             ],
-            "key_message": ""
+            "key_message": "Summarizes the importance of shapes in PowerPoint and encourages practice",
+            "img_keywords": "PowerPoint shapes, conclusion, importance"
         }
     ]
 }'''