Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-svg

A small SVG parser, flattener and rasteriser (coverage masks and linear RGBA) for Luce/Base, with SVG files drawn as pictures, their text set in the system's fonts.

A library written in luce-base. Latest release 0.9.2.

Install#

luc add dymokomi/luce-svg

Documentation#

luce-svg

A small SVG parser, flattener and rasteriser for Luce/Base. It reads an SVG string (path, rect, circle, ellipse, line, polyline, polygon and nested g), flattens curves and arcs to polylines, and produces a Drawing: a viewBox size plus contours over a flat point buffer, in viewBox coordinates. Each contour records its element (an element's subpaths fill together by its fill-rule) and its paints: fill and stroke as sRGB colors, currentColor or gradients, opacities, and its pen (width, caps, joins, miter limit, dashes). The parser depends on luce-std and luce-color (sRGB decoding); the picture renderer adds luce-fonts for text (its platform faces), and the full renderer luce-fonts' font files and shaping for text and luce-png, luce-jpeg and luce-compress for images.

The full renderer

load(source, options) -> interop.Reference[Picture] reads a whole SVG document the way resvg (and so, closely, a browser) does, and `render(picture, transform, width, height, pixels) draws it into straight-alpha sRGB RGBA bytes (render_float` gives floats, encoded or in linear light; fit_transform stretches the picture's size over the bitmap). It is built in four stages, each its own set of fragments:

  • XML (xml.lucb): elements, attributes, text and CDATA, the five predefined entities, character references and a DOCTYPE's own <!ENTITY>s (which may hold markup), namespace prefixes (only SVG, XLink and XML matter), malformed markup an error.
  • The SVG tree (tree*.lucb, css.lucb): only SVG elements are kept; every element's attributes are cascaded from presentation attributes, <style> rules (type, *, .class, #id, attribute tests, :first-child, descendant, child and sibling combinators, ordered by specificity, !important honoured) and its style attribute; inherit is resolved; use gets a copy of its target as its child; text white space is collapsed as SVG 1.1 and Chrome do.
  • Conversion (convert*.lucb) into a render tree (scene.lucb) of groups, shapes and images with every property resolved: lengths in every unit against the nearest viewport, display, visibility, conditional processing (switch, systemLanguage, requiredFeatures), use/symbol/nested svg viewports with viewBox, preserveAspectRatio and overflow clipping, transforms with transform-origin (lengths and keywords, as svgtypes reads them), fills and strokes (colors, currentColor, gradients with fallbacks, fill-rule, dashes, caps, joins including miter-clip, paint-order, shape-rendering), markers (start, mid and end; orient auto and auto-start-reverse, markerUnits, viewBox, refX/refY, overflow clipping) with context-fill and context-stroke (in markers and in use), paint-order, and groups only where one is needed (opacity, blend mode, isolation, clip path, mask, filter).
  • Rendering (raster.lucb, scanline.lucb, stroker.lucb, canvas.lucb, shade.lucb, render_scene.lucb): curves flattened to a twentieth of a device pixel, coverage from sixteen sub-scanlines a row with exact horizontal spans and true nonzero and even-odd winding, strokes built in user space (so a skewed transform skews them), gradients with pad, reflect and repeat spreads and two-point conical radial gradients (the focal radius fr included), group layers composited with opacity and all sixteen CSS blend modes, clip paths (nested, with clip-rule) and masks (luminance or alpha, nested, with their region). Patterns (with href inheritance, both unit systems, viewBox and patternTransform) are drawn as a tile at the device's scale and repeated, sampled bicubically unless the tile lands on the pixel grid, as resvg samples them.
  • Images: <image> from data URLs (base64 or percent-encoded, the format from the MIME type or sniffed) or from files relative to Options.resources (never from inside an image that is itself an SVG); PNG and JPEG decode through luce-png and luce-jpeg, SVG and gzip-compressed SVGZ images convert into the picture as vector groups. Fitted by preserveAspectRatio (clipped when slicing), sampled as image-rendering asks. GIF and WebP are recognised but not decoded.
  • Filters (convert_filter.lucb, convert_primitive.lucb, convert_fe.lucb, filter_*.lucb): filter lists of url(#id) and the CSS filter functions (blur, drop-shadow, brightness, contrast, grayscale, hue-rotate, invert, opacity, saturate, sepia); filter elements with href inheritance, filterUnits and primitiveUnits, subregions, named results and color-interpolation-filters (each image converted between sRGB and linearRGB as a primitive needs); every primitive resvg renders — feBlend, feColorMatrix, feComponentTransfer, feComposite (with arithmetic), feConvolveMatrix, feDisplacementMap, feDropShadow, feFlood, feGaussianBlur (box blurs for large deviations, a Gaussian kernel for small), feImage (images and document elements), feMerge, feMorphology, feOffset, feTile, feTurbulence, and feDiffuseLighting and feSpecularLighting with distant, point and spot lights. A filtered group is drawn in a layer round its filter regions, up to twice the canvas past each side, so offsets and blurs can bring in content from beyond it.
  • Text (text_*.lucb): <text>, <tspan>, <tref>, <a> and <textPath> laid out as usvg lays them: chunks at each absolute x or y, per-character x, y, dx, dy and rotate lists, text-anchor, letter-spacing, word-spacing, kerning, textLength with lengthAdjust, baseline-shift (lengths, percentages, sub and super), dominant-baseline and alignment-baseline, underline, overline and line-through painted as the element that asks for them, text along a path (startOffset, glyphs turned with the path and hidden past its ends), and each span's fill, stroke and paint-order, with bounding-box paint servers measuring the whole text, and vertical writing modes (CJK upright, other scripts turned a quarter). Glyphs come from a GlyphSource — faces chosen by family list, weight, style and stretch, glyphs by scalar with a fallback face, advances, pair kerning, metrics and outlines, and (optionally) shape, which shapes a run of one direction as HarfBuzz does (ligatures, marks, contextual forms, small caps); a source that does not shape maps a scalar at a time with pair kerning. luce-svg itself splits each chunk into bidi runs (UAX #9 for one left-to-right paragraph, text_bidi.lucb), shapes the chunk per span as usvg does, and forms clusters from the shaped glyphs.
  • Fonts (text_font_files.lucb, text_font_catalog.lucb): FontFiles is the GlyphSource over font files, read and shaped by luce-fonts' opentype and shaping modules (HarfBuzz's default shaper). FontFiles.system() catalogues the platform's font directories, FontFiles.open(directories) the caller's (recursively; .ttf, .otf, .ttc and .otc); only each face's small tables are read until its glyphs are needed. Families match without regard to case, styles and weights by CSS's rules, generic families stand for each platform's usual faces unless set_generic("serif", "Noto Serif") says otherwise, an uninstalled list falls back to serif, and a character a face lacks comes from the first face that has it. Faces with bitmap or SVG color glyphs are left out. When Options.glyphs is none, load sets text in FontFiles.system() (catalogued once per process, on the first text that needs it; conversions that use it take turns); Options(system_fonts = false) leaves such text undrawn. Arabic joining and Indic reordering need the shaper's complex-script shapers, and variable fonts (font-variation-settings), vertical glyph substitutes and color fonts need additions to luce-fonts and the source interface.

Compositing is in sRGB, as browsers and resvg composite: colors blend as their encoded values, so half-transparent black over white is 50 % grey. This is the default of the full renderer only; RenderOptions(linear = true) composites in linear light instead. The Drawing renderer below keeps its linear-light compositing, unchanged for its callers (luce-image's pictures, luce-vector's tiles).

The value parsers are public so other code can share one spec-correct reading: parse_number, parse_length (a Length with its Unit), parse_angle, parse_transform_list (all six functions), parse_view_box, parse_aspect_ratio and view_box_transform, parse_path_data into a Path (move, line, cubic, close; quadratics and arcs become cubics; tight bounds), parse_points, iri and func_iri, and parse_rgba (every CSS color: hex in four lengths, the named colors, rgb/rgba/hsl/hsla in both syntaxes, hwb, lab, lch, oklab, oklch and color() in the predefined spaces, converted with luce-color); parse_color reads the same colors without their alpha.

Paints and colors

fill, stroke, fill-opacity, stroke-opacity, opacity and the stroke properties are read from style="..." first, then from presentation attributes, and inherit through groups. Colors are #rgb, #rrggbb, rgb(r, g, b) with numbers or percentages, and the 148 CSS named colors; paints add none, transparent, inherit and currentColor. SVG's defaults hold: fill black, stroke none. opacity multiplies into both paints of everything inside it (not as an isolated group layer). parse_color(text) -> Color? parses a color on its own.

url(#id) paints with a linearGradient or radialGradient found anywhere in the document: stops with offset, stop-color and stop-opacity (attributes or style), gradientUnits (objectBoundingBox, the default, or userSpaceOnUse), gradientTransform, x1 y1 x2 y2, cx cy r fx fy, and href/xlink:href inheritance of stops and attributes. Stops blend in sRGB, as browsers do, before decoding to linear. A missing or stopless gradient paints the fallback written after the url(...), else nothing.

Strokes are traced as one shape per element under the nonzero rule: a rectangle per segment, stroke-linejoin miter (the default, with stroke-miterlimit, default 4, falling back to bevel), round or bevel at every vertex, and stroke-linecap butt, round or square at open ends.

rasterize_rgba(drawing, width, height, pixels, current) draws in color into width * height * 4 floats of straight-alpha RGBA in linear light: every paint is decoded from sRGB before blending, and current is the sRGB Color that currentColor means. Element by element in document order, the fill and then the stroke composite source-over, with the same exact-area anti-aliasing as the coverage rasteriser.

SVG files as pictures

svg_render (module render) is what an image editor opening an SVG wants: is_svg(path) and render_svg(path, max_bytes, max_pixels) -> Rendered, the file drawn in color at its own size, scaled up until its longer side is at least 1024 pixels, in linear light with straight alpha (Rendered.pixels, 4 floats a pixel in the heap; free them there), currentColor black. Its <text> is set with the system's fonts through luce-fonts, in paint order among the shapes (text.lucb, with faces chosen in faces.lucb): a run's family list is tried in order, generic families stand for each platform's usual faces, and the style nearest its weight and slant is taken; a run whose font cannot be set is left out. This moved here from luce-image (2026-09-27).

Text

The parser reads <text> into runs; svg_render sets them, and a caller with its own fonts can too. text_count() and text_run(index) -> TextRun give each run of one style — the <text> itself or a <tspan> — with its characters (entities decoded, white space collapsed as browsers collapse it), the first value of x, y, dx and dy, whether it opens a <text> or starts an anchored chunk, text-anchor, the font-family list (family_count(), family(i); generics as written), font-size (px, pt, pc, mm, cm, in, em, ex, rem, %, keywords) in the run's own units, font-weight, font-style, its fill (color, currentColor, or a gradient's first stop) and opacity, the transform (a Matrix) from its coordinates to the viewBox, and its order: how many shape elements paint before it.

To draw text in paint order, clear the pixels, then for each run call rasterize_rgba_elements(drawing, width, height, pixels, current, drawn, order) for the shapes before it, set the run over them, and finish with the shapes up to element_count(). pixel_transform(drawing, width, height) maps the viewBox onto the bitmap as the rasterisers place it.

Limits of the Drawing

  • The parser only reads text (see above); only the first value of x, y, dx and dy is used, and rotate, textLength, textPath, stroked text, dominant-baseline and vertical writing are not read.
  • Every spreadMethod pads (reflect and repeat draw as pad).
  • Contents of defs, clipPath, mask, symbol, pattern and marker are not drawn; there is no use, clipping, masking, pattern paint, filter, fill-rule="evenodd" or image.
  • Group opacity fades each paint rather than compositing the group as a layer.
  • In the Drawing, an unknown color name paints black and a color's alpha is dropped.

Assets: rounded icons by Dy Mokomi (luciaos-assets), CC BY 4.0.

Rasteriser and conformance

rasterize(drawing, width, height, coverage) fills an 8-bit coverage bitmap with exact-area anti-aliasing (the signed-area accumulation font rasterisers use): each element's subpaths filled together by its fill-rule (so holes stay open), strokes with their width, caps, joins and dash patterns, and fill/stroke opacity; elements composite source-over, so the mask is the alpha rasterize_rgba draws and translucent layers build up as in a browser. It ignores colors and gradients. luce-ui draws icons through it as tinted masks.

tools/conformance.py renders every luciaos-assets icon with resvg and with tools/render.lucb at 256 px, ranks the differences and writes a side-by-side sheet of the worst (build/conformance/worst.png). On 2026-09-22 all 157 icons were within 0.26 % of resvg's pixels (150 within 0.2 %); synthetic shapes match their analytic areas to 0.05 %. Needs brew install resvg and python3 -m venv build/env && build/env/bin/pip install pillow numpy.

resvg's test suite

tools/suite.py measures the full renderer against resvg's 1719 integration tests (crates/resvg/tests/tests of https://github.com/linebender/resvg, cloned into ../.donors/resvg; the suite is never committed here). tools/suite.lucb draws each test 300 pixels wide, as resvg drew its reference PNGs; a pixel differs when a premultiplied RGBA8 channel is off by more than 40, and a test passes when at most 0.5 % of its pixels differ. That absorbs anti-aliasing differences (tiny-skia samples four sub-scanlines a pixel, so its edge coverage is off the exact area by up to an eighth) but not a missing or misplaced feature. It prints a pass table per feature directory and category; --save run.json and --compare run.json track changes between runs, --list-failing names the failures, --only painting/fill runs a subset and --drawing measures the Drawing renderer.

Baseline (2026-10-03, the Drawing renderer before this work, in linear light): 472 of 1719 — filters 77/397, masking 8/93, paint-servers 99/153, painting 117/306, shapes 91/133, structure 62/258, text 18/379.

The full renderer (2026-10-03): 1308 of 1719 without a GlyphSource — filters 389/397, masking 88/93, paint-servers 151/153, painting 285/306, shapes 133/133, structure 244/258, text 18/379 (text needs glyphs). With FontFiles over the suite's fonts (crates/resvg/tests/fonts, which tools/suite.py passes as --fonts, with resvg's generic families; --system-fonts sets text in the system's instead), 2026-10-03: 1671 of 1719 — filters 396, masking 93, paint-servers 152, painting 305, shapes 133, structure 254, text 338. What still fails: GIF and WebP images (no decoders), rgba() with a percentage alpha (read as CSS Color 4 reads it; resvg rejects it), two transform-precision cases, and text that needs more of its source than that one gives — Arabic joining and Indic shaping, variable fonts, color fonts.

Dependencies#

Versions#

0.9.2

Browse source · pack · commit b7255f30756f

SHA-256 6438ff1a04645bd48236a93fd1c72e991890aafb05f02b17ca63e819a38dbce1

luce-svg 0.9.2: batch release

0.9.1

Browse source · pack · commit 940c5ebc1680

SHA-256 fdb351d623c3a29958b31895cf073c143ee7f7055de52abb2b19a014bfd8b1c2

dependencies name no version