Product Architecture

Packaging

DsImaging is a collection of cross-platform .NET class libraries written in C#, providing an API that allows to create image from scratch and to load, analyze and modify existing images.

DsImaging is compatible with .NET Core 2.x/3.x, .NET Standard 2.x, .NET Framework 4.6.2 or higher, and .NET 6 or higher.

DsImaging and supporting packages are available on nuget.org:

• DS.Documents.Imaging

• DS.Documents.Imaging.Windows

• DS.Documents.Imaging.Skia

• DS.Documents.DX.Windows

To use DsImaging in an application, you need to reference just the DS.Documents.Imaging package. It pulls in the required infrastructure packages.

On a Windows system, you can optionally install DS.Documents.Imaging.Windows. It contains GcWicBitmap class that works efficiently with various image formats and allows drawing text and graphics using DirectWrite/Direct2D-based functionality. Also, it provides support for font linking specified in the Windows registry. This library can be referenced on a non-Windows system, but does nothing.

DsImaging API Overview

Namespaces

DsImaging provides classes for three main purposes.

• Creating new images or loading images from various formats including multi-frame GIFs and TIFFs

• Drawing graphics and text on the in-memory bitmaps, applying various effects and transformation to the bitmaps

• Saving the resulting images as JPEG, PNG, BMP, multipage TIFF, multi-frame GIF or WebP.

DsImaging classes can be used efficiently in a multi-threaded environment. They don't depend on system handles or UI threads.

Image Containers

There are several containers in the DsImaging package (DS.Documents.Imaging) and in the related Windows specific package (DS.Documents.Imaging.Windows).

• GcBitmap is a platform-independent storage for raster images. You can access individual pixels as 32-bit unsigned integer values in the ARGB format where alpha component is the most significant byte. The Alpha channel is either pre-multiplied to Red, Green, Blue color channels or it is not pre-multiplied at all. GcBitmap can be encoded and saved to BMP, PNG, JPEG, GIF, TIFF, WebP or decoded and loaded from the same set of image formats.

• GrapeCity.Documents.Imaging.Windows.GcWicBitmap which resides in the DS.Documents.Imaging.Windows package, is very similar to GcBitmap but uses the Windows Imaging Component (WIC) subsystem for storing a raster image. GcWicBitmap supports various pixel formats and conversion between the formats. Usually, it works with 32-bit ARGB pixels and pre-multiplied Alpha channel. It is easy to copy such an image between GcWicBitmap and GcBitmap classes. GcWicBitmap can be saved to BMP, PNG, JPEG, GIF, TIFF, WebP, JPEGXR and loaded from BMP, PNG, JPEG, GIF, TIFF, WebP, JPEGXR, ICO image formats. It works faster than GcBitmap but is available only on the Windows platform and lacks some of the functionalities of GcBitmap such as direct pixel access.

• GrayscaleBitmap is a platform-independent storage for a grayscale image with 8 bits per pixel or an 8-bit transparency mask. It is four times more compact than GcBitmap. A full-color GcBitmap can be transformed to grayscale using GrayscaleEffect, and can easily be converted to GrayscaleBitmap. It is possible to save a GrayscaleBitmap to TIFF and load it from a TIFF file. Working with other image formats requires conversion to GcBitmap. GrayscaleBitmap is handy to use as a transparency mask to be applied to GcBitmap.

• BilevelBitmap is a compact storage for a bi-level transparency mask or an image containing two colors, such as black and white. To convert a full-color GcBitmap to BilevelBitmap, you need to apply the GrayscaleEffect, then apply one of the dithering or thresholding effects to make the image bi-level. The result can be stored as a BilevelBitmap. It supports saving to TIFF and loading from TIFF. You can read or modify individual pixels in BilevelBitmap and apply it to GcBitmap as a transparency mask.

• Indexed4bppBitmap and Indexed8bppBitmap are palette-based containers with 4-bit or 8-bit pixels containing indices of corresponding palette entries. These images can be saved to TIFF and loaded from TIFF. Indexed8bppBitmap can also be loaded from GIF and both Indexed4bppBitmap and Indexed8bppBitmap can be saved to GIF. It is easy to convert full-color GcBitmap to an indexed bitmap using one of the dithering algorithms. The palette entries and pixels are accessible for modifications.

• Image is a lightweight class representing the image in a file, stream, or array of bytes. You can draw the Image on GcGraphics, convert it to GcBitmap, or save to a MemoryStream in the original format.

Graphics

GrapeCity.Documents.Drawing.GcGraphics is an abstract base class for implementing graphics functionality for different targets. It allows to draw graphics primitives and text on various media, including GcBitmap, GcWicBitmap, and GcPdfDocument. The GcGraphics class offers roughly the same functionality as System.Drawing.Graphics class in WinForms but is platform-independent and provides implementations for different targets.

The GcBitmapGraphics class is derived from GcGraphics and allows to draw on a GcBitmap. Use GcBitmap.CreateGraphics() method to create an instance of GcBitmapGraphics. Likewise, GcWicBitmap.CreateGraphics() method creates an instance of GcWicBitmapGraphics that can be used to draw on a GcWicBitmap. Please note that you need to dispose the graphics objects after use.

