Skip to content

feat(render): a layout's PDF is a GeoPDF: its map frames georeferenced (#1191) - #1585

Merged
giswqs merged 21 commits into
opengeos:mainfrom
elpidioassinaturas:feat/1191-geopdf
Nov 9, 2026
Merged

giswqs merged 21 commits into
opengeos:mainfrom
elpidioassinaturas:feat/1191-geopdf

Conversation

@elpidioassinaturas

@elpidioassinaturas elpidioassinaturas commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #1191. A layout's PDF (#1359's vector writer) becomes a GeoPDF: each map frame is georeferenced as an ISO 32000 geospatial viewport, the encoding GDAL's PDF driver, QGIS, Acrobat and Avenza read. A reader then shows coordinates and measures in the frame, and GDAL or QGIS open the page as a georeferenced raster in the map's own coordinate system.

Coordinates only: this adds no layers and no feature attributes (not the layered kind of GeoPDF).

On each page with map frames, the page dictionary gets a /VP array of viewports, one per georeferenced frame, or several where other frames are drawn over it (below):

<< /Type /Viewport /BBox [x1 y1 x2 y2] /Name (Main map)
   /Measure << /Type /Measure /Subtype /GEO /Bounds [0 0 0 1 1 1 1 0]
     /GPTS [lat lon …4 corners] /LPTS [0 1 1 1 1 0 0 0]
     /GCS << /Type /PROJCS /WKT (PROJCS[…]) /EPSG 31983 >> /PDU [/M /SQM /DEG] >> >>

Changes

  • rustgis-render, pdf.rs: Viewport (always with a /GEO measure), Page::with_viewports, and the /VP entry. A document with georeferenced frames is PDF 1.7 with Adobe's extension level 3 (/Extensions in the catalog), where viewports are defined (now in ISO 32000-2). A document without them is written exactly as before (1.4). The WKT is a PDF literal of any length (literal), since text_string cuts at 200 characters.

  • rustgis-render, layout.rs: frame_viewports works out each frame's corners with the frame's own camera (frame_camera, as drawing does) and the map's coordinate system:

    • an EPSG code: to_wkt(Crs::Epsg), with /EPSG;
    • Web Mercator: EPSG 3857;
    • a preset or local:: the WKT of its PROJ definition, with no code.

    A frame drawn over another, georeferenced or not, is cut out of the other's viewport (uncovered): the other becomes up to four rectangles around it, each with its own corners on the same projection, so no two viewports overlap. A frame left out has no viewport.

  • rustgis-data: proj4_to_wkt (the body of to_wkt, split so a PROJ definition with no EPSG code can be written), and lonlat_on_datum_of. wkt.rs also writes Natural Earth, Winkel Tripel and Eckert IV (Natural_Earth, Winkel_Tripel, Eckert_IV), which proj4rs doesn't define. That changes to_wkt for them too: the Shapefile .prj, GeoPackage and FlatGeobuf writers and the ESRI codes 54012 and 54077 now write those systems where they wrote none (and said so). A reader takes the corners (/GPTS) on the WKT's own geographic system. Without this step, a system with a datum shift from WGS 84 (SAD69, Córrego Alegre…) would be placed tens of metres off.

  • rustgis-engine, layout_bytes: every PDF page, vector or pictured, carries its frames' viewports, a map series page with that page's view. What can't be georeferenced is said in one Info notice with a count, each frame (by its id, so two frames sharing a name are two) with its reason; the frames georeferenced only by their corners in another. layout.export takes "georeference" (default true); false writes no viewports.

  • rustgis-ui-egui: a Georeference PDF toggle in the Publish tab's Export group (below).

  • docs/user-guide/layouts.md, data-formats.md.

Choices and known limits

  • On by default, and can be turned off ("georeference": false, or the toggle), for a map whose places shouldn't travel with it.
  • Left out, and said ("The PDF doesn't georeference 2 map frames (Main: it is tilted, …)"): a tilted frame (perspective, no flat map to measure on), a frame on the globe, a frame whose map is on another body than the Earth (writing a planetary system into the viewport is left for later), a frame whose map is missing, a frame with a corner off the Earth, a frame across its projection's edge (Web Mercator's world repeated across 180°, which a reader would wrap to the other side), a frame whose corners can't be moved onto its datum, and a frame cut into more than 64 rectangles by the frames over it. The notice is Info: nothing wrong is written.
  • No WKT form (a system with a grid shift): the frame is georeferenced in longitude/latitude (GEOGCS, EPSG 4326) by its corners only when that puts every point of a 9 × 9 grid over it, its edges included, within 0.5 mm on paper of where the frame draws it (measured against the real projection); a place between its corners off the map leaves it out with its own reason; otherwise it is left out. Across 180° the corners are kept within half a turn of each other.
  • Frames over frames, and Acrobat. By ISO 32000-1 12.9.2 a reader takes the last viewport holding a point, so a measureless viewport over the main map would hide its coordinates. Acrobat Reader doesn't follow that: a viewport with no /Measure makes it show no coordinates anywhere on the page, and one with a rectilinear (/RL) measure crashes it (26.3, access violation) when the Geospatial Location pointer enters it. Hence the cut-out viewports, which rely on no reader's choice between overlapping ones. GDAL reads the page by its largest viewport.
  • The box is where the page draws the frame: a pictured page rounds a frame's left and top to whole pixels and stretches its pixels over the paper, so at 72 dpi a frame at 10 mm is at 9.88 mm, and its viewport too.
  • Work per page: each frame's WKT and PROJ systems are built again on every page of a map series. Not measured; cheap next to drawing the page.
  • Shaped frames (circle, ellipse, polygon) are georeferenced by their rectangle, the box their map is drawn in, when no frame is under them. One drawn over another frame is left out and said, as its box would give its places where the page shows the other's map; it still cuts the frame under it, which has no coordinates in its box.
  • Only layouts. Print Map (share.rs), reports and presentations still write plain PDFs. They could follow with the same with_viewports if wanted.
  • No OGC "best practice" (/LGIDict) encoding. GDAL reads both; Acrobat and Avenza read ISO 32000.

