make_pptx.py

"""
Generates the class presentation deck for the Image Processor project.
Run:  python3 make_pptx.py
Output: design/ImageProcessor_Presentation.pptx
"""

from pptx import Presentation
from pptx.util import Inches, Pt, Emu
from pptx.dml.color import RGBColor
from pptx.enum.text import PP_ALIGN
import os

# ---------------------------------------------------------------------------
# Paths
# ---------------------------------------------------------------------------
DESIGN = os.path.join(os.path.dirname(__file__), "design")
OUT    = os.path.join(DESIGN, "ImageProcessor_Presentation_claude.pptx")

def img(name, ext="png"):
    return os.path.join(DESIGN, f"{name}.{ext}")

# ---------------------------------------------------------------------------
# Palette
# ---------------------------------------------------------------------------
SU_RED    = RGBColor(0xAA, 0x00, 0x00)   # Seattle University red
DARK_GRAY = RGBColor(0x2B, 0x2B, 0x2B)
MID_GRAY  = RGBColor(0x55, 0x55, 0x55)
LIGHT_BG  = RGBColor(0xF7, 0xF7, 0xF7)
WHITE     = RGBColor(0xFF, 0xFF, 0xFF)
ACCENT    = RGBColor(0x33, 0x66, 0xAA)   # blue used in diagrams
GREEN     = RGBColor(0x1A, 0x7A, 0x1A)

# Slide dimensions: widescreen 16:9
W = Inches(13.33)
H = Inches(7.5)

# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
prs = Presentation()
prs.slide_width  = W
prs.slide_height = H

BLANK = prs.slide_layouts[6]   # completely blank

def add_slide():
    return prs.slides.add_slide(BLANK)

def rect(slide, l, t, w, h, fill=None, line=None):
    shape = slide.shapes.add_shape(1, l, t, w, h)
    shape.line.fill.background()
    if fill:
        shape.fill.solid()
        shape.fill.fore_color.rgb = fill
    else:
        shape.fill.background()
    if line:
        shape.line.color.rgb = line
        shape.line.width = Pt(1)
    else:
        shape.line.fill.background()
    return shape

def txbox(slide, text, l, t, w, h,
          bold=False, italic=False, size=18,
          color=DARK_GRAY, align=PP_ALIGN.LEFT,
          wrap=True):
    tb = slide.shapes.add_textbox(l, t, w, h)
    tf = tb.text_frame
    tf.word_wrap = wrap
    p  = tf.paragraphs[0]
    p.alignment = align
    run = p.add_run()
    run.text = text
    run.font.bold   = bold
    run.font.italic = italic
    run.font.size   = Pt(size)
    run.font.color.rgb = color
    return tb

def header_bar(slide, title, subtitle=None):
    """Red header bar across the top."""
    rect(slide, 0, 0, W, Inches(1.05), fill=SU_RED)
    txbox(slide, title,
          Inches(0.35), Inches(0.1), Inches(12.5), Inches(0.65),
          bold=True, size=28, color=WHITE, align=PP_ALIGN.LEFT)
    if subtitle:
        txbox(slide, subtitle,
              Inches(0.35), Inches(0.7), Inches(12.5), Inches(0.4),
              size=14, color=RGBColor(0xFF,0xCC,0xCC), align=PP_ALIGN.LEFT)

def bullet_box(slide, items, l, t, w, h, size=17, title=None, title_size=19):
    """Multi-line bullet list in a textbox."""
    tb = slide.shapes.add_textbox(l, t, w, h)
    tf = tb.text_frame
    tf.word_wrap = True
    first = True
    if title:
        p = tf.paragraphs[0] if first else tf.add_paragraph()
        first = False
        run = p.add_run()
        run.text = title
        run.font.bold  = True
        run.font.size  = Pt(title_size)
        run.font.color.rgb = ACCENT
    for item in items:
        p = tf.paragraphs[0] if (first and not title) else tf.add_paragraph()
        first = False
        indent = item.startswith("    ")
        text   = item.lstrip()
        bullet = "  ◦ " if indent else "• "
        run = p.add_run()
        run.text = bullet + text
        run.font.size  = Pt(size - 2 if indent else size)
        run.font.color.rgb = MID_GRAY if indent else DARK_GRAY
    return tb

def _image_dimensions(path):
    """Return (width, height) in pixels for PNG/JPG (via PIL) or SVG (via XML)."""
    if path.lower().endswith(".svg"):
        import xml.etree.ElementTree as ET, re
        try:
            root = ET.parse(path).getroot()
            w = re.sub(r'[^\d.]', '', root.get('width',  '1472') or '1472')
            h = re.sub(r'[^\d.]', '', root.get('height', '896')  or '896')
            return float(w or 1472), float(h or 896)
        except Exception:
            return 1472.0, 896.0
    else:
        from PIL import Image as PILImage
        im = PILImage.open(path)
        return float(im.size[0]), float(im.size[1])

