Tutorial: Converting to Image Formats

In this tutorial, you’ll learn how to convert various document types to image formats using GroupDocs.Conversion Cloud API. You’ll master conversions to JPG, PNG, TIFF, and other image formats with full control over image quality, resolution, and other parameters.

Learning Objectives

By the end of this tutorial, you will be able to:

Convert documents to various image formats (JPG, PNG, TIFF, BMP, etc.)
Customize image conversion options including quality, resolution, and color settings
Implement multi-page document conversion with page control
Handle both storage-based and stream-based image conversions
Troubleshoot common image conversion challenges

Prerequisites

Before starting this tutorial, you need:

A GroupDocs.Conversion Cloud account
Your Client ID and Client Secret credentials
Basic understanding of REST API concepts
Development environment with your preferred programming language set up
Sample documents to test conversion (we’ll use various formats including PDF and Word)

Implementation Steps

Step 1: Authentication with GroupDocs.Conversion Cloud API

Before performing any operations, we need to authenticate with the API using your Client ID and Client Secret.

Try it yourself

First, let’s obtain a JWT access token using cURL:

# First get JSON Web Token
curl -v "https://api.groupdocs.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

Step 2: Basic Document to Image Conversion

Let’s start with a basic conversion from a Word document to JPG format:

Try it yourself

Using cURL:

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion" \
-H "accept: application/json" \
-H "authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d "{  
      'FilePath': 'documents/sample.docx',  
      'Format': 'jpg',  
      'OutputPath': 'converted'
    }"

Don’t forget to replace YOUR_JWT_TOKEN with the actual token received in Step 1.

The response will contain URLs to the converted image files (one per page):

[
  {
    "name": "sample-page-1.jpg",
    "size": 107611,
    "url": "MyStorage:converted/sample-page-1.jpg"
  },
  {
    "name": "sample-page-2.jpg",
    "size": 45075,
    "url": "MyStorage:converted/sample-page-2.jpg"
  }
]

Step 3: Converting to JPG with Quality and Color Options

Now let’s implement a complete example that converts a document to JPG with specific image conversion options:

// C# SDK Example
using System;
using System.Collections.Generic;
using GroupDocs.Conversion.Cloud.Sdk.Api;
using GroupDocs.Conversion.Cloud.Sdk.Client;
using GroupDocs.Conversion.Cloud.Sdk.Model;
using GroupDocs.Conversion.Cloud.Sdk.Model.Requests;

namespace ImageConversionTutorial
{
    class Program
    {
        static void Main(string[] args)
        {
            // Configure API client
            var configuration = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
            var apiInstance = new ConvertApi(configuration);

            try
            {
                // Set up conversion from DOCX to JPG with options
                var settings = new ConvertSettings
                {
                    StorageName = "MyStorage",
                    FilePath = "documents/sample.docx",
                    Format = "jpg",
                    // For password-protected documents
                    LoadOptions = new DocxLoadOptions() { Password = "" },
                    // JPG-specific convert options
                    ConvertOptions = new JpegConvertOptions()
                    {
                        FromPage = 1,              // Start from first page
                        PagesCount = 2,            // Convert first two pages
                        Quality = 100,             // Maximum quality (1-100)
                        Grayscale = false,         // Color image (not grayscale)
                        RotateAngle = 0,           // No rotation
                        UsePdf = false,            // Direct conversion (not via PDF)
                        Dpi = 300                  // 300 DPI resolution
                    },
                    OutputPath = "converted"
                };

                // Execute conversion
                List<StoredConvertedResult> response = apiInstance.ConvertDocument(
                    new ConvertDocumentRequest(settings));
                
                Console.WriteLine("Document converted successfully to images: " + response.Count);
                foreach (var image in response)
                {
                    Console.WriteLine(" - " + image.Name + " (" + image.Size + " bytes)");
                }
            }
            catch (Exception e)
            {
                Console.WriteLine("Error: " + e.Message);
            }
        }
    }
}

