Image rendering

CreateSvg returns markup that a browser draws. When you need pixels, for an email, a mobile application or a file to upload, CreateScene returns the same avatar as a Scene of Vector graphics: a shape and a text, with the same colors and initials.

Draw an avatar as a PNG

Meziantou.Framework.Imaging.VectorGraphics draws scenes as images. Add it to the project:

dotnet package add Meziantou.Framework.Imaging.VectorGraphics

Then lay the avatar out with the measurer of the fonts that draw the image, and draw it with ToImage. The example also uses the Meziantou.Framework.Imaging.VectorGraphics and Meziantou.Framework.Imaging.Formats namespaces:

// Lay the avatar out with the fonts that draw the image, so the initials are centered
var measurer = SceneImageRenderer.CreateMeasurer();
var scene = AvatarGenerator.CreateScene("John Doe", new AvatarOptions { Size = 128 }, measurer);

using var image = scene.ToImage();
Assert.Equal((128, 128), (image.Width, image.Height));

// Save to a file (image.Save("avatar.png")) or to a stream, in any format
using var png = new MemoryStream();
image.Save(png, new PngEncoder());

The initials are centered with the metrics of the measurer, so pass the measurer of the fonts that draw the image: CreateMeasurer with the same SceneImageOptions as ToImage. Without a measurer, the scene is laid out with the metrics of Helvetica (AfmTextMeasurer), for an SVG: the capital letters are centered, whatever font of the Helvetica and Arial family the viewer draws them with. Scale multiplies the pixels, for high-density screens.

Fonts

By default, the image is drawn with the fonts of Meziantou.Framework.Imaging.VectorGraphics: Liberation Sans, bold, subset to the Latin characters. Initials in other scripts, such as 山田 or an emoji, need a font that has them. Put the fonts in a SceneFontCollection, the main font first, and pass it in SceneImageOptions.Fonts to CreateMeasurer. The characters the main font does not have are drawn with the other fonts of the collection. See the fonts of image rendering.

CreateScene sets the fonts of the measurer as the fonts of the scene (Scene.Fonts), so ToImage draws the initials with the fonts that measured them, without options. To write the SVG of such a scene with its fonts, set SvgRenderOptions.EmbedFonts: every viewer then draws the initials with these fonts.

The SVG of CreateSvg uses a monospace font, while a scene uses the font of the measurer, so initials such as WM are wider: the scene draws them with a smaller font when they would be wider than the shape.

Use the scene

The scene is a regular Scene: its first element is the shape, a SceneCircle or a SceneRectangle, and its second is the SceneText of the initials. Add elements to it, such as a status badge, or write it as SVG with SvgSceneRenderer:

// The scene holds the shape and the initials: add elements, or write it as SVG
var scene = AvatarGenerator.CreateScene("Ada Lovelace", new AvatarOptions { Shape = AvatarShape.RoundedSquare });
var initials = scene.Root.Children.OfType<SceneText>().Single();
Assert.Equal("AL", initials.Text);

var svg = SvgSceneRenderer.Render(scene);
Assert.StartsWith("<svg ", svg);

The title of the scene is the accessible label: the bigram, or AccessibleLabel. It is null when IsDecorative is true.

Colors

A scene needs colors it can draw, so every pair of the palette must use a color that SceneColor.Parse accepts: #rgb, #rrggbb, #rrggbbaa, rgb(), hsl() or a CSS color name. CreateScene throws an ArgumentException for any other color, such as var(--accent) or currentColor, which only CreateSvg supports.