PdfCraft: An open-source PDF reader and editor written by scratch in pure Rust
M2: page_render and render_preview report the render warnings next to the PNG (#4340)
Lcoding1580f919977b1e
diff --git a/crates/automation/README.md b/crates/automation/README.mdindex cdaaa13e6..2b36242e5 100644--- a/crates/automation/README.md+++ b/crates/automation/README.md@@ -181,6 +181,12 @@ working document unchanged.`content_list` or `object_list`. It removes only that item in a read-only preview and ismutually exclusive with `hide_text_block`.+When the renderer reports a warning for the page, `page_render` and `render_preview` return a+JSON part after the PNG, `{ "page": 1, "warnings": [...] }`, with the sentences+`pdfcraft-cli render` prints: "content past the page's safety budget was skipped" and "a colour+that could not be computed was painted in a fallback colour". A page without warnings returns+the PNG alone.+## Existing text and document fontsdiff --git a/crates/automation/src/conventions.rs b/crates/automation/src/conventions.rsindex ac670109f..a84c6488a 100644--- a/crates/automation/src/conventions.rs+++ b/crates/automation/src/conventions.rs@@ -1,7 +1,7 @@//! Shared command/inspection/preview entry points, using the existing confined tool path.use serde_json::{Value, json};-use crate::{Args, Automation, Content, Result, ToolError, encode_png, failed, info, tools};+use crate::{Args, Automation, Content, Result, ToolError, failed, info, rendered_content, tools};use pdfcraft_engine::commands;use pdfcraft_render::{RenderRequest, RequestKind};@@ -108,7 +108,8 @@ impl Automation {Ok(json!({"documents":self.session.docs().iter().map(info).collect::<Vec<_>>()}))}- pub(crate) fn render_preview(&mut self, args: &Args) -> Result<Content> {+ /// A bounded PNG of the page, with its render warnings after it as `page_render` gives them.+ pub(crate) fn render_preview(&mut self, args: &Args) -> Result<Vec<Content>> {let id = if args.opt_int("doc")?.is_some() {self.doc(args)?.id} else {@@ -134,7 +135,6 @@ impl Automation {if let Some(error) = out.error {return Err(failed(error));}- let data = encode_png(out.width, out.height, &out.rgba)?;- Ok(Content::Png { data, width: out.width, height: out.height })+ rendered_content(&out, page)}}diff --git a/crates/automation/src/lib.rs b/crates/automation/src/lib.rsindex e94354021..5b6a0219f 100644--- a/crates/automation/src/lib.rs+++ b/crates/automation/src/lib.rs@@ -225,7 +225,7 @@ impl Automation {let edit = Edit::SetInfo { key: a.str("key")?.into(), value: a.str("value")?.into() };self.apply(&a, edit)?}- "page_render" => return self.page_render(&a).map(|c| vec![c]),+ "page_render" => return self.page_render(&a),"comment_image_preview" => return self.comment_image_preview(&a),"text_extract" => self.text_extract(&a)?,"text_word_count" => self.text_word_count(&a)?,@@ -329,7 +329,7 @@ impl Automation {"command_run" => return self.command_run(&a),"command_batch" => self.command_batch(&a)?,"doc_inspect" => self.doc_inspect(&a)?,- "render_preview" => return self.render_preview(&a).map(|c| vec![c]),+ "render_preview" => return self.render_preview(&a),"page_number" => {use pdfcraft_organize::LabelStyle as L;let n = self.doc(&a)?.info.pages.len();@@ -2023,7 +2023,9 @@ impl Automation {Ok(&mut entry.1)}- fn page_render(&mut self, a: &Args) -> Result<Content> {+ /// The page as a PNG, followed by a JSON part listing the render warnings when there are any,+ /// so a caller can tell that the picture is incomplete, as `pdfcraft-cli render` does (#4340).+ fn page_render(&mut self, a: &Args) -> Result<Vec<Content>> {let id = self.doc(a)?.id;let page = self.page(a)?;let dpi = a.opt_num("dpi")?.unwrap_or(DEFAULT_DPI);@@ -2056,8 +2058,7 @@ impl Automation {if let Some(e) = out.error {return Err(failed(format!("page {} could not be rendered: {e}", page + 1)));}- let data = encode_png(out.width, out.height, &out.rgba)?;- Ok(Content::Png { data, width: out.width, height: out.height })+ rendered_content(&out, page)}/// A page as RGBA pixels, without encoding a PNG. `page` is 1-based and `scale` is pixels@@ -2733,6 +2734,29 @@ fn encode_png(width: u32, height: u32, premultiplied: &[u8]) -> Result<Vec<u8>>pdfcraft_engine::export::encode_png(width, height, premultiplied).map_err(failed)}+/// The output of a page-rendering tool: the PNG of the 0-based `page`, followed by a JSON part+/// listing its render warnings when there are any. Without warnings it is the PNG alone, as it+/// always was.+fn rendered_content(out: &pdfcraft_render::RenderedPage, page: usize) -> Result<Vec<Content>> {+ let data = encode_png(out.width, out.height, &out.rgba)?;+ let mut content = vec![Content::Png { data, width: out.width, height: out.height }];+ if !out.warnings.is_empty() {+ // Sentences, like the other tools' `warnings`, so command_run can add its own to the list.+ let warnings: Vec<&str> = out.warnings.iter().map(|&w| render_warning_text(w)).collect();+ content.push(Content::Json(json!({ "page": page.saturating_add(1), "warnings": warnings })));+ }+ Ok(content)+}++/// What a render warning means, in the words `pdfcraft-cli render` prints for it.+fn render_warning_text(warning: pdfcraft_render::RenderWarning) -> &'static str {+ use pdfcraft_render::RenderWarning;+ match warning {+ RenderWarning::ContentTruncated => "content past the page's safety budget was skipped",+ RenderWarning::ColourFallback => "a colour that could not be computed was painted in a fallback colour",+ }+}+/// Extract the text of `pages` (0-based) with one renderer per worker thread.fn extract_parallel(bytes: &Arc<Vec<u8>>, password: Option<Arc<str>>, pages: &[usize]) -> PageTexts {let extract = |r: &mut PageRenderer, p: usize| {diff --git a/crates/automation/src/tools.rs b/crates/automation/src/tools.rsindex 1bfcc7798..e78930e88 100644--- a/crates/automation/src/tools.rs+++ b/crates/automation/src/tools.rs@@ -164,7 +164,7 @@ pub fn tools() -> Vec<ToolDef> {)),t("doc_set_info", "Set document metadata", "Set a document information entry such as Title, Author, Subject or Keywords, or a custom property under any other name (no spaces, delimiters, / or #; at most 127 bytes; doc_info lists them under custom); an empty value removes it. When the file has XMP metadata, the matching XMP property (dc:title, dc:creator, dc:description, pdf:Keywords, xmp:CreatorTool, pdf:Producer) is changed too, so viewers that read XMP first show the new value. Undoable.").with(schema(json!({ "doc": doc(), "key": { "type": "string" }, "value": { "type": "string" } }), &["doc", "key", "value"])),- t("page_render", "Render a page", "Render one page to a PNG image (default 96 dpi, at most 600).")+ t("page_render", "Render a page", "Render one page to a PNG image (default 96 dpi, at most 600). When the picture is incomplete or approximate (content cut at the page's safety budget, a colour painted in a fallback colour), a JSON part follows the image: { page, warnings: [sentence, ...] }.").ro().with(schema(json!({ "doc": doc(), "page": { "type": "integer", "minimum": 1 }, "dpi": { "type": "number", "minimum": 1, "maximum": 600 },"hide_text_block": { "type": "integer", "minimum": 1, "description": "Render an inline editor background without this paragraph (number from text_paragraphs, resolved as text_edit does: refused once an edit merged that paragraph into a neighbour). Does not modify the document." },@@ -1442,7 +1442,7 @@ pub fn tools() -> Vec<ToolDef> {.destructive().with(schema(json!({"steps":{"type":"array","items":schema(json!({"id":{"type":"string"},"params":{"type":"object"}}), &["id"])},"stop_on_error":{"type":"boolean"}}), &["steps"])),t("doc_inspect", "Inspect open documents", "With doc, return doc_info; otherwise return information for every open document (empty documents array when none are open).").ro().with(schema(json!({"doc":doc()}), &[])),- t("render_preview", "Render a preview", "Render a PNG bounded by max_side (default 1024), without changing or saving the document. Page defaults to 1; doc may be omitted when exactly one document is open.")+ t("render_preview", "Render a preview", "Render a PNG bounded by max_side (default 1024), without changing or saving the document. Page defaults to 1; doc may be omitted when exactly one document is open. Render warnings follow the image as page_render gives them.").ro().with(schema(json!({"doc":doc(),"page":{"type":"integer","minimum":1},"max_side":{"type":"integer","minimum":1,"maximum":4096}}), &[])),]}diff --git a/crates/automation/tests/it/main.rs b/crates/automation/tests/it/main.rsindex d94aa9f7c..f38c8599a 100644--- a/crates/automation/tests/it/main.rs+++ b/crates/automation/tests/it/main.rs@@ -8,3 +8,4 @@ mod button_caption;mod form_bulk;mod hostile_args;mod optimize_content_boundaries;+mod render_warnings;diff --git a/crates/automation/tests/it/render_warnings.rs b/crates/automation/tests/it/render_warnings.rsnew file mode 100644index 000000000..ff50c11e1--- /dev/null+++ b/crates/automation/tests/it/render_warnings.rs@@ -0,0 +1,119 @@+//! `page_render` reports the renderer's warnings next to the PNG, so a headless caller can tell+//! that a picture is incomplete or approximate, as `pdfcraft-cli render` can (#4340).++use std::path::PathBuf;++use pdfcraft_automation::{Automation, Content};+use serde_json::{Value, json};++/// The warning a colour that falls back gives, worded as `pdfcraft-cli render` prints it.+const FALLBACK: &str = "a colour that could not be computed was painted in a fallback colour";++/// A one-page 200 × 200 pt PDF that draws `content`, with the colour space `CS1` defined as+/// `[/DeviceN [/Spot1 /Spot2] /DeviceRGB 5 0 R]` and object 5 a calculator function `program`.+fn devicen_pdf(content: &str, program: &str) -> Vec<u8> {+ format!(+ "%PDF-1.7\n1 0 obj << /Type /Catalog /Pages 2 0 R >> endobj\n\+ 2 0 obj << /Type /Pages /Kids [3 0 R] /Count 1 >> endobj\n\+ 3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Resources << /ColorSpace << /CS1 [/DeviceN [/Spot1 /Spot2] /DeviceRGB 5 0 R] >> >> /Contents 4 0 R >> endobj\n\+ 4 0 obj << /Length {} >> stream\n{content}\nendstream endobj\n\+ 5 0 obj << /FunctionType 4 /Domain [0 1 0 1] /Range [0 1 0 1 0 1] /Length {} >> stream\n{program}\nendstream endobj\n\+ trailer << /Root 1 0 R >>\n%%EOF",+ content.len(),+ program.len()+ )+ .into_bytes()+}++/// A page whose colour falls back: the tint transform pops more than it is given, so it can't be+/// evaluated (the renderer's own test of the warning uses the same function).+fn fallback_pdf() -> Vec<u8> {+ devicen_pdf("/CS1 cs 0.5 0.5 scn 0 0 100 100 re f", "{ pop pop pop }")+}++/// The same page with a tint transform that works: nothing to warn about.+fn clean_pdf() -> Vec<u8> {+ devicen_pdf("/CS1 cs 0.5 0.5 scn 0 0 100 100 re f", "{ pop pop 0 0 0 }")+}++/// A fresh folder holding `fallback.pdf` and `clean.pdf`, and an automation rooted there.+fn setup(test: &str) -> (PathBuf, Automation) {+ let dir = std::env::temp_dir().join(format!("pdfcraft-render-warnings-{test}-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&dir);+ std::fs::create_dir_all(&dir).unwrap();+ std::fs::write(dir.join("fallback.pdf"), fallback_pdf()).unwrap();+ std::fs::write(dir.join("clean.pdf"), clean_pdf()).unwrap();+ let a = Automation::new().with_root(&dir).unwrap();+ (dir, a)+}++fn open(a: &mut Automation, path: &str) -> u64 {+ match a.call("doc_open", &json!({ "path": path })).unwrap().remove(0) {+ Content::Json(v) => v["doc"].as_u64().unwrap(),+ other => panic!("expected JSON: {other:?}"),+ }+}++#[test]+fn page_render_lists_the_warnings_after_the_png() {+ let (dir, mut a) = setup("fallback");+ let doc = open(&mut a, "fallback.pdf");+ let out = a.call("page_render", &json!({ "doc": doc, "page": 1, "dpi": 72 })).unwrap();+ assert_eq!(out.len(), 2, "the PNG and the warnings: {out:?}");+ assert!(matches!(out[0], Content::Png { width: 200, height: 200, .. }), "the image comes first, as before");+ let Content::Json(report) = &out[1] else { panic!("expected the warnings as JSON: {:?}", out[1]) };+ assert_eq!(report["page"], 1, "the page is 1-based, like the argument");+ assert_eq!(report["warnings"], json!([FALLBACK]));+ let _ = std::fs::remove_dir_all(dir);+}++#[test]+fn render_preview_lists_the_warnings_after_the_png_too() {+ let (dir, mut a) = setup("preview");+ let doc = open(&mut a, "fallback.pdf");+ let out = a.call("render_preview", &json!({ "doc": doc, "max_side": 64 })).unwrap();+ assert!(matches!(out.first(), Some(Content::Png { width: 64, height: 64, .. })), "{out:?}");+ let Some(Content::Json(report)) = out.get(1) else { panic!("expected the warnings as JSON: {out:?}") };+ assert_eq!(report["page"], 1, "the page defaults to the first");+ assert_eq!(report["warnings"], json!([FALLBACK]));+ let clean = open(&mut a, "clean.pdf");+ assert_eq!(a.call("render_preview", &json!({ "doc": clean })).unwrap().len(), 1, "a clean page gives the PNG alone");+ let _ = std::fs::remove_dir_all(dir);+}++#[test]+fn a_clean_page_renders_to_the_png_alone() {+ let (dir, mut a) = setup("clean");+ let fallback = open(&mut a, "fallback.pdf");+ let clean = open(&mut a, "clean.pdf");+ // The warning of one render doesn't carry over to the next, nor to another document.+ a.call("page_render", &json!({ "doc": fallback, "page": 1, "dpi": 72 })).unwrap();+ let out = a.call("page_render", &json!({ "doc": clean, "page": 1, "dpi": 72 })).unwrap();+ assert_eq!(out.len(), 1, "no warnings, no extra part: {out:?}");+ assert!(matches!(out[0], Content::Png { .. }));+ let again = a.call("page_render", &json!({ "doc": fallback, "page": 1, "dpi": 72 })).unwrap();+ assert_eq!(again.len(), 2, "a cached renderer still reports the page's warning: {again:?}");+ let _ = std::fs::remove_dir_all(dir);+}++/// Over MCP the warnings are a text block after the image and the call's `structuredContent`.+#[cfg(feature = "mcp")]+#[test]+fn mcp_page_render_carries_the_warnings_as_structured_content() {+ use pdfcraft_automation::mcp::McpServer;+ let (dir, a) = setup("mcp");+ let mut s = McpServer::new(a);+ let mut rpc = |id: u64, method: &str, params: Value| -> Value {+ let line = json!({ "jsonrpc": "2.0", "id": id, "method": method, "params": params }).to_string();+ serde_json::from_str(&s.handle_line(&line).expect("a reply")).unwrap()+ };+ rpc(1, "initialize", json!({}));+ rpc(2, "tools/call", json!({ "name": "doc_open", "arguments": { "path": "fallback.pdf" } }));+ let reply = rpc(3, "tools/call", json!({ "name": "page_render", "arguments": { "doc": 1, "page": 1 } }));+ let result = &reply["result"];+ assert_eq!(result["isError"], false, "{reply}");+ assert_eq!(result["content"][0]["type"], "image");+ assert_eq!(result["content"][1]["type"], "text");+ assert_eq!(result["structuredContent"]["warnings"], json!([FALLBACK]));+ let _ = std::fs::remove_dir_all(dir);+}