def add_image(slide, path, l, t, w, h=None):
    """Add image; if h is None, preserve aspect ratio within w."""
    iw, ih = _image_dimensions(path)
    aspect = ih / iw
    actual_h = h if h else int(w * aspect)
    slide.shapes.add_picture(path, l, t, w, actual_h)
    return actual_h

def divider(slide, y):
    ln = slide.shapes.add_connector(1, Inches(0.35), y, Inches(13.0), y)
    ln.line.color.rgb = RGBColor(0xCC,0xCC,0xCC)
    ln.line.width = Pt(0.75)

# ---------------------------------------------------------------------------
# Slide 1 — Title
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=SU_RED)
rect(s, 0, Inches(2.5), W, Inches(3.2), fill=DARK_GRAY)

txbox(s, "Image Processor System",
      Inches(0.6), Inches(2.65), Inches(12), Inches(1.1),
      bold=True, size=44, color=WHITE, align=PP_ALIGN.CENTER)
txbox(s, "Architecture & Design Presentation",
      Inches(0.6), Inches(3.65), Inches(12), Inches(0.6),
      size=22, color=RGBColor(0xFF,0xCC,0xCC), align=PP_ALIGN.CENTER)
txbox(s, "Lynn Trickey  ·  CPSC 5200-02  ·  Seattle University  ·  March 2026",
      Inches(0.6), Inches(4.25), Inches(12), Inches(0.45),
      size=15, color=RGBColor(0xBB,0xBB,0xBB), align=PP_ALIGN.CENTER)

# ---------------------------------------------------------------------------
# Slide 2 — Agenda
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Agenda")

items = [
    "Architecture — what makes this unique: Microkernel + Pipe-and-Filter",
    "Why Microkernel? — design decision and gold plating rationale",
    "API — gRPC endpoints and proto messages",
    "Two Little Languages — filter definition grammar + CLI grammar",
    "Demo — two success scenarios and one error scenario",
    "Extensibility — adding a new filter in two steps",
]
bullet_box(s, items, Inches(1.0), Inches(1.3), Inches(11.5), Inches(5.5), size=22)

# ---------------------------------------------------------------------------
# Slide 3 — Pipe-and-Filter Pipeline (diagram)
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Pipe-and-Filter Pipeline",
           "Filters run inside the kernel — sequential, stateless, composable")

add_image(s, img("Pipeline_FilterOverview"),
          Inches(0.5), Inches(1.15), Inches(12.3))

# ---------------------------------------------------------------------------
# Slide 4 — Architecture: Microkernel (diagram)
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Architecture — What Makes This Unique",
           "Microkernel: stable core, plug-in filters registered at runtime")

add_image(s, img("MicroKernel_Architecture"),
          Inches(0.2), Inches(1.1), Inches(13.0))

# ---------------------------------------------------------------------------
# Slide 5 — Why Microkernel? (design decision / gold plating rationale)
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Why Microkernel?",
           "A deliberate design decision — inspired by VioletUML")

col_w = Inches(6.0)
tops  = Inches(1.25)
row_h = Inches(1.55)
GAP   = Inches(0.18)

# Left column — the problem / motivation
rect(s, Inches(0.25), tops, col_w, Inches(5.9), fill=WHITE, line=SU_RED)
bullet_box(s, [
    "Filters change; the pipeline should not",
    "Adding a new filter in a monolith means touching",
    "  client code, server code, and tests simultaneously",
    "Recognised as gold plating — more architecture",
    "  than a simple project strictly requires",
    "Chose it anyway: the learning value outweighed",
    "  the cost, and the result is genuinely extensible",
], Inches(0.4), tops + Inches(0.05), col_w - Inches(0.3), Inches(5.5),
   size=13, title="The Problem", title_size=15)

# Right column — the benefit
rect(s, Inches(6.75), tops, col_w, Inches(5.9), fill=WHITE, line=ACCENT)
bullet_box(s, [
    "Add a filter → drop one file + one JSON entry",
    "Client code never changes — it calls",
    "  GetTransformations() and discovers new filters",
    "  automatically at runtime",
    "Inspired by VioletUML's plug-in architecture:",
    "  core is frozen; capabilities grow at the edges",
    "Same pattern used in IDEs, browsers, and OS kernels",
    "  to manage long-lived, evolving feature sets",
], Inches(6.9), tops + Inches(0.05), col_w - Inches(0.3), Inches(5.5),
   size=13, title="The Benefit", title_size=15)

