Automating Professional Map Layouts in QGIS Using PyQGIS

map-series/
  bengaluru_map_series.qgz            the QGIS project
  data/bengaluru_map_series.gpkg      the input data
  templates/corporation_map_template.qpt
  scripts/starter_script.py
  scripts/make_map_series.py
  output/                             sample results; the script writes new files here
  QA_checklist.md

# The shortest version: one map, from a template, exported as a PDF.
# Open bengaluru_map_series.qgz first, then run this in the QGIS Python Console.

# Step 1: bring in the QGIS tools we need
from pathlib import Path
from qgis.core import QgsExpressionContextUtils, QgsLayoutExporter, QgsPrintLayout, QgsProject, QgsReadWriteContext
from qgis.PyQt.QtXml import QDomDocument

# Step 2: find the folder that holds the project file. Everything else is found relative to it.
project = QgsProject.instance()                    # the project that is open in QGIS right now
folder = Path(project.homePath())

# Step 3: build a new Print Layout from the saved template (the .qpt file)
document = QDomDocument()                          # a container for the template's text
document.setContent((folder / "templates" / "corporation_map_template.qpt").read_text(encoding="utf-8"))
layout = QgsPrintLayout(project)                   # an empty page
layout.loadFromTemplate(document, QgsReadWriteContext(), True)   # fill it from the template; True = clear the page first

# Step 4: pick the East corporation from the layer. The filter text works like a QGIS expression.
region = project.mapLayersByName("Parks and lakes, share of area (%)")[0]
east = next(region.getFeatures("\"short\" = 'East'"))      # next() takes the first (only) match

# Step 5: write East's title and subtitle on the page. itemById finds an item by the ID typed in the template.
layout.itemById("map_title").setText(east["title"])
layout.itemById("map_subtitle").setText(east["subtitle"])

# Step 6: tell the dark outline layer which corporation to draw
QgsExpressionContextUtils.setProjectVariable(project, "focus_name", "East")

# Step 7: zoom the map to East, with a quarter more space around it
extent = east.geometry().boundingBox()             # the rectangle that just fits East
extent.scale(1.25)                                 # make it 25 percent bigger on each side
layout.itemById("main_map").zoomToExtent(extent)

# Step 8: make an output folder and save the page as a PDF
(folder / "output").mkdir(exist_ok=True)
result = QgsLayoutExporter(layout).exportToPdf(str(folder / "output" / "East.pdf"), QgsLayoutExporter.PdfExportSettings())

# Step 9: say whether it worked
print("Exported" if result == QgsLayoutExporter.Success else f"Export failed: {result}")

# The tools this script uses. Each name after "import" is a tool that QGIS or Python provides.
import csv
import re
import time
from pathlib import Path

from qgis.core import (
    QgsExpressionContextUtils,   # sets project variables, such as focus_name
    QgsLayoutExporter,           # saves a layout as PDF or image
    QgsLayoutItemLabel,          # a text label on the page
    QgsLayoutItemLegend,         # the legend
    QgsLayoutItemMap,            # a map frame
    QgsLayoutItemScaleBar,       # the scale bar
    QgsPrintLayout,              # a Print Layout (the page)
    QgsProject,                  # the open QGIS project
    QgsReadWriteContext,         # needed when loading a template
)
from qgis.PyQt.QtXml import QDomDocument

# These are the only lines you should need to edit. Names in CAPITALS are settings.
project = QgsProject.instance()                     # the project that is open in QGIS
PROJECT_FOLDER = Path(project.homePath())           # the folder that holds the .qgz file
TEMPLATE = PROJECT_FOLDER / "templates" / "corporation_map_template.qpt"   # the saved page design
OUTPUT = PROJECT_FOLDER / "output"                  # where the finished maps are saved

# Layer names: they must match the names in the QGIS Layers panel exactly
REGIONS_LAYER = "Parks and lakes, share of area (%)"   # one feature per map
FOCUS_LAYER = "Selected corporation"                   # draws the dark outline
ROADS_LAYER = "Major roads"
LOCATOR_LAYER = "Karnataka"

# Field names: columns in the regions layer's attribute table
NAME_FIELD = "short"                                   # used for file names and the outline
TITLE_FIELD = "title"
SUBTITLE_FIELD = "subtitle"

# Every item the template must contain: item ID -> what kind of item it must be.
# The script stops early, with a clear message, if one is missing.
REQUIRED_ITEMS = {
    "main_map": QgsLayoutItemMap,
    "map_title": QgsLayoutItemLabel,
    "map_subtitle": QgsLayoutItemLabel,
    "main_legend": QgsLayoutItemLegend,
    "main_scale_bar": QgsLayoutItemScaleBar,
    "map_credits": QgsLayoutItemLabel,
    "locator_map": QgsLayoutItemMap,
}

PADDING = 1.25        # 1.25 leaves 25 percent empty space around each area
PNG_DPI = 150         # picture sharpness of the PNG files

# Helper 1: look a layer up by its name
def find_layer(name):

