Documents for Imaging, .NET Edition Documentation
In This Topic
    Product Architecture
    In This Topic

    Packaging

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

    GcImaging works on all platforms supported by .NET Standard, including .NET Core, ASP.NET Core, .NET Framework and so on.

    GcImaging and supporting packages are available on nuget.org:

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

    On a Windows system, you can optionally install Grapecity.Documents.Common.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.

    GcImaging API Overview

    Namespaces

    Namespaces Description
    GrapeCity.Documents.Common  Infrastructure and utility types (including fonts support).
    GrapeCity.Documents.Drawing Framework for drawing on the abstract GcGraphics surface.
    GrapeCity.Documents.Imaging Types used to create, process and modify images. Nested namespaces contain types supporting specific image spec areas:
    GrapeCity.Documents.Text Text processing sub-system.

    GcImaging provides classes for three main purposes.

    GcImaging 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 GcImaging package (GrapeCity.Document.Imaging) and in the related Windows specific package (GrapeCity.Documents.Common.Windows).

    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 GcBitmapGcWicBitmap, 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

    GcImaging 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 GrapeCity.Documents.Common.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 GrayscaleBitmapIndexed8bppBitmap 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

    GcImaging 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.

    GcHtml API Overview

    GcHtml is a utility library that renders HTML to PDF file or an image in PNG or JPEG format. It is based on the industry standard Chrome web browser engine working in headless mode, offering the benefit of rendering HTML to PDF or image on any platform - Windows, Linux and macOS. Currently, GcHtml works only on Intel-based 64-bit processor architecture. 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 GcHtml library consists of a platform-independent main package that exposes the HTML rendering functionality, and three platform-dependent packages that implement it on Windows, Linux and macOS. The main package must always be added to a project to use GcHtml. One or more platform-dependent packages should be added depending on the target platform(s) (all three can be added). GcHtml will select and use the correct package at runtime automatically.

    GcHtml NuGet Packages

    Description

    GrapeCity.Documents.Html

    The GrapeCity.Documents.Html package contains the following namespaces:

    • GrapeCity.Documents.Html namespace provides GcHtmlRenderer, PdfSettings, ImageSettings, PngSettings classes etc.
    • GrapeCity.Documents.Pdf namespace provides the GcPdfGraphicsExt and HtmltoPdfFormat classes.
    • GrapeCity.Documents.Drawing namespace provides GcGraphicsExt and HtmlToImageFormat class.
    GrapeCity.Documents.Html.Windows.X64 It is the interface unit and Chromium browser engine for 64-bit Windows platform.

    GrapeCity.Documents.Html.Mac.X64

    It is the interface unit and Chromium browser engine for macOS platform.

    GrapeCity.Documents.Html.Linux.X64

    It is the interface unit and Chromium browser engine for 64-bit Linux platform.

    Note that to use GcHtml on Linux, Chromium dependencies must be installed. The following command installs the necessary packages on Ubuntu:

    Copy Code
    sudo apt-get update
    sudo apt-get install libxss1 libappindicator1 libindicator7 libnss3-dev
    

    Namespaces

    Namespaces Description
    GrapeCity.Documents.Drawing

    It provides extension methods and formatting attributes for rendering HTML to image.

    The namespace comprises the following classes:

    GrapeCity.Documents.Html

    It provides methods for converting HTML to PDF or images and defines parameters for the PDF or image.

    The namespace comprises the following classes:

    GrapeCity.Documents.Pdf

    It provides the extension methods for rendering HTML to image and represents the formatting attributes for rendering HTML to image.

    The namespace comprises the following classes:

    GrapeCity.Documents.Html.GcHtmlRenderer

    The GcHtmlRenderer class provides methods for converting HTML to PDF and images. An instance of this class is created for each HTML page/string to be rendered. Also, it must be disposed after using to delete temporary files. GcHtmlRenderer class has two constructors, the one that accepts Uri to the source HTML page and the other that accepts HTML string. GcHtmlRenderer can convert the source HTML to the following formats: PDF, JPEG, PNG. The corresponding methods are RenderToPdf, RenderToJpegRenderToPng. All these methods accept the output file path as the first parameter. GcHtmlRenderer always saves the result to file.

    GrapeCity.Documents.Html.ImageSettings

    ImageSettings is the base abstract class for two specific classes: PngSettings and JpegSettings. The difference between two is that the latter one has an additional property – CompressionQuality providing the JPEG compression quality (from 0% to 100%).

    DefaultBackgroundColor provides the background color to be used if the HTML page doesn't specify one. When exporting HTML to PNG you can set DefaultBackgroundColor to Color.Transparent to draw HTML with transparent background. It looks like background colors with semi-transparency aren’t yet supported by the Chromium engine. The background can be either opaque or fully transparent.

    WindowSize specifies the virtual window size in pixels. It affects the layout of the source HTML page. The FullPage property allows to capture the whole scrollable page.

    The WindowSize and Clip property should not be mixed. 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, MaxBottomMarginMaxLeftMarginMaxRightMargin 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 ImageSettings class:

    HtmlToImageFormat Property ImageSettings Property
    MaxWindowWidth (in pixels, default is 1200, used only if FullPage is false) WindowSize.Width
    MaxWindowHeight (in pixels, default is 1600, used only if FullPage is false) WindowSize.Height
    WindowSize (defaults to 800x600, used only if FullPage is true) WindowSize
    DefaultBackgroundColor (default is Color.White) DefaultBackgroundColor
    Clip (unassigned by default) Clip
    Scale (default is 1.0) Scale
    FullPage (default is false) FullPage

    GcBitmapGraphics Extension Methods

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