#!/usr/bin/env python3
"""
Generate a simple HTML gallery for a state's exported heatmap artifacts.
The report references PNG previews (including hotspot overlays) and links to
the GeoTIFF rasters for download.
"""
import argparse
from datetime import datetime
from html import escape
from pathlib import Path
def parse_args():
parser = argparse.ArgumentParser(
description="Generate an HTML report summarizing exported heatmap assets."
)
parser.add_argument("state", help="State name (e.g., alabama).")
parser.add_argument(
"--title",
default=None,
help="Optional title for the HTML page (defaults to ' Heatmap Report').",
)
parser.add_argument(
"--output",
type=Path,
default=None,
help="Optional output HTML path (defaults to state folder).",
)
return parser.parse_args()
def gather_files(state_dir, patterns):
matches = []
for pattern in patterns:
matches.extend(sorted(state_dir.glob(pattern)))
unique = []
seen = set()
for path in matches:
if path not in seen and path.is_file():
unique.append(path)
seen.add(path)
return unique
def build_html(title, images, rasters):
timestamp = datetime.utcnow().isoformat()
img_sections = []
for image in images:
name = image.name
img_sections.append(
f"""
{escape(name)}
"""
)
raster_links = []
for raster in rasters:
name = raster.name
raster_links.append(f'
')
images_html = "\n".join(img_sections) if img_sections else "
No images found.
"
rasters_html = (
"
" + "\n".join(raster_links) + "
"
if raster_links
else "
No GeoTIFF rasters found.
"
)
return f"""
{escape(title)}
{escape(title)}
Generated: {escape(timestamp)} UTC
Image Previews
{images_html}
GeoTIFF Downloads
{rasters_html}
"""
def main():
args = parse_args()
state = args.state.lower()
# Check if state is in germany subdirectory first
germany_dir = Path("output") / "germany" / state
if germany_dir.exists():
state_dir = germany_dir
else:
state_dir = Path("output") / state
if not state_dir.exists():
raise SystemExit(f"❌ State directory not found: {state_dir}")
title = args.title or f"{state.capitalize()} Heatmap Report"
output_path = args.output or (state_dir / f"{state}_report.html")
image_patterns = [
"*heatmap*.png",
"*road_density_*km.png",
"*hotspots*.png",
"*layers*.png",
]
raster_patterns = ["*road_density_*km.tif"]
images = gather_files(state_dir, image_patterns)
rasters = gather_files(state_dir, raster_patterns)
if not images and not rasters:
raise SystemExit(f"⚠️ No exported artifacts found in {state_dir}")
html_content = build_html(title, images, rasters)
output_path.write_text(html_content, encoding="utf-8")
print(f"📄 Saved HTML report to: {output_path}")
if __name__ == "__main__":
main()