Regions, Spotlights & Layout

The AI Tutor Course Creator uses a region-based layout system to control what the student sees, where they draw or type answers, and where the teacher's explanation appears. This article covers the coordinate system and each region type.

Coordinate System

All coordinates in the AI Tutor Course Creator are expressed as percentages (0–100) of the slide dimensions, not pixels. This ensures layouts scale correctly across different screen sizes.

Every region uses the format x, y, w, h where:

• x — Distance from the left edge (0 = left, 100 = right)
• y — Distance from the top edge (0 = top, 100 = bottom)
• w — Width of the region
• h — Height of the region

For example, 10, 20, 50, 30 means a region starting 10% from the left, 20% from the top, spanning 50% of the slide width and 30% of the slide height.

Multi-Region Spotlights

When you need to highlight more than one area of the slide at the same time, use a semicolon separator between coordinate sets:

x1,y1,w1,h1; x2,y2,w2,h2

Example: 5,12,45,40; 55,12,40,40 highlights two side-by-side areas.

Spotlight Regions

A spotlight highlights a portion of the slide while dimming everything else with a semi-transparent overlay. It focuses the student's attention on the current problem or section of the slide.

Placement Guidelines

• Trace PPTX box borders with precision. Spotlights should tightly follow the bounding box of the content they highlight, not use crude full-width bands. Trace the actual shape or table cell borders on the slide.
• Corner radius is 6px. All spotlights render with rounded corners for a polished appearance.
• Include the title bar when relevant. If the problem title is at the top of the slide, extend the spotlight up to y=0 to include it.
• Add generous padding. Start at y=0 when appropriate and add at least 10% padding below the content to avoid clipping.

HTML-Generated Slides

Slides generated via the HTML template system (720×405 resolution) have a permanent header bar and logo. These are automatically included as spotlight regions and do not need to be manually specified.

Drawing Regions

Drawing regions define answer boxes positioned on the slide where students write, draw, or place answers. They are used with question types like write_regions, region_drawing, draggable_labels, and draggable_buckets.

Format

Each drawing region is a JSON object with x, y, w, h keys:

{"x": 55, "y": 30, "w": 15, "h": 10}

Important: Regions MUST be JSON objects, never nested arrays.

Optional Keys

• colors — An array of expected colors (used for drawing questions where color matters).
• label — For write_regions, the expected answer text. For AI-evaluated types, a description of what the correct answer looks like.

Visibility Rule

Drawing regions must overlap at least one spotlight region to be visible to the student. If a drawing region falls entirely within the dimmed area, it will not be interactive.

Teacher Pad (Scratchpad)

The teacher pad is a yellow sticky-note overlay that displays the teacher's explanation, solution steps, or worked example. It appears on top of the dimmed area of the slide.

Positioning

The scratchpad is positioned with x, y, w, h percentage coordinates, just like other regions. Key rules:

• Must NOT overlap the spotlight. The scratchpad belongs in the dimmed area so it does not cover the problem the student is working on.
• Fill available space generously. Width should be at least 60% of the slide. Height should fill the available zone in the dimmed area.
• Up to 2 pads per question. Some questions benefit from a second scratchpad for additional explanation.

Timing Options

The scratchpad timing field controls when it appears:

• "question" — Shows when the question first loads. Use for setup instructions or context the student needs before answering.
• "response" — Shows after the student answers correctly. This is the most common setting, used to reveal the teacher's worked solution.
• "both" — Shows at both times.

Overlay Text

Overlay text is a JSON array of text items displayed on the teacher pad (scratchpad). Each item controls one line or block of text on the sticky note.

Item Properties

• text — The text string to display. Supports {o}...{/o} markup for overline (repeating decimals).
• x — Horizontal position (percentage). Should fall inside the scratchpad region.
• y — Vertical position (percentage). Must be inside the scratchpad, starting at scratchpad_y + 7% for the first line.
• size — Font size. Minimum 20 for readability. Common default: 20.
• color — Text color as hex string. Common default: #2e7d32 (green).
• font — Font family. Use mono for numbers and math expressions, sans for explanatory text.

Spacing Guidelines

• Use 7% minimum vertical spacing between lines.
• Always read the current scratchpad_region coordinates before setting overlay text y values — overlay text y-coordinates are relative to the slide, not to the scratchpad.
• Keep text within the scratchpad boundaries so it does not overflow the sticky note.

Pointer Animations

Pointer animations display a red laser pointer dot that guides the student's attention across the slide. The pointer is a JSON array of positions, each with x, y, and delay (in milliseconds).

Styles

• point — A single position. The dot appears at one location to draw attention.
• trace — Outlines a shape by moving through a series of positions along its border.
• walk — Visits a sequence of objects one by one, pausing 1.5 seconds at each.
• compare — Highlights two groups of objects, pausing 1.0 second between groups.

Usage Rules

• Do not use with write_regions or drawing questions. Pointer animations are for observation and comprehension, not answer-entry questions.
• Never sweep across text. The pointer should point at diagrams, shapes, and pictures, not drag across words.
• Best for diagrams and pictures. Use the pointer to guide the student through visual elements like geometric shapes, graphs, Venn diagrams, and illustrations.

Auto-Layout (Build Regions)

The Build Regions feature uses AI to automatically compute spotlight, scratchpad, and overlay text positions based on the slide content. This saves time when setting up new questions.

How It Works

1. Open the question in the AI Tutor Course Creator.
2. Click the Build Regions button in the assistant panel.
3. The AI analyzes the slide image and question content to determine optimal placement for the spotlight (covering the problem area), scratchpad (in the dimmed zone), and overlay text (inside the scratchpad).
4. Review the generated layout and adjust if needed.

Scope

• Build Regions can generate layout for a single question or an entire slide (all questions on that slide).
• The generated layout follows all the rules described in this article: spotlight precision, scratchpad in the dimmed area, overlay text with proper spacing, and drawing regions overlapping the spotlight.

While Build Regions produces good results in most cases, always review the output visually to ensure the spotlight precisely traces the content borders and the scratchpad does not overlap the highlighted area.