Classes like GcBitmapGraphics and GcWicBitmapGraphics obey the universal object model for drawing with GcGraphics. Internally, both classes are based on more specific implementations targeting the actual media, such as GcBitmap or GcWicBitmap.

Renderer Classes

The target-specific renderer classes like BitmapRenderer for GcBitmap and GrapeCity.Documents.DX.Direct2D.RenderTarget for GcWicBitmap provide access to various fine-tuning settings and to methods not supported by the universal GcGraphics abstract class.

For example, you must work with BitmapRenderer to update anti aliasing setting or to enable multi threading during the rendering phase. An instance of BitmapRenderer is available through the GcBitmap.Renderer and GcBitmapGraphics.Renderer properties. An important feature provided by BitmapRenderer is the capability to work with lightweight objects called regions, that can be created from simple figures and graphics paths. Regions can be combined using various logical operations, then filled with brushes or used for clipping.

TIFF Reader/Writer

DsImaging has special support for multi page TIFF format. GcTiffReader allows to read individual images from a multi page TIFF file or stream. After the proper initialization, the user can access GcTiffReader.Frames property, which is a list of TiffFrame class instances. TiffFrame is a lightweight reference to the actual image data. It allows to read the frame image into one of the container classes, such as BilevelBitmap or GcBitmap. GcTiffReader works on any platform but has some limitations. For example, it does not currently support TIFF-JPEG compression scheme.

The GcWicTiffReader from GrapeCity.Documents.Imaging.Windows namespace in DS.Documents.Imaging.Windows package is a platform-dependent counterpart for GcTiffReader. It is based on the Windows Imaging Component subsystem and supports a few color spaces and compression schemes which are currently not available with platform-independent GcTiffReader. The Frames collection in GcWicTiffReader contains instances of the WicTiffFrame class. It allows to read frame images into the GcWicBitmap image container.

GcTiffWriter is a platform-independent class making it possible to create a multi page TIFF file or stream from a set of individual images. You can append images, such as GrayscaleBitmap, Indexed8bppBitmap and so on, to a GcTiffWriter and specify the detailed settings controlling the frame storage format and metadata using the TiffFrameSettings class. GcTiffWriter fully supports the Baseline TIFF specification and several TIFF extensions, such as tiled images, the Deflate compression scheme, associated and unassociated Alpha and other features.

GcWicTiffWriter is a Windows-specific WIC-based class that allows to write GcWicBitmaps to TIFF as separate frames. It does not offer much functionality beyond GcTiffWriter, but may be handy when drawing images to GcWicBitmap and saving them as a bunch.

GIF Reader/Writer

DsImaging has special support for multi-frame GIF format. GcGifReader allows to read individual frames. After the proper initialization, the user can access GcGifReader.Frames property, which is a list of GifFrame class instances. GifFrame is a lightweight reference to the actual image data. It allows to read the frame image into one of the container classes, such as Indexed8bppBitmap or GcBitmap.

GcGifWriter is a platform-independent class making it possible to create a multi-frame GIF file or stream from a set of individual images. You can append images, such as GrayscaleBitmap, Indexed8bppBitmap and so on, to a GcGifWriter and specify the detailed settings controlling the frame storage format and the playback (animation) properties.

DsHtml API Overview

DsHtml is a utility library that renders HTML to PDF file or an image in PNG, JPEG, and WebP format. DsHtml uses a Chrome or Edge browser (already installed in the current system, or downloaded from a public web site) in headless mode. Also, it doesn’t matter whether your .NET application is built for x64, x86 or AnyCPU platform target. The browser is continuously working in a separate process.

The DS.Documents.Html library consists of a platform-independent main package that exposes the HTML rendering functionality. The main package contains the following namespaces:

GrapeCity.Documents.Html.BrowserFetcher

The BrowserFetcher class has two static methods: GetSystemChromePath() and GetSystemEdgePath(). The methods return the path to an executable file of Chrome or Edge browsers correspondingly. Another option is to download and install Chromium into a local folder. You can create an instance of BrowserFetcher and pass the information such as host, platform, revision, and the destination folder, if needed. Then, execute the BrowserFetcher.GetDownloadedPath() method which downloads Chromium, if required, and returns the path to an executable file for running the Chromium.

GrapeCity.Documents.Html.GcHtmlBrowser

The GcHtmlBrowser class provides methods for converting HTML to PDF and images. With path to executable file for running the Chromium fetched using BrowserFetcher class, we can create an instance of GcHtmlBrowser class which effectively runs the browser process in the background. GcHtmlBrowser also accepts another parameter of LaunchOptions type. The LaunchOptions class provides various settings specific to launching the browser.

The class has two important methods: NewPage(Uri uri) and NewPage(string html). Both methods return an instance of HtmlPage class which represents a browser tab after navigating to the specified web address, file, or the arbitrary HTML content. The second parameter of PageOptions type provides various properties to be applied to the new browser page such as username, password for HTTP authentication, disabling JavaScript, lazy loading etc.

