Print Layouts

This page is generated from the repository on every merge to main; changes made here are overwritten.

create_print_layout

Create a map print layout composition with title, legend, scalebar, north arrow, and an optional summary text panel -- then optionally export it. Exports at output_path if given: '.pdf' for a vector PDF, '.png'/'.jpg'/'.jpeg' for a raster image at the given dpi (default 300, print quality). ALWAYS use this instead of hand-writing QgsPrintLayout/QgsLayoutItemMap/QgsLayoutExporter code via execute_pyqgis_script, even for a richer composition than this tool's parameters look like they cover -- body_text accepts multi-line text (use \n between bullets/findings for a summary panel), and the legend/scale bar/north arrow are already included, so accepting this tool's defaults for those is strongly preferred over reimplementing the object-graph by hand. Hand-written layout code has repeatedly produced silently broken exports in live testing (a blank map area with no visible error, and real PyQGIS/Qt API mistakes, e.g. QFont.Italic and QgsLegendStyle.Item are not real attributes) that this tool doesn't have. The map area captures whatever extent is currently on screen -- pass zoom_to_layer to fit a specific layer's full extent first (e.g. the national boundary layer for a country-wide sitrep map); otherwise a stale or zoomed-in canvas view produces a cropped map missing large parts of the area of interest. title and body_text must only describe real, verified findings -- never invent incidents, casualties, threat assessments, severity ratings, or other real-world claims to make a report look complete. If you don't have verified data for what's being asked, say so in your chat response instead of writing placeholder or invented content into this layout -- a printed/exported layout reads as an authoritative finished document, not a draft, so anything fabricated here is far more likely to be trusted and acted on than the same claim in chat. Every export from this tool carries a standing disclaimer footer for exactly this reason, but that does not excuse writing fabricated content in the first place. Also includes a coordinate graticule, a CRS/datum + representative-fraction scale label ('1:N', alongside the graphical scale bar), and -- when include_inset_map is true -- a small locator/inset map showing where the main map sits within a wider surrounding area.

