Compressing and Converting Images

In ImageGear, both compression and conversion operations are closely related with Saving; these two operations are performed in ImageGear by setting some optional control parameters during saving operation.

On one hand, image compression can be accomplished by manipulating the specific parameters of the filter corresponding to the target format File Formats Reference. Such a filter can be accessed by passing the appropriate ImGearFormats value to the Get method of ImGearFileFilters object; see Loading and Saving for more information.

On the other hand, image conversion is associated with saving an image by specifying a relevant set of options through an instance of ImGearSaveOptions. ImageGear supports a variety of pixel formats (color spaces and channel depths). For more information, the user can refer to File Formats. However, most image file formats support only a limited set of pixel formats. For example, PNG format does not support CMYK color space, and JPEG Lossy format does not support storing 16-bit per channel pixel values. ImageGear provides conversion from a source image's pixel format into one of the pixel formats supported by the destination image file format.

Availability of a specific pixel format for saving depends on the requested compression, saving options, and filter control parameters.

ImageGear uses the following logic to select the pixel format for saving:

If the format filter directly supports saving of an image's pixel format, ImageGear uses this pixel format;
Otherwise, if the format filter supports saving of pixel formats that exceed the image's pixel format (so no image quality degradation occurs), ImageGear uses the one that takes least storage space;
Otherwise, ImageGear uses the pixel format that results in the least degradation of image quality.

A special case is when the image color space has to be converted, and multiple choices of channel depths are available. In that case, ImageGear selects channel depths that are equal to the image's channel depths, rather than larger channel depths. This results in a slightly worse quality degradation, but avoids an unexpected increase in image size. For example, PNG format does not support CMYK color space, but it supports storing 8- or 16-bits per channel. ImageGear saves a 32-bit CMYK to PNG as 24-bit RGB rather than 48-bit RGB. ImageGear does not support conversion from multichannel truecolor color spaces (RGB, CMYK, etc.) into an indexed color space during saving.

Use the ImGearSaveOptions.ConversionMode property to specify the acceptability of image quality degradation or bit depth promotion during saving.
Use the ImGearSaveOptions.ForceColorspace property to make ImageGear use a specific color space for saving.

Example

The following code demonstrates how to convert a PNG image to a compressed JPG format image. For this example, we set the Lossy compression parameters for a local JPG filter. Then, we use an instance of ImGearSaveOptions object to set the conversion options for the output image. It is worth noticing how we combine image compression and conversion: set the parameter Filters of ImGearSaveOptions with the local JPG filter designed for compression.

For an example of how to convert a PDF document to an image, see PDF > How to... > Convert...

using ImageGear.Core;
using ImageGear.Formats;
using ImageGear.Formats.JPG;

// JPG Compression.
public ImGearFileFilters SetJPGCompressionParameters(ImGearJpegSaveType jpegSaveType, int quality)
{
    // Create local control parameters for the filter corresponding to the format to be compressed (i.e. the global filter is not modified).
    ImGearFileFilters localFilters = new ImGearFileFilters();

    // Get control parameters for the target format.
    ImGearFormatParameters formatParameters = localFilters.Get(ImGearFormats.JPG).Parameters;

    // Set output type for JPG format.
    // Possible values: ImGearJpegSaveType.Lossy; ImGearJpegSaveType.Lossless; ImGearJpegSaveType.Progressive.
    formatParameters.GetByName("SaveType").Value = (int)(jpegSaveType);

    // Set quality for Lossy compression ([1, 100]).
    // The lower the setting, the greater the number of original pixels lost, and therefore the smaller the resulting compressed file will be.
    formatParameters.GetByName("Quality").Value = quality;

    return localFilters;
}

// Set common image save options for conversion.
public ImGearSaveOptions SetConversionParameters()
{
    ImGearSaveOptions saveOptions = new ImGearSaveOptions();

    // Set conversion mode.
    // Allow any conversion supported by ImageGear: ImGearRasterConversionModes.ANY.
    // See ImGearRasterConversionModes enumerator for more options.
    saveOptions.ConversionMode = ImGearRasterConversionModes.ANY;

    // Set target color space.
    // Preserve source color space: ImGearColorSpaceIDs.NONE.
    // See ImGearColorSpaceIDs enumerator for more options.
    saveOptions.ForceColorspace = ImGearColorSpaceIDs.NONE;

    // (Optional). Use only if we want to conduct compression.
    // Set the filters for JPG Lossy compression.
    // The lower the setting, the greater the number of original pixels lost, and therefore the smaller the resulting compressed file will be.
    saveOptions.Filters = SetJPGCompressionParameters(ImGearJpegSaveType.Lossy, 30);

    return saveOptions;
}

