Home

Awesome

VectSharp: a light library for C# vector graphics

<img src="icon.svg" width="256" align="right">

License: LGPL v3 Version Downloads

Full documentation with interactive examples

Introduction

VectSharp is a library to create vector graphics (including text) in C#, without too many dependencies.

VectSharp is written using .NET Core, and is available for Mac, Windows and Linux. Since version 2.0.0, it is released under an LGPLv3 license. It includes 14 standard fonts, originally released under an ASL-2.0 license.

It includes an abstract layer on top of which output layers can be written. Currently, there are five available output layers:

VectSharp.Raster and VectSharp.Raster.ImageSharp are somewhat overlapping, as both of them can be used to create PNG images. However, VectSharp.Raster is much faster, though it only supports the PNG format. Instead, VectSharp.Raster.ImageSharp is slower, but supports more formats and has a more permissive licence. Another difference is that VectSharp.Raster carries a native dependency (through MuPDFCore), while VectSharp.ImageSharp does not.

Furthermore:

<p style="text-align: center"> <img src="https://user-images.githubusercontent.com/32712606/209444145-e4833187-37a7-4682-9f64-a16d1d03d84c.gif" style="width: 90%"> </img> </p>

Installing VectSharp

To include VectSharp in your project, you will need one of the output layer NuGet packages: VectSharp.PDF, VectSharp.Canvas, VectSharp.Raster, VectSharp.Raster.ImageSharp, or VectSharp.SVG. You will need VectSharp.ThreeD to work with 3D graphics or VectSharp.Plots to create plots. You may want the VectSharp.MuPDFUtils package if you wish to manipulate raster images, and the VectSharp.Fonts.Nimbus if you want to restore the GPL-licensed fonts used in previous versions of the library.

Usage

You can find detailed documentation for the VectSharp library, including interactive examples, at the documentation website. A comprehensive API reference is also available, both as a website and as a PDF manual.

In general, working with VectSharp involves: creating a Document, adding Pages, drawing to the Pages' Graphics objects and, finally, exporting them to a PDF document, Canvas, PNG image or SVG document.

using VectSharp;
// ...
Document doc = new Document();

doc.Pages.Add(new Page(1000, 1000));

Graphics gpr = doc.Pages.Last().Graphics;
gpr.FillRectangle(100, 100, 800, 800, Colour.FromRgb(128, 128, 128));

using VectSharp.PDF;
//...
doc.SaveAsPDF(@"Sample.pdf");

using VectSharp.Canvas;
//...
Avalonia.Controls.Canvas can = doc.Pages.Last().PaintToCanvas();

using VectSharp.Canvas;
//...
// A single page
Avalonia.Controls.Canvas can = doc.Pages.Last().PaintToSKCanvas();

// The whole document - each page will correspond to a layer
Avalonia.Controls.Canvas can = doc.PaintToSKCanvas();

using VectSharp.Raster;
//...
doc.Pages.Last().SaveAsPNG(@"Sample.png");

using VectSharp.Raster.ImageSharp;
//...
doc.Pages.Last().SaveAsImage(@"Sample.jpg");

using VectSharp.SVG;
//...
doc.Pages.Last().SaveAsSVG(@"Sample.svg");

using VectSharp;
using VectSharp.PDF;
using VectSharp.SVG;
//...
Document document = new Document();
Page page = new Page(1000, 1000);
document.Pages.Add(page);

page.Graphics.FillRectangle(100, 100, 800, 50, Colour.FromRgb(128, 128, 128), tag: "linkToGitHub");
page.Graphics.FillRectangle(100, 300, 800, 50, Colour.FromRgb(255, 0, 0), tag: "linkToBlueRectangle");
page.Graphics.FillRectangle(100, 850, 800, 50, Colour.FromRgb(0, 0, 255), tag: "blueRectangle");

Dictionary<string, string> links = new Dictionary<string, string>() { { "linkToGitHub", "https://github.com/" }, { "linkToBlueRectangle", "#blueRectangle" } };

page.SaveAsSVG(@"Links.svg", linkDestinations: links);
document.SaveAsPDF(@"Links.pdf", linkDestinations: links);

This code produces a document with three rectangles: the grey one at the top links to the GitHub home page, while the red one in the middle is a hyperlink to the blue one at the bottom. Links in PDF documents can refer to objects that are in a different page than the one containing the link.

The public classes and methods are fully documented (with interactive examples created using Blazor), and you can find a (much) more detailed code example in MainWindow.xaml.cs. A detailed guide about 3D graphics in VectSharp.ThreeD is available in the VectSharp.ThreeD folder. Further example code for animations is available in the DemoAnimation project.

Font libraries

Since version 2.0.0, font names are resolved using a "font library". This is a class that implements the VectSharp.IFontLibrary interface, providing methods to obtain a FontFamily object from a string or a FontFamily.StandardFontFamilies enumeration. The default font library included in VectSharp uses the embedded fonts (Arimo, Tinos, Cousine) as the standard font families.