Ribbon

  • Task: say whether a layout's PDF carries its map frames' coordinates. It sits in the Publish tab's Export group, beside Export and Print, which it applies to: the tab where a layout is exported and printed.
  • Kind: a small toggle, like Snap and Rulers in the same tab. It runs nothing itself: it sets what the next PDF export or print writes. It is on by default and kept for the session. It is no split button.
  • At 1366 px the Publish tab is wider than the window, as it was before this PR, so the screenshot shows it scrolled to the Export group with the ribbon's arrow:

Tests

  • a_map_series_pdf_georeferences_each_page_with_its_view (engine): every page of a series over the lakes has a viewport, and no two have the same corners.
  • a_frame_drawn_over_another_leaves_the_rest_of_it (render): a rectangle without another, beside, over a corner, past it, covered, and a strip under 0.01 mm dropped.
  • a_frame_drawn_over_another_is_cut_out_of_its_viewport (engine): a tilted inset over a UTM frame leaves four viewports around it, none over the inset, their area the frame's less the inset's, meeting at the same places; a georeferenced inset adds its own, last.
  • world_projections_proj4rs_lacks_are_written (data): Natural Earth, Winkel Tripel and Eckert IV as WKT.
  • a_georeferenced_frame_is_a_viewport_on_its_page (render): the box from the page's bottom, corners as latitude then longitude, a 400+ character WKT whole with its \, ( and ) escaped, /VP only on the page that has it, 1.7 and /Extensions only when there is one, a plain document unchanged.
  • a_layout_pdf_georeferences_its_map_frames (engine): a frame in SIRGAS 2000 / UTM 23S (EPSG:31983) exported. Its four corners, taken back to the map, make the frame's rectangle (top and bottom level, sides upright within 1 cm) as wide as the frame at its scale. Tilted, it is left out and said; in Winkel Tripel, written as WKT; in ESRI:102498 (no WKT), georeferenced by its corners at 1:50,000 and left out at 1:10,000,000, where its corners would put places more than 0.5 mm off; with "georeference": false, no viewports; in SAD69 / UTM 23S (EPSG:29193, +towgs84), its first corner 10 to 200 m from WGS 84's; in Web Mercator centred on 180°, and on Mars, left out and said.
  • a_pdf_says_which_frames_it_doesnt_georeference (engine): one Info notice with a count; two frames named alike are both said.
  • a_viewport_is_where_the_page_draws_its_frame (render): at 72 dpi the box is the drawn one (9.88 mm for 10 mm), at 254 dpi the frame's own.
  • a_point_moves_onto_a_shifted_datum_and_not_onto_an_unshifted_one (data): SAD69 moves a point, SIRGAS 2000 doesn't.

Read with GDAL 3.7 (QGIS 3.32.1's gdalinfo), each frame centred on 45° W, 20° S. Every one opened as "PDF/Geospatial PDF", its neatline a rectangle:

Map projection GDAL's coordinate system Neatline
EPSG:31983 SIRGAS 2000 / UTM zone 23S (EPSG 31983) x 300561.67 to 699438.33, centred on 500000 (the zone's meridian)
Web Mercator WGS 84 / Pseudo-Mercator rectangle
Mollweide (preset, no code) Mollweide, from proj4_to_wkt rectangle
local:-45,-20 Azimuthal Equidistant symmetric about the centre

Run on Windows at ab22ca54 (main 040b48df merged in):

  • cargo fmt --check and clippy -D warnings (data, render, engine) pass.
  • Libraries: rustgis-data lib 760 passed, rustgis-render lib 372 passed, rustgis-engine lib 1055 passed and 1 failed: export_map_to_geotiff_draws_tile_layers_and_keeps_their_credits (from feat(share): Export Map writes the view as a GeoTIFF placed on the ground #1566), which deletes an MBTiles file still open, and Windows refuses (os error 32). It doesn't reach this PR's code.

Acrobat Reader 26.3.22075 (Measure › Geospatial Location), on a PDF exported by this branch: a UTM 23S frame at 1:4,000,000 with a tilted inset over its top-left. Near the top-left corner it reads -16.9793, -48.6961 (corner -16.8567, -48.7423, the pointer a few mm inside); near the bottom-right -22.6488, -41.3457 (corner -23.0600, -41.1082); left of, right of and below the inset -19.0266, -48.5878, -18.1308, -45.1596 and -20.4570, -47.3629; inside the inset nothing, and no crash. GDAL 3.7 still opens it as "PDF/Geospatial PDF" in EPSG 31983.

Not run: Avenza (no device), Linux and macOS, and a map series export through GDAL.

🤖 Generated with Claude Code

Summary by CodeRabbit

Summary

  • New Features
    • PDF layout exports can include geographic information for map frames, including coordinate systems and geographic bounds when available.
    • Export notices identify frames georeferenced from their corners and frames that could not be georeferenced.
    • The Georeference PDF option lets you omit geographic information from PDF exports and is enabled by default.
    • PDFs with geographic information use GeoPDF support; other PDFs retain their existing format.
  • Documentation
    • Updated PDF export guidance to describe GeoPDF support, the option, and its limitations.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Export in GEOPDF

4 participants