Using the Library

Working with XpdfImageExtract

The XpdfImageExtract library uses an opaque handle (type PDFHandle) to represent a PDF file. Multiple PDF files can be open simultaneously (each with its own handle).

Any program that uses the library must include the XpdfImageExtract header file:

#include "XpdfImageExtract.h"

Using XpdfImageExtract, you can load PDF files and extract images. Typical code looks like this:

PDFHandle pdf; int i, mask, colorSpace, w, h; err = pdfLoadFile(&pdf, "c:/test/file.pdf"); if (err != pdfOk) { /* handle the error */ } /* extract images on page 1 */ pdfGetImages(pdf, 1); for (i = 0; i < pdfGetNumImages(pdf); ++i) { pdfGetImageInfo(pdf, i, &mask, &colorSpace, &w, &h); printf(" %d: %s %d x %d\n", i, mask ? "mask" : "image", w, h); }

Using XpdfImageExtract in a multithreaded application

In a multithreaded application, the pdfInitLibrary function must be called before any other functions are called. Unlike in single-thread applications where this is optional, the pdfInitLibrary call is required in multithreaded applications. Each PDF handle must be used by only one thread. Given that constraint, all XpdfImageExtract functions (other than pdfInitLibrary) are thread-safe.

Compiling & linking on Windows

The XpdfImageExtract library is supplied as a DLL (XpdfImageExtract.dll) and an import library (XpdfImageExtract.lib).

The following instructions are for Microsoft Visual C++ 6. Similar steps should work for other development environments.

Add the include file directory: in the "Project Settings" dialog, under the "C/C++" tab, in the "Preprocessor" category, add the library include file directory (....\XpdfImageExtract\include).
Add the import library: in the "Project Settings" dialog, under the "Link" tab, in the "General" category, add the library (....\XpdfImageExtract\lib\XpdfImageExtract.lib).
Either add the library directory (....\XpdfImageExtract\lib) to your executable search path, or copy XpdfImageExtract.dll into the same directory as your application's executable.

Compiling & linking on Linux

The XpdfImageExtract library is supplied as a shared library (libXpdfImageExtract.so).

When compiling C or C++ code that uses the XpdfImageExtract library, you'll need to supply a "-I" flag pointing to the directory containing the XpdfImageExtract includes. When linking, you'll need to supply a "-L" flag pointing to the directory containing the XpdfImageExtract library, and a "-lXpdfImageExtract" flag to link with the library.

gcc -c -I/usr/local/XpdfImageExtract/include application.c gcc -o application application.o \ -L/usr/local/XpdfImageExtract/lib -lXpdfImageExtract

Look at the Makefile in the example code for a complete demonstration.

Before running the application, make sure that the XpdfImageExtract library directory is on the library search path. This this can be done either by setting the LD_LIBRARY_PATH environment variable or by editing the system-wide /etc/ld.so.conf configuration file.

Compiling & linking on Mac OS X

Using XpdfImageExtract on OS X is very similar to using it on Linux. The shared library has a different extension (libXpdfImageExtract.dylib), and you'll need to set the DYLD_LIBRARY_PATH environment variable.

Example code

The XpdfImageExtract library distribution includes two sample programs, dumpImages.c and dumpImages2.c, located in the examples directory. These programs demonstrate the use of the various XpdfImageExtract functions. Both programs dump all images from a PDF file to separate image files (PBM/PPM on Unix, BMP on Windows). dumpImages.c extracts the images to memory and then creates the image files; dumpImages2.c uses XpdfImageExtract's save-to-file functions.

To build on Linux, edit the included Makefile and set the XPDFLIBDIR, XPDFINCDIR, and LIB variables according to the instructions inside the Makefile. Then run "make".

To build on Windows, create a Visual C++ project, as described above.