Metadata-Version: 2.4
Name: wordcloud-d3
Version: 0.1.0
Summary: Generate offline static D3 word-cloud HTML from plain text, idioms, or frequency files.
Author: PiPiCat
License-Expression: MIT
Keywords: wordcloud,chinese,idiom,d3,jieba,spacy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jieba>=0.42.1
Provides-Extra: spacy
Requires-Dist: spacy<4,>=3.7; extra == "spacy"
Provides-Extra: speedups
Requires-Dist: pyahocorasick>=2.0; extra == "speedups"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# 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

```powershell
pip install wordcloud-d3
```

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

```powershell
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:

```powershell
pip install "wordcloud-d3[speedups]"
```

## Quick Start

Frequency-file mode is the most direct:

```text
future 12
language 9
research 7
```

```powershell
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

```powershell
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:

```text
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:

```powershell
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

```python
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",
)
```