# ---------------------------------------------------------------------------
# Slide 6 — gRPC API
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "gRPC API", "Two endpoints — discover then transform")

# Left: GetTransformations
rect(s, Inches(0.25), Inches(1.2), Inches(6.1), Inches(5.85), fill=WHITE, line=ACCENT)
bullet_box(s, [
    "Request:  google.protobuf.Empty",
    "Response: SupportedTransformations",
    "    List of FilterConfig messages",
    "    Each FilterConfig has name, description,",
    "    and typed ParameterSpec list",
    "ParameterSpec includes:",
    "    type: INTEGER | ENUM | STRING | DOUBLE",
    "    min/max for integers and doubles",
    "    allowed_values for enums",
    "Called on startup — drives CLI display",
    "    and all client-side validation",
], Inches(0.4), Inches(1.3), Inches(5.8), Inches(5.5),
   size=14, title="GetTransformations  →  unary RPC", title_size=16)

# Right: Transform
rect(s, Inches(6.95), Inches(1.2), Inches(6.1), Inches(5.85), fill=WHITE, line=SU_RED)
bullet_box(s, [
    "Request stream:  ImageMessage",
    "    image_data (bytes)",
    "    image_format (FileType enum)",
    "    transformations (ordered list)",
    "        name + key=value params",
    "Response stream: TransformedImageMessage",
    "    image_data, image_format",
    "    thumbnail (bytes, PNG, optional)",
    "Errors: gRPC status codes",
    "    (google.rpc.Code convention)",
    "Max 10 transformations per request",
], Inches(7.1), Inches(1.3), Inches(5.8), Inches(5.5),
   size=14, title="Transform  →  stream / stream RPC", title_size=16)

# ---------------------------------------------------------------------------
# Slide 7 — CLI Little Language (two grammars)
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Two Little Languages", "One defines filters; one lets users invoke them")

col_w = Inches(6.3)
tops  = Inches(1.2)
box_h = Inches(4.9)
gap   = Inches(0.43)
CODE  = RGBColor(0x22, 0x44, 0x88)

# ── Left: Filter Definition Language (config grammar) ───────────────────────
rect(s, Inches(0.25), tops, col_w, box_h, fill=WHITE, line=SU_RED)
txbox(s, "Grammar 1 — Filter Definition Language  (filter_config.json)",
      Inches(0.4), tops + Inches(0.08), col_w - Inches(0.2), Inches(0.42),
      bold=True, size=13, color=SU_RED)

config_grammar = (
    "filter_definition =\n"
    "    filter_name , description ,\n"
    "    parameter_list , class_ref , library_name ;\n\n"
    "filter_name    = letter , { letter | \"_\" } ;\n"
    "description    = (* human-readable string *) ;\n"
    "parameter_list = empty | ( param_name , { param_name } ) ;\n"
    "param_name     = letter , { letter | \"_\" } ;\n"
    "class_ref      = module_name , \".\" , class_name ;\n"
    "library_name   = \"PIL\" | (* other libraries *) ;\n"
    "empty          = ;"
)
txbox(s, config_grammar,
      Inches(0.4), tops + Inches(0.6), col_w - Inches(0.2), Inches(4.1),
      size=12, color=CODE)

# ── Right: CLI Grammar ───────────────────────────────────────────────────────
rect(s, Inches(0.25) + col_w + gap, tops, col_w, box_h, fill=WHITE, line=ACCENT)
txbox(s, "Grammar 2 — CLI Little Language  (user input)",
      Inches(0.4) + col_w + gap, tops + Inches(0.08), col_w - Inches(0.2), Inches(0.42),
      bold=True, size=13, color=ACCENT)

cli_grammar = (
    "session     ::= { filter_cmd }  control_cmd\n\n"
    "control_cmd ::= \"done\" | \"show\" | \"clear\" | \"list\"\n\n"
    "filter_cmd  ::= filter_name { \" \" param_pair }\n\n"
    "param_pair  ::= identifier \"=\" value\n\n"
    "value       ::= integer | float | enum_lit\n\n"
    "integer     ::= digit { digit }\n"
    "float       ::= digit { digit } \".\" digit { digit }\n"
    "enum_lit    ::= \"+\" | \"-\" | identifier\n"
    "identifier  ::= letter { letter | digit | \"_\" }"
)
txbox(s, cli_grammar,
      Inches(0.4) + col_w + gap, tops + Inches(0.6), col_w - Inches(0.2), Inches(4.1),
      size=12, color=CODE)