// Save PNG image converted and compressed to JPG format based on the options available in ImageGear.
public void SavePNGToJPG(ImGearPage loadedPNGPage, string outputJPGFilePath)
{
    // Specify options for saving.
    ImGearSaveOptions saveJPGOptions = SetConversionParameters();
    ImGearSavingFormats destinationFormat = ImGearSavingFormats.JPG;

    // Save to JPG file.
    using (FileStream fileStream = new FileStream(outputJPGFilePath, FileMode.OpenOrCreate, FileAccess.ReadWrite))
    {
        ImGearFileFormats.SavePage(loadedPNGPage, fileStream, 0, ImGearSavingModes.OVERWRITE, ImGearSavingFormats.JPG);
    }
}

VB.NET

Imports ImageGear.Core
Imports ImageGear.Formats
Imports ImageGear.Formats.JPG

' JPG Compression.
Public Function SetJPGCompressionParameters(jpegSaveType As ImGearJpegSaveType, quality As Integer) As ImGearFileFilters

    ' Create local control parameters for the filter corresponding to the format to be compressed (i.e. the global filter is not modified).
    Dim localFilters As New ImGearFileFilters()

    ' Get control parameters for the target format.
    Dim formatParameters As ImGearFormatParameters = localFilters.[Get](ImGearFormats.JPG).Parameters

    ' Set the parameters related with the compression intended.
    ' Set output type for JPG format.
    ' Possible values: ImGearJpegSaveType.Lossy; ImGearJpegSaveType.Lossless; ImGearJpegSaveType.Progressive.
    formatParameters.GetByName("SaveType").Value = CInt(jpegSaveType)

    ' Set quality for Lossy compression ([1, 100]).
    ' The lower the setting, the greater the number of original pixels lost, and therefore the smaller the resulting compressed file will be.
    formatParameters.GetByName("Quality").Value = quality

    Return localFilters

End Function

' Set common image save options for conversion.
Public Function SetConversionParameters() As ImGearSaveOptions

    Dim saveOptions As New ImGearSaveOptions()

    ' Set conversion mode.
    ' Allow any conversion supported by ImageGear: ImGearRasterConversionModes.ANY.
    ' See ImGearRasterConversionModes enumerator for more options.
    saveOptions.ConversionMode = ImGearRasterConversionModes.ANY

    ' Set target color space.
    ' Preserve source color space: ImGearColorSpaceIDs.NONE.
    ' See ImGearColorSpaceIDs enumerator for more options.
    saveOptions.ForceColorspace = ImGearColorSpaceIDs.NONE

    ' (Optional). Use only if we want to conduct compression.
    ' Set the filters for JPG Lossy compression.
    ' The lower the setting, the greater the number of original pixels lost, and therefore the smaller the resulting compressed file will be.
    saveOptions.Filters = SetJPGCompressionParameters(ImGearJpegSaveType.Lossy, 50)

    Return saveOptions

End Function

' Save PNG image converted and compressed to JPG format based on the options available in ImageGear.
Public Sub SavePNGToJPG(loadedPNGPage As ImGearPage, outputJPGFilePath As String)

    ' Specify options for saving.
    Dim saveJPGOptions As ImGearSaveOptions = SetConversionParameters()

    Dim destinationFormat As ImGearSavingFormats = ImGearSavingFormats.JPG

    ' Save to JPG file.
    Using fileStream As New FileStream(outputJPGFilePath, FileMode.OpenOrCreate, FileAccess.ReadWrite)
        ImGearFileFormats.SavePage(loadedPNGPage, fileStream, 0, ImGearSavingModes.OVERWRITE, ImGearSavingFormats.JPG)
    End Using

End Sub