# Helper 2: make a name safe to use as a file name
def safe_filename(text):

# Helper 3: build a fresh page from the template
def load_layout():

# Helper 4: find every item the template must have, by its ID
def get_items(layout):

# Helper 5: choose which layers each map frame draws
def set_layers(items):

# Helper 6: save the page as a PDF and a PNG, and check both files
def export_files(layout, base_name):

# Step 1: the regions layer must exist and have the three fields we read
regions = find_layer(REGIONS_LAYER)
for field in (NAME_FIELD, TITLE_FIELD, SUBTITLE_FIELD):
    if regions.fields().indexFromName(field) == -1:       # -1 means "no such field"
        raise ValueError(f"The regions layer has no field called {field!r}")

# Step 2: the template must load and contain every required item
get_items(load_layout())            # stops with a clear message if the template is wrong

# Step 3: make the output folder, and say how many maps are coming
OUTPUT.mkdir(exist_ok=True)
print(f"Checks passed. {regions.featureCount()} maps will be made in {OUTPUT}")

report = []                                                # one line per output, saved at the end

# The loop below runs once for each corporation, in alphabetical order (sorted by the short name)
for feature in sorted(regions.getFeatures(), key=lambda f: f[NAME_FIELD]):
    name = feature[NAME_FIELD]                             # for example "East"
    started = time.time()                                  # note the time, to report how long it took

    # Step 1: a fresh page from the template, with its items and layers ready
    layout = load_layout()
    items = get_items(layout)
    set_layers(items)

    # Step 2: the text for this map. Plain text replaces the Atlas expression stored in the template.
    items["map_title"].setText(feature[TITLE_FIELD])
    items["map_subtitle"].setText(feature[SUBTITLE_FIELD])

    # Step 3: draw the dark outline around this corporation only
    QgsExpressionContextUtils.setProjectVariable(project, "focus_name", name)

    # Step 4: zoom to this corporation with some space around it
    extent = feature.geometry().boundingBox()              # the rectangle that just fits this corporation
    extent.scale(PADDING)                                  # make it bigger by the padding
    items["main_map"].zoomToExtent(extent)
    items["main_map"].invalidateCache()                    # make sure the map redraws

    # Step 5: save the PDF and PNG, and note whether it worked
    problems = export_files(layout, safe_filename(name))
    report.append({
        "map": name,
        "status": "ok" if not problems else "; ".join(problems),
        "seconds": round(time.time() - started, 1),
    })
    print(f"{name}: {report[-1]['status']}")

# Atlas makes one page for each feature of a layer, all in one file.

# Step 1: a fresh page, as before. An empty focus_name stops the loop's outline from carrying over.
layout = load_layout()
items = get_items(layout)
set_layers(items)
QgsExpressionContextUtils.setProjectVariable(project, "focus_name", "")

# Step 2: switch the Atlas on and tell it which layer to step through, in what order
atlas = layout.atlas()
atlas.setCoverageLayer(regions)                      # one page per feature of this layer
atlas.setSortFeatures(True)
atlas.setSortExpression(f'"{NAME_FIELD}"')           # alphabetical order, by the short name
atlas.setEnabled(True)

# Step 3: make the map frame follow the Atlas, so each page zooms to its own corporation
items["main_map"].setAtlasDriven(True)
items["main_map"].setAtlasScalingMode(QgsLayoutItemMap.Auto)   # choose the scale automatically
items["main_map"].setAtlasMargin(0.15)                         # 15 percent empty space around each area

# Step 4: write all the pages into one PDF, then check the file is there and not empty
combined_path = OUTPUT / "bengaluru_city_corporations_series.pdf"
result, error = QgsLayoutExporter.exportToPdf(atlas, str(combined_path), QgsLayoutExporter.PdfExportSettings())
combined_ok = result == QgsLayoutExporter.Success and combined_path.exists() and combined_path.stat().st_size > 0

# Step 5: add this PDF to the report, and print the result
report.append({
    "map": "combined series (Atlas)",
    "status": "ok" if combined_ok else f"failed: {error}",
    "seconds": 0,
})
print("Combined PDF:", "ok" if combined_ok else f"failed ({error})")

# Step 1: save the report as a CSV file (a table you can open in Excel)
with open(OUTPUT / "export_report.csv", "w", newline="", encoding="utf-8") as file:
    writer = csv.DictWriter(file, fieldnames=["map", "status", "seconds"])
    writer.writeheader()                             # the column names
    writer.writerows(report)                         # one row per output

# Step 2: print a summary, and point to anything that failed
failed = [row for row in report if row["status"] != "ok"]
print(f"Done. {len(report) - len(failed)} of {len(report)} outputs succeeded.")
if failed:
    print("Look at these first:", [row["map"] for row in failed])
else:
    print("Now open the PDFs and go through the quality checklist.")

Checks passed. 5 maps will be made in ...\output
Central: ok
East: ok
North: ok
South: ok
West: ok
Combined PDF: ok
Done. 6 of 6 outputs succeeded.
Now open the PDFs and go through the quality checklist.