openscad-cpp-evaluator 1.10.0__tar.gz → 1.11.0__tar.gz

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/CLAUDE.md

@@ -916,8 +916,8 @@ grep for `ponytail:`.
   — skip it and the mesh comes out non-manifold at the seam). Self-contained 2D geometry math here
   (`dot2`/`len2`/`norm2`, the parabola-canonical-frame rotation in `discretizeArc`) exists nowhere
   else in this codebase.
-- `include/openscad_cpp_evaluator/export.hpp`, `src/export.cpp` — the writers for all nine
-  formats `exportExtensions()` lists: 3MF, AMF, STL, OBJ, OFF, PLY, SVG, VRML, X3D (3MF via
+- `include/openscad_cpp_evaluator/export.hpp`, `src/export.cpp` — the writers for all ten
+  formats `exportExtensions()` lists: 3MF, AMF, PDF, STL, OBJ, OFF, PLY, SVG, VRML, X3D (3MF via
   `zip_stored.hpp`'s `writeDeflateZip`). **`exportExtensions()` is the one source of truth for
   which formats exist** — the Python facade and BelfrySCAD's dialog/CLI all ask it rather than
   restating the list, because three hand-written copies had already drifted far enough that `.off`
@@ -937,6 +937,22 @@ grep for `ponytail:`.
   binary's, vertex order and 6-vertex line wrap included. A 3D body in the list throws
   ("Current top level object is not a 2D object"), as OpenSCAD refuses too: there is no projection
   to fall back on. `ExportOptions::svg` carries OpenSCAD's five `-O export-svg/...` settings.
+  **`writePdf` is the other 2D writer**, and shares `collect2d()` with `writeSvg` so the all-2D
+  rule and its refusal have one implementation. Everything else differs from SVG: the drawing is
+  **centred on a fixed paper size** rather than the page being cut to fit, and **PDF user space is
+  Y-up like the model's, so there is NO Y negation** — `pt = mm * 72/25.4` plus a centring offset,
+  symmetric in both axes. (OpenSCAD's own file negates Y only because Cairo draws Y-down and then
+  flips the whole page; its centring is also a fraction of a point off, because it truncates the
+  span to an `int` — a bug, not a spec, so ours centres exactly.) With `showScale` it draws
+  OpenSCAD's ruler: two axes at a 30pt margin, ticks every **10mm of model space** (hard-coded —
+  `gridSize` drives only the optional grid), labels on every second tick, and the caption telling
+  you what to measure. That ruler is the point of the format: it is what lets a printed page reveal
+  a printer's scaling error. Text is the **base-14 `/Helvetica`** every reader supplies, so nothing
+  is embedded and no font metrics are needed — Cairo's subset-embedded font is a Cairo habit, not a
+  PDF requirement, and skipping it is what turned this from a project into a writer. The content
+  stream is Flate-compressed through `zip_stored.hpp`'s `zlibCompress` (PDF's `/FlateDecode` *is* a
+  zlib stream), falling back to raw when that would not shrink it. `writePdf` returns warnings
+  rather than `void`: a model too big for the page is drawn anyway and said so.
   `colored_body.hpp`/`.cpp`'s `toRenderableBodies()` (thin-extrudes any top-level 2D-only result to
   a 1-unit-tall `flatPreview` Manifold) must run on a body list before handing it to any of the
   MESH writers — none of them look at `ColoredBody::section` at all, only `.body`. Not before

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 1.10.0
+Version: 1.11.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/bindings/module.cpp

