Module: svgImport

Utilities to parse a vector-graphics (SVG) file into native cubic Bezier / line / elliptical-arc segments so they can be imported into the ray optics scene as Bezier-based mirror/custom-surface/glass/GRIN-glass objects, or as a free-form Drawing (polyline).

The parser walks the SVG DOM, applies the accumulated transform stack at every node, and converts every supported shape (<line>, <polyline>, <polygon>, <rect>, <circle>, <ellipse>, <path>) to a list of path segments. Quadratic Beziers are raised to cubic exactly. Elliptical arcs (from SVG A commands, <circle>, <ellipse>) are kept exact as 'A' segments and only flattened to cubics later, at import time, using the user-selected tolerance — so the same SVG can be re-imported at different tolerances without losing precision.

Presentation attributes (stroke, fill, stroke-opacity, fill-opacity, and style="...") are resolved along the tree so each returned path knows which color to use for its stroke and its fill.

Each returned path has the shape { start: { x, y }, segments: [ { type: 'L', end } // straight line { type: 'C', c1, c2, end } // cubic Bezier { type: 'A', center, mat, theta0, theta1, // elliptical arc end } ], closed: boolean, stroke: { r, g, b, a } | null, fill: { r, g, b, a } | null, source: string, }

An 'A' segment parameterizes its arc as P(θ) = center + [a b; c d] · (cos θ, sin θ)ᵀ, for θ ∈ [theta0, theta1] where mat = { a, b, c, d }. This encoding is closed under affine transforms: applying a 2×2 linear map M to the arc yields another arc with matrix M · mat and center M · center — so arcs survive the SVG transform stack and the user's scale/offset without any loss.

Alpha is preserved for reference but the caller is expected to group paths by the RGB portion only, per the user-facing requirement.

Source:

Members

(inner, constant) ARC_MAX_SUBDIV

Maximum recursion depth for subdividing an arc piece to meet tolerance.

Source:

(inner, constant) ARC_PREVIEW_REL_TOL

Preview-only tolerance, relative to an arc's characteristic radius.

Source:

(inner, constant) CSS_COLORS

A minimal subset of named CSS colors commonly seen in vector-graphics exports.

Source:

Methods

(static) computePathsBBox(paths) → {Object|null}

Compute a bounding box for a preview. Straight and cubic segments use their control hulls (which always contain the true curve); arc segments are sampled at a fixed number of equal-angle steps, which overestimates only by a negligible amount.

Parameters:
Name Type Description
paths Array.<ParsedPath>
Source:
Returns:
Type
Object | null

(static) flattenArcSegments(paths, tolerance) → {Array.<ParsedPath>}

Replace every 'A' (elliptical arc) segment in each path with a sequence of cubic Bezier 'C' segments, using adaptive subdivision. The maximum deviation of any output cubic from the true arc stays below tolerance (in whatever coordinate space the paths live in at the time of the call).

Call this after applying the scene transform and before simplifyPaths, so that tolerance refers to on-screen units.

Parameters:
Name Type Description
paths Array.<ParsedPath>
tolerance number
Source:
Returns:
Type
Array.<ParsedPath>

(static) flattenPathToPolyline(path, tolerance) → {Array.<{x:number, y:number}>}

Flatten a parsed path to a polyline by sampling each curved segment at a resolution that keeps the deviation below tolerance scene units. Used for the Drawing target which only stores polyline strokes.

Parameters:
Name Type Description
path ParsedPath
tolerance number

maximum deviation in scene coordinates.
Source:
Returns:
Type
Array.<{x:number, y:number}>

(static) parseShapesFile(svgString) → {Object}

Same as parseSvg; named for callers that treat the input as a generic "vector shapes" file (currently always SVG).

Parameters:
Name Type Description
svgString string
Source:
Returns:
Type
Object

(static) parseSvg(svgString) → {Object}

Parse an SVG string.

Parameters:
Name Type Description
svgString string
Source:
Returns:
Type
Object

(static) pathToSvgPathD(path)

Produce an SVG d string describing a parsed path, useful for rendering a preview with <path d="...">. Arc segments are flattened to cubics at a fine preview tolerance (relative to the arc's characteristic radius).

Parameters:
Name Type Description
path ParsedPath
Source:

(static) simplifyPaths(paths, tolerance) → {Array.<ParsedPath>}

Simplify consecutive cubic Bezier segments in a path by merging adjacent cubics whose union can be represented as a single cubic within tolerance. This is the "subsampling" strategy for overly dense cubic paths.

Parameters:
Name Type Description
paths Array.<ParsedPath>
tolerance number
Source:
Returns:
Type
Array.<ParsedPath>

(inner) adaptiveArcSamples()

Adaptive polyline sampler for an arc segment.

Source:

(inner) arcCharRadius()

Characteristic radius used to pick preview tolerance per arc.

Source:

(inner) arcSubrangeToCubic()

Exact Maisonobe (2003) cubic approximation of an elliptical arc from θ0 to θ1, using the stored parameterization in seg. The returned cubic matches the arc exactly at both endpoints in both position and tangent.

Source:

(inner) arcToArcSegment()

Convert an SVG elliptical arc command to a single 'A' segment with an exact parametric description. No cubic flattening happens here — that is deferred to flattenArcSegments at import time so the tolerance drives the subdivision.

Returns an array (always length 1 for a non-degenerate arc) so callers can treat it uniformly with the other segment producers.

Source:

(inner) cubicApproxError()

Check whether a single cubic approximates a sequence of cubics within tol.

Source:

(inner) ellipsePath()

Produce a path (in local coordinates) describing a full ellipse as a single closed 'A' (arc) segment. The caller is responsible for any outer transform. Flattening to cubics happens later, at import time, honoring the user-selected tolerance.

The start parameter θ = 0 corresponds to +x on the ellipse, i.e. point (cx + rx, cy). The arc sweeps a full 2π (counter-clockwise in SVG coordinates, where +y points down).

Source:

(inner) evalArc()

Evaluate an 'A' segment at parameter θ.

Source:

(inner) evalArcDeriv()

Evaluate the derivative of an 'A' segment at parameter θ.

Source:

(inner) flattenArcToCubics()

Flatten one 'A' segment into a sequence of cubic segments whose maximum deviation from the true arc is ≤ tolerance. Each initial piece spans at most 90° (so the Maisonobe formula starts well-conditioned); beyond that, it is halved recursively whenever the mid-parameter error exceeds the tolerance.

Source:

(inner) mergeTwoCubics()

Build a single cubic Bezier from two consecutive cubics by keeping the start tangent of the first and the end tangent of the second. Returns null if the tangents are degenerate.

Source:

(inner) parseColor()

Parse a CSS color string. Supports none, named colors, #rgb, #rrggbb, #rrggbbaa, rgb(), rgba(). Returns null for none, and fallback when the value is unrecognized (e.g. url(#gradient)).

Source:

(inner) parsePathD()

Parse the d attribute and produce one or more sub-paths with cubic Beziers / lines. The returned structure is independent of any transform; the caller composites the transform afterwards.

Source:

(inner) resolveStyle()

Resolve inherited presentation style for a node. Only stroke, fill, stroke-opacity and fill-opacity are considered; unsupported style attributes are ignored.

Source: