wordcloud-d3 0.1.0

Generate offline static D3 word-cloud HTML from plain text, idioms, or frequency files.

wordcloud-d3

Generate offline static D3 word-cloud HTML from plain text, idiom lexicons, or pre-counted frequency files.

The generated HTML is self-contained: D3 and d3-cloud are bundled into the page, so the result can be opened without a server or internet connection. The page also includes a Save PNG button that exports the rendered SVG word cloud in the browser.

Install

pip install wordcloud-d3

For spaCy tokenization, install the optional extra and whichever spaCy model you want to use:

pip install "wordcloud-d3[spacy]"
python -m spacy download en_core_web_sm
python -m spacy download zh_core_web_sm

You can also install the optional idiom-scanning speedup:

pip install "wordcloud-d3[speedups]"

Quick Start

Frequency-file mode is the most direct:

future 12
language 9
research 7

wordcloud-d3 counts.txt --mode freq -o cloud.html

Open cloud.html in a browser, then click Save PNG to download the image.

Common Options

wordcloud-d3 input.txt `
  --mode words `
  --nlp-backend jieba `
  --max-words 160 `
  --aspect-ratio 16:9 `
  --background-text CLOUD `
  --high-color "#d62828" `
  --low-color "#111111" `
  --background-color "#fafaf6"

--asp-ratio is accepted as a short alias for --aspect-ratio.

Supported aspect ratios:

1:1, 4:3, 3:2, 16:9, 3:4, 2:3, 9:16

spaCy Models

The --spacy-model option is intentionally free-form. Pass any installed spaCy pipeline name or local model path:

wordcloud-d3 input.txt --mode words --nlp-backend spacy --spacy-model en_core_web_lg
wordcloud-d3 input.txt --mode words --nlp-backend spacy --spacy-model zh_core_web_sm
wordcloud-d3 input.txt --mode words --nlp-backend spacy --spacy-model ./models/custom_pipeline

Modes

• words: tokenize source text with jieba by default, or spaCy when selected.
• idiom: scan source text against the bundled idiom lexicon CSV.
• freq: parse pre-counted lines like word 12, word,12, or word<TAB>12.

Python API

from wordcloud_d3.cli import render_html

html = render_html(
    words=[{"text": "future", "count": 12, "rank": 1}],
    title="Demo",
    subtitle="1 word",
    background_text="",
    red_ratio=0.1,
    gray_ratio=0.25,
    vertical_ratio=0.2,
    aspect_ratio="16:9",
)