KnowledgePicker.WordCloud 1.3.1

.NET Standard 2.0
dotnet add package KnowledgePicker.WordCloud --version 1.3.1
NuGet\Install-Package KnowledgePicker.WordCloud -Version 1.3.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KnowledgePicker.WordCloud" Version="1.3.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add KnowledgePicker.WordCloud --version 1.3.1
#r "nuget: KnowledgePicker.WordCloud, 1.3.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install KnowledgePicker.WordCloud as a Cake Addin
#addin nuget:?package=KnowledgePicker.WordCloud&version=1.3.1

// Install KnowledgePicker.WordCloud as a Cake Tool
#tool nuget:?package=KnowledgePicker.WordCloud&version=1.3.1

WordCloud for .NET

Nuget GitHub

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.

Sample Word Cloud

How to use

  1. Install NuGet package KnowledgePicker.WordCloud.

    Note There's currently only one drawing engine based on SkiaSharp. On some platforms, additional dependencies need to be installed to make SkiaSharp work correctly. For example, on Linux, add SkiaSharp.NativeAssets.Linux; for Blazor WebAssembly, add SkiaSharp.Views.Blazor.

  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);
    

    You can also use SpecificColorizer to colorize specific words with chosen colors:

    var colorizer = new SpecificColorizer(
        new Dictionary<string, Color>
        {
            ["KnowledgePicker"] = Color.FromArgb(0x0f3057),
            ["WordCloud"] = Color.FromArgb(0xe25a5a)
        },
        fallback: new RandomColorizer()); // fallback argument is optional
    
  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);
        var color = wcg.GetColorHexString(item);
        <text transform="translate(@x, @y)" font-size="@fs" fill="@color">@item.Entry.Word</text>
    }
    </svg>
    
  6. Alternatively, we can draw the topic cloud (see also example WordFrequencies.ConsoleApp):

    using var final = new SKBitmap(wordCloud.Width, wordCloud.Height);
    using var canvas = new SKCanvas(final);
    
    // Draw on white background.
    canvas.Clear(SKColors.White);
    using var bitmap = wcg.Draw();
    canvas.DrawBitmap(bitmap, 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.

Testing

Tests are currently only supported on Linux, because they are snapshot tests (generating a word cloud image and comparing it byte-by-byte with a snapshot) and more work is needed to ensure this is cross-platform (e.g., use exactly the same font). On Windows, tests can be run in WSL (Visual Studio supports this directly). Tests are also automatically run in GitHub Actions.

Release process

After pushing a tag, GitHub workflow release.yml is triggered which builds and publishes the NuGet package.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.3.1 169 4/26/2023
1.3.0 1,348 12/22/2022
1.2.0 317 12/10/2022
1.1.2 698 10/1/2022
1.1.1 1,913 5/23/2022
1.1.0 754 4/4/2022
1.0.2 1,273 8/11/2021
1.0.1 2,119 3/20/2021
1.0.0 268 2/26/2021