Save diagrams as svg and pdf files

[camUrban]

Description

This PR lets every diagram method save its diagram as an svg or pdf file, chosen by the path's suffix, alongside the existing WebP output. The scene is recorded in a new private module, _vector_export.py, as the rendering helpers draw it, then exported through a parallel camera that matches the window's final view. Visibility is resolved in software: opaque fills are split and ordered by a BSP painter, and strokes are cut wherever they pass through a fill or swap depth order with another stroke they overlap, and painted among the fills in depth order, each before the fills that hide it and after everything else it overlaps, with the dots painted among them the same way, so the file shows what the window showed. Labels are read from VTK after every render, so dragged and edited labels survive, and are written as selectable text with their fonts embedded. The diagram methods also gain figure_size_in, font_size, text_color, and line_width, which size a vector diagram for a paper the way plot_results_versus_time sizes its figures.

The export also keeps its files small: runs of fills and strokes that share a style are written as single compound paths, segments shared by neighboring polylines are drawn once, and an svg's path coordinates are rounded to hundredths of a point. Some programs that import an svg ignore its embedded fonts and draw its text in other fonts, which misplaces the parts of math labels, so the diagram methods also gain selectable_text. Setting it to False draws an svg's labels as glyph outlines, which look the same in every program but can't be selected or searched.

All new parameters default to the current behavior, so existing calls are unaffected, and the WebP output is unchanged. output.draw is deliberately out of scope here and will adopt the same module in a follow-up PR, so the module's translucent polygon and screen polygon support, which only draw needs, is currently unused.

Motivation

Diagrams are mainly useful as figures in papers, slides, and documentation, where a WebP screenshot blurs when scaled and its labels can't be selected or searched. VTK's own vector export (GL2PS) rasterizes 3D geometry with the OpenGL2 backend, so it can't produce true vector output of these scenes. Recording the scene and resolving visibility in software gives sharp output at any size whose labels stay text. The figure parameters exist because a vector diagram is otherwise sized by the window, so its fonts and lines have no predictable physical size on a printed page.

Relevant Issues

Part of #266.

Changes

• Added _vector_export.py with VectorCamera (a parallel camera that projects diagram axes to display coordinates, plus fit_to_page), VectorText, VectorLayer, and VectorScene. A layer records opaque quadrilaterals, polylines, convex occluders (the arrow tips), dots, and translucent polygons, and VectorScene.save writes the scene through Matplotlib with TrueType fonts in pdf files and embedded fonts in svg files.
• Implemented the BSP painter (get_paint_order), adapted from csg.js, which uses explicit stacks and samples candidate splitters, so it orders crossing fills exactly and can't hit the recursion limit.
• Resolved convex occluders in the fills' BSP. VectorLayer._get_fills_and_strokes turns each occluder's faces that face the camera into fill triangles, and its silhouette and outlined faces into strokes owned by those triangles, so occluders are ordered exactly against the other fills and against each other, however they interpenetrate. Occluders must now be closed, since their faces that face away are dropped.
• Painted the fills and strokes in one depth order (_order_items):
  • _cut_at_pierces cuts each stroke where its centerline passes through a fill it doesn't outline.
  • _get_overlap_gaps compares each stroke piece with each fill it overlaps on screen, averaged over the region where they overlap, so the piece is painted before the fills it is behind, which cover the part of its width they hide, and after the rest. Pieces of different strokes are ordered by their depths where they come closest (_get_stroke_constraints), and overlapping fills keep the BSP's order.
  • Pieces caught in a cycle of constraints are split for up to _SPLIT_ROUNDS rounds, and _break_cycles breaks any cycle that survives, within each strongly connected component, by dropping the lightest constraint of each cycle in turn (_get_greedy_drops).
  • _cut_at_depth_swaps also cuts two strokes that overlap on screen wherever they swap which of them is nearer, except strokes that share an end, so strokes lying along each other on screen are each painted over the other only where they are nearer. Pairs of pieces are compared by their depth difference averaged over the stretch where they overlap (_get_average_gaps), rather than where they come closest.
