SVG Size, Bounds and Flat

The main class for handling SVG documents in LEADTOOLS is the Leadtools.Svg.SvgDocument class.

Size, Bounds and Flat

A SVG (Scalable Vector Graphics) format document may or may not have a size. If the document has a size, it is stored in the width and height attributes of the root svg element and can be in any coordinate system. An SVG renderer will typically use this value to determine the final bounding rectangle of the document. If it is omitted, it will require this information to be supplied externally (for example, by using the parent container of the SVG). A unit of measurement is also required to convert all coordinate system to physical pixels. This is called the viewport of the document.

SVG documents contain a hierarchy of elements. The final transformation (such as position and size) and style (such as color and fill) can depend on the transformation and style of the parent(s) inside the hierarchy. An SVG renderer has to calculate and keep track of this information when outputting the document to a device for viewing. This procedure is defined by LEADTOOLS as flattening the document. A document that does not have the transformation/styles applied on the child elements is defined as a non-flat document by LEADTOOLS. A document that has the transformation/styles applied to the child elements is defined as a flat document by LEADTOOLS.

To render an SVG document, the following steps are usually performed:

• The document is flattened so that each child element has its final transformation/style applied.

• The viewport is used to place or render each element into its final position and size.

• Rendering is performed.

SvgDocument Support

The Leadtools.Svg.SvgDocument class can handle any type of SVG (with or without a size, flat, or non-flat). However, to render the document or to extract final element position and size, any missing information must be either be calculated automatically or supplied by the user.

To convert a non-flat document to a flat one, in-place, use the SvgDocument.Flat method. This method accepts an SvgFlatOptions parameter that can contain the final desired size of the document in pixels. If this parameter is omitted or the value of the size is 0, then SvgDocument will try calculating the final size automatically. When this method returns, the transformation and style values will be applied to each child element. Use SvgDocument.ToFlat to perform flattening on a target document without modifying the source.

To determine whether a document is flat, call the SvgDocument.IsFlat property. This as an internal state saved by the class and will be false if SvgDocument.Flat has not been called on the document previously. The SvgDocument.SetFlat method can be used to set or reset the state of this flag manually if desired.

The size and final viewport of a flat SVG document can be calculated using the SvgDocument.CalculateBounds method. This method will use the current size information (if available) plus the physical position, size, and transformation of each element to compute the final size in pixels and the resolution of the document. This method will store the value in the SvgDocument.Bounds property.

SvgDocument.CalculateBounds accepts a Boolean value that controls whether to ignore the current size information (if available), and purely use the child element's position and size (trimmed) or use the size if available (non-trimmed). SvgDocument.CalculateBounds will fail if the document is not flat.

SvgDocument.Bounds is of type SvgBounds. To determine whether the size of the document has been calculated, use the SvgBounds.IsValid property. This is an internal state saved by this class and will be false if SvgDocument.CalculateBounds has not been called on the document previously. The SvgBounds.Bounds and SvgBounds.Resolution contain the physical bounding rectangle in pixels and the resolution in DPI of the document, respectively. The SvgDocument.SetBounds method can be used to set or reset the bounds manually if desired.

When loading an SVG document directly using SvgDocument.LoadFromFile, SvgDocument.LoadFromStream or SvgDocument.LoadFromMemory, no flattening or size calculation will take place. The document is loaded as is.

When using RasterCodecs.LoadSvg or DocumentsPage.GetSvg to convert a page from any document or vector to SVG, the resulting document may or may not contain size, bounds or flat information.

SvgDocument.Render is used to render an SVG document to a target device. This method requires a flat document with valid bounds. For more information, refer to SVG Rendering.

The following code illustrates how to render a document by automatically checking its flat and bounds state:

void RenderDocument(IRenderingEngine engine, SvgRenderOptions options, SvgDocument svgDocument) 
{ 
   // If the document is not flat, flatten it and automatically calculate its size 
   if (!svgDocument.IsFlat) 
      svgDocument.Flat(null); 
             
   // If the document does not have valid bounds, calculate it now automatically 
   var svgBounds = svgDocument.Bounds; 
   if (!svgBounds.IsValid) 
      svgDocument.CalculateBounds(false); 
             
   // Now, render the document 
   svgDocument.Render(engine, options); 
} 

Some parts of LEADTOOLS will automatically perform flattening and calculation of SVG bounds as illustrated above (for example, setting an SVG document in an image viewer (ImageViewer) using ImageViewerItem.SvgDocument or an SVG ImageViewerItem.Url.)

Working With SVG SVG Rendering