svg-parse-path-normalized

Parses path data from string including fine-grained normalisation and conversion options.

This library aims to provide a performant yet compact (~6KB/3KB minified; gzipped) parser – respecting all minified/shorthand notations as a basis for all kinds of custom path data manipulations.

• 1. Basic functionality and helpers
  • 1.1 Parse, normalize and stringify
  • 1.2 Advanced conversions
• 2. Usage parser
  • 2.1 Browser
  • 2.2 Node
• 3. Pathdata format
• 4. All normalization options
  • 4.1 Original path data: normalization disabled
  • 4.2 Recommendations
• 5. Stringify to back to d attribute string
• 6. More conversions via pathDataConvert.js
  • 6.1 Usage
  • 6.2 Usage as an addon/plugin for getPathData()
  • 6.3 Convert pathdata structure
    • 6.3.1 Array notation to pathdata
    • 6.3.2 pathDataToVerbose(pathData)
• 7. Demos
• Credits

1. Basic functionality and helpers

1.1 Parse, normalize and stringify

Usually parsing alone is not enough to get computable path data values – due to relative or shorthand commands or a arcto commands that may rather complicate further manipulations such as length or area calculations – especially when dealing with elliptical and/or rotated arcs.

Normalization (admittedly a slightly ambigious term) via parsePathDataNormalized(d) applies by default these conversions:

• (default) all commands to absolute
• (default) decompose implicit or repeated commands
  e.g m 0 0 .5.5.5.5 to M 0 0 l 0.5 0.5 l 0.5 0.5
• commands to shorthand/reflected commands to longhand equivalents like e.g h, v, s, t to L, C, T
• (optional) convert/approximate arcs to cubics
• (optional) convert quadratic béziers to cubics
• (optional) debug: detect malformed path data inputs
• (optional) round coordinates
• stringify to d attribute – including minification options

1.2 Advanced conversions

Provided by pathDataConvert.js: Useful to convert your manipulated/processed path data to all kind of command types/structures (E.g to get a more compact or special formats like lineto-to-bezier conversions for morphing animations by converting)

• all commands to relative (usually more concise in file size)
• apply shorthands – if possible (also decreases filesize)
• linetos to cubic or quadratic béziers
• cubic béziers to quadratic
• different path data formats e.g array based path data notations as used in snap.svg and other libraries or APIs
• this scripts also includes all normalizations options such as relative-absolute, shorthand-to-longhands, rounding etc.
• can be used as an addon complementing getPathData() or other parsers compliant with the w3C SVGPathData interface draft format recommendations.

2. Usage parser

2.1 Browser

<script src="https://www.unpkg.com/svg-parse-path-normalized@latest/js/pathDataParseNormalized.js"></script>

Optional: Load minified script via jsDelivr (~6KB/3KB minified; gzipped)

<!--basic parser --->
<script src="https://cdn.jsdelivr.net/npm/svg-parse-path-normalized@latest/js/pathDataParseNormalized.min.js"></script>

<script>

//parse
const d ="m 0 0 .5.5.5.5a 5 10 45 1040 20" ;
let pathData = parsePathDataNormalized(d)

//stringify to pathdata d string
let minify = false;
let dNew = pathDataToD(pathData, 1, minify);

console.log(pathData);
console.log(dNew);

</script>

2.2 Node

npm install svg-parse-path-normalized

const parsepathData = require('svg-parse-path-normalized');
const {parsePathDataNormalized, pathDataToD} = parsepathData;

//parse
const d ="m 0 0 .5.5.5.5a 5 10 45 1040 20" ;
let pathData = parsePathDataNormalized(d)

//stringify to pathdata d string
let minify = false;
let dNew = pathDataToD(pathData, 1, minify);

console.log(pathData);
console.log(dNew);

3. Pathdata format

This library uses the pathdata format as suggested in the w3C SVGPathData interface draft.

The returned path data parsed from a stringified pathdata d attribute string is an array representing each command as an object like so:

const d ="m 0 0 .5.5.5.5a 5 1045 1040 20" 
parsePathDataNormalized(d)

[
    {"type":"M","values":[0,0]},
    {"type":"L","values":[0.5, 0.5]},
    {"type":"L","values":[1, 1]},
    {"type":"A","values":[5, 10, 45, 1, 0, 41, 21]}
]

The above example illustrates a problem with overly "lightweight" path parsers:
We need an extra check to "unravel" the A arcto's largeArc and sweep flags, which can be concatenated with the subsequent on-path x coordinate value. (See basic example)

4. All normalization options

parsePathDataNormalized(d, options) accepts these parameters

let options= {
    normalize: null,          //shorthand for aggressive normalisation
    toAbsolute: true,         //necessary for most calculations
    unshort: true,            //dito
    arcToCubic: false,        //sometimes necessary
    quadraticToCubic: false,  //frankly, not necessary most of the time
    lineToCubic: false,       //handy for morphing animations
    debug: false,             //handy to detect malformed pathdata retrieved from user inputs
    decimals: -1              //-1=no rounding
}

| parameter | default | effect | | -- | -- | -- | | toAbsolute | true | convert all to absolute | | unshort | true | convert all shorthands to longhands | | arcToCubic | false | convert arcs A commands to cubic béziers | | quadraticToCubic | false | convert quadratic to cubic béziers | | lineToCubic | false | convert all L linetos to cubic béziers (handy for morphing animations) | | decimals | -1 | round values to floating point decimals. -1=no rounding | | debug | false | reports malformed path data structures via console.log| | normalize | null | shorthand to also convert arcs and quadratic béziers to cubic – similar to the W3C draft's suggested getPathData({normalize:true}) parameter |

4.1 Original path data: normalization disabled

Set normalize to false to get the original (not normalized) pathdata – including relative or shorthand commands.

parsePathDataNormalized(d, {normalize:false})

4.2 Recommendations

• Quadratic béziers usually provide much faster calculations/algorithms – think twice before converting to cubic.
• debug:true can be handy if you need to find errors in malformed pathdata – maybe caused by manual path splitting
• Arc to cubic conversion/approximation is quite complex and thus quite expensive – you may not need this conversion

5. Stringify to back to d attribute string

Options:

• decimals: rounds pathdata
• minify: omits command letters for implicit or repeated commands and leading zeros

pathDataToD(pathData, decimals, minify) 

6. More conversions via pathDataConvert.js

Load pathDataConvert.js to get more conversion methods. This script is intended to provide various conversions to optimize the path data after processing e.g for a minified path output.

| parameter | default | effect | | -- | -- | -- | | toRelative | false | convert all to relative | | toAbsolute | true | convert all to absolute | | toShorthands | false | convert all to to shorthands – if applicable | | toLonghands | true | convert all shorthands to longhands | | arcToCubic | false | convert arcs A commands to cubic béziers | | lineToCubic | false | convert all L linetos to cubic béziers (handy for morphing animations) | | quadraticToCubic | false | convert quadratic to cubic béziers | | cubicToQuadratic | false | convert all cubic to quadratic | | cubicToQuadraticPrecision | 0.1 | cubic to quadratic accuracy | | decimals | -1 | round values to floating point decimals. -1=no rounding | | normalize | null , true, false | shorthand to also convert arcs and quadratic béziers to cubic – similar to the W3C draft's suggested getPathData({normalize:true}) parameter |
| optimize | false | shorthand to convert to shorthands, relative and round to 3 decimals for a more compact output |

6.1 Usage

<script src="https://www.unpkg.com/svg-parse-path-normalized@latest/js/pathDataConvert.js"></script>

Load minified via jsDelivr (13KB/6KB minified)

<!-- optional conversions -->
<script src="https://cdn.jsdelivr.net/npm/svg-parse-path-normalized@latest/js/pathDataConvert.min.js"></script>

let options = {arcToCubic:true, toRelative:true, decimals:0}
let pathDataCon = pathData.convert(options)

