nanosvg

Version, currently 1.1.02 versions

github.com/OrelSokolov/nanosvg.cr

Pure Crystal SVG parser and rasterizer, extended from NanoSVG. Started as a faithful port (byte-identical output on the test artwork) and goes beyond the C original: <use> with <defs> path templates and nested <svg> viewports, enough to render MathJax SVG output. No C extensions, no external dependencies.

0 stars
3 dependents
License: Zlib

Installation

# Add this to your shard.yml
dependencies:
  nanosvg:
    github: OrelSokolov/nanosvg.cr
    version: ~> 1.1.0

Then run:

shards install

shard.yml

Crystal
no constraint declared
License
Zlib
Author
Oleg Orlov

Dependencies

This version declares no dependencies.

README

nanosvg.cr

Pure Crystal SVG parser and rasterizer, based on NanoSVG by Mikko Mononen (zlib license).

Parses SVG files into a list of cubic bezier shapes and rasterizes them to an RGBA buffer. It started as a faithful port of the C library — on the test artwork it produces byte-identical output — and has since been extended beyond the C original: <use> with <defs> path templates, nested <svg> viewports, MathJax-compatible rendering (see "Differences from C"), and <text>/<tspan> rendering with real font outlines, advances and GPOS kerning (see "Text rendering").

Installation

  1. Add the dependency to your shard.yml:
dependencies:
  nanosvg:
    github: OrelSokolov/nanosvg.cr
  1. Run shards install

Usage

require "nanosvg"

# Parse (units: "px", "pt", "pc", "mm", "cm", "in"; DPI controls conversion)
image = NanoSVG.parse_from_file("test.svg", "px", 96.0f32)
puts "size: #{image.width} x #{image.height} (#{image.shapes.size} shapes)"

# Walk the shapes: each path is a flat Float32 array of
# x0,y0, cpx1,cpx1,cpx2,cpy2,x1,y1, ... (npts-1 divisible by 3)
image.shapes.each do |shape|
  shape.paths.each do |path|
    i = 0
    while i < path.npts - 1
      p = i*2
      draw_cubic_bez(path.pts[p], path.pts[p+1], path.pts[p+2], path.pts[p+3],
                     path.pts[p+4], path.pts[p+5], path.pts[p+6], path.pts[p+7])
      i += 3
    end
  end
end

# Rasterize to a non-premultiplied RGBA buffer
scale = 2.0f32
w = (image.width * scale).round.to_i32
h = (image.height * scale).round.to_i32
pixels = NanoSVG::Rasterizer.rasterize(image, 0.0f32, 0.0f32, scale, w, h)

A persistent NanoSVG::Rasterizer instance can be reused for multiple images. See examples/render.cr for a complete parse → rasterize → PNG pipeline (built on the stdlib, no external shards):

crystal run examples/render.cr -- example_data/drawing.svg out.png 512

