KnowledgePicker.WordCloud 1.1.0

WordCloud for .NET

KnowledgePicker.WordCloud is a modern (.NET Standard 2.0) and fast library for arranging and drawing word clouds (a.k.a. tag clouds or wordle). It uses Quadtrees for blazing-fast performance. It is maintained by the KnowledgePicker team.

How to use

1. Install NuGet package KnowledgePicker.WordCloud.

2. Get collection of WordCloudEntrys. For example, suppose we have dictionary of word frequencies:

   var frequencies = new Dictionary<string, int>();
   // ...collect word frequencies somehow...
   IEnumerable<WordCloudEntry> wordEntries = frequencies.Select(p => new WordCloudEntry(p.Key, p.Value));
   

3. Create world cloud configuration:

   var wordCloud = new WordCloudInput(wordEntries)
   {
       Width = 1024,
       Height = 256,
       MinFontSize = 8,
       MaxFontSize = 32
   };
   

4. We need to create drawing engine, font sizer and layout. Currently, we use SkiaSharp for fast cross-platform font measuring (and drawing). We also only support logarithmic font sizes and spiral layout. All these things are implemented in a generic way and can be easily extended (contributions are welcome).

   var sizer = new LogSizer(wordCloud);
   using var engine = new SkGraphicEngine(sizer, wordCloud);
   var layout = new SpiralLayout(wordCloud);
   var colorizer = new RandomColorizer(); // optional
   var wcg = new WordCloudGenerator<SKBitmap>(wordCloud, engine, layout, colorizer);
   

5. Now we can arrange the topic cloud:

   IEnumerable<(LayoutItem Item, double FontSize)> items = wcg.Arrange();
   

   And if we are in a Razor view of an ASP.NET Core application, for example, we can generate SVG from items:

   <svg viewBox="0,0,@wordCloud.Width,@wordCloud.Height">
   @foreach (var (item, fontSize) in items)
   {
       const string format = "0.##"; // Use at most 2 decimal places.
       var x = (item.Location.X - item.Measured.Left).ToString(format);
       var y = (item.Location.Y - item.Measured.Top).ToString(format);
       var fs = fontSize.ToString(format);
       <text transform="translate(@x, @y)" font-size="@fs">@item.Entry.Word</text>
   }
   </svg>
   

6. Alternatively, we can draw the topic cloud (see also example WordFrequencies.ConsoleApp):

   using var bitmap = new SKBitmap(wordCloud.Width, wordCloud.Height);
   using var canvas = new SKCanvas(bitmap);
   
   // Draw on white background.
   canvas.Clear(SKColors.White);
   canvas.DrawBitmap(wcg.Draw(), 0, 0);
   
   // Save to PNG.
   using var data = final.Encode(SKEncodedImageFormat.Png, 100);
   using var writer = File.Create("output.png");
   data.SaveTo(writer);
   

Algorithm

The world cloud algorithm was initially ported from SourceCodeCloud. It uses Quadtrees, hence it should be reasonably fast. It is inspired by implementation of Wordle (once famous algorithm used on now-defunct site wordle.net).

Examples

Simple console application which draws word cloud PNG for words given on its standard input is WordFrequencies.ConsoleApp.

This library is also used in production by KnowledgePicker. They use it to draw topic clouds for user profiles.

Contributing

As mentioned above, only subset of functionality is implemented now, but all contributions are welcome. Feel free to open issues and pull requests.

Creating NuGet package

Until we have a CI pipeline, this is how we release new version of the package (don't forget to replace 1.0.0 with the correct version):

cd src/KnowledgePicker.WordCloud
dotnet pack -c Release --include-symbols --include-source -p:PackageVersion=1.0.0