• Painted the dots among the fills and strokes in depth order, rather than over everything in a pass of their own. Each dot is ordered as a stroke of zero length as wide as the dot and drawn as a filled circle, so a dot hidden in the window behind a panel, an arrow tip, or a nearer line is hidden in the file too. Each layer now draws in two passes.
• Removed the seams between abutting fills. _merge_abutting_fills paints abutting fills of one color together, as one compound path, wherever that keeps the order possible, and _get_underlaps reaches each fill under the abutting fills painted after it, with a strip of its color along their shared edge. Fills with almost no area on screen, such as faces seen edge on, are dropped.
• Kept the ordering fast enough for large diagrams: every overlap test is narrowed by a grid on screen (_get_overlapping_boxes), the overlap-region test and the grid lookup are compiled with Numba, the fills' constraints are found once and each piece's are cached until it is split, and each search for a cycle skips the items an earlier search finished.
• Reduced the size of the exported files:
  • VectorLayer.draw writes each run of consecutive opaque fills of the same color, and of consecutive opaque strokes of the same color and width, as one compound path in a PathCollection, rather than one svg element per piece. Each fill piece is wound counterclockwise so the nonzero fill rule never cancels overlapping pieces, translucent strokes stay separate, and Matplotlib's path simplification is turned off for the strokes so no segment is dropped.
  • VectorLayer.add_polylines skips a segment that repeats one it already added in the same color and width, such as an edge shared by neighboring panels or ring vortices.
  • VectorScene.save rounds the coordinates in an svg's path data to _SVG_DECIMAL_PLACES (2) decimal places with _round_svg_path_data, since Matplotlib always writes six.
• Moved SVG font embedding from _output_plotting.py to _fonts.py as embed_fonts_in_svg, which avoids an import cycle. It now embeds every face the text uses, including the STIX faces Matplotlib writes math in, each subset to its glyphs. plot_results_versus_time uses the moved function.
• Threaded an optional layer parameter through add_axes_and_points, _add_arrow_tips, add_airfoil, add_airfoil_lines, add_airfoils, add_panels, add_vortices, and add_steady_problem in _output_rendering.py. Each helper records what it draws as it adds the PyVista actors, and each collocation point's cross is recorded as four half arms so its strokes don't clip each other.
• Updated show_diagram to read the camera, window size, and labels after every render (_get_diagram_export_state) and to export from the last reading when the path ends with ".svg" or ".pdf", in any case. Each label is drawn in its VTK background box, with math in STIX and other text in Liberation Mono. VectorScene.save also checks the suffix without regard to case.
• Widened path on Airfoil.diagram, WingCrossSection.diagram, Wing.diagram, Airplane.diagram, SteadyProblem.diagram, the unsteady problems' diagram, and the three solvers' diagram methods to accept ".svg" and ".pdf".
• Added figure_size_in, font_size, text_color, and line_width to the same methods, validated by _output_rendering.validate_diagram_figure_parameters:
  • figure_size_in opens the window at the page's aspect ratio, at least 1 pixel on each side, and scales the view to fill the page, while text and line widths stay in points.
  • font_size sets every label's size, including math labels.
  • text_color colors the labels.
  • line_width sets the width of the panel edges, airfoil lines, and vortices, and scales the other lines with it.
  • None of them affect the window or WebP output.