Supported SVG features

  • Elements: svg (root and nested — a nested <svg> acts as a viewport transform, used by MathJax for stretchy delimiters), g, path, rect, circle, ellipse, line, polyline, polygon, defs, linearGradient, radialGradient, stop, style (simple .class selectors), use (references a <path id> from defs via href / xlink:href, with x/y and transform; forward references are resolved after parsing — this is what MathJax SVG output is built on)
  • Path commands: all of MmLlHhVvCcSsQqTtAaZz (arcs are converted to cubic beziers)
  • Styles: presentation attributes, inline style="...", CSS classes, display:none
  • Paint: solid colors (#rgb, #rrggbb, rgb(), 147 named colors), linear/radial gradients (objectBoundingBox/userSpaceOnUse, gradientTransform, stops, xlink:href stop inheritance)
  • Stroke: width, opacity, caps (butt/round/square), joins (miter/round/bevel), miter-limit, dashes + offset, paint-order
  • transform (matrix/translate/scale/rotate/skewX/skewY) with nesting
  • viewBox, preserveAspectRatio, units (px pt pc mm cm in em ex %), DPI
  • Fill rules: nonzero and evenodd; anti-aliased scanline rasterization (5 sub-scanlines, 1/1024 fixed-point)
  • text/tspan: real glyph outlines from system TrueType fonts (font-family/size/weight/style, fill/gradient/opacity/transform, text-anchor, dominant-baseline, letter-spacing, x/y/dx/dy), with hmtx advances and GPOS PairPos kerning (formats 1/2, incl. extension lookups; legacy kern table as a fallback) — see "Text rendering"

Not supported: use referencing non-path elements, symbol, clip paths, masks, filters, patterns, markers, CSS cascade beyond simple classes, OpenType features beyond kerning (ligatures, marks), CFF (.otf) and variable-font outlines, bidi/complex scripts.

Known limitations of the <use>/nested-<svg> support:

  • A transform attribute on the <path> template inside defs is ignored when the template is instantiated by <use> (MathJax output does not use it).
  • <use> with a forward reference (the defs entry appears after the <use> in the document) is resolved after parsing and appended to the end of the shape list, so it paints on top rather than in document order. Invisible with opaque glyphs; may matter for overlapping semi-transparent shapes.
  • A nested <svg> with a viewBox but no width/height falls back to scale 1 instead of the spec default (100% of the parent viewport), and the implicit clipping of nested viewports is not applied.

Text rendering

<text>/<tspan> elements become glyph-outline shapes placed along the baseline with hmtx advances and GPOS kerning, laid out the way Pango/HarfBuzz would lay the same string:

  • A minimal TrueType reader (src/nanosvg/font.cr, no dependencies): cmap (formats 4/12), hmtx, loca/glyf (simple + composite glyphs, quadratics elevated to cubics), hhea/OS/2 metrics.
  • Kerning (font_kern.cr): the GPOS kern feature — PairPos formats 1 and 2, class-based and pair-set, extension (type 9) lookups — with the legacy kern table as a fallback. Values verified against HarfBuzz (Liberation Sans kern(A,V) = -152, kern(space,A) = -113; DejaVu Sans kern(A,V) = -131; Lato kern(A,V) = -108 — all exact).
  • Families resolve through fontconfig (fc-match, the same library Pango uses), so both renderers pick the same font file; explicit registration is available via NanoSVG::FontStore.register.

Validated against librsvg on a 100-case dataset (dataset/text/gen.py, references rendered with hinting disabled so both sides rasterize raw outlines): mean |Δα| averages 0.15 (0.35 on plain text, worst case 1.72 on dominant-baseline="middle" where rsvg's metrics differ from ours by ~1px at 32px); 0.33% of pixels differ by |Δα|>16 — the antialiasing floor between the NanoSVG scanline rasterizer and Cairo/FreeType coverage. Byte identity is not expected across different rasterizer algorithms; the residual is edge coverage only, not geometry. See bench/text_pixel_diff.cr.

When no font can be resolved (no fc-match, e.g. headless Windows), text elements are skipped silently — the pre-text behavior.

Differences from C

  • Extended beyond the C original: <use href="#id"> referencing a <path id> from <defs> (with x/y, transform, and forward references), nested <svg> elements treated as viewport transforms — this is what MathJax SVG output is built on — and <text>/<tspan> rendering (see "Text rendering").
  • Colors use the same bit layout as C: 0xAABBGGRR (R in the low byte).
  • The NOTE(port) comments in the sources mark deliberate deviations (mostly: C read uninitialized memory in degenerate cases; the port uses deterministic values).
  • The C memory pool/freelist in the rasterizer is left to the GC.
  • The full NANOSVG_ALL_COLOR_KEYWORDS list is always enabled.

Development

crystal spec                        # run the test suite
crystal run examples/render.cr -- example_data/23.svg out.png 512

License

zlib — same as the original NanoSVG (see LICENSE). The polygon rasterization is based on the stb_truetype rasterizer by Sean Barrett.