{"id":16886676,"url":"https://github.com/alisoftware/ohpdfimage","last_synced_at":"2025-09-21T12:32:52.765Z","repository":{"id":62449303,"uuid":"27972182","full_name":"AliSoftware/OHPDFImage","owner":"AliSoftware","description":"A library to easily load PDF files as UIImages","archived":false,"fork":false,"pushed_at":"2016-03-17T20:30:55.000Z","size":295,"stargazers_count":56,"open_issues_count":5,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-28T16:48:23.704Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AliSoftware.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-13T20:03:06.000Z","updated_at":"2023-12-10T17:15:19.000Z","dependencies_parsed_at":"2022-11-01T23:17:22.221Z","dependency_job_id":null,"html_url":"https://github.com/AliSoftware/OHPDFImage","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliSoftware%2FOHPDFImage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliSoftware%2FOHPDFImage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliSoftware%2FOHPDFImage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AliSoftware%2FOHPDFImage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AliSoftware","download_url":"https://codeload.github.com/AliSoftware/OHPDFImage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233753377,"owners_count":18724823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T16:40:42.334Z","updated_at":"2025-09-21T12:32:52.418Z","avatar_url":"https://github.com/AliSoftware.png","language":"Objective-C","readme":"# OHPDFImage\n\n\n[![Version](http://cocoapod-badges.herokuapp.com/v/OHPDFImage/badge.png)](http://cocoadocs.org/docsets/OHPDFImage)\n[![Platform](http://cocoapod-badges.herokuapp.com/p/OHPDFImage/badge.png)](http://cocoadocs.org/docsets/OHPDFImage)\n[![Build Status](https://travis-ci.org/AliSoftware/OHPDFImage.png?branch=master)](https://travis-ci.org/AliSoftware/OHPDFImage)\n\n\nThis library intends to easily load PDF documents to use them as vector images.\n\n## Installation\n\nThe recommended way to install this library is using [CocoaPods](http://guides.cocoapods.org). Simply add it to your `Podfile`:\n\n```\npod 'OHPDFImage'\n```\n\n## Adding PDF files to your project\n\nIf 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.\n\n#### Don't use Assets Catalog for PDF files\n\nXcode 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.\n\n#### Exporting PDF files from Photoshop\n\nIf 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.  \nIn that case, be careful to select the **\"High Quality Print\" preset**, which is the only preset that conserve the PDF transparency / alpha channel.\n\n## Using a PDF as an image\n\n### The `UIImage` category\n\nIf you simply intend to use the PDF as an image as-is, you can use:\n\n```objc\nself.imageView.image = [UIImage imageWithPDFNamed:@\"vector_image\"\n                                        fitInSize:self.imageView.bounds.size];\n```\n\nThis 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.\n\n\u003e 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.\n\n### More control with the `OHVectorImage` class\n\nIf 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`:\n\n* **Change the background color** of the generated image using the `backgroundColor` property (`nil` to generate transparent images);\n* **Re-tint the image** using the `tintColor` property (in that case the PDF is merely used as a mask for which only its alpha channel is used);\n* **Add a drop shadow** using the `shadow` property (a `NSShadow` object that lets you customize the shadow offset, blur radius and color);\n* **Add insets** (`UIEdgeInsets`) to the image when rendering:\n  * either to translate the image to any direction,\n  * or to add margins to the image (useful when you add a drop shadow to ensure it is not clipped),\n  * or to reduce/remove margins present in the original PDF (by using negative insets)\n  * ...\n* **Customize the graphic context** before the vector image is rendered, using the `prepareContextBlock` property\n  * This is mostly intended for advanced usage, like applying a custom transform or adding a custom clipping path to the `CGContextRef` before rendering the PDF vector image.\n\n#### Drop shadow and insets\n\nDrop 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.\n\nThis 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.\n\n#### Keeping aspect ratio\n\n* When you call `-[OHVectorImage renderAtSize:]` with the expected size, it does not try to keep the aspect ratio, and simply use the given size as-is, stretching the image if necessary (\"Scale to Fill\" behavior).\n\n* If you want to keep the aspect ratio of the original PDF, you can compute the size that fits a given size using `-[OHVectorImage sizeThatFits:]` first, and then use this size when calling `-[OHVectorImage renderAtSize:]`.\n\n\u003e _Note: This is actually what `+[UIImage imageWithPDFNamed:fitInSize:]` does internally._\n\nThe `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.\n\n* As wanting to keep the aspect ratio is a quite common case, a convenience method `-[OHVectorImage renderAtSizeThatFits:]` is provided that simply calls the two aforementioned methods one after the other.\n\n* You may also use the `-[OHVectorImage scaleForSize:]` method that returns a `CGSize` containing the scale factors (both horizontal and vertical) to apply to scale the vector image to the given size. This basically returns the result of dividing the given `size` by the vector image's `nativeSize`, but also taking the `insets` into account.\n\n\u003e 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.\n\n#### Example\n\n```objc\nOHVectorImage* vImage = [OHVectorImage imageWithPDFNamed:@\"vector_image\"];\nvImage.backgroundColor = [UIColor colorWithRed:0.9 green:1.0 blue:0.9 alpha:1.0];\nvImage.tintColor = [UIColor redColor];\n// Shadow \u0026 Insets\nvImage.shadow = [NSShadow new];\nvImage.shadow.shadowOffset = CGSizeMake(2,2);\nvImage.shadow.shadowBlurRadius = 3.f;\nvImage.shadow.shadowColor = [UIColor darkGrayColor];\nvImage.insets = UIEdgeInsetsMake(0,0,5,5);\n// Render as an UIImage, ensuring to keep aspect ratio\nUIImage* image = [vImage renderAtSizeThatFits:imageViewSize];\n```\n\nA complete example is also available in the Demo project provided in this repo.\nDon'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!)\n\n## Loading a PDF document\n\nThe main goal of this library is to use PDF as images using the `UIImage` category or `OHVectorImage` class directly.\n\nHowever, 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.\n\nYou 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).  \nFor example, the following code read every page of a PDF as a vector image and build an animated `UIImage` from it:\n\n```objc\nNSURL* pdfURL = [[NSBundle mainBundle] URLForResource:@\"vector_images\" withExtension:@\"pdf\"];\nOHPDFDocument* doc = [OHPDFDocument documentWithURL:pdfURL];\nNSMutableArray* frames = [NSMutableArray arrayWithCapacity:doc.pagesCount];\nCGSize frameSize = CGSizeMake(100,100);\nfor(size_t pageNum = 0; pageNum \u003c doc.pagesCount; ++pageNum)\n{\n  OHPDFPage* page = [doc pageAtIndex:pageNum+1]; // Note: page indexes start at 1\n  OHVectorImage* vImage = [OHVectorImage imageWithPDFPage:page];\n  [frames addObject:[vImages renderAtSize:frameSize]];\n}\n\nNSTimeInterval duration = doc.pagesCount * 2.0; // 2.0s per frame \nUIImage* animatedImage = [UIImage animatedImageWithImages:frames\n                                                 duration:duration];\n```\n\n## License\n\nThis library is authored by Olivier Halligon and is distributed under the MIT License (see `LICENSE` file).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falisoftware%2Fohpdfimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falisoftware%2Fohpdfimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falisoftware%2Fohpdfimage/lists"}