printpdf is a library designed for creating printable PDF documents.
rust
[dependencies]
printpdf = "0.1.0"
Currently, printpdf can only write documents, not read them.
There are two types of functions: add_* and use_*. add_*-functions operate on the
document and return a reference to the content that has been added. This is used for
instantiating objects via references in the document (for example, for reusing a block of
data - like a font) without copying it (and bloating the file size).
Instancing happens via the use_*-functions, which operate on the layer. Meaning, you can only
instantiate blobs / content when you have a reference to the layer. Here are some examples:
```rust use printpdf::*; use std::fs::File;
let (doc, page1, layer1) = PdfDocument::new("PDFDocumenttitle", 247.0, 210.0, "Layer 1"); let (page2, layer1) = doc.add_page(10.0, 250.0,"Page 2, Layer 1");
doc.save(&mut File::create("test_working.pdf").unwrap()).unwrap(); ```
```rust use printpdf::*; use std::fs::File;
let (doc, page1, layer1) = PdfDocument::new("PDFDocumenttitle", 247.0, 210.0, "Layer 1");
let mut currentlayer = doc.getpage(page1).get_layer(layer1);
// Quadratic shape. The "false" determines if the next (following) // point is a bezier handle (for curves) // If you want holes, simply reorder the winding of the points to be // counterclockwise instead of clockwise. let points1 = vec![(Point::new(100.0, 100.0), false), (Point::new(100.0, 200.0), false), (Point::new(300.0, 200.0), false), (Point::new(300.0, 100.0), false)];
// Is the shape stroked? Is the shape closed? Is the shape filled? let line1 = Line::new(points1, true, true, true);
// Triangle shape let points2 = vec![(Point::new(150.0, 150.0), false), (Point::new(150.0, 250.0), false), (Point::new(350.0, 250.0), false)];
let line2 = Line::new(points2, true, false, false);
let fillcolor = Color::Cmyk(Cmyk::new(0.0, 0.23, 0.0, 0.0, None)); let outlinecolor = Color::Rgb(Rgb::new(0.75, 1.0, 0.64, None)); let mut dashpattern = LineDashPattern::default(); dashpattern.dash_1 = Some(20);
currentlayer.setfillcolor(fillcolor); currentlayer.setoutlinecolor(outlinecolor); currentlayer.setoutline_thickness(10);
// Draw first line currentlayer.addshape(line1);
let fillcolor2 = Color::Cmyk(Cmyk::new(0.0, 0.0, 0.0, 0.0, None)); let outlinecolor2 = Color::Greyscale(Greyscale::new(0.45, None));
// More advanced graphical options currentlayer.setoverprintstroke(true); currentlayer.setblendmode(BlendMode::Seperable(SeperableBlendMode::Multiply)); currentlayer.setlinedashpattern(dashpattern); currentlayer.setlinecap_style(LineCapStyle::Round);
currentlayer.setfillcolor(fillcolor2); currentlayer.setoutlinecolor(outlinecolor2); currentlayer.setoutline_thickness(15);
// draw second line currentlayer.addshape(line2); ```
Note: Images only get compressed in release mode. You might get huge PDFs (6 or more MB) in debug mode. In release mode, the compression makes these files much smaller (~ 100 - 200 KB).
To make this process faster, use BufReader instead of directly reading from the file.
Images are currently not a top priority.
Scaling of images is implicitly done to fit one pixel = one dot at 300 dpi.
```rust
extern crate printpdf; extern crate image; /* currently: version 0.14.0 */
use printpdf::*; use std::fs::File; use std::convert::TryFrom; use std::convert::From;
fn main() { let (doc, page1, layer1) = PdfDocument::new("PDFDocumenttitle", 247.0, 210.0, "Layer 1"); let currentlayer = doc.getpage(page1).get_layer(layer1);
// currently, the only reliable file format is bmp (jpeg works, but not in release mode)
// this is an issue of the image library, not a fault of printpdf
let mut image_file = File::open("assets/img/BMP_test.bmp").unwrap();
let image = Image::try_from(image::bmp::BMPDecoder::new(&mut image_file)).unwrap();
// translate x, translate y, rotate, scale x, scale y
// by default, an image is optimized to 300 DPI (if scale is None)
// rotations and translations are always in relation to the lower left corner
image.add_to_layer(current_layer.clone(), None, None, None, None, None, None);
// you can also construct images manually from your data:
let mut image_file_2 = ImageXObject {
width: 200,
height: 200,
color_space: ColorSpace::Greyscale,
bits_per_component: ColorBits::Bit8,
interpolate: true,
/* put your bytes here. Make sure the total number of bytes =
width * height * (bytes per component * number of components)
(e.g. 2 (bytes) x 3 (colors) for RGB 16bit) */
image_data: Vec::new(),
image_filter: None, /* does not work yet */
clipping_bbox: None, /* doesn't work either, untested */
};
let image2 = Image::from(image_file_2);
} ```
Note: Fonts are shared between pages. This means that they are added to the document first and then a reference to this one object can be passed to multiple pages. This is different to images, for example, which can only be used once on the page they are created on (since that's the most common use-case).
WARNING: rusttype can only load .ttf files, not .otf or other formats.
```rust use printpdf::*; use std::fs::File;
let (doc, page1, layer1) = PdfDocument::new("PDFDocumenttitle", 247.0, 210.0, "Layer 1"); let currentlayer = doc.getpage(page1).get_layer(layer1);
let text = "Lorem ipsum"; let text2 = "unicode: стуфхfцчшщъыьэюя";
let font = doc.addfont(File::open("assets/fonts/RobotoMedium.ttf").unwrap()).unwrap(); let font2 = doc.addfont(File::open("assets/fonts/leaguespartan-bold.ttf").unwrap()).unwrap();
// text, font size, x from left edge, y from top edge, font currentlayer.usetext(text, 48, 200.0, 200.0, &font);
// For more complex layout of text, you can use functions
// defined on the PdfLayerReference
// Make sure to wrap your commands
// in a begin_text_section() and end_text_section() wrapper
currentlayer.begintext_section();
// setup the general fonts.
// see the docs for these functions for details
current_layer.set_font(&font2, 33);
current_layer.set_text_cursor(10.0, 10.0);
current_layer.set_line_height(33);
current_layer.set_word_spacing(3000);
current_layer.set_character_spacing(10);
current_layer.set_text_rendering_mode(TextRenderingMode::Stroke);
// write two lines (one line break)
current_layer.write_text(text.clone(), &font2);
current_layer.add_line_break();
current_layer.write_text(text2.clone(), &font2);
current_layer.add_line_break();
// write one line, but write text2 in superscript
current_layer.write_text(text.clone(), &font2);
current_layer.set_line_offset(10);
current_layer.write_text(text2.clone(), &font2);
currentlayer.endtext_section(); ```
The PDFDocument is hidden behind a PDFDocumentReference, which locks the things you can
do behind a facade. Pretty much all functions operate on a PDFLayerReference, so that would
be where to look for existing functions or where to implement new functions. The PDFDocumentReference
is a reference-counted document. It uses the pages and layers for inner mutablility, because
I ran into borrowing issues with the document. IMPORTANT: All functions that mutate the state
of the document, "borrow" the document mutably for the duration of the function. It is important
that you don't borrow the document twice (your program will crash if you do so). I have prevented
this wherever possible, by making the document only public to the crate so you cannot lock it from
outside of this library.
Images have to be added to the pages resources before using them. Meaning, you can only use an image on the page that you added it to. Otherwise, you may end up with a corrupt PDF.
Fonts are embedded using rusttype. In the future, there should be an option to use freetype,
because freetype can use OpenType fonts. Please report issues if you have any, especially if you
see BorrowMut errors (they should not happen). Kerning is currently not done, should be added later.
However, "correct" kerning / placement requires a full font shaping engine, etc. This would be a completely
different project.
For learning how a PDF is actually made, please read the wiki. When I began making this library, these resources were not available anywhere, so I hope to help other people with these topics. Reading the wiki is essential if you want to contribute to this library.
The goal of printpdf is to be a general-use PDF library, such as libharu or similar. PDFs generated by printpdf must always adhere to a PDF standard. However, not all standards are supported. See this list:
Over time, there will be more standards supported. Checking a PDF for errors is currently only a stub.
/src/types/plugins/[family of your type]/[type].rsIntoPdfObject, so that it can be added to the documentpage and `layer content types to have a convenience function for adding your typecargo readme > README.md.Currently the testing is pretty much non-existent, because PDF is very hard to test. This should change over time: Testing should be done in two stages. First, test the individual PDF objects, if the conversion into a PDF object is done correctly. The second stage is manual inspection of PDF objects via Adobe Preflight.
Put the tests of the first stage in /tests/mod.rs. The second stage tests are better to be handled
inside the plugins' mod.rs file. printpdf depends highly on lopdf,
so you can either construct your test object against a real type or a debug string of your serialized
type. Either way is fine - you just have to check that the test object is conform to what PDF expects.
Here are some resources I found while working on this library
PDFXPlorer, shows the DOM tree of a PDF, needs .NET 2.0