# ── Bottom: rationale ────────────────────────────────────────────────────────
note_top = tops + box_h + Inches(0.1)
rect(s, Inches(0.25), note_top, Inches(13.08), Inches(1.0), fill=WHITE, line=RGBColor(0x99,0x99,0x99))
bullet_box(s, [
    "Grammar 1 is written by the developer — it defines what filters exist and what parameters they accept.",
    "Grammar 2 is typed by the user — filter_cmd and param_pair map directly onto Grammar 1 entries.",
    "Adding a new filter to Grammar 1 automatically makes it a valid filter_cmd in Grammar 2 at runtime.",
], Inches(0.4), note_top + Inches(0.05), Inches(12.8), Inches(0.9), size=12)

# ---------------------------------------------------------------------------
# Slide 8 — Demo: Success Scenarios (combined)
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Demo — Success Scenarios", "Two filter pipelines; one command each")

tops  = Inches(1.25)
half  = Inches(6.35)
gap   = Inches(0.23)
inner = Inches(0.18)
ih    = Inches(5.9)

# ── Scenario 1 (left half) ──────────────────────────────────────────────────
rect(s, Inches(0.2), tops, half, ih, fill=WHITE, line=SU_RED)
bullet_box(s, [
    "Scenario 1 — Rotate 45° + Grayscale  |  Input: JPEG",
    "",
    "CLI:  rotate direction=+ degrees=45, grayscale",
    "",
    "Pipeline:",
    "  1. Decode JPEG → PIL Image",
    "  2. RotateFilter: expand canvas, transparent fill",
    "     → JPEG has no alpha: composite onto white",
    "  3. GrayscaleFilter: convert to grayscale,",
    "     restore original colour mode",
    "  4. Encode → JPEG bytes, stream response",
    "",
    "Output:  sample-trees_transformed.jpeg",
    "Thumbnail: none requested",
], Inches(0.35), tops + Inches(0.1), half - Inches(0.3), ih - Inches(0.15),
   size=13, title="", title_size=1)

# ── Scenario 2 (right half) ──────────────────────────────────────────────────
rect(s, Inches(0.2) + half + gap, tops, half, ih, fill=WHITE, line=ACCENT)
bullet_box(s, [
    "Scenario 2 — Brightness 1.5 + Thumbnail  |  Input: PNG",
    "",
    "CLI:  brightness factor=1.5, thumbnail",
    "",
    "Pipeline:",
    "  1. Decode PNG → PIL Image",
    "  2. BrightnessFilter: enhance 1.5× via",
    "     PIL ImageEnhance.Brightness",
    "  3. ThumbnailFilter: scale to fit 300×300,",
    "     centre-paste → captured as thumbnail,",
    "     image continues through pipeline",
    "  4. Encode → PNG bytes + thumbnail PNG,",
    "     stream both in response",
    "",
    "Output:  sample-square_transformed.png",
    "         sample-square_thumbnail.png",
], Inches(0.35) + half + gap, tops + Inches(0.1), half - Inches(0.3), ih - Inches(0.15),
   size=13, title="", title_size=1)

# ---------------------------------------------------------------------------
# Slide 10 — Demo: Error Scenario
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Demo — Error Scenario", "Invalid parameter caught client-side and server-side")

# Left: what the user types
rect(s, Inches(0.3), tops, Inches(5.8), Inches(5.9), fill=WHITE, line=SU_RED)
txbox(s, "What the user types",
      Inches(0.45), tops + Inches(0.05), Inches(5.5), Inches(0.42),
      bold=True, size=16, color=SU_RED)
bad_input = (
    "  [0/10] > resize percentage=0\n\n"
    "  Error: 'percentage' must be an\n"
    "  integer between 1 and 500\n\n"
    "  [0/10] > resize percentage=abc\n\n"
    "  Error: 'percentage' must be an\n"
    "  integer between 1 and 500\n\n"
    "  [0/10] > ___"
)
txbox(s, bad_input,
      Inches(0.45), tops + Inches(0.55), Inches(5.5), Inches(4.8),
      size=15, color=RGBColor(0x22, 0x44, 0x88))

# Right: explanation
rect(s, Inches(6.9), tops, Inches(6.1), Inches(5.9), fill=WHITE, line=ACCENT)
bullet_box(s, [
    "Client-side validation catches bad params before",
    "    sending any data to the server",
    "Constraints come from ParameterSpec returned by",
    "    GetTransformations — no hard-coding in the CLI",
    "If a bad request reaches the server anyway:",
    "    Pipeline raises ValueError on filter construction",
    "    Server returns gRPC INVALID_ARGUMENT status",
    "    CLI prints: Error from server (INVALID_ARGUMENT): ...",
    "Server also catches unexpected errors:",
    "    Returns gRPC INTERNAL status",
    "    Logged as ERROR in server terminal",
], Inches(7.05), tops + Inches(0.05), Inches(5.8), Inches(5.5),
   size=14, title="Why No Request Is Sent", title_size=16)

