# printpdf
`printpdf` is a library designed for creating printable PDF documents.
```toml
[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
```rust
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
```rust
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);
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)];
let line1 = Line::new(points1, true, true, true);
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);
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));
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);
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.
```rust
extern crate printpdf;
extern crate image;
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);
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();
image.add_to_layer(current_layer.clone(), None, None, None, None, None, None);
let mut image_file_2 = ImageXObject {
width: 200,
height: 200,
color_space: ColorSpace::Greyscale,
bits_per_component: ColorBits::Bit8,
interpolate: true,
image_data: Vec::new(),
image_filter: None,
clipping_bbox: None,
};
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).
```rust
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();
current_layer.use_text(text, 48, 200.0, 200.0, &font);
current_layer.begin_text_section();
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);
current_layer.write_text(text.clone(), &font2);
current_layer.add_line_break();
current_layer.write_text(text2.clone(), &font2);
current_layer.add_line_break();
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)
# Further reading
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 `freetype`. In the future, there should be an option to use `rusttype`.
Please report issues if you have any, especially if you see `BorrowMut` errors (they should not happen).
Kerning is currently not done, because neither `freetype` nor `rusttype` can reliably read kerning data.
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](https://github.com/sharazam/printpdf/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.
# 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
- [x] 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 !!!](https://github.com/sharazam/printpdf/wiki)
- 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](https://github.com/J-F-Liu/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](http://www.o2sol.com/pdfxplorer/download.htm)
[Official PDF 1.7 reference](http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/pdf_reference_1-7.pdf)
[[GERMAN] How to embed unicode fonts in PDF](http://www.p2501.ch/pdf-howto/typographie/vollzugriff/direkt)
[PDF X/1-a Validator](https://www.pdf-online.com/osa/validate.aspx)
[PDF X/3 technical notes](http://www.pdfxreport.com/lib/exe/fetch.php?media=en:technote_pdfx_checks.pdf)