@@ -356,13 +356,56 @@ struct Geometry {
 
 // exportModel, with the path/format/warnings marshalling. Releases the GIL:
 // a large export is seconds of Manifold work with no Python involved.
+// The PDF option set is big enough (paper size, orientation, four
+// ruler switches, fill/stroke, four metadata fields) that a dict keyed the
+// way OpenSCAD names its own `-O export-pdf/...` settings is kinder than
+// fourteen keyword arguments. Unknown keys raise rather than being ignored
+// -- a silently dropped "paper-size" would print the wrong page size with
+// nothing to explain it.
+void applyPdfOptions(const nb::dict& d, oscadeval::ExportPdfOptions& pdf) {
+    for (auto item : d) {
+        const std::string key = nb::cast<std::string>(item.first);
+        const nb::handle v = item.second;
+        if (key == "paper-size") {
+            const std::string name = nb::cast<std::string>(v);
+            if (!oscadeval::paperFromName(name, pdf.paper))
+                throw std::runtime_error("unknown paper-size '" + name +
+                                          "' (a6, a5, a4, a3, letter, legal, tabloid)");
+        } else if (key == "orientation") {
+            const std::string name = nb::cast<std::string>(v);
+            if (!oscadeval::orientationFromName(name, pdf.orientation))
+                throw std::runtime_error("unknown orientation '" + name + "' (portrait, landscape, auto)");
+        } else if (key == "show-scale") pdf.showScale = nb::cast<bool>(v);
+        else if (key == "show-scale-message") pdf.showScaleMsg = nb::cast<bool>(v);
+        else if (key == "show-grid") pdf.showGrid = nb::cast<bool>(v);
+        else if (key == "grid-size") pdf.gridSize = nb::cast<double>(v);
+        else if (key == "show-filename") pdf.showFilename = nb::cast<bool>(v);
+        else if (key == "design-filename") pdf.designFilename = nb::cast<std::string>(v);
+        else if (key == "fill") pdf.fill = nb::cast<bool>(v);
+        else if (key == "fill-color") pdf.fillColor = nb::cast<std::string>(v);
+        else if (key == "stroke") pdf.stroke = nb::cast<bool>(v);
+        else if (key == "stroke-color") pdf.strokeColor = nb::cast<std::string>(v);
+        else if (key == "stroke-width") pdf.strokeWidth = nb::cast<double>(v);
+        else if (key == "add-meta-data") pdf.addMetaData = nb::cast<bool>(v);
+        else if (key == "title") pdf.metaTitle = nb::cast<std::string>(v);
+        else if (key == "author") pdf.metaAuthor = nb::cast<std::string>(v);
+        else if (key == "subject") pdf.metaSubject = nb::cast<std::string>(v);
+        else if (key == "keywords") pdf.metaKeywords = nb::cast<std::string>(v);
+        else throw std::runtime_error("unknown pdf option '" + key + "'");
+    }
+}
+
 nb::list exportModelPy(const std::string& path, const Geometry& geom, const std::string& format, bool asciiStl,
                         bool stripSlivers, bool splitComponents, bool svgFill, const std::string& svgFillColor,
-                        bool svgStroke, const std::string& svgStrokeColor, double svgStrokeWidth) {
+                        bool svgStroke, const std::string& svgStrokeColor, double svgStrokeWidth,
+                        nb::object pdfOptions) {
+    oscadeval::ExportPdfOptions pdf;
+    if (!pdfOptions.is_none()) applyPdfOptions(nb::cast<nb::dict>(pdfOptions), pdf);
     std::vector<std::string> warnings;
     {
         nb::gil_scoped_release rel;
         oscadeval::ExportOptions opts;
+        opts.pdf = pdf;
         opts.format = format;
         opts.asciiStl = asciiStl;
         opts.stripSlivers = stripSlivers;
@@ -802,6 +845,7 @@ NB_MODULE(_openscad_cpp_evaluator, m) {
           nb::arg("split_components") = false, nb::arg("svg_fill") = false,
           nb::arg("svg_fill_color") = std::string("white"), nb::arg("svg_stroke") = true,
           nb::arg("svg_stroke_color") = std::string("black"), nb::arg("svg_stroke_width") = 0.35,
+          nb::arg("pdf_options") = nb::none(),
           "Write `geometry` to `path`, format taken from the extension unless `format` says otherwise. "
           "Returns the warnings to surface (open shells, mesh problems, slivers removed) rather than "
           "logging them. Raises RuntimeError when there is no geometry, the format is unknown, or the "
@@ -811,7 +855,12 @@ NB_MODULE(_openscad_cpp_evaluator, m) {
           "per colour however many pieces it is in.\n\n"
           "The svg_* arguments are OpenSCAD's -O export-svg/... set and apply to .svg only. "
           "svg_stroke/svg_stroke_width also pad the page, so they are not purely cosmetic. An .svg "
-          "export needs an all-2D model and raises otherwise, as OpenSCAD does.");
+          "export needs an all-2D model and raises otherwise, as OpenSCAD does.\n\n"
+          "pdf_options is a dict keyed as OpenSCAD names its -O export-pdf/... settings "
+          "(paper-size, orientation, show-scale, show-scale-message, show-grid, grid-size, "
+          "show-filename, design-filename, fill, fill-color, stroke, stroke-color, stroke-width, "
+          "add-meta-data, title, author, subject, keywords). An unknown key raises rather than "
+          "being ignored. .pdf is 2D-only too, and centres the drawing on a fixed paper size.");
 
     m.def("export_extensions", []() { return oscadeval::exportExtensions(); },
           "The file extensions export_model understands, dot-prefixed. Read from the C++ writer table "

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/include/openscad_cpp_evaluator/export.hpp

@@ -157,6 +157,68 @@ struct ExportSvgOptions {
 void writeSvg(const std::string& path, const std::vector<ColoredBody>& bodies,
               const ExportSvgOptions& opts = {});
 
+// Options for the PDF writer, named and defaulted after OpenSCAD's own
+// `-O export-pdf/...` set.
+struct ExportPdfOptions {
+    enum class Paper { A6, A5, A4, A3, Letter, Legal, Tabloid };
+    // AUTO picks landscape when the model is wider than it is tall.
+    enum class Orientation { Portrait, Landscape, Auto };
+
+    Paper paper = Paper::A4;
+    Orientation orientation = Orientation::Portrait;
+    // The ruler, its labels and the caption that explains them. This is
+    // what makes a printed page a measuring tool rather than a plot, and
+    // is why the format was asked for at all.
+    bool showScale = true;
+    bool showScaleMsg = true;
+    bool showGrid = false;
+    double gridSize = 10.0;
+    // Drawn bottom-left when set. The DESIGN's name -- the writer has no
+    // way to know it, so a caller that wants it must pass it.
+    bool showFilename = false;
+    std::string designFilename;
+    bool fill = false;
+    std::string fillColor = "black";
+    bool stroke = true;
+    std::string strokeColor = "black";
+    double strokeWidth = 0.35;
+    bool addMetaData = true;
+    std::string metaTitle;
+    std::string metaAuthor;
+    std::string metaSubject;
+    std::string metaKeywords;
+};
+
+// "a4"/"letter"/... (case-insensitive) -> Paper. Returns false for a name
+// it does not know, leaving `out` untouched.
+bool paperFromName(const std::string& name, ExportPdfOptions::Paper& out);
+// "portrait"/"landscape"/"auto" -> Orientation, same contract.
+bool orientationFromName(const std::string& name, ExportPdfOptions::Orientation& out);
+
+// PDF 1.4 of a 2D-only model, drawn at 1:1 and CENTRED on a fixed paper
+// size -- unlike SVG, where the page is cut to fit the model.
+//
+// PDF user space is Y-up like model space, so unlike writeSvg there is NO
+// Y negation: the placement is `pt = mm * 72/25.4` plus a centring offset,
+// symmetric in both axes. (OpenSCAD's own file negates Y only because
+// Cairo draws Y-down and then flips the whole page.)
+//
+// With `showScale` on it also draws OpenSCAD's ruler: a left and bottom
+// axis at a 30pt margin, ticks every 10mm of MODEL space (hard-coded --
+// `gridSize` belongs to the optional grid, not to this), numeric labels on
+// every second tick, and the caption explaining what to measure. That
+// ruler is the point of the format: it is what lets a printed page tell
+// you how far off your printer's scaling is.
+//
+// Text uses the base-14 Helvetica every PDF reader supplies, so nothing is
+// embedded and no font metrics are needed.
+//
+// Returns the warnings to surface (a model too large for the page is drawn
+// anyway, and said so). Throws std::runtime_error if any top-level body is
+// 3D, if there is nothing to draw, or if the file cannot be opened.
+std::vector<std::string> writePdf(const std::string& path, const std::vector<ColoredBody>& bodies,
+                                   const ExportPdfOptions& opts = {});
+
 // -- one entry point ------------------------------------------------------
 
 struct ExportOptions {
@@ -176,6 +238,8 @@ struct ExportOptions {
     bool splitComponents = false;
     // .svg only.
     ExportSvgOptions svg;
+    // .pdf only.
+    ExportPdfOptions pdf;
 };
 
 // Writes `bodies` to `path`, choosing the writer from the extension (or

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/include/openscad_cpp_evaluator/zip_stored.hpp

@@ -28,6 +28,14 @@ void writeStoredZip(const std::string& path, const std::vector<ZipEntry>& entrie
 // std::runtime_error if the file can't be opened for writing.
 void writeDeflateZip(const std::string& path, const std::vector<ZipEntry>& entries);
 
+// Compresses `data` to a zlib stream (RFC 1950: 2-byte header, DEFLATE
+// data, Adler-32 trailer) -- which is exactly what PDF's /FlateDecode
+// filter reads, so the PDF writer uses this rather than growing its own
+// compressor. Same stb_image_write.h implementation the ZIP writer above
+// deflates with, only without the wrapper stripped off. Empty if
+// compression fails; the caller can always write the data uncompressed.
+std::vector<uint8_t> zlibCompress(const uint8_t* data, size_t size);
+
 // Reads one entry (by exact name match) from a ZIP archive via its central
 // directory (authoritative regardless of how local headers were written).
 // Supports both STORED (method 0, this project's own writeStoredZip()

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "1.10.0"
+version = "1.11.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-1.10.0 → openscad_cpp_evaluator-1.11.0}/python/openscad_cpp_evaluator/__init__.py

@@ -295,7 +295,7 @@ def export_model(path: str, geometry, format: str = "", ascii_stl: bool = False,
                  strip_slivers: bool = True, split_components: bool = False,
                  svg_fill: bool = False, svg_fill_color: str = "white",
                  svg_stroke: bool = True, svg_stroke_color: str = "black",
-                 svg_stroke_width: float = 0.35) -> list:
+                 svg_stroke_width: float = 0.35, pdf_options: dict | None = None) -> list:
     """Write `geometry` to `path`. Returns the warnings to surface.
 
     `geometry` is the handle an Evaluator stashes on itself as
@@ -321,11 +321,23 @@ def export_model(path: str, geometry, format: str = "", ascii_stl: bool = False,
     `svg_stroke`/`svg_stroke_width` also pad the page, so they are not
     purely cosmetic. An `.svg` export of anything 3D raises, as OpenSCAD's
     does -- there is no projection to fall back on.
+
+    `pdf_options` is a dict keyed the way OpenSCAD names its own
+    `-O export-pdf/...` settings: `paper-size`, `orientation`,
+    `show-scale`, `show-scale-message`, `show-grid`, `grid-size`,
+    `show-filename`, `design-filename`, `fill`, `fill-color`, `stroke`,
+    `stroke-color`, `stroke-width`, `add-meta-data`, `title`, `author`,
+    `subject`, `keywords`. An unknown key raises rather than being
+    ignored -- a silently dropped `paper-size` would print the wrong page
+    size with nothing to explain it. `.pdf` is 2D-only like `.svg`, and
+    centres the drawing on a fixed paper size instead of cutting the page
+    to fit.
     """
     try:
         return list(_ext.export_model(path, geometry, format, ascii_stl, strip_slivers,
                                        split_components, svg_fill, svg_fill_color,
-                                       svg_stroke, svg_stroke_color, svg_stroke_width))
+                                       svg_stroke, svg_stroke_color, svg_stroke_width,
+                                       pdf_options))
     except Exception as e:
         raise EvalError(str(e)) from e