Home

Awesome

OHPDFImage

Version Platform Build Status

This library intends to easily load PDF documents to use them as vector images.

Installation

The recommended way to install this library is using CocoaPods. Simply add it to your Podfile:

pod 'OHPDFImage'

Adding PDF files to your project

If you intend to use a PDF as a vector image, you should add it as a resource in your project. Especially, you should NOT add the PDF in your Images.xcassets Assets Catalog.

Don't use Assets Catalog for PDF files

Xcode 6 accept PDF files to be added to an Assets Catalog, but when you do so, it in fact re-create PNG assets at compile time, embedding the rasterized bitmaps in the final application instead of embedding the original PDF vector image. That's why you should add the PDF file as a standard resource and not in the xcassets catalog.

Exporting PDF files from Photoshop

If your vector image has been created using Photoshop and you intend to export it as PDF, you may choose the "Save As…" menu item and choose the "Photoshop PDF" file format to create the PDF.
In that case, be careful to select the "High Quality Print" preset, which is the only preset that conserve the PDF transparency / alpha channel.

Using a PDF as an image

The UIImage category

If you simply intend to use the PDF as an image as-is, you can use:

self.imageView.image = [UIImage imageWithPDFNamed:@"vector_image"
                                        fitInSize:self.imageView.bounds.size];

This will load the PDF, use its first page to create an OHVectorImage, then rasterize this vector image as an UIImage of the requested size, ensuring to keep its aspect ratio.

Note: PDF pages are cached, so that requesting an image with the same PDF name, even with a different size, will use the cached version of the PDF instead of loading it again from disk. Thus, only the rasterization into a bitmap image is recreated.

More control with the OHVectorImage class

If you need more options on how the vector image will be rendered, you can directly manipulate OHVectorImage objects. Here is what you can do when using OHVectorImage:

Drop shadow and insets

Drop shadow values (offset and blur radius) as well as insets are expressed in the coordinate system of the vector image (i.e. with the same scale as when the vector image is rendered using its nativeSize), so that they can be resolution-independant.

This way, if you add a drop shadow with shadowOffset = (CGSize){2,2} and blurRadius = 3 then you can safely use an inset = (UIEdgeInsets){ .right = 5, .bottom = 5 } to ensure the shadow won't be clipped, without worrying about the size at which the image will be rendered.

Keeping aspect ratio

Note: This is actually what +[UIImage imageWithPDFNamed:fitInSize:] does internally.

The sizeThatFits: method takes the vector image's insets property into account when computing the fitting size — as these insets values will be applied when rendering as well.

Note: sizeThatFits: actually uses MIN(width, height) of these scale factors to determine the scale factor to "aspect fit" the image in the provided size. If you instead need to scale the image so it does an "aspect fill" scaling — cropping the image if necessary to fill the whole size — you may instead use MAX(width, height) to compute the scale and thus the size at which to render the image.

Example

OHVectorImage* vImage = [OHVectorImage imageWithPDFNamed:@"vector_image"];
vImage.backgroundColor = [UIColor colorWithRed:0.9 green:1.0 blue:0.9 alpha:1.0];
vImage.tintColor = [UIColor redColor];
// Shadow & Insets
vImage.shadow = [NSShadow new];
vImage.shadow.shadowOffset = CGSizeMake(2,2);
vImage.shadow.shadowBlurRadius = 3.f;
vImage.shadow.shadowColor = [UIColor darkGrayColor];
vImage.insets = UIEdgeInsetsMake(0,0,5,5);
// Render as an UIImage, ensuring to keep aspect ratio
UIImage* image = [vImage renderAtSizeThatFits:imageViewSize];

A complete example is also available in the Demo project provided in this repo. Don't hesitate to try it (you may use pod try OHPDFImage to give it a try even if you haven't cloned the repo yet!)

Loading a PDF document

The main goal of this library is to use PDF as images using the UIImage category or OHVectorImage class directly.

However, you can also use the OHPDFDocument and OHPDFPage classes to load a PDF document and get its pages, and render those pages individually in a graphic context (CGContextRef) you provide.

You can also use this to fetch an arbitrary page of a given PDF to generate a vector image (instead of using the first page, which is the default).
For example, the following code read every page of a PDF as a vector image and build an animated UIImage from it:

NSURL* pdfURL = [[NSBundle mainBundle] URLForResource:@"vector_images" withExtension:@"pdf"];
OHPDFDocument* doc = [OHPDFDocument documentWithURL:pdfURL];
NSMutableArray* frames = [NSMutableArray arrayWithCapacity:doc.pagesCount];
CGSize frameSize = CGSizeMake(100,100);
for(size_t pageNum = 0; pageNum < doc.pagesCount; ++pageNum)
{
  OHPDFPage* page = [doc pageAtIndex:pageNum+1]; // Note: page indexes start at 1
  OHVectorImage* vImage = [OHVectorImage imageWithPDFPage:page];
  [frames addObject:[vImages renderAtSize:frameSize]];
}

NSTimeInterval duration = doc.pagesCount * 2.0; // 2.0s per frame 
UIImage* animatedImage = [UIImage animatedImageWithImages:frames
                                                 duration:duration];

License

This library is authored by Olivier Halligon and is distributed under the MIT License (see LICENSE file).