#!/usr/bin/env python3
import os
import re
import json
from datetime import datetime
from pathlib import Path
from PIL import Image # pip install Pillow
IMAGES_DIR = Path("images")
THUMBS_DIR = IMAGES_DIR / "thumbs"
OUTPUT_HTML = Path("timeline.html")
THUMB_MAX_SIZE = (800, 800) # max width/height for thumbnails
JPEG_QUALITY = 80 # JPEG thumbnail quality
# --- Helpers -----------------------------------------------------------
def humanize_title(slug: str) -> str:
"""Turn 'my-cool_title' into 'My Cool Title' (used for alt text only)."""
if not slug:
return "Untitled"
text = re.sub(r"[-_]+", " ", slug).strip()
return re.sub(r"\b\w", lambda m: m.group(0).upper(), text)
def parse_date_from_filename(filename: str):
"""
Parse date from the filename.
Tries (in order):
1) YYYY-MM-DD or YYYY_MM_DD at the start
2) DD-MM-YYYY-...
3) MM-YYYY-...
4) YYYY-...
5) Any 4-digit year (19xx or 20xx) anywhere in the name
Returns (date_obj, label, rest_slug)
- date_obj: datetime or None
- label: string representation to display
- rest_slug: remaining part for alt text
"""
name = os.path.splitext(filename)[0]
# 1) YYYY-MM-DD or YYYY_MM_DD at the start
m = re.match(r"^(\d{4})[-_](\d{1,2})[-_](\d{1,2})(?:[-_](.*))?$", name)
if m:
yyyy, mm, dd, rest = m.groups()
try:
dt = datetime(int(yyyy), int(mm), int(dd))
except ValueError:
dt = None
label = f"{yyyy}-{mm.zfill(2)}-{dd.zfill(2)}"
return dt, label, (rest or "")
# 2) DD-MM-YYYY-...
m = re.match(r"^(\d{1,2})-(\d{1,2})-(\d{4})(?:[-_](.*))?$", name)
if m:
dd, mm, yyyy, rest = m.groups()
try:
dt = datetime(int(yyyy), int(mm), int(dd))
except ValueError:
dt = None
label = f"{dd.zfill(2)}-{mm.zfill(2)}-{yyyy}"
return dt, label, (rest or "")
# 3) MM-YYYY-...
m = re.match(r"^(\d{1,2})-(\d{4})(?:[-_](.*))?$", name)
if m:
mm, yyyy, rest = m.groups()
try:
dt = datetime(int(yyyy), int(mm), 1)
except ValueError:
dt = None
label = f"{mm.zfill(2)}-{yyyy}"
return dt, label, (rest or "")
# 4) YYYY-...
m = re.match(r"^(\d{4})(?:[-_](.*))?$", name)
if m:
yyyy, rest = m.groups()
try:
dt = datetime(int(yyyy), 1, 1)
except ValueError:
dt = None
label = f"{yyyy}"
return dt, label, (rest or "")
# 5) Fallback: any 4-digit year (19xx or 20xx) anywhere in the name
m = re.search(r"(19|20)\d{2}", name)
if m:
yyyy = int(m.group(0))
try:
dt = datetime(yyyy, 1, 1)
except ValueError:
dt = None
label = str(yyyy)
# remove that year from the slug for a cleaner title
rest = name.replace(str(yyyy), "")
rest = re.sub(r"^[-_]+|[-_]+$", "", rest)
return dt, label, rest
# No recognizable date at all
return None, name, ""
def ensure_thumbnail(src_path: Path) -> Path:
"""
Ensure a thumbnail exists for src_path inside THUMBS_DIR.
Returns the thumbnail Path.
"""
THUMBS_DIR.mkdir(parents=True, exist_ok=True)
thumb_path = THUMBS_DIR / src_path.name
# If thumbnail already exists, reuse it
if thumb_path.exists():
return thumb_path
try:
with Image.open(src_path) as im:
im = im.convert("RGB")
im.thumbnail(THUMB_MAX_SIZE)
save_kwargs = {"optimize": True}
if thumb_path.suffix.lower() in {".jpg", ".jpeg"}:
save_kwargs["quality"] = JPEG_QUALITY
im.save(thumb_path, **save_kwargs)
except Exception as e:
print(f"[WARN] could not create thumbnail for {src_path}: {e}")
# fallback: copy original
try:
import shutil
shutil.copy2(src_path, thumb_path)
except Exception as e2:
print(f"[WARN] and could not copy original either: {e2}")
return thumb_path
def collect_events():
"""
Scan IMAGES_DIR for .jpg/.jpeg/.png and build event objects.
If a matching .txt exists, include its contents in the event.
If a matching .jxl exists, include it for JPEG XL loading.
Also generate / use thumbnails in images/thumbs/.
"""
if not IMAGES_DIR.is_dir():
raise SystemExit(f"Images directory not found: {IMAGES_DIR}")
events = []
for entry in sorted(IMAGES_DIR.iterdir()):
if not entry.is_file():
continue
ext = entry.suffix.lower()
if ext not in {".jpg", ".jpeg", ".png"}:
continue
dt, label, rest_slug = parse_date_from_filename(entry.name)
# Full-size image path (for fullscreen)
full_rel_path = f"{IMAGES_DIR.name}/{entry.name}"
# Thumbnail (for timeline display)
thumb_path = ensure_thumbnail(entry)
thumb_rel_path = f"{IMAGES_DIR.name}/{THUMBS_DIR.name}/{thumb_path.name}"
base_no_ext = os.path.splitext(entry.name)[0]
title = humanize_title(rest_slug or entry.stem)
# Robust year detection: any 4-digit year in label or name
year = None
if dt:
year = dt.year
else:
m = re.search(r"(19|20)\d{2}", label)
if m:
year = int(m.group(0))
else:
m2 = re.search(r"(19|20)\d{2}", base_no_ext)
if m2:
year = int(m2.group(0))
# Matching .txt file next to the image
txt_path = IMAGES_DIR / (base_no_ext + ".txt")
text_content = ""
if txt_path.exists():
text_content = txt_path.read_text(encoding="utf-8", errors="ignore")
# Matching .jxl file (for JPEG XL) – used in fullscreen only
jxl_path = IMAGES_DIR / (base_no_ext + ".jxl")
jxl_rel_path = None
if jxl_path.exists():
jxl_rel_path = f"{IMAGES_DIR.name}/{base_no_ext}.jxl"
events.append({
"image": thumb_rel_path, # thumbnail for timeline
"full_image": full_rel_path, # full-res for fullscreen
"jxl_image": jxl_rel_path, # optional JXL (fullscreen)
"date_label": label, # displayed chip (date)
"file_label": base_no_ext, # filename without extension
"title": title, # alt text only
"description": "", # unused for now
"text": text_content, # contents of matching .txt if any
"year": year,
"sort_key": dt.isoformat() if dt else None,
})
# Sort by date (None at the end, in name order)
def sort_key(ev):
return (ev["sort_key"] is None, ev["sort_key"] or "")
events.sort(key=sort_key)
return events
def build_html(events):
# Strip sort_key before embedding
for ev in events:
ev.pop("sort_key", None)
events_json = json.dumps(events, ensure_ascii=False, indent=2)
html_template = r"""
OSS Jedburghs: Team Augustus
This project is a work in progress
Click anywhere to continue
OSS Jedburghs: Team Augustus
Operational Timeline & Archival Records
Office Of Strategic Services — Declassified Reproduction
"""
return html_template.replace("__EVENTS_JSON__", events_json)
def main():
events = collect_events()
html = build_html(events)
OUTPUT_HTML.write_text(html, encoding="utf-8")
print(f"Generated {OUTPUT_HTML} with {len(events)} events.")
if __name__ == "__main__":
main()