MSDF Atlas Generator - Terminal Usage Guide
MSDF Atlas Generator - Terminal Usage Guide
MSDF Atlas Generator creates multi-channel signed distance field font atlases for high-quality text rendering in graphics applications.
1. Installation
Windows
Download the pre-built binary from the Releases page.
Build from Source
git clone https://github.com/Chlumsky/msdf-atlas-gen.git
cd msdf-atlas-gen
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake
cmake --build .
2. Basic Usage
msdf-atlas-gen -font <font.ttf> -type msdf -imageout <output.png> -json <output.json>
3. Required Arguments
| Argument | Description |
|---|---|
-font <file.ttf/otf> |
Path to the font file (required) |
4. Atlas Type (-type)
| Type | Description |
|---|---|
hardmask |
Hard-edge mask |
softmask |
Anti-aliased mask |
sdf |
Single-channel signed distance field |
psdf |
Pseudo signed distance field |
msdf |
Multi-channel signed distance field (default) |
mtsdf |
Multi-channel + true SDF in alpha |
5. Output Options
-imageout <filename.png> # Output atlas image
-json <filename.json> # Layout metadata and metrics
-csv <filename.csv> # Glyph positioning data
-arfont <filename.arfont> # Artery Font format
6. Character Set Selection
# Use a charset file (one character per line or ranges)
-charset charset.txt
# Use inline characters
-chars "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
# Use all glyphs in the font
-allglyphs
# Use glyph indices
-glyphset glyphs.txt
-glyphs "0-127"
7. Size and Dimensions
-size <pixels> # Glyph size in pixels per em (e.g., 32, 48, 64)
-dimensions <width> <height> # Fixed atlas dimensions
-pxrange <pixels> # Distance field range (default: 2)
-empadding <width> # Padding in em units
-pxpadding <width> # Padding in pixels
Dimension Constraints
| Option | Description |
|---|---|
-square4 |
Side length divisible by 4 (default) |
-square |
Square atlas |
-square2 |
Side length divisible by 2 |
-pots |
Power of two square |
-potr |
Power of two rectangle |
8. Image Format (-format)
| Format | Description |
|---|---|
png |
PNG image (default) |
bmp |
BMP image |
tiff |
TIFF image |
rgba |
Raw RGBA bytes |
fl32 |
32-bit float |
bin |
Binary format |
9. Advanced Options
-threads <N> # Number of threads (0 = auto-detect)
-yorigin <bottom/top> # Y-axis origin (default: bottom)
-angle <degrees> # Corner detection threshold
-coloringstrategy <method> # Edge coloring: simple, inktrap, distance
-miterlimit <value> # Sharp corner extension limit
-overlap # Support overlapping contours
10. Variable Fonts
-varfont "font.ttf?wght=700&wdth=100"
11. Example Commands
Basic MSDF Atlas
msdf-atlas-gen -font arial.ttf -type msdf -size 32 -imageout atlas.png -json atlas.json
ASCII Character Set with Custom Size
msdf-atlas-gen -font roboto.ttf -type msdf -size 48 -chars " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_\`abcdefghijklmnopqrstuvwxyz{|}~" -imageout atlas.png -json atlas.json
High-Quality Atlas with Larger Range
msdf-atlas-gen -font myfont.otf -type mtsdf -size 64 -pxrange 4 -imageout atlas.png -json atlas.json
Using a Charset File
msdf-atlas-gen -font font.ttf -type msdf -charset characters.txt -size 32 -imageout atlas.png -json atlas.json
Fixed Dimensions
msdf-atlas-gen -font font.ttf -type msdf -size 32 -dimensions 512 512 -imageout atlas.png -json atlas.json
All Glyphs with Multi-threading
msdf-atlas-gen -font font.ttf -type msdf -allglyphs -size 32 -threads 8 -imageout atlas.png -json atlas.json
12. Get Help
msdf-atlas-gen -help
13. Output JSON Structure
The JSON output contains:
- Atlas dimensions and type
- Font metrics (line height, ascender, descender)
- Per-glyph data (unicode, advance, bounds, atlas position)
Use this data to render text correctly in your application.