In practice, assuming you want to use the default font library, you have the following options to create a FontFamily object:

using VectSharp;

// ...

FontFamily helvetica = FontFamily.ResolveFontFamily(FontFamily.StandardFontFamilies.Helvetica); // Will resolve to the Arimo font family.
FontFamily times = FontFamily.ResolveFontFamily("Times-Roman"); // Will resolve to the Tinos font family.

These replace the FontFamily(string) and FontFamily(StandardFontFamilies) constructors of previous versions of VectSharp. Overloads of this method let you specify a list of "fallback" fonts that will be used if the first font you specify is not available.

If you wish, you can replace the default font library with a different one; this will change the way font families are resolved. For example, after installing the VectSharp.Fonts.Nimbus NuGet package, you can do:

using VectSharp;

// ...

FontFamily.DefaultFontLibrary = VectSharp.Fonts.Nimbus.Library;

FontFamily helvetica = FontFamily.ResolveFontFamily(FontFamily.StandardFontFamilies.Helvetica); // Will resolve to the Nimbus Sans L font family.
FontFamily times = FontFamily.ResolveFontFamily("Times-Roman"); // Will resolve to the Nimbus Roman No 9 L font family.

This will let you re-enable the fonts that were used in previous versions of VectSharp.

You can also use multiple font libraries in the same project. Again, assuming you have installed the VectSharp.Fonts.Nimbus NuGet package:

using VectSharp;

FontFamily helvetica1 = FontFamily.ResolveFontFamily(FontFamily.StandardFontFamilies.Helvetica); // Will resolve to the Arimo font family.
FontFamily times1 = FontFamily.ResolveFontFamily("Times-Roman"); // Will resolve to the Tinos font family.

FontFamily helvetica2 = VectSharp.Fonts.Nimbus.ResolveFontFamily(FontFamily.StandardFontFamilies.Helvetica); // Will resolve to the Nimbus Sans L font family.
FontFamily times2 = VectSharp.Fonts.Nimbus.ResolveFontFamily("Times-Roman"); // Will resolve to the Nimbus Roman No 9 L font family.

Finally, you can create your own font library class (which could implement things such as dowloading fonts from Google Fonts, or finding them in the user's system font directory...) by creating a class that implements the IFontLibrary interface or that extends the FontLibrary class (in this latter case, you get a default implementation for the ResolveFontFamily overloads that use a list of fallback fonts).

Creating new output layers

VectSharp can be easily extended to provide additional output layers. To do so:

  1. Create a new class implementing the IGraphicsContext interface.
  2. Provide an extension method to either the Page or Document types.
  3. Somewhere in the extension method, call the CopyToIGraphicsContext method on the Graphics object of the Pages.
  4. Opportunely save or return the rendered result.

Compiling VectSharp from source

The VectSharp source code includes an example project (VectSharp.Demo) presenting how VectSharp can be used to produce graphics.

To be able to compile VectSharp from source, you will need to install the latest .NET SDK for your operating system.

You can use Microsoft Visual Studio to compile the program. The following instructions will cover compiling VectSharp from the command line, instead.

First of all, you will need to download the VectSharp source code: VectSharp.tar.gz and extract it somewhere.

Windows

Open a command-line window in the folder where you have extracted the source code, and type:

BuildDemo <Target>

Where <Target> can be one of Win-x64, Linux-x64 or Mac-x64 depending on which platform you wish to generate executables for.

In the Release folder and in the appropriate subfolder for the target platform you selected, you will find the compiled program.

macOS and Linux

Open a terminal in the folder where you have extracted the source code, and type:

./BuildDemo.sh <Target>

Where <Target> can be one of Win-x64, Linux-x64 or Mac-x64 depending on which platform you wish to generate executables for.

In the Release folder and in the appropriate subfolder for the target platform you selected, you will find the compiled program.

If you receive an error about permissions being denied, try typing chmod +x BuildDemo.sh first.

Note about VectSharp.MuPDFUtils and .NET Framework

If you wish to use VectSharp.MuPDFUtils in a .NET Framework project, you will need to manually copy the native MuPDFWrapper library for the platform you are using to the executable directory (this is done automatically if you target .NET core).

One way to obtain the appropriate library files is:

  1. Manually download the NuGet package for MuPFDCore (click on the "Download package" link on the right).
  2. Rename the .nupkg file so that it has a .zip extension.
  3. Extract the zip file.
  4. Within the extracted folder, the library files are in the runtimes/xxx-yyy/native/ folder, where xxx is either linux, osx or win, depending on the platform you are using, and yyy is x64, x86 or arm64 depending on the architecture.

Make sure you copy the appropriate file to the same folder as the executable!