Conversion can be applied via

• chainable prototype method convert(options) to apply all conversions at once
• separate chainable methods like pathData.toAbsolute(), pathData.toRelative(), pathData.toLonghands(), pathData.toShorthands(), pathData.round(), pathData.toQuadratic(), pathData.toVerbose()
• individual functions like pathDataToAbsolute(pathData), pathDataToRelative(pathData), pathDataToShorthands(pathData), pathDataToShorthands(pathData), pathDataToQuadratic(pathData), roundPathData(pathData)

6.2 Usage as an addon/plugin for getPathData()

Currently, the W3C draft for the SVGPathData interface is not supported by any major browser. Fortunately Jarek Foksa wrote a this great polyfill library and also contributed to the potential spec outcome – most importantly that it should include geometry elements like circle, rect, polygon, line to retrieve path data.
This polyfill is a "battle-proof" parser! Since the W3C draft doesn't include fine-grained control over the normalisation/conversion process you can use the pathDataConvert.js script as an addon/plugin alongside with the aforementioned polyfill script. (See Demo/getPathDataAddon.html)

6.3 Convert pathdata structure

You may already have a set of parsed/abstracted path data retrieved from other libraries or APIs or need a more verbose notation.
In this case you may use these conversion methods.

6.3.1 Array notation to pathdata

A lot of libraries – such as snap.svg use a nested array structure for each command like so

[
    ["M", 0, 0] ,
    ["L", 0.5, 0.5],
    ["L", 1, 1],
    ["A", 5, 10, 45, 1, 0, 41, 21]
]

In case you need to convert these you can use the helper methods (included in pathDataConvert.js) to convert format in both directions

• convertArrayPathData(pathDataArray)
• revertPathDataToArray(pathData)

6.3.2 pathDataToVerbose(pathData)

Besides you can use pathDataToVerbose(pathData) to get a more detailed data array including original and absolute point coordinates as well as parametrized arc data rx and ry, startAngle, endAngle, deltaAngle (in radians)

let data = [
  {
    type: "M",
    values: [0, 0],
    valuesAbsolute: [0, 0],
    pFinal: { x: 0, y: 0 },
    isRelative: false
  },
  {
    type: "l",
    values: [0.5, 0.5],
    valuesAbsolute: [0.5, 0.5],
    pFinal: { x: 0.5, y: 0.5 },
    isRelative: true,
    pPrev: { x: 0, y: 0 }
  },
  {
    type: "l",
    values: [0.5, 0.5],
    valuesAbsolute: [1, 1],
    pFinal: { x: 1, y: 1 },
    isRelative: true,
    pPrev: { x: 0.5, y: 0.5 }
  },
  {
    type: "a",
    values: [5, 10, 45, 1, 0, 40, 20],
    valuesAbsolute: [5, 10, 45, 1, 0, 41, 21],
    pFinal: { x: 41, y: 21 },
    isRelative: true,
    pPrev: { x: 1, y: 1 },
    rx: 21.505813167606572,
    ry: 43.011626335213144,
    xAxisRotation: 45,
    largeArcFlag: 1,
    sweepFlag: 0,
    startAngle: 2.976443999504017,
    endAngle: 6.118036608390327,
    deltaAngle: -3.1415926982932767
  }
];

7. Demos

• parse pathdata with different normalization options (demos/index.html)
• pathDataConvert.js as a addon/plugin for path.getPathData() (demos/getPathDataAddon.html)
• convert commands to pretty much anything | (demos/converter.html)

Credits

• Jarek Foksa for his great polyfill heavily inspring to adopt the new pathData interface methodology and for contributing to the specification
• Dmitry Baranovskiy for (raphael.j/snap.svg) pathToAbsolute/Relative functions
• Vitaly Puzrin (fontello) for the arc to cubic conversion method a2c.js and cubic to quadratic approximation
• Mike "POMAX" Kammermans for his great A Primer on Bézier Curves