Step 4: Converting to PNG with Background Color Setting

PNG is ideal for documents with transparency or when lossless compression is required:

// Java SDK Example
import com.groupdocs.cloud.conversion.api.*;
import com.groupdocs.cloud.conversion.client.ApiException;
import com.groupdocs.cloud.conversion.model.*;
import com.groupdocs.cloud.conversion.model.requests.*;
import java.util.List;

public class DocumentToPngExample {
    public static void main(String[] args) {
        // Configure API client
        String clientId = "YOUR_CLIENT_ID";
        String clientSecret = "YOUR_CLIENT_SECRET";
        Configuration configuration = new Configuration(clientId, clientSecret);
        ConvertApi apiInstance = new ConvertApi(configuration);
        
        try {
            // Prepare convert settings
            ConvertSettings settings = new ConvertSettings();
            settings.setFilePath("documents/sample.pdf");
            settings.setFormat("png");
            
            // Set PDF-specific load options if needed
            PdfLoadOptions loadOptions = new PdfLoadOptions();
            loadOptions.setPassword("");  // If PDF is protected
            settings.setLoadOptions(loadOptions);
            
            // Configure PNG-specific convert options
            PngConvertOptions convertOptions = new PngConvertOptions();
            convertOptions.setFromPage(1);
            convertOptions.setPagesCount(3);
            convertOptions.setDpi(300);
            convertOptions.setBackgroundColor("white"); // Set background color
            
            settings.setConvertOptions(convertOptions);
            settings.setOutputPath("converted");
            
            // Execute conversion
            List<StoredConvertedResult> result = apiInstance.convertDocument(
                new ConvertDocumentRequest(settings));
            
            System.out.println("Document converted successfully to PNG: " + result.size() + " images");
            for (StoredConvertedResult image : result) {
                System.out.println(" - " + image.getName() + " (" + image.getSize() + " bytes)");
            }
        } catch (ApiException e) {
            System.err.println("Exception when calling ConvertApi: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Step 5: Converting to TIFF (Multi-page Image)

TIFF is useful when you want to store multiple pages in a single image file:

# Python SDK Example
import groupdocs_conversion_cloud
from groupdocs_conversion_cloud.models.requests import ConvertDocumentRequest

# Configure API client
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
api_instance = groupdocs_conversion_cloud.ConvertApi.from_keys(client_id, client_secret)

try:
    # Prepare conversion settings
    settings = groupdocs_conversion_cloud.ConvertSettings()
    settings.file_path = "documents/multipage.pdf"
    settings.format = "tiff"
    
    # Configure PDF-specific load options
    load_options = groupdocs_conversion_cloud.PdfLoadOptions()
    load_options.password = ""  # If PDF is protected
    
    settings.load_options = load_options
    
    # Configure TIFF-specific convert options
    convert_options = groupdocs_conversion_cloud.TiffConvertOptions()
    convert_options.from_page = 1
    convert_options.pages_count = 5
    convert_options.dpi = 200
    convert_options.width = 1200        # Specify width in pixels
    convert_options.height = 800        # Specify height in pixels
    convert_options.brightness = 50     # Adjust brightness (0-100)
    convert_options.contrast = 50       # Adjust contrast (0-100)
    convert_options.gamma = 0.5         # Adjust gamma
    convert_options.rotation_angle = 0  # No rotation
    
    settings.convert_options = convert_options
    settings.output_path = "converted"
    
    # Execute conversion
    request = ConvertDocumentRequest(settings)
    result = api_instance.convert_document(request)
    
    print(f"Document converted successfully to TIFF: {len(result)} files")
    for image in result:
        print(f" - {image.name} ({image.size} bytes)")
except groupdocs_conversion_cloud.ApiException as e:
    print(f"Exception when calling ConvertApi: {e}")

Step 6: Stream-Based Conversion to Image Format

For applications that need to process the converted images directly:

// Node.js SDK Example
const { ConvertApi, Configuration } = require("groupdocs-conversion-cloud");
const fs = require("fs");

// Configure API client
const clientId = "YOUR_CLIENT_ID";
const clientSecret = "YOUR_CLIENT_SECRET";
const config = new Configuration(clientId, clientSecret);
const apiInstance = new ConvertApi(config);

// Prepare conversion settings
const settings = {
    filePath: "documents/sample.docx",
    format: "jpg",
    loadOptions: {
        // DOCX-specific load options if needed
    },
    convertOptions: {
        // JPG-specific convert options
        fromPage: 1,
        pagesCount: 2,
        quality: 90,
        grayscale: false,
        rotateAngle: 0
    },
    // Set outputPath to null for stream output
    outputPath: null
};

// Execute conversion
apiInstance.convertDocumentDownload({ convertSettings: settings })
    .then((result) => {
        // Create a folder for storing images if it doesn't exist
        if (!fs.existsSync("./images")) {
            fs.mkdirSync("./images");
        }
        
        // Save the stream to a file
        const fileName = "./images/converted-image.jpg";
        const writeStream = fs.createWriteStream(fileName);
        
        result.pipe(writeStream);
        
        writeStream.on("finish", () => {
            console.log(`Document converted and saved to ${fileName}`);
        });
    })
    .catch((error) => {
        console.log(`Error: ${error.message}`);
    });

Image-Specific Conversion Options

When converting to image formats, you can leverage these specialized options:

Option	Description	Applicable Formats	Default
FromPage	First page number to convert	All	1
PagesCount	Number of pages to convert	All	All pages
Dpi	Resolution in dots per inch	All	96
Width	Width of the resulting image	All	Automatic
Height	Height of the resulting image	All	Automatic
Quality	Image quality (1-100)	JPG	90
Grayscale	Convert to grayscale	JPG, PNG, TIFF, BMP	false
RotateAngle	Rotation angle	All	0
UsePdf	Use PDF as intermediate format	All	false
BackgroundColor	Background color	PNG, BMP	“white”
Brightness	Image brightness (0-100)	TIFF	50
Contrast	Image contrast (0-100)	TIFF	50
Gamma	Image gamma (0.0-2.0)	TIFF	1.0

Troubleshooting Common Issues

1. Image Quality Issues

If the converted images have poor quality:

Increase the DPI value (200-300 is recommended for good quality)
For JPG format, increase the quality setting (90-100 for high quality)
If text appears blurry, try enabling the UsePdf option for better text rendering

2. Size and Resolution Problems

If the images aren’t the expected size:

Explicitly set both width and height parameters
If aspect ratio is important, set only one dimension (width or height) and let the API calculate the other
For very large documents, consider increasing DPI gradually to avoid memory issues

3. Color and Appearance Issues

If colors don’t match the original document:

For PNG, try different background color settings
For JPG, adjust quality, and disable grayscale if color is needed
For TIFF, adjust brightness, contrast, and gamma settings

4. Multi-page Document Handling

When working with multi-page documents:

Use the FromPage and PagesCount parameters to control which pages are converted
For large documents, consider processing pages in batches to avoid timeouts
Remember that each page typically generates a separate image file (except for multi-page TIFF)

What You’ve Learned

In this tutorial, you’ve learned:

How to convert various document formats to different image formats
Customizing image conversion options for optimal quality and appearance
Controlling page selection for multi-page document conversion
Implementing both storage-based and stream-based image conversions
Troubleshooting common image conversion challenges

Further Practice

To reinforce your learning, try these exercises:

Create a thumbnail generator that converts each page to a small PNG image
Build a document previewer that shows document pages as images in a web interface
Implement a batch conversion utility that processes multiple documents to images
Create a service that automatically optimizes image quality based on content type

Additional Resources

Have questions about this tutorial? Feel free to reach out on our forum for support.