https://github.com/acture/glyphweave
Shape-constrained SVG word clouds, built for speed. Fast Rust CLI + library.
https://github.com/acture/glyphweave
cli creative-coding layout-algorithms rust svg visualization wordcloud
Last synced: about 1 month ago
JSON representation
Shape-constrained SVG word clouds, built for speed. Fast Rust CLI + library.
- Host: GitHub
- URL: https://github.com/acture/glyphweave
- Owner: Acture
- License: agpl-3.0
- Created: 2025-06-10T16:42:07.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2026-03-06T09:07:00.000Z (3 months ago)
- Last Synced: 2026-04-06T18:07:20.532Z (2 months ago)
- Topics: cli, creative-coding, layout-algorithms, rust, svg, visualization, wordcloud
- Language: Rust
- Homepage: https://docs.rs/glyphweave
- Size: 257 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# GlyphWeave
[](https://crates.io/crates/glyphweave)
[](https://github.com/Acture/glyphweave/actions/workflows/release.yml)
[](LICENSE)
## Shape-constrained SVG word clouds, built for speed.
GlyphWeave is a fast Rust CLI + library for generating bold SVG word clouds inside text and shape masks with multiple layout engines, reproducible runs, and palette control.
- Fast by default
- Visual by design
- CLI + library
## Example Gallery
Generated with fixed seeds, `fast-grid`, and `fonts/Roboto-Regular.ttf`.
| RUST (`auto`) | AI (`complementary`) |
|---|---|
|  |  |
| DATA (`analogous`) | CODE (`vibrant`) |
|---|---|
|  |  |
Reproduce these assets:
```bash
bash docs/examples/generate.sh
```
## Why It Feels Different
- Fast layouts out of the box with `fast-grid`, plus `mcts`, `simulated-annealing`, `spiral-greedy`, and `random-baseline`
- Strong visual control with palette strategies, weighted words, rotations, and SVG output
- Reproducible runs through `--seed`, config files, and library integration for automation
## Install
```bash
cargo install glyphweave
```
Optional: include embedded Noto Sans SC at build time.
```bash
cargo install glyphweave --features embedded_fonts
```
## Quick Start
```bash
glyphweave \
--text "RUST" \
--words "cloud,speed,layout,mask,svg,grid" \
--canvas-size 1400,800 \
--algorithm fast-grid \
--palette auto \
--seed 42 \
--output output.svg
```
Use weighted input from file:
```text
# words.txt
rust,3
cloud,2
layout,2
mask
svg
```
```bash
glyphweave --text "AI" --word-file words.txt --algorithm spiral-greedy --rotations 0,90 --output ai.svg
```
Show all flags:
```bash
glyphweave --help
```
## Use Cases
- Design assets and posters with text-shaped SVG output that stays easy to post-process
- Data storytelling visuals where the shape matters as much as the words
- Scripted and batch generation pipelines through the Rust API or CLI configs
## Library Example
```rust
use glyphweave::{
generate, load_font_from_file, AlgorithmKind, CanvasConfig, CloudRequest, FontSizeSpec,
RenderOptions, ShapeConfig, StyleConfig, WordEntry,
};
use std::{path::Path, sync::Arc};
let font = load_font_from_file(Path::new("fonts/NotoSansSC-Regular.ttf"))?;
let result = generate(CloudRequest {
canvas: CanvasConfig { width: 1200, height: 700, margin: 12 },
shape: ShapeConfig { text: "DATA".into(), font_size: FontSizeSpec::AutoFit },
words: vec![WordEntry::new("rust", 2.0), WordEntry::new("svg", 1.0)],
style: StyleConfig::default(),
algorithm: AlgorithmKind::FastGrid,
ratio_threshold: 0.85,
max_try_count: 10_000,
seed: Some(7),
font: Arc::new(font),
render: RenderOptions::default(),
})?;
std::fs::write("cloud.svg", result.svg)?;
# Ok::<(), Box>(())
```
## Algorithm Cheat Sheet
| Algorithm | Speed | Fill Quality | Best Use Case |
|---|---:|---:|---|
| `fast-grid` | High | High | Default production choice |
| `mcts` | Medium-Low | High | Search-driven quality improvements |
| `simulated-annealing` | Medium-Low | Medium-High | Stochastic optimization and exploration |
| `spiral-greedy` | Medium | Medium-High | Center-focused, stable visual structure |
| `random-baseline` | Low | Medium | Baseline and regression comparison |
## Fonts
- Default behavior: try system fonts automatically
- Use `--font ` to pin a `.ttf/.otf`
- Use `--choose-system-font` for interactive font selection
- Embedded font feature: `embedded_fonts` (off by default)
- Embedded font: Noto Sans SC, SIL Open Font License 1.1
- License text: `fonts/OFL-NotoSansSC.txt`
## Config
Config precedence (later overrides earlier):
1. `~/.config/glyphweave/config.toml` (or `$XDG_CONFIG_HOME/glyphweave/config.toml`)
2. `.glyphweave.toml` in current directory
3. `--config `
4. CLI flags
Minimal example:
```toml
canvas_size = [1600, 900]
algorithm = "fast-grid"
palette = "analogous"
palette_base = "#0EA5E9"
ratio = 0.85
max_tries = 12000
rotations = [0, 90]
```
## Documentation
- [Architecture](docs/architecture.md)
- [Library API](docs/library-api.md)
- [Algorithms](docs/algorithms.md)
- [Tuning](docs/tuning.md)
- [Migration v0.2](docs/migration-v0.2.md)
## For Maintainers
The `Release` workflow supports tag-driven and manual publishing to GitHub Releases, crates.io, and the `Acture/homebrew-ac` tap.
- Secrets: `HOMEBREW_TAP_TOKEN`
- Manual inputs: `tag`, `upload_assets`, `publish_cargo`, `update_homebrew`
- crates.io publishing uses Trusted Publishing via GitHub OIDC; configure `Acture/glyphweave`, workflow `release.yml`, and environment `release` as a trusted publisher on crates.io
- The first publish of a brand-new crate can be done locally; once the crate exists, rerun the workflow or use future tags for Trusted Publishing
- Use the `release` environment if you gate publishing with environment approvals
## License
AGPL-3.0. See [LICENSE](LICENSE).