• Added selectable_text (default True) to the same methods, passed through show_diagram to VectorScene.save. When it is False, an svg is written with svg.fonttype set to "path" and without embedded fonts, so every label, math included, is drawn as glyph outlines. It has no effect on pdf or WebP output.
• Added "fontTools" to autodoc_mock_imports in docs/website/conf.py, so the website build doesn't need it installed.
• Added tests/unit/test_vector_export.py and its fixtures, covering projection, page fitting, paint order (including a test that samples inside every fragment's footprint), the painting of strokes behind, in front of, and through fills and occluders, the depth order of crossing and coincident strokes, the cut where two strokes swap depth order, the painting of dots in depth order, the culling of occluders' faces that face away, line width scaling, the drawing of shared polyline edges once, and svg and pdf writing, including an svg whose text is drawn as outlines. Added tests/unit/test_fonts.py for the moved font embedding, and extended tests/unit/test_output_rendering.py for layer recording, export state reading, page fitting, label sizing and coloring, and parameter validation.
• Added _vector_export.py to the architecture list in CLAUDE.md, and updated the _fonts.py entry.

Dependency Updates

None.

Change Magnitude

Moderate: Medium-sized change that adds or modifies a feature without large-scale impact.

Checklist (check each item when completed or not applicable)

• I am familiar with the current contribution guidelines.
• PR description links all relevant issues and follows this template.
• My branch is based on main and is up to date with the upstream main branch.
• All calculations use S.I. units.
• Code is formatted with black (line length = 88).
• Code is well documented with block comments where appropriate.
• Any external code, algorithms, or equations used have been cited in comments or docstrings.
• All new modules, classes, functions, and methods have docstrings in reStructuredText format, and are formatted using docformatter (--in-place --black). See the style guide for type hints and docstrings for more details.
• All new classes, functions, and methods in the pterasoftware package use type hints. See the style guide for type hints and docstrings for more details.
• If any major functionality was added or significantly changed, I have added or updated tests in the tests package.
• Code locally passes all tests in the tests package.
• This PR passes the ReadTheDocs build check (this runs automatically with the other workflows).
• This PR passes the ascii-only, pre-commit-hooks, and zizmor GitHub actions.
• This PR passes the lint job of the CI GitHub action.
• This PR passes the test jobs of the CI GitHub action.

Assisted-by: Claude Opus 5.5

[Copilot]

Copilot review overview

🟡 Changes recommended

Format dispatch, overlapping-occluder visibility, and unconditional scene-recording issues remain unresolved.

Review effort: Balanced
Findings: 2 · 2

Open (4)

• Normalize suffix before output format dispatch · New
• Normalize suffix before selecting SVG writer · New
• Avoid mandatory scene construction for non-vector output · New
• Resolve overlapping occluders by surface depth · New

What changed in this PR

Adds SVG/PDF diagram export with selectable embedded-font text, configurable figure styling, and software-resolved visibility, advancing issue #266.

Changes:

• Records rendered diagram geometry into vector scenes with BSP and hidden-line processing.
• Extends all diagram APIs with vector formats and figure styling parameters.
• Moves SVG font embedding into _fonts.py and adds focused tests.

File	Description
CLAUDE.md	Documents vector export architecture.
pterasoftware/​_core.py	Forwards new diagram options.
pterasoftware/​_fonts.py	Embeds all used SVG font faces.
pterasoftware/​_output_plotting.py	Uses shared font embedding.
pterasoftware/​_output_rendering.py	Records scenes and dispatches exports.
pterasoftware/​_vector_export.py	Implements vector projection and visibility.
pterasoftware/​geometry/​airfoil.py	Adds vector airfoil diagrams.
pterasoftware/​geometry/​airplane.py	Adds vector airplane diagrams.
pterasoftware/​geometry/​wing.py	Adds vector wing diagrams.
pterasoftware/​geometry/​wing_cross_section.py	Adds vector cross-section diagrams.
pterasoftware/​problems.py	Adds vector problem diagrams.
pterasoftware/​steady_horseshoe_vortex_lattice_method.py	Exports horseshoe-solver diagrams.
pterasoftware/​steady_ring_vortex_lattice_method.py	Exports ring-solver diagrams.
pterasoftware/​unsteady_ring_vortex_lattice_method.py	Exports unsteady-solver diagrams.
tests/​unit/​fixtures/​fonts_fixtures.py	Adds SVG font fixtures.
tests/​unit/​fixtures/​output_plotting_fixtures.py	Removes relocated SVG fixture.
tests/​unit/​fixtures/​vector_export_fixtures.py	Adds vector geometry fixtures.
tests/​unit/​test_fonts.py	Tests multi-face font embedding.
tests/​unit/​test_output_plotting.py	Removes relocated embedding tests.
tests/​unit/​test_output_rendering.py	Tests recording and export state.
tests/​unit/​test_vector_export.py	Tests vector algorithms and output.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 90.14085% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.26%. Comparing base (0a9c36f) to head (e6544f2).

Files with missing lines	Patch %	Lines
pterasoftware/_output_rendering.py	80.37%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #328      +/-   ##
==========================================
- Coverage   96.41%   95.26%   -1.15%     
==========================================
  Files          48       49       +1     
  Lines       10642    12040    +1398     
==========================================
+ Hits        10260    11470    +1210     
- Misses        382      570     +188     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟡 Changes recommended

Vector output has unresolved depth-ordering mismatches and an invalid zero-sized viewport edge case.

3 open findings

• Split stroke overlaps where depth ordering reverses · New
• Prevent zero-sized windows for extreme aspect ratios · New
• Depth-test dots instead of always painting them last · New

4 resolved since last review

• Normalize suffix before selecting SVG writer
• Normalize suffix before output format dispatch
• Resolve overlapping occluders by surface depth
• Avoid mandatory scene construction for non-vector output

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[Copilot]

🟡 Changes recommended

Fixed-interval sampling can miss narrow stroke depth swaps, and the public vector-export path lacks integration coverage.

2 open findings

• Fixed sampling misses narrow stroke overlaps · New
• Add public SVG/PDF diagram save integration coverage · New

3 resolved since last review

• Split stroke overlaps where depth ordering reverses
• Depth-test dots instead of always painting them last
• Prevent zero-sized windows for extreme aspect ratios

🧠 Review effort: Balanced

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[camUrban]

Closing this without merging. After working through it, the feature doesn't justify what it would add to the codebase.

Producing true vector output means resolving visibility in software, since VTK's own vector export rasterizes 3D geometry. Getting that close to what the window shows took a BSP painter for the fills, a depth ordering of every stroke and dot among them, cuts where strokes pass through fills or swap depth with each other, and cycle breaking for orderings that can't be satisfied. That brought the change to roughly 6,000 lines, most of it intricate geometry that would need ongoing maintenance.

Even then, it remains a tradeoff between accuracy, robustness, and speed rather than a solved problem. Each accuracy fix uncovered new edge cases, and the more exact methods made exports of large unsteady solver diagrams slow enough to be impractical. That's a hard balance to keep stable given this project's focus is the solvers, not the rendering, so the raster output will stay the supported diagram format for now.