Thumbnails

A document list with a preview of each file, a template picker that shows the first page of every template, a page overview before a document is signed: all of them need page images. The thumbnails endpoint of the DocumentProcessing Web API renders the pages of a document as images, in the size and format you choose, and returns one image per page.

How Thumbnails Work

The endpoint is POST /documentprocessing/document/thumbnails:

SVG was added in version 3.2.0. An image format the endpoint doesn't support and invalid page numbers are refused with 400 Bad Request.

Every request needs an access token, as Authentication describes.

Thumbnails on Linux

When DS Server runs on Linux, the Core build doesn't render documents as bitmaps: SVG is its only rendering format, as the changelog of version 4.0 states. Request imageFormat=SVG there: PNG, JPG, GIF and BMP are bitmap formats. The Core build also supports only DOCX, HTML, PDF and XLSX documents on Linux. Limits on Linux lists all limits.

Create Thumbnails With curl

The following commands render the first three pages of document.docx at half their size and save each image as a file:

DS=http://localhost:5000
TOKEN="<access_token>"

# Wrap the Base64 string of the document in a JSON string
base64 -w 0 document.docx | jq -Rs . > document.json

curl --request POST "$DS/documentprocessing/document/thumbnails?imageFormat=PNG&zoomFactor=50&fromPage=1&toPage=3" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @document.json \
  --output thumbnails.json

# Decode each Base64 string of the array into page-1.png, page-2.png ...
count=$(jq length thumbnails.json)
for i in $(seq 0 $((count - 1))); do
  jq -r ".[$i]" thumbnails.json | base64 -d > "page-$((i + 1)).png"
done

The commands work as follows:

• base64 -w 0 encodes the file without line breaks, and jq -Rs . makes a JSON string of it, which is the whole body.
• The query parameters select the pages and the size. Leave out fromPage and toPage to render every page.
• The response is an array with one Base64 string per page. jq -r ".[$i]" takes one element without quotes, and base64 -d decodes it into an image file.

On Linux, replace PNG with SVG in the url and save the files as page-1.svg and so on.

Create Thumbnails With .NET

The package TXTextControl.DocumentServices.DocumentProcessing returns the images as byte arrays, one per page:

using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

byte[] document = File.ReadAllBytes("document.docx");

// Pages 1 to 3 at a zoom factor of 50 percent
byte[][] pages = await documentProcessing.Thumbnails(document, 50, 1, 3, ImageFormat.PNG);

for (int i = 0; i < pages.Length; i++)
{
    File.WriteAllBytes($"page-{i + 1}.png", pages[i]);
}

The code works as follows:

• The DocumentProcessing constructor takes the service URL and the credentials of a security profile, and requests an access token.
• Thumbnails takes the document, the zoom factor, the first and the last page and an ImageFormat value. The package decodes the Base64 strings, so each element of the result is the image file itself.
• ImageFormat has the values PNG, JPG, BMP and GIF and, in version 5.0.0 of the package, also SVG.

Shorter overloads leave out the trailing arguments and create PNG images: Thumbnails(document) renders every page at 100 percent, and Thumbnails(document, zoomFactor), Thumbnails(document, zoomFactor, fromPage) and Thumbnails(document, zoomFactor, fromPage, toPage) set the size and the pages. A longer overload adds a sixth argument, maxImageResolution. The package sends it as a query parameter of the same name, with the value 96 when you use an overload without it; DS Server 5.0.2 accepts the parameter, which the endpoint reference doesn't describe. The classes are listed in the DocumentProcessing namespace of the .NET API.

Choose the Size and the Pages

• Size. zoomFactor is a percentage of the page size, from 1 to 400. A value of 100, the default, renders the page at its full size, and smaller values give smaller images for a preview list.
• First page only. For a single preview image of a document, set fromPage=1&toPage=1, or pass 1, 1 as the page arguments in C#.
• Every page. Leave out fromPage and toPage, or use the overloads without them, and the array has one image for every page of the document.

Next Steps

• Converting Documents: convert the document itself into another format.
• Document Information: read the properties and the merge structure of a document.
• Supported File Formats: the formats of each endpoint.
• Errors and Status Codes: what a refused request means.