!type=note

Note:

• We recommend using Chrome browser with GcHtmlBrowser class as Edge has some differences in the implementation of some DevTools features.

• It is important to dispose every instance of the GcHtmlBrowser and HtmlPage classes after use.

Grapecity.Documents.Html.HtmlPage

The HtmlPage class represents a browser tab after navigating to the specified web address, file, or the arbitrary HTML content. The class has methods such as SaveAsPng, SaveAsJpeg, and SaveAsWebp to save the current page as a raster image of PNG, JPEG, or WebP formats respectively. The first parameter of these methods specifies the destination file or stream. The second parameter passes the additional options for rendering HTML page as single image, scaling or cropping the image, or setting the image quality.

The HtmlPage class contains the additional methods that help to interact with HTML page content. For example, you can obtain the full HTML content of the page using the GetContent method. The SetContent method updates the HTML markup. You can reload the web page with the Reload method or even execute a script in the browser context using the EvaluateExpression method. The WaitForNetworkIdle method helps with loading asynchronous web content.

GrapeCity.Documents.Html.ImageOptions

ImageOptions is the base abstract class for three specific classes: PngOptions, WebpOptions and JpegOptions. As compared to PngOptions and WebpOptions classes, the JpegOptions class has an additional property(CompressionQuality) for providing the JPEG compression quality (from 0% to 100%).

The FullPage property allows to capture the whole scrollable page. While the Clip property specifies the region to capture (if FullPage is false). Clip and Scale properties work with the result of layout. They allow to extract and scale some rectangular area and are applied before the rasterization stage. So, any graphics remains crisp with any scale factor. When exporting HTML to images the Dots Per Inch (DPI) is not set in the resulting image file. It requires some post-processing in order to set DPI.

GrapeCity.Documents.Drawing.HtmlToImageFormat

The HtmlToImageFormat class represents the formatting attributes for rendering HTML to GcGraphics as an image. Also, it helps converting HTML to a GcBitmap.

MaxTopMargin, MaxBottomMargin, MaxLeftMargin, MaxRightMargin properties specify the maximum allowable margins of the resulting image (larger margins will be trimmed), in pixels. Setting these properties to a negative value prevents trimming the margins. All those properties are equal to 0 by default which means no margins.

Other properties of HtmlToImageFormat are mapped to the corresponding properties of the ImageOptions/PageOptions class:

GcBitmapGraphics Extension Methods

DsHtml provides 2 methods that extend GcBitmapGraphics and allow to render an HTML text or page as an image:

• Draws an HTML string on this GcBitmapGraphics at a specified position.

  bool GcBitmapGraphics.DrawHtml(GcHtmlBrowser browser, string html, float x, float y, HtmlToImageFormat format, out SizeF size, bool loadLazyImages = false)

• Draws an HTML page provided by a URI on this GcBitmapGraphics at a specified position.

  bool GcBitmapGraphics.DrawHtml(GcHtmlBrowser browser, Uri htmlUri, float x, float y, HtmlToImageFormat format, out SizeF size, bool loadLazyImages = false)

Skia API Overview

Namespaces

Skia comprises the following main classes:

• GcSkiaBitmap: It represents a bitmap in CPU memory. It works similar to GcBitmap and GcWicBitmap but internally encapsulates an instance of SKBitmap object from SkiaSharp. GcSkiaBitmap can load images in JPEG, PNG, and WEBP formats and save images in the same formats. Also, you can convert GcSkiaBitmap to a GcBitmap or GcSkiaImage and vice versa. It is possible to draw text and graphics on GcSkiaBitmap after executing the CreateGraphics method which returns an instance of the associated GcSkiaGraphics.

• GcSkiaImage: It is an immutable image based on SKImage. It looks like a lightweight version of GcSkiaBitmap which does not support any modifications. You can load and save GcSkiaImage to the same formats as GcSkiaBitmap, and convert it to GcBitmap or GcSkiaBitmap. Both GcSkiaImage and GcSkiaBitmap implement the Image interface and hence can be drawn to any GcGraphics derived class.

• GcSkiaGraphics: It is the main drawing class which is derived from GcGraphics. You can create an instance of GcSkiaGraphics from either GcSkiaBitmap or directly. When the drawing is done you can simply dispose the graphics object in case of drawing to GcSkiaBitmap. If the GcSkiaGraphics object was created directly you can execute ToSkiaImage() or ToGcBitmap() methods to get a snapshot of the current drawing. If you draw text to multiple instances of GcSkiaGraphics please make sure that you created and assigned the same SkiaFontCache object to the FontCache property of all those instances.

For more information about Skia library, see Render using Skia Library.

!type=note

Note: In DsImaging release version 6.0.0, the GcHtmlRenderer class has been marked obsolete and has been replaced by the new GcHtmlBrowser class. This is done to avoid GPL or LGPL licensed software that had to be used in the custom chromium build. To know tips about migration from obsolete GcHtmlRenderer class, see Tips to Migrate from Obsolete GcHtmlRenderer class.