mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-14 18:24:37 -06:00
311 lines
17 KiB
Python
311 lines
17 KiB
Python
#!/usr/bin/env python3
|
|
"""Export a finite, captioned GIF of a shared-player figure's committed states.
|
|
|
|
Run against a rendered chapter or a QA fixture served over HTTP. This captures
|
|
step endpoints, not interpolated motion, and never edits the chapter or player.
|
|
The GIF has no interactive controls. Raw PNG frames and a provenance manifest
|
|
are retained beside it. Requires Playwright Chromium, Pillow, and PyYAML.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import hashlib
|
|
import html
|
|
import json
|
|
from pathlib import Path
|
|
import subprocess
|
|
import sys
|
|
from urllib.parse import urljoin
|
|
|
|
ROOT = Path(__file__).resolve().parents[3]
|
|
EXT = ROOT / 'books/_extensions/mlsysbook-ext/figure-explore'
|
|
|
|
|
|
def sha256(data: bytes) -> str:
|
|
return hashlib.sha256(data).hexdigest()
|
|
|
|
|
|
def canonical_url(source: str, figure_id: str, site_url: str) -> str:
|
|
"""Quarto publishes the books-relative source path under website.site-url."""
|
|
path = Path(source).relative_to('books').with_suffix('.html').as_posix()
|
|
return urljoin(site_url.rstrip('/') + '/', path) + '?view=explore#' + figure_id
|
|
|
|
|
|
def frame_duration(text: str, minimum_ms: int, words_per_minute: int) -> int:
|
|
"""Constructed reading allowance, rounded upward to GIF's centisecond tick."""
|
|
import math
|
|
return math.ceil(max(minimum_ms, len(text.split()) * 60000 / words_per_minute) / 10) * 10
|
|
|
|
|
|
def encode_gif(frames: list[Path], durations: list[int], destination: Path) -> None:
|
|
from PIL import Image
|
|
if not frames or len(frames) != len(durations):
|
|
raise ValueError('One duration is required for every frame.')
|
|
images = [Image.open(path).convert('RGB') for path in frames]
|
|
if len({image.size for image in images}) != 1:
|
|
raise ValueError('Export frames must have identical dimensions.')
|
|
# Omitting GIF's loop extension means one playback; loop=0 would loop forever.
|
|
images[0].save(destination, save_all=True, append_images=images[1:],
|
|
duration=durations, disposal=2, optimize=False)
|
|
|
|
|
|
CAPTURE_CSS = """
|
|
.mlsys-original-jump-anchor, .mlsys-original-jump, .mlsys-original-cue,
|
|
.mlsys-original-dock, .mlsys-original-controls, .mlsys-original-tooltip,
|
|
.mlsys-original-speed-popover, #quarto-header, #quarto-sidebar,
|
|
#quarto-margin-sidebar { visibility: hidden !important; pointer-events: none !important; }
|
|
"""
|
|
|
|
|
|
def prepare_capture(root, width: int) -> dict:
|
|
"""Expand a private browser's stage; reject residual overflow instead of cropping.
|
|
|
|
The chapter reading column is often narrower than its figure's minimum SVG
|
|
width. Fix the capture width independently of that column and open only HTML
|
|
scroll containers. Do not change SVG viewBoxes or shrink away source labels.
|
|
"""
|
|
return root.evaluate(r"""(root, width) => {
|
|
root.style.setProperty('width', width + 'px', 'important');
|
|
root.style.setProperty('max-width', 'none', 'important');
|
|
const stage = root.querySelector('.mlsys-original-stage');
|
|
// Opaque capture surface prevents the chapter column's border/shadow
|
|
// showing through a diagram expanded beyond that column.
|
|
stage.style.setProperty('background-color', '#fff', 'important');
|
|
stage.style.setProperty('position', 'relative', 'important');
|
|
stage.style.setProperty('z-index', '1', 'important');
|
|
for (let n = stage; n; n = n.parentElement) {
|
|
n.style.setProperty('overflow', 'visible', 'important');
|
|
n.scrollLeft = 0; n.scrollTop = 0;
|
|
}
|
|
stage.style.setProperty('width', width + 'px', 'important');
|
|
stage.style.setProperty('max-width', 'none', 'important');
|
|
// Open inner HTML scrolling panes, including minimum-width source SVGs.
|
|
// SVG overflow keeps its authored setting; validation below catches labels
|
|
// that would require changing source artwork to export correctly.
|
|
for (const node of stage.querySelectorAll('*')) {
|
|
if (node.namespaceURI !== 'http://www.w3.org/1999/xhtml') continue;
|
|
node.scrollLeft = 0; node.scrollTop = 0;
|
|
node.dispatchEvent(new Event('scroll'));
|
|
const css = getComputedStyle(node);
|
|
if (/(auto|scroll|hidden|clip)/.test(css.overflowX + ' ' + css.overflowY)) {
|
|
node.style.setProperty('overflow', 'visible', 'important');
|
|
node.style.setProperty('max-height', 'none', 'important');
|
|
}
|
|
}
|
|
let required = width;
|
|
const box = stage.getBoundingClientRect();
|
|
for (const node of stage.querySelectorAll('*')) {
|
|
if (node.closest('defs,clipPath,mask,symbol')) continue;
|
|
const css = getComputedStyle(node), b = node.getBoundingClientRect();
|
|
if (css.display !== 'none' && css.visibility !== 'hidden' && b.width && b.height)
|
|
required = Math.max(required, b.right - box.left + 8);
|
|
}
|
|
// Avoid iterative growth from the stage's own full-width children.
|
|
if (required > width + 9) {
|
|
root.style.setProperty('width', Math.ceil(required) + 'px', 'important');
|
|
stage.style.setProperty('width', Math.ceil(required) + 'px', 'important');
|
|
}
|
|
return {requested_width: width, capture_width: stage.getBoundingClientRect().width};
|
|
}""", width)
|
|
|
|
|
|
def validate_capture(root) -> dict:
|
|
"""Fail when visible diagram content would be cropped by the stage or an SVG."""
|
|
geometry = root.evaluate(r"""root => {
|
|
const stage = root.querySelector('.mlsys-original-stage'), box = stage.getBoundingClientRect();
|
|
const problems = [];
|
|
const outside = (a,b) => a.left < b.left-2 || a.right > b.right+2 || a.top < b.top-2 || a.bottom > b.bottom+2;
|
|
for (const node of stage.querySelectorAll('svg, img, canvas, text, foreignObject, [data-mlsys-keep], [data-mlsys-focus]')) {
|
|
if (node.closest('defs,clipPath,mask,symbol')) continue;
|
|
const css = getComputedStyle(node), b = node.getBoundingClientRect();
|
|
if (!b.width || !b.height || css.display === 'none' || css.visibility === 'hidden' || Number(css.opacity) === 0) continue;
|
|
if (outside(b,box)) problems.push('outside stage: ' + node.tagName + ' ' + (node.textContent || '').slice(0,80));
|
|
const svg = node.ownerSVGElement;
|
|
if (svg && ['hidden','clip','auto','scroll'].includes(getComputedStyle(svg).overflow) && outside(b,svg.getBoundingClientRect()))
|
|
problems.push('outside SVG: ' + node.tagName + ' ' + (node.textContent || '').slice(0,80));
|
|
}
|
|
return {width:box.width,height:box.height,problems};
|
|
}""")
|
|
if geometry['problems']:
|
|
raise ValueError('Figure cannot be exported without clipping: ' + '; '.join(geometry['problems']))
|
|
return geometry
|
|
|
|
|
|
def export_text(locator, remove: str) -> str:
|
|
"""Preserve readable block boundaries when removing interactive disclosures."""
|
|
return locator.evaluate(r"""(node, remove) => {
|
|
const copy = node.cloneNode(true);
|
|
copy.querySelectorAll(remove).forEach(e => e.remove());
|
|
copy.querySelectorAll('div,p,section,article,li,dt,dd,tr,h1,h2,h3,h4,br').forEach(e => {
|
|
e.prepend(document.createTextNode('\n')); e.append(document.createTextNode('\n'));
|
|
});
|
|
return copy.textContent.replace(/[ \t]+/g,' ').replace(/\n\s*\n/g,'\n').trim();
|
|
}""", remove)
|
|
|
|
|
|
def export(args) -> dict:
|
|
import base64
|
|
import yaml
|
|
from playwright.sync_api import sync_playwright
|
|
|
|
registry = json.loads((EXT / 'figure-registry.json').read_text())
|
|
if args.key not in registry:
|
|
raise ValueError('Unknown registered figure: ' + args.key)
|
|
record = registry[args.key]
|
|
if not record.get('shared_player'):
|
|
raise ValueError('This exporter currently supports shared-player lessons only.')
|
|
config = ROOT / f'books/config/_quarto-html-vol{record["volume"]}.yml'
|
|
site_url = yaml.safe_load(config.read_text())['website']['site-url']
|
|
source_url = canonical_url(record['source'], record['figure_id'], site_url)
|
|
out = args.output.resolve()
|
|
out.parent.mkdir(parents=True, exist_ok=True)
|
|
frame_dir = out.with_suffix('')
|
|
frame_dir.mkdir(exist_ok=True)
|
|
if out.exists() or any(frame_dir.iterdir()):
|
|
raise ValueError('Choose a new output name; exports do not overwrite prior receipts.')
|
|
resources = {}
|
|
errors = []
|
|
states = []
|
|
with sync_playwright() as p:
|
|
browser = p.chromium.launch()
|
|
page = browser.new_page(viewport={'width': args.width, 'height': 1200},
|
|
color_scheme='light', reduced_motion='reduce', device_scale_factor=2)
|
|
page.on('pageerror', lambda e: errors.append(str(e)))
|
|
def resource(response):
|
|
if response.request.resource_type in {'document', 'script', 'stylesheet', 'image'} and response.ok:
|
|
try:
|
|
resources[response.url] = sha256(response.body())
|
|
except Exception:
|
|
pass
|
|
page.on('response', resource)
|
|
page.goto(args.url, wait_until='networkidle')
|
|
outer = page.locator('[id=' + json.dumps(record['figure_id']) + ']')
|
|
outer.scroll_into_view_if_needed()
|
|
page.wait_for_function('id => { const e=document.getElementById(id); return e && (e.dataset.fixtureState === "ready" || e.dataset.mlsysExploreState === "ready"); }', arg=record['figure_id'])
|
|
explore = outer.get_by_role('tab', name='Explore', exact=True)
|
|
if explore.count():
|
|
explore.click()
|
|
root = outer.locator('.mlsys-original-player')
|
|
root.wait_for(state='visible')
|
|
title = root.locator('.mlsys-original-title').inner_text()
|
|
assumptions = export_text(root.locator('.mlsys-original-assumptions'), 'summary,button,select')
|
|
menu = root.locator('.mlsys-original-sequence select')
|
|
values = menu.locator('option').evaluate_all('(nodes) => nodes.map(n => n.value)')
|
|
page.add_style_tag(content=CAPTURE_CSS)
|
|
# Fix Whole view when offered: a shareable preview must retain the full
|
|
# source composition rather than crop away context as a focus follows.
|
|
for selector in root.locator('select').all():
|
|
if selector.locator('option[value="whole"]').count():
|
|
selector.select_option('whole', force=True)
|
|
capture_width = args.width - 56
|
|
for value in values:
|
|
menu.select_option(value, force=True)
|
|
capture_width = max(capture_width, prepare_capture(root, capture_width)['capture_width'])
|
|
# Keep the capture canvas inside the browser viewport even when the
|
|
# chapter column starts after a sidebar. Otherwise screenshot stitching
|
|
# can carry viewport-edge shadows through a wide SVG. Export-sheet width
|
|
# remains the caller's requested width.
|
|
import math
|
|
page.set_viewport_size({'width': max(args.width, math.ceil(capture_width) + 1024), 'height': 1200})
|
|
for ordinal, value in enumerate(values):
|
|
menu.select_option(value, force=True)
|
|
prepare_capture(root, capture_width)
|
|
page.evaluate('() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))')
|
|
stage = root.locator('.mlsys-original-stage')
|
|
stage.scroll_into_view_if_needed()
|
|
page.evaluate('() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))')
|
|
geometry = validate_capture(root)
|
|
png = stage.screenshot(animations='disabled')
|
|
stage_path = frame_dir / f'stage-{ordinal:03d}.png'
|
|
stage_path.write_bytes(png)
|
|
narration = root.locator('.mlsys-original-narration').inner_text()
|
|
details = export_text(root.locator('.mlsys-original-details'), 'details,button,select')
|
|
# Narrative and details are captured as text from the committed state,
|
|
# not reconstructed from lesson source or inferred from an animation.
|
|
states.append({'value': value, 'narration': narration, 'details': details,
|
|
'stage': stage_path, 'png': png, 'geometry': geometry})
|
|
if errors:
|
|
raise RuntimeError('Chapter emitted errors: ' + '; '.join(errors))
|
|
from PIL import Image
|
|
import io
|
|
diagram_height = max(Image.open(io.BytesIO(s['png'])).height / Image.open(io.BytesIO(s['png'])).width * (args.width - 56) for s in states)
|
|
sheet = browser.new_page(viewport={'width': args.width, 'height': 1200}, device_scale_factor=1)
|
|
style = '''body{margin:0;background:white;color:#16212b;font:22px/1.4 system-ui,sans-serif}main{box-sizing:border-box;padding:28px;width:100%;background:white}h1{font-size:28px;margin:0 0 8px}p{margin:10px 0}.scope{font-size:17px;color:#44515b}.diagram{width:100%;height:auto;display:block}.diagram-box{overflow:hidden}.narration{font-size:22px;white-space:pre-line}.details{font-size:18px;white-space:pre-line}footer{border-top:1px solid #bcc7cf;margin-top:18px;padding-top:12px;font-size:16px;overflow-wrap:anywhere}.kind{font-size:16px;color:#44515b}'''
|
|
heights = []
|
|
for state in states:
|
|
stage_data = base64.b64encode(state['png']).decode()
|
|
markup = '<!doctype html><meta charset="utf-8"><style>' + style + '</style><main>'
|
|
markup += '<h1>' + html.escape(title) + '</h1><div class="kind">Step-by-step preview · GIF has no interactive controls</div>'
|
|
markup += '<p class="scope">' + html.escape(assumptions) + '</p>'
|
|
markup += '<div class="diagram-box" style="height:' + str(diagram_height) + 'px"><img class="diagram" src="data:image/png;base64,' + stage_data + '"></div>'
|
|
markup += '<p class="narration">' + html.escape(state['narration']) + '</p>'
|
|
if state['details']:
|
|
markup += '<p class="details">' + html.escape(state['details']) + '</p>'
|
|
markup += '<footer><strong>MLSysBook</strong> · Explore the interactive figure:<br>' + html.escape(source_url) + '</footer></main>'
|
|
state['markup'] = markup
|
|
sheet.set_content(markup)
|
|
sheet.locator('.diagram').evaluate('(img) => img.decode()')
|
|
heights.append(sheet.locator('main').bounding_box()['height'])
|
|
import math
|
|
height = math.ceil(max(heights))
|
|
sheet.set_viewport_size({'width': args.width, 'height': height})
|
|
frames = []
|
|
durations = []
|
|
for ordinal, state in enumerate(states):
|
|
sheet.set_content(state['markup'])
|
|
sheet.locator('.diagram').evaluate('(img) => img.decode()')
|
|
sheet.add_style_tag(content=f'main{{min-height:{height}px}}')
|
|
path = frame_dir / f'frame-{ordinal:03d}.png'
|
|
sheet.screenshot(path=str(path))
|
|
frames.append(path)
|
|
durations.append(frame_duration(state['narration'] + ' ' + state['details'], args.minimum_ms, args.words_per_minute))
|
|
browser.close()
|
|
encode_gif(frames, durations, out)
|
|
bound_paths = [ROOT / record['source'], config, Path(__file__).resolve(),
|
|
ROOT / 'books/config/shared/html/figure-explore.yml']
|
|
for name in ('script', 'stylesheet'):
|
|
if record.get(name):
|
|
bound_paths.append(EXT / record[name])
|
|
bound_paths += [EXT / name for name in ('original-player.js', 'original-player.css', 'figure-explore.js', 'figure-views.js', 'figure-views.css')]
|
|
manifest = {
|
|
'key': args.key, 'kind': 'constructed step-by-step GIF preview',
|
|
'capture_url': args.url, 'source_url': source_url,
|
|
'limitations': ['Committed endpoints only; interpolated motion is not captured.',
|
|
'No interactive controls; reading durations are constructed display allowances.',
|
|
'Capture is not evidence of learning outcomes or technical correctness.'],
|
|
'git_commit': subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=ROOT, text=True).strip(),
|
|
'git_dirty': bool(subprocess.check_output(['git', 'status', '--porcelain'], cwd=ROOT, text=True).strip()),
|
|
'command': sys.argv, 'input_sha256': {str(path.relative_to(ROOT)): sha256(path.read_bytes()) for path in bound_paths},
|
|
'fetched_resource_sha256': resources,
|
|
'width': args.width, 'height': height, 'loop': 'once',
|
|
'frames': [{'file': str(path), 'sha256': sha256(path.read_bytes()), 'duration_ms': duration,
|
|
'state': state['value'], 'capture_geometry': state['geometry'], 'narration': state['narration'], 'details': state['details']}
|
|
for path, duration, state in zip(frames, durations, states)],
|
|
'output': str(out), 'output_sha256': sha256(out.read_bytes()),
|
|
}
|
|
from datetime import datetime, timezone
|
|
manifest['created_at'] = datetime.now(timezone.utc).isoformat()
|
|
out.with_suffix('.json').write_text(json.dumps(manifest, indent=2) + '\n')
|
|
return manifest
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
parser.add_argument('--url', required=True, help='Rendered chapter or QA fixture URL')
|
|
parser.add_argument('--key', required=True, help='Registered volN:fig-id')
|
|
parser.add_argument('--output', required=True, type=Path, help='New .gif output path')
|
|
parser.add_argument('--width', type=int, default=1100)
|
|
parser.add_argument('--minimum-ms', type=int, default=3500)
|
|
parser.add_argument('--words-per-minute', type=int, default=180)
|
|
args = parser.parse_args()
|
|
if args.width < 320 or args.minimum_ms <= 0 or args.words_per_minute <= 0:
|
|
parser.error('Width must be at least 320; timing values must be positive.')
|
|
if args.output.suffix.lower() != '.gif':
|
|
parser.error('--output must end in .gif')
|
|
manifest = export(args)
|
|
print(json.dumps({k: manifest[k] for k in ('output', 'output_sha256', 'source_url', 'width', 'height')}))
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|