👁 Image
Sdcb.WordCloud 2.0.1

Sdcb.WordCloud 👁 NuGet

English |

Sdcb.WordCloud is a versatile, cross-platform library for generating word cloud images, SVGs, or JSON data based on word frequencies. It harnesses the power of SkiaSharp for graphical operations, ensuring high performance and quality without relying on System.Drawing. This makes it an excellent choice for applications running across various platforms, including server-side scenarios where GUI libraries might not be available.

Key Features

• Cross-platform compatibility: Works across different operating systems without dependency on System.Drawing.
• Multiple output formats: Supports generating word clouds as images, SVGs, or JSON data.
• Flexible configuration: Customize your word clouds with various options, including text orientations, fonts, and masks.
• Open-source: Freely available under the MIT license, welcoming contributions and modifications.

Installation

To start using Sdcb.WordCloud in your project, install it via NuGet:

dotnet add package Sdcb.WordCloud

Usage Example

Below are some examples showcasing different capabilities of the Sdcb.WordCloud library. Note: The demonstrations use a shared word frequency list, as provided in the method MakeDemoScore().

Example 1: Different Text Orientations

This example demonstrates creating word clouds with 5 different text orientations.

void Main()
{
 TextOrientations[] orientations = 
 [
 TextOrientations.PreferHorizontal, // default
 TextOrientations.PreferVertical, 
 TextOrientations.HorizontalOnly,
 TextOrientations.VerticalOnly, 
 TextOrientations.Random,
 ];
 foreach (var o in orientations)
 {
 WordCloud wc = WordCloud.Create(new WordCloudOptions(600, 600, MakeDemoScore())
 {
 TextOrientation = o,
 });
 byte[] pngBytes = wc.ToSKBitmap().Encode(SKEncodedImageFormat.Png, 100).AsSpan().ToArray();
 File.WriteAllBytes($"{o}.png", pngBytes);
 }
}

Example 2: Converting Word Cloud to JSON and Back

Generate a word cloud, convert it to JSON, and then reconstruct it to demonstrate the flexibility of manipulating word cloud data.

void Main()
{
 WordCloud wc = WordCloud.Create(new WordCloudOptions(900, 900, MakeDemoScore())
 {
 FontManager = new FontManager([SKTypeface.FromFamilyName("Times New Roman")]),
 Mask = MaskOptions.CreateWithForegroundColor(SKBitmap.Decode(
 new HttpClient().GetByteArrayAsync("https://io.starworks.cc:88/cv-public/2024/alice_mask.png").GetAwaiter().GetResult()),
 SKColors.White)
 });
 string json = wc.ToJson();
 Console.WriteLine(json);

 // can convert back from generated json
 WordCloud wc2 = WordCloud.FromJson(json);
 File.WriteAllText($"json-convert-back.svg", wc2.ToSvg());
}

Note: This example illustrates how a word cloud's data can be stored in and reconstructed from JSON, enabling easy sharing and modification.

Example 3: Applying a Mask

Creating a word cloud with a mask, allowing words to fill a specific shape.

void Main()
{
 WordCloud wc = WordCloud.Create(new WordCloudOptions(900, 900, MakeDemoScore())
 {
 FontManager = new FontManager([SKTypeface.FromFamilyName("Times New Roman")]),
 Mask = MaskOptions.CreateWithForegroundColor(SKBitmap.Decode(
 new HttpClient().GetByteArrayAsync("https://io.starworks.cc:88/cv-public/2024/alice_mask.png").GetAwaiter().GetResult()),
 SKColors.White)
 });
 byte[] pngBytes = wc.ToSKBitmap().Encode(SKEncodedImageFormat.Png, 100).AsSpan().ToArray();
 File.WriteAllBytes($"mask.png", pngBytes);
}

Example 4: Using a Specific Font

Demonstrates how to utilize a specific font for the word cloud generation.

void Main()
{
 WordCloud wc = WordCloud.Create(new WordCloudOptions(600, 600, MakeDemoScore())
 {
 FontManager = new FontManager([SKTypeface.FromFamilyName("Consolas")])
 });
 byte[] pngBytes = wc.ToSKBitmap().Encode(SKEncodedImageFormat.Png, 100).AsSpan().ToArray();
 File.WriteAllBytes($"specified-font.png", pngBytes);
}

