webPDF Toolbox Webservice Image: Graphic Export

Minimum Technical Requirements​

  • Java version: 7
  • webPDF version: 7
  • wsclient version: 1

In this article, we use code examples to introduce the Image operation of the webPDF ToolboxWebService and show how to use it with the wsclient library.

Important Note​

The following code example is based on the webPDF wsclient library. To understand and apply it correctly, you should first read the relevant introductory blog post.

To follow this example exactly, you should call the webservice as shown here. First create a REST or SOAP session. Then use WebserviceFactory to create either a ToolboxWebService object for a SOAP session:

ToolboxWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

Or create a ToolboxRestWebService object for a REST session:

ToolboxRestWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

Then pass either a RestDocument or a SoapDocument object to this WebService object using the setDocument() method.

Password Protection: Getting Write Access​

How do you obtain write access to a document in order to modify it?

To gain write access, it is often necessary to pass the open and/or permission password of the document to the webservice call. You can do this on the created ToolboxWebService object:

toolboxWebService.getPassword().setOpen("password");
toolboxWebService.getPassword().setPermission("password");

If the document is not password-protected, you can skip this step.

The Image Webservice Parameter​

The ToolboxWebService is an endpoint of your webPDF server that combines a range of operations for manipulating PDF documents. One of these operations is Image, which serves as our example here.

The Image operation, in other words graphic export, lets you export pages from a PDF document as images.

You add an Image operation to your WebService object as follows:

ImageType image = new ImageType();
toolboxWebService.getOperation().add(image);

Possible Parameters on the Image Object​

pages (default value: "1")​

Defines the page range from which images should be created. You can specify a single page ("1"), a list of pages ("1,3,5"), a page range ("1-5"), or a combination of these elements ("1,3-5,6"). All pages of the document can be selected with "*".

image.setPages("1,3-5,6");

fileNameTemplate (default value: "page[%d]")​

If several pages of the document are exported, the individual images are usually stored in a ZIP archive. This template defines the name of the individual image files in the archive. The string "%d" must be included and is replaced by the page number.

image.setFileNameTemplate("p[%d]");

Selecting the Image Format​

If an object of type JpegType, GifType, PngType, TiffType, or BmpType is passed to the Image object, all exported images are created in the selected format.

First, we look at the common parameters and then briefly describe the special characteristics of the different formats.

The following parameters can be set on all of these objects:

metrics (default value: "mm")​

Specifies the unit used for the size values of the other parameters. The following values are available:

  • mm = Millimeters
  • px = Pixels
format.setMetrics(MetricsType.PX);

height (default value: 0)​

The maximum height of the exported images. A value of 0 means no limit.

format.setHeight(600);

width (default value: 0)​

The maximum width of the exported images. A value of 0 means no limit.

format.setWidth(600);

dpi (default value: 72)​

This parameter defines the DPI resolution of the image. The higher the value, the greater the X/Y resolution of the image. As the DPI increases, the byte size of the image file also increases.

format.setDpi(200);

The jpeg Image Format​

If a JpegType object is passed to the Image object, all exported images are created in JPEG format.

JpegType jpeg = new JpegType();
image.setJpeg(jpeg);

In addition to the standard parameters, the following parameter can also be set on the Jpeg object:

jpegQuality (default value: 80)​

This percentage value influences the compression of the generated JPEG images. It can be between 1 and 100. The higher the value, the lower the quality loss compared with the original, but the lower the image compression.

jpeg.setJpegQuality(100);

The bmp Image Format​

If a BmpType object is passed to the Image object, all exported images are created in bitmap format.

BmpType bmp = new BmpType();
image.setBmp(bmp);

No additional parameters are available for the bitmap format beyond the standard parameters.

The png Image Format​

If a PngType object is passed to the Image object, all exported images are created in PNG format.

PngType png = new PngType();
image.setPng(png);

No additional parameters are available for the PNG format beyond the standard parameters.

The gif Image Format​

If a GifType object is passed to the Image object, all exported images are created in GIF format.

GifType gif = new GifType();
image.setGif(gif);

No additional parameters are available for the GIF format beyond the standard parameters.

The tiff Image Format​

If a TiffType object is passed to the Image object, all exported images are created in TIFF format.

TiffType tiff = new TiffType();
image.setTiff(tiff);

In addition to the standard parameters, the following parameters can also be set on the Tiff object:

multipage (default value: false)​

If this value is set to true, a multipage TIFF is created for a multi-page export instead of a ZIP archive.

tiff.setMultipage(true);

compression (default value: false)​

This value defines the compression method for the exported TIFFs. The following values are available:

  • rle = TIFF CCITT Modified Huffman RLE compression
  • deflate = TIFF Deflate lossless compression, Zip-in-TIFF
  • group3 = TIFF CCITT Group 3 fax encoding
  • group4 = TIFF CCITT Group 4 fax encoding
  • jpeg = TIFF JPEG-in-TIFF compression
  • lzw = TIFF LZW compression
  • packbits = TIFF byte-oriented run-length encoding, PackBits compression
  • zlib = TIFF ZLib compression
tiff.setCompression(TiffCompressionType.DEFLATE);

Our Code Example​

Finally, here is a more detailed example of the full webservice call for addressing the SOAP interface:

try (
    // Set up a session with the webPDF server, here using SOAP.
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Provide the document to be processed and the target file.
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) catch (ResultException | MalformedURLException ex)

More code examples for webservices that you can use with the wsclient library can be found here.