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 clipped against every nearer triangle and against each other, 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.

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.
• Implemented hidden-line removal (get_visible_intervals). Each stroke and each occluder outline hides the strokes behind it across its own width, so the nearer of two crossing strokes shows, matching VTK's depth test. Strokes that share an end are exempt, and triangles are looked up through a grid on screen so diagrams with tens of thousands of strokes stay fast.
• 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". Each label is drawn in its VTK background box, with math in STIX and other text in Liberation Mono.
• 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 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 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), stroke clipping and depth ties, line width scaling, and svg and pdf writing. 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 93.78698% with 42 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.24%. Comparing base (aa23f51) to head (b6e5715).

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #328      +/-   ##
==========================================
- Coverage   96.41%   96.24%   -0.17%     
==========================================
  Files          48       49       +1     
  Lines       10642    11281     +639     
==========================================
+ Hits        10260    10857     +597     
- Misses        382      424      +42     

☔ 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.