Parameter	Type	Required	Description
title	string	yes
page_orientation	string	no	'Landscape' (default) or 'Portrait'.
output_path	string	no	Where to export -- '.pdf' for a vector PDF, '.png'/'.jpg'/'.jpeg' for a raster image. Omit to create the layout in the project without exporting.
dpi	integer	no	Export resolution in DPI, for both PDF and image export. Defaults to 300 (print quality).
profile	string	no	Name of a saved map profile (a JSON file the organisation keeps in the project's cartogen_profiles folder or the QGIS profile folder) that sets page size, orientation, export preset, file name pattern and required elements. Explicit arguments beat the profile.
page_size	string	no	Page size: 'A4' (default), 'A3', 'A2' or 'A1'. The same layout is scaled up, and the map shows the same area larger.
preset	string	no	Export purpose instead of a dpi number: 'draft' (96), 'web' (150) or 'print' (300). An explicit dpi wins.
output_format	string	no	Only when output_path is a FOLDER: 'pdf' (default), 'png' or 'jpg'. The file is then named <title>_..
body_text	string	no	Optional summary/sitrep text shown in a panel on the layout (e.g. priority findings, data sources).
zoom_to_layer	string	no	Name of a layer to fit the map to its full extent before capturing it, e.g. the national boundary layer for a full-country sitrep map. Omit to use whatever extent the canvas currently shows.
template	string	no	'standard' (default), 'access_map', 'sitrep', 'field_report', 'change_report' or 'epi_bulletin'. 'access_map': for the result of a service-area / facility-access analysis. Fits the map to the reach layer when zoom_to_layer is omitted, lists the reach polygon, access points and cost-graded roads first in the legend, and (when body_text is empty) adds a short 'how to read this map' guide for the layers present. 'sitrep': a one-page situation report; body_text is the situation summary, key_figures and sources fill the KEY FIGURES and SOURCES sections, and a standing handling note (estimates, no exact locations of people or sensitive sites) and the preparation date are always added. 'field_report' (one field: body_text is the field summary, key_figures the index readings with their dates and units) and 'change_report' (two dates: key_figures the change figures such as hectares lost, gained and stable) use the same panel with a reading guide and a standing note of their own: index values are not a yield or rate recommendation; change classes are a screening, not a survey. They keep the map where it is unless zoom_to_layer is given. 'epi_bulletin' (an epidemic bulletin: body_text is the summary, key_figures the case and rate figures with the date they were reported to, sources the data sources) uses the same panel with a METHOD AND LIMITS note of its own: rates are crude and for areas not individuals, areas under 5 cases are not shown, a cluster is not a cause. It keeps the map where it is unless zoom_to_layer is given.
key_figures	array[object]	no	For template='sitrep': up to 8 headline figures, each copied from a tool result (never estimated or remembered), e.g. {label: 'People within 1 hour of a clinic', value: '412,000 (estimate)', source: 'population_access_gap'}.
key_figures_from	object	no	For template='sitrep': take the headline figures straight from a layer, e.g. {layer_name: 'admin_units', label_field: 'ADM2_EN', value_field: 'people_in_need', top_n: 3}. The numbers are read from the layer, so they cannot be mistyped; prefer this over typing figures. Any typed key_figures whose number is not found in a project layer (a value, or a total, minimum, maximum, mean or count of a numeric field) is marked 'not found in the project data' on the layout and listed in the reply.
sources	array[string]	no	For template 'sitrep', 'field_report', 'change_report' or 'epi_bulletin': the data sources behind the figures, e.g. ['OCHA COD-AB 2024', 'WorldPop 2020'].
include_inset_map	boolean	no	Add a small locator/inset map (zoomed out ~6x from the main map, same center) showing the main map's location within its wider region. Defaults to true.

export_layout_atlas

Exports one file PER FEATURE of a coverage layer from an existing print layout -- e.g. one PDF per district, one PNG per health facility catchment -- using QgsLayoutAtlas. This is the full-atlas half of point 15 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md; list_layout_items/update_layout_item_text (the other half) address items within ONE layout, this generates MANY layouts (one per feature). Only works on a layout built by create_print_layout, since it re-points that layout's MAP_MAIN item to follow the atlas -- there is no addressable map item on a hand-built layout to atlas-drive. Each output file is named from filename_field's value on that feature (e.g. a district-name field), sanitized for use as a filename; a non-unique or empty field value across features will silently overwrite an earlier output with the same name, so pick a field that's actually unique per feature (a P-code, not a display name that repeats). A map or coverage layer tagged RESTRICTED or SENSITIVE makes the export wait for the user's confirmation.

Parameter	Type	Required	Description
layout_name	string	yes	An existing layout built by create_print_layout.
coverage_layer_name	string	yes	The layer whose features drive one output page each, e.g. an admin-boundary layer.
output_directory	string	yes	Directory to write the per-feature files into. Created if it doesn't exist.
filename_field	string	yes	Field on coverage_layer_name whose value names each output file. Should be unique per feature.
output_format	string	no	'pdf' (default), 'png', 'jpg', or 'jpeg'.
dpi	integer	no	Export resolution in DPI. Defaults to 300 (print quality).

list_layout_items

Lists the addressable items in a print layout -- id, type, and current text (for text items) -- so the agent can check what's actually in a layout before editing it with update_layout_item_text, instead of guessing. create_print_layout gives every item it builds a stable id (MAP_MAIN, TITLE, LEGEND, SCALEBAR, NORTH_ARROW, BODY_TEXT, FOOTER -- NORTH_ARROW/BODY_TEXT only appear when that item was actually built). Point 15 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md (stable item addressability -- full QgsLayoutAtlas per-feature pagination is a separate capability, export_layout_atlas).

Parameter	Type	Required	Description
layout_name	string	yes

list_layouts

List the print layouts already in the current QGIS project by name -- lets the agent check what layouts exist (e.g. before deciding whether to build a new one with create_print_layout or address an existing one) instead of guessing layout names. Point 21 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md (a project inspector) -- covers layouts only; QGIS Map Themes are a separate concept, listed by list_map_themes instead (point 16 of the same review, project_tools.py).

No parameters.

update_layout_item_text

Updates the text of one existing item in a print layout (e.g. a stale title or summary panel) by its stable id -- without rebuilding the whole layout with create_print_layout. Use list_layout_items first to see what ids exist. Only works on text items (TITLE, BODY_TEXT, FOOTER); MAP_MAIN/LEGEND/SCALEBAR/NORTH_ARROW have no settable text. Point 15 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md.

Parameter	Type	Required	Description
layout_name	string	yes
item_id	string	yes	Stable id from list_layout_items, e.g. 'TITLE'.
text	string	yes