printpdf

printpdf is a library designed for creating printable PDF documents.

[dependencies]
printpdf = "0.2.0"

Features

Currently, printpdf can only write documents, not read them.

Page generation
Layers (Illustrator like layers)
Graphics (lines, shapes, bezier curves)
Images (currently BMP only or generate your own images)
Embedded fonts (TTF and OTF) with Unicode support
Advanced graphics - overprint control, blending modes, etc.
Advanced typography - character scaling, character spacing, superscript, subscript, outlining, etc.
PDF layers (you should be able to open the PDF in Illustrator and have the layers appear)

Getting started

Writing PDF

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:

Simple page

use printpdf::*;
use std::fs::File;
use std::io::BufWriter;

let (doc, page1, layer1) = PdfDocument::new("PDF_Document_title", 247.0, 210.0, "Layer 1");
let (page2, layer1) = doc.add_page(10.0, 250.0,"Page 2, Layer 1");

doc.save(&mut BufWriter::new(File::create("test_working.pdf").unwrap())).unwrap();

Adding graphical shapes

use printpdf::*;

let (doc, page1, layer1) = PdfDocument::new("PDF_Document_title", 247.0, 210.0, "Layer 1");

let mut current_layer = doc.get_page(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 fill_color = Color::Cmyk(Cmyk::new(0.0, 0.23, 0.0, 0.0, None));
let outline_color = Color::Rgb(Rgb::new(0.75, 1.0, 0.64, None));
let mut dash_pattern = LineDashPattern::default();
dash_pattern.dash_1 = Some(20);

current_layer.set_fill_color(fill_color);
current_layer.set_outline_color(outline_color);
current_layer.set_outline_thickness(10);

// Draw first line
current_layer.add_shape(line1);

let fill_color_2 = Color::Cmyk(Cmyk::new(0.0, 0.0, 0.0, 0.0, None));
let outline_color_2 = Color::Greyscale(Greyscale::new(0.45, None));

// More advanced graphical options
current_layer.set_overprint_stroke(true);
current_layer.set_blend_mode(BlendMode::Seperable(SeperableBlendMode::Multiply));
current_layer.set_line_dash_pattern(dash_pattern);
current_layer.set_line_cap_style(LineCapStyle::Round);

current_layer.set_fill_color(fill_color_2);
current_layer.set_outline_color(outline_color_2);
current_layer.set_outline_thickness(15);

// draw second line
current_layer.add_shape(line2);

Adding images

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.

extern crate printpdf;
extern crate image; /* currently: version 0.14.0 */

use printpdf::*;
use std::convert::From;
use std::fs::File;

fn main() {
    let (doc, page1, layer1) = PdfDocument::new("PDF_Document_title", 247.0, 210.0, "Layer 1");
    let current_layer = doc.get_page(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);
}

Adding fonts

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

use printpdf::*;
use std::fs::File;

let (doc, page1, layer1) = PdfDocument::new("PDF_Document_title", 247.0, 210.0, "Layer 1");
let current_layer = doc.get_page(page1).get_layer(layer1);

let text = "Lorem ipsum";
let text2 = "unicode: стуфхfцчшщъыьэюя";

let font = doc.add_external_font(File::open("assets/fonts/RobotoMedium.ttf").unwrap()).unwrap();
let font2 = doc.add_external_font(File::open("assets/fonts/RobotoMedium.ttf").unwrap()).unwrap();

// text, font size, x from left edge, y from top edge, font
current_layer.use_text(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
current_layer.begin_text_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);

current_layer.end_text_section();

Upgrading to `0.2.0` / Changelog

The document.save() method now needs a BufWriter, to enforce buffered output (breaking change).
The PdfDocument now implements Clone, so you can write one document to multiple outputs.
You can disable the automatic embedding of an ICC profile by using a CustomPdfConformance. See examples/no_icc.rs for usage information.
add_font changed to add_external_font + added add_builtin_font function (see example folder)

Goals and Roadmap

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:

PDF/A-1b:2005
PDF/A-1a:2005
PDF/A-2:2011
PDF/A-2a:2011
PDF/A-2b:2011
PDF/A-2u:2011
PDF/A-3:2012
PDF/UA-1
PDF/X-1a:2001
PDF/X-3:2002
PDF/X-1a:2003
PDF/X-3:2003
PDF/X-4:2010
PDF/X-4P:2010
PDF/X-5G:2010
PDF/X-5PG:2010
PDF/X-5N:2010
PDF/E-1
PDF/VT:2010

Over time, there will be more standards supported. Checking a PDF for errors is currently only a stub.

Planned features

Clipping
Aligning / layouting text
Open Prepress Interface
Halftoning images, Gradients, Patterns
SVG / instantiated content
More font support
Forms, annotations
Bookmarks / Table of contents
Conformance / error checking for various PDF standards
Embedded Javascript
Reading PDF
Completion of printpdf wiki

Contributing

READ THE WIKI FIRST !!!

Fork the project, make you own branch
If you want to add support for some data type, let's say images or embedded video, create your type in /src/types/plugins/[family of your type]/[type].rs
The type should implement IntoPdfObject, so that it can be added to the document
Change the page and `layer content types to have a convenience function for adding your type
Document your changes. Add a doc test (how you expect the type to be used) and a unit test (if the type is conform to the expected PDF type)
If you want to change this README, change the lib.rs instead and run cargo readme > README.md.
Create pull request

Testing

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.

Useful links

Here are some resources I found while working on this library

PDFXPlorer, shows the DOM tree of a PDF, needs .NET 2.0

Official PDF 1.7 reference

[GERMAN] How to embed unicode fonts in PDF

PDF X/1-a Validator

PDF X/3 technical notes

printpdf 0.2.0

printpdf

Features

Getting started

Writing PDF

Simple page

Adding graphical shapes

Adding images

Adding fonts

Upgrading to `0.2.0` / Changelog

Further reading

Goals and Roadmap

Planned features

Contributing

Testing

Useful links

printpdf 0.2.0

printpdf

Features

Getting started

Writing PDF

Simple page

Adding graphical shapes

Adding images

Adding fonts

Upgrading to 0.2.0 / Changelog

Further reading

Goals and Roadmap

Planned features

Contributing

Testing

Useful links

Upgrading to `0.2.0` / Changelog