How To Convert Common Documents to PNG Image Arrays in Java
In this article, we’ll learn how to easily convert a wide variety of common document formats to PNG image arrays using a web API in Java. Before we get to the demonstration portion of this article, we’ll first review the common logic behind converting documents to less flexible formats, and we’ll ultimately discuss the benefits PNG format offers over other common formats like PDF or JPG.
Why Convert Documents To Inflexible Formats?
File formats optimized for document editing and manipulation typically aren’t optimized for efficiency in other scenarios. There’s a long list of arguments to be made in favor of converting such documents to a static format (like PDF) for any scenario other than document editing and manipulation.
Content security is one of the strongest arguments among those. Document formats designed to be opened and manipulated within an editing application retain highly accessible and easily fungible properties by design, and that means unsolicited third parties (i.e., strangers with unknown) can make changes to our documents within those applications at will. The more technically adept folks among those can even make programmatic/automated changes to common document formats with minimal effort. There is, for example, no shortage of APIs and libraries designed to unzip and manipulate open office XML (OpenXML) files like XLSX, DOCX, or PPTX (I’ve written about quite a few of those in previous articles). Sharing or displaying Office documents publicly in their original format is asking for trouble; there’s a reason we hardly ever see that done in the real world.
It's not all about security, of course. Complex OpenXML files and other similar layered document formats are designed to retain a large amount of data in one place — including text, links, metadata, and multimedia — and that makes storing, transmitting, or streaming those files a burden at any kind of scale. For example, if we were to share a series of finalized Excel XLSX reports (complete with graphs and figures) with stakeholders in our network, we’d chew up a large amount of bandwidth in the process, and our transmission speed would suffer as a result. If we stored all those files together without compressing them, we’d consume a disproportionately high volume of our file storage allocation, which would likely prove costly over time — especially with modern pay-as-you-go cloud storage models. Similarly, if we were writing applications to pipeline Excel files into web-based file viewers on a web application portal (i.e., using an iframe tag), we’d likely slow down the loading speed of that page considerably.
In the real world, the result of these challenges is that most documents are commonly converted to a secure, static, and relatively simple format before entering a state of storage, transmission, or streaming. In most cases, that format is PDF.
Pros and Cons of PDF
PDF is the de facto publishing format for most common forms of content — especially OpenXML documents — and there’s a good reason for that. It’s accessible on any web browser, and it offers all kinds of security benefits while remaining compatible with myriad file rendering and processing applications. It can be structured as a multimedia vector file or a raster (bitmap) file, ensuring a wide range of unique content types can be accommodated for an equally wide range of display scenarios.
The problem PDF doesn’t solve immediately on its own, however, is compression. PDFs are still relatively complex files that often store layouts, fonts, vector graphics, document history, and document metadata in their file structure. Further, raster PDFs display pixels in bitmap format, which includes a higher range of color depths (e.g., 24-bit or 32-bit) by default than other image types. That makes raster PDFs a great choice for high-quality static document content displays and document printing, but a less advantageous choice for lightweight storage and transfer.
Choosing PNG Over JPG as a PDF Alternative
When the features and capabilities of PDF file structure are in excess of our needs, we can turn our attention to considerably simpler and lighter-weight format options. Among those options are two of the most common image formats found anywhere in the world: PNG and JPG.
Both formats offer significant compression capabilities, and JPG does so to a greater extent than PNG. With JPG, however, that compression comes at a much greater cost. The JPG compression algorithm attempts to reduce file size by removing some of the image details we don't usually notice as easily, using a combination of color subsampling (i.e., storing color information at a lower resolution than brightness information) and quantization (i.e., reducing the overall precision of color and brightness values within an image) among other techniques. JPG compressions become more and more noticeable over time, which makes converting detailed documents to JPG screenshots a somewhat risky endeavor. PNG, on the other hand, sacrifices a slightly larger ultimate file size for a compression algorithm that doesn’t discard data related to image quality. PNG compression employs concepts like predictive coding and pixel value filtering to optimize image data, and it uses Deflate Compression to identify repeated patterns in image data and replace those with shorter codes. Resulting PNG files might be slightly larger than JPG, but their quality is assured to remain consistent over time, making them an excellent option for storing and displaying high-quality document content.
Demonstration
In the demonstration portion of this article, we’ll learn step-by-step how to call a free API that automatically detects and converts a wide range of input document types (including all major Office document formats, PDFs, and over 100 different image formats) to PNG image arrays. In practice, it's effectively an automated screenshotting solution we can slot directly into our Java web applications. It optimizes the download process post-conversion by returning PNG file contents as an array of temporary URLs (one per PNG image) which can be subsequently downloaded and converted to file bytes. To use this API, we’ll just need a free API key, which will give us a limit of 800 API calls to use each month.
To begin structuring our API call, we’ll first install the Maven SDK (jitpack is used to dynamically compile the library). Let’s add a reference to the repository in pom.xml.
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>And after that, let’s add a reference to the dependency in pom.xml:
<dependencies>
<dependency>
<groupId>com.github.Cloudmersive</groupId>
<artifactId>Cloudmersive.APIClient.Java</artifactId>
<version>v4.25</version>
</dependency>
</dependencies>In our next step, we’ll add the following imports to the top of our file:
// Import classes:
//import com.cloudmersive.client.invoker.ApiClient;
//import com.cloudmersive.client.invoker.ApiException;
//import com.cloudmersive.client.invoker.Configuration;
//import com.cloudmersive.client.invoker.auth.*;
//import com.cloudmersive.client.ConvertDocumentApi;And right after that, we’ll add the configuration snippet to capture our API key:
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: Apikey
ApiKeyAuth Apikey = (ApiKeyAuth) defaultClient.getAuthentication("Apikey");
Apikey.setApiKey("YOUR API KEY");
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//Apikey.setApiKeyPrefix("Token");Finally, we’ll add the below snippet to create an instance of the API and call the function to make our conversion:
ConvertDocumentApi apiInstance = new ConvertDocumentApi();
File inputFile = new File("/path/to/inputfile"); // File | Input file to perform the operation on.
try {
AutodetectToPngResult result = apiInstance.convertDocumentAutodetectToPngArray(inputFile);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling ConvertDocumentApi#convertDocumentAutodetectToPngArray");
e.printStackTrace();
}We can handle the conversion from temporary URLs to PNG file bytes in a few different ways. We could make a secondary API call (from the same library and following the same basic structure as before) with the following code to handle that:
// Import classes:
//import com.cloudmersive.client.invoker.ApiClient;
//import com.cloudmersive.client.invoker.ApiException;
//import com.cloudmersive.client.invoker.Configuration;
//import com.cloudmersive.client.invoker.auth.*;
//import com.cloudmersive.client.EditDocumentApi;
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure API key authorization: Apikey
ApiKeyAuth Apikey = (ApiKeyAuth) defaultClient.getAuthentication("Apikey");
Apikey.setApiKey("YOUR API KEY");
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//Apikey.setApiKeyPrefix("Token");
EditDocumentApi apiInstance = new EditDocumentApi();
FinishEditingRequest reqConfig = new FinishEditingRequest(); // FinishEditingRequest | Cloudmersive Document URL to complete editing on
try {
byte[] result = apiInstance.editDocumentFinishEditing(reqConfig);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling EditDocumentApi#editDocumentFinishEditing");
e.printStackTrace();
}Alternatively, we could use java.net.HttpURLConnection from the java.net class (a fundamental part of the JDK). This allows us to create a URL object from the file URL, read and write file bytes from the URL, and convert the byte stream into downloadable file content.
In either case, we just need to write our file bytes to new PNG documents, and we can easily store, transmit, or stream that content anywhere downstream from our conversion workflow.
Conclusion
In this article, we learned how to convert documents to PNG as an alternative to using PDF or JPG format. We reviewed some of the reasons why documents are best stored, transported, and streamed in static image formats, and we learned how PNG offers lightweight lossless compression in a way that PDF and JPG aren’t capable of.