# ---------------------------------------------------------------------------
# Slide 11 — Extensibility: Adding a New Filter
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=LIGHT_BG)
header_bar(s, "Extensibility", "Adding a new filter — two steps, no core changes")

# Step 1
rect(s, Inches(0.3), Inches(1.2), Inches(6.1), Inches(5.85), fill=WHITE, line=ACCENT)
txbox(s, "Step 1 — Register in filter_config.json",
      Inches(0.45), Inches(1.28), Inches(5.9), Inches(0.45),
      bold=True, size=16, color=ACCENT)

code1 = ('{\n'
         '  "name": "brightness",\n'
         '  "description": "Adjust brightness",\n'
         '  "parameters": [{\n'
         '    "name": "factor",\n'
         '    "type": "double",\n'
         '    "min": 0.0, "max": 4.0\n'
         '  }],\n'
         '  "class": "filters.BrightnessFilter",\n'
         '  "library": "PIL"\n'
         '}')
txbox(s, code1,
      Inches(0.45), Inches(1.8), Inches(5.7), Inches(2.7),
      size=13, color=RGBColor(0x22, 0x44, 0x88))

bullet_box(s, [
    "name — what the client types in the CLI",
    "class — dynamically imported at runtime",
    "GetTransformations advertises it immediately",
    "    No client code changes needed",
], Inches(0.45), Inches(4.55), Inches(5.7), Inches(2.3), size=14)

# Step 2
rect(s, Inches(6.9), Inches(1.2), Inches(6.1), Inches(5.85), fill=WHITE, line=SU_RED)
txbox(s, "Step 2 — Implement FilterInterface",
      Inches(7.05), Inches(1.28), Inches(5.9), Inches(0.45),
      bold=True, size=16, color=SU_RED)

code2 = ('from .filter_interface import FilterInterface\n'
         'from PIL import ImageEnhance\n\n'
         'class BrightnessFilter(FilterInterface):\n\n'
         '    def __init__(self, **kwargs):\n'
         '        super().__init__(**kwargs)\n'
         '        self.factor = float(kwargs.get(\n'
         '            \'factor\', 1.0))\n\n'
         '    def apply(self, image_data):\n'
         '        enhancer = ImageEnhance.Brightness(\n'
         '            image_data)\n'
         '        return enhancer.enhance(self.factor)')
txbox(s, code2,
      Inches(7.05), Inches(1.8), Inches(5.7), Inches(3.2),
      size=12, color=RGBColor(0x22, 0x44, 0x88))

bullet_box(s, [
    "Override apply() — only requirement",
    "Pipeline handles encode/validation automatically",
], Inches(7.05), Inches(5.05), Inches(5.7), Inches(1.8), size=14)

# ---------------------------------------------------------------------------
# Slide 12 — Thank You / Q&A
# ---------------------------------------------------------------------------
s = add_slide()
rect(s, 0, 0, W, H, fill=SU_RED)
rect(s, 0, Inches(2.6), W, Inches(2.5), fill=DARK_GRAY)

txbox(s, "Thank You",
      Inches(0.5), Inches(2.7), Inches(12.3), Inches(1.0),
      bold=True, size=48, color=WHITE, align=PP_ALIGN.CENTER)
txbox(s, "Questions?",
      Inches(0.5), Inches(3.55), Inches(12.3), Inches(0.65),
      size=26, color=RGBColor(0xFF,0xCC,0xCC), align=PP_ALIGN.CENTER)

txbox(s, "github.com/ltrickey/image-processor",
      Inches(0.5), Inches(5.5), Inches(12.3), Inches(0.5),
      size=16, color=RGBColor(0xFF,0xDD,0xDD), align=PP_ALIGN.CENTER)

txbox(s, "Lynn Trickey  ·  CPSC 5200-02  ·  Seattle University  ·  March 2026",
      Inches(0.5), Inches(6.2), Inches(12.3), Inches(0.4),
      size=13, color=RGBColor(0xBB,0xBB,0xBB), align=PP_ALIGN.CENTER)

# ---------------------------------------------------------------------------
# Save
# ---------------------------------------------------------------------------
prs.save(OUT)
print(f"Saved: {OUT}")