Example 5: Generating SVG Output

Shows how to generate an SVG from a word cloud, useful for web applications where scalability is crucial.

void Main()
{
 WordCloud wc = WordCloud.Create(new WordCloudOptions(900, 900, MakeDemoScore())
 {
 FontManager = new FontManager([SKTypeface.FromFamilyName("Times New Roman")]),
 Mask = MaskOptions.CreateWithForegroundColor(SKBitmap.Decode(
 new HttpClient().GetByteArrayAsync("https://io.starworks.cc:88/cv-public/2024/alice_mask.png").GetAwaiter().GetResult()),
 SKColors.White)
 });
 File.WriteAllText($"json-convert-back.svg", wc.ToSvg());
 //new Svg(wc.ToSvg(), wc.Width, wc.Height).Dump();
}

Shared Word Frequency List

All examples use the following word frequency list:

static IEnumerable<WordScore> MakeDemoScore()
{
 string text = """
 459 cloud
 112 Retrieved
 88 form
 78 species
 74 meteorolog
 66 type
 62 ed.
 54 edit
 53 cumulus
 52 World
 50 into
 50 level
 49 Organization
 49 air
 48 International
 48 atmosphere
 48 troposphere
 45 Atlas
 45 genus
 44 cirrus
 43 convection
 42 vertical
 40 altitude
 40 stratocumulus
 38 high
 38 weather
 37 climate
 37 layer
 36 cumulonimbus
 35 appear
 35 variety
 34 more
 34 water
 33 altocumulus
 33 feature
 33 low
 31 formation
 31 other
 28 precipitation
 28 produce
 27 .mw-parser-output
 27 name
 27 surface
 27 very
 26 base
 25 April
 25 ISBN
 25 also
 25 origin
 24 cirrocumulus
 24 color
 24 cool
 24 stratiformis
 24 stratus
 23 Earth
 23 structure
 22 altostratus
 22 cumuliform
 22 doi
 22 genera
 22 physics
 22 result
 22 see
 22 stratiform
 22 usual
 21 general
 21 p.
 21 seen
 21 temperature
 21 than
 20 polar
 20 space
 20 top
 19 Bibcode
 19 National
 19 cirrostratus
 19 fog
 19 lift
 19 mostly
 19 over
 18 Archived
 18 Latin
 18 Universe
 18 group
 18 sometimes
 18 supplementary
 18 tower
 18 warm
 17 January
 17 change
 17 light
 17 main
 17 nimbostratus
 17 occur
 17 only
 17 stratocumuliform
 17 unstable
 17 wind
 16 associated
 16 cause
 16 global
 16 instability
 16 mid-level
 16 nasa
 16 new
 16 noctilucent
 16 range
 16 science
 16 show
 16 tend
 15 accessory
 15 any
 15 cirriform
 15 droplets
 15 during
 15 extent
 15 multi-level
 15 near
 15 one
 15 rain
 15 reflect
 15 stratosphere
 15 used
 14 J.
 14 October
 14 PDF
 14 airmass
 14 become
 14 common
 14 converge
 14 crystal
 14 cyclone
 14 front
 14 high-level
 14 observes
 14 stable
 14 system
 14 white
 13 all
 13 along
 13 because
 13 classify
 13 each
 13 fibratus
 13 higher
 13 identify
 13 increase
 13 large
 13 mesosphere
 13 sun
 12 castellanus
 12 classification
 12 compose
 12 condenses
 12 congestus
 12 effect
 12 fractus
 12 heavy
 12 include
 12 low-level
 12 moderate
 12 process
 12 radiation
 12 resemble
 12 solar
 12 term
 12 vapor
 12 zone
 11 August
 11 Ci
 11 February
 11 July
 11 M.
 11 March
 11 November
 11 b.
 11 conditions
 11 different
 11 ground
 11 known
 11 lead
 11 most
 11 occasional
 11 often
 11 perlucidus
 11 pressure
 11 research
 11 satellite
 11 saturated
 11 severe
 11 storm
 11 thunderstorm
 11 tornado
 11 visible
 """;

 return text
 .Split("\n")
 .Select(x => x.Trim().Split("\t"))
 .Select(x => new WordScore(Score: int.Parse(x[0]), Word: x[1]));
}

License

Sdcb.WordCloud is open-source software licensed under the MIT license.