@davepagurek/flo-mat

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>FloMat</title> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">FloMat</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-only-exported" /> <label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <ul class="tsd-breadcrumb"> <li> <a href="globals.html">Globals</a> </li> </ul> <h1> FloMat</h1> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <a href="#medial-and-scale-axis-transform-library---svg-focused" id="medial-and-scale-axis-transform-library---svg-focused" style="color: inherit; text-decoration: none;"> <h1>Medial (and Scale) Axis Transform library - SVG focused</h1> </a> A pure JavaScript (source in TypeScript) Medial (and Scale) Axis Transform (MAT/SAT) library. <hr> Bug reports, pull requests and ⭐⭐⭐⭐⭐s are welcome and appreciated! <hr> <a href="https://mat-demo.appspot.com">Demo</a> <a href="https://stackblitz.com/edit/typescript-yucdon">Full simple 140 Lines of Code live StackBlitz project</a> <a href="https://github.com/FlorisSteenkamp/MAT">GitHub</a> <a href="https://github.com/FlorisSteenkamp/mat-examples">More examples</a> <a href="https://mat-demo.appspot.com/docs/index.html">Documentation</a>, but also see installation instructions below. <a href="#introduction" id="introduction" style="color: inherit; text-decoration: none;"> <h2>Introduction</h2> </a> The <a href="https://en.wikipedia.org/wiki/Medial_axis">MAT</a> is an analytical form of skeletonization of a shape. It is perfectly suited to SVG. Described by many scholars as the most important image transform, it has endless use cases, e.g.: <ul> <li>Morphing</li> <li>Shape thinning and fattening ⭐⭐ NEW ⭐⭐ <a href="https://stackblitz.com/edit/typescript-xuruhe?file=index.ts">StackBlitz demo</a></li> <li>Shape classification</li> <li>Shape simplification</li> <li>Image compression</li> <li>Shape Triangulation</li> </ul> The <a href="http://www.balintmiklos.com/scale-axis/theory_socg_2009.html">SAT</a> is similar to the MAT (and indeed uses it as input) but is often more practical as it removes insignifacant MAT branches based on the local image scale. The culling severity of branches is controlled by a parameter called s. In the image below, the gray silhouette is the original SVG shape and the blue curves represents the SAT. The SAT (and MAT) is internally represented as a tree data structure with branches being quadratic beziers. <img src="https://raw.github.com/FlorisSteenkamp/MAT/master/github%20assets/two-hole.png" alt="Alt text"> FloMat is a MAT/SAT library for planar shapes composed of a closed sequence of linear, quadratic and cubic bezier curves (such as in SVG). The shape need not be simple, can contain holes and may include multiple 'loops'. For those who are interested, the implementation of the MAT is based on a paper by Hyeong In Choi, Sung Woo Choi, Hwan Pyo Moon and Nam-Sook Wee that can be freely downloaded <a href="https://pdfs.semanticscholar.org/70ae/5b583303af0b4d60d356d08f8ed84e1babbc.pdf">here</a>. It also gives some valuable insight into the nature of the MAT. For a less mathematical explanation of the algorithm see <a href="https://stackoverflow.com/questions/29921826/how-do-i-calculate-the-medial-axis-for-a-2d-vector-shape">this Stack Overflow answer</a>. The implementation of the SAT is similar to the original ideas that can be found in <a href="http://www.balintmiklos.com/scale-axis/scale_axis_transform_socg_2009.pdf">this paper</a> but it has been improved to preserve topology at any scale >= 1. It also guarantees that the SAT is a subset of the MAT. <a href="#code-example" id="code-example" style="color: inherit; text-decoration: none;"> <h1>Code example</h1> </a> Note that the example code given here is in TypeScript since the types make the code clearer but plain JavaScript can also be used. The live, interactive code can be viewed in this <a href="https://stackblitz.com/edit/typescript-yucdon">StackBlitz project</a>. The code can also be found under 'draw-mat-ts' in the <a href="https://github.com/FlorisSteenkamp/mat-examples">examples on GitHub</a>. Only the .css and .ts files are reproduced here. style.css <pre><code class="language-css">h1, h2 { font-family: Lato; } .shape-path { fill: lightgray; stroke: darkgray; stroke-width: 0.1%; } .mat { fill: none; stroke: deeppink; stroke-width: 0.1%; } .sat { fill: none; stroke: blue; stroke-width: 0.2%; }</code></pre> index.ts <pre><code class="language-typescript">import './style.css'; // Import stylesheets import { findMats, getPathsFromStr, Mat, traverseEdges, toScaleAxis } from 'flo-mat'; const NS = 'http://www.w3.org/2000/svg'; // Svg namespace /** * Creates and returns an SVG DOM element. * @param id The dom id to assign to the SVG element, e.g. 1 -> 'svg-1' */ function createSvg(id: number) { let $e = document.createElementNS(NS, 'svg'); $e.setAttributeNS(null, 'id', 'svg' + id); $e.setAttributeNS(null, 'style', 'width: 100%; display: inline-block'); $e.setAttributeNS(null, 'viewBox', '75 4 557 502'); return $e; } /** * Returns an SVG path string of a line. * @param ps The line endpoints. */ function getLinePathStr(ps: number[][]) { let [[x0,y0],[x1,y1]] = ps; return `M${x0} ${y0} L${x1} ${y1}`; } /** * Returns an SVG path string of a quadratic bezier curve. * @param ps The quadratic bezier control points. */ function getQuadBezierPathStr(ps: number[][]) { let [[x0,y0],[x1,y1],[x2,y2]] = ps; return `M${x0} ${y0} Q${x1} ${y1} ${x2} ${y2}`; } /** * Returns an SVG path string of a cubic bezier curve. * @param ps The cubic bezier control points. */ function getCubicBezierPathStr(ps: number[][]) { let [[x0,y0],[x1,y1],[x2,y2],[x3,y3]] = ps; return `M${x0} ${y0} C${x1} ${y1} ${x2} ${y2} ${x3} ${y3}`; } /** * The SVG path string representing our shape. */ const svgPathStr = ` M 144 251 C 145 169 110 82 227 59 C 344 36 429 -46 505 96 C 581 238 696 407 554 435 C 412 463 191 532 197 442 C 203 352 213 363 276 346 C 339 329 563 318 437 242 C 311 166 302 181 297 314 C 292 447 160 585 151 419 C 142 253 87.12 312.78 86 314 C 87.16 312.74 142.8632 252.2348 144 251 z `; /** * Adds a path to the given SVG element and give it a shape-path class. */ function setSvgShapePath( $svg: SVGSVGElement, pathStr: string) { let $path = document.createElementNS(NS, 'path'); // Create SVG path elem. $path.setAttribute('class', 'shape-path'); $svg.appendChild($path); // Add the path element to the SVG. document.body.appendChild($svg); // Add the SVG to the document body. $path.setAttribute('d', svgPathStr); } function main() { // Create and add and SVG element to our HTML page. let $svg = createSvg(1); // Create SVG element. setSvgShapePath($svg, svgPathStr); // Get loops (representing the shape) from some SVG path. let bezierLoops = getPathsFromStr(svgPathStr); // We could also just give an array of linear, quadratic or cubic beziers as // below (all lines in this case). Note that in the below case there is only // one array of beziers (forming a single loop shape). /* bezierLoops = [ [ [[50.000, 95.000],[92.797, 63.905]], [[92.797, 63.905],[76.450, 13.594]], [[76.450, 13.594],[23.549, 13.594]], [[23.549, 13.594],[7.202, 63.90]], [[7.202, 63.900],[50.000, 95.000]] ] ]; */ // Get MATs from the loops. let mats = findMats(bezierLoops, 3); // Draw the MATs. drawMats(mats, $svg, 'mat'); // Get the SAT (at scale 1.5) of the MATs (of which there is only 1) let sats = mats.map(mat => toScaleAxis(mat, 1.5)); drawMats(sats, $svg, 'sat'); } /** * Returns a function that draws an array of MAT curves on an SVG element. * @param mats An array of MATs to draw. * @param svg The SVG element on which to draw. * @param type The type of MAT to draw. This simply affects the class on the * path element. */ function drawMats( mats: Mat[], svg: SVGSVGElement, type: string /* 'mat' | 'sat' */) { mats.forEach(f); /** * Draws a MAT curve on an SVG element. */ function f(mat: Mat) { let cpNode = mat.cpNode; if (!cpNode) { return; } let fs = [,,getLinePathStr, getQuadBezierPathStr, getCubicBezierPathStr]; traverseEdges(cpNode, function(cpNode) { if (cpNode.isTerminating()) { return; } let bezier = cpNode.matCurveToNextVertex; if (!bezier) { return; } let $path = document.createElementNS(NS, 'path'); $path.setAttributeNS( null, "d", fs[bezier.length](bezier) ); $path.setAttributeNS(null, "class", type); svg.appendChild($path); }); } } main();</code></pre> The first part of the code is just concerned with importing stuff. Then there is a function for programatically creating an SVG HTML element. The next three functions, <code>getLinePathStr</code>, <code>getQuadBezierPathStr</code> and <code>getCubicBezierPathStr</code> will be used for creating the paths that will represent the Medial Axis on our SVG. Following that is the SVG path string of our shape and a function, <code>setSvgShapePath</code>, to add the path to the SVG. The next function, <code>main</code>, is the entry point of our example. The first two lines creates the SVG and sets the path. The third line: <pre><code class="language-typescript">let bezierLoops = getPathsFromStr(svgPathStr);</code></pre> extracts the path data into an array that is suitable to be comsumed by <code>findMats</code>, the function from the library that will do the number crunching and return an array of Medial Axis Transforms. The array, <code>bezierLoops</code> is of type <code>number[][][][]</code>. It is an array of 'loops'. Each 'loop' (of which there is only one in our case) is a sequence of bezier curves such that the starting point of the first bezier corresponds to the end point of the last. Each bezier in the loop is represented by its (2, 3 or 4) control points which has type signature <code>number[][]</code> hence the type <code>number[][][][]</code> for <code>bezierLoops</code>. For example, the cubic bezier with control points at (1,1), (5,1), (5,2) and (4,2) is represented as an array of points <code>[[1,1],[5,1],[5,2],[4,2]]</code>. A loop consisting of just 2 beziers can be encoded as say <code>[ [[1,1],[5,1],[5,2],[4,2]], [4,2],[3,3],[1,3],[1,1] ]</code> and finally we can make an array of loops from this (containing just 1 element) as follows: <code>[[ [[1,1],[5,1],[5,2],[4,2]], [4,2],[3,3],[1,3],[1,1] ]]</code>. The reason for being able to provide an array of loops is because a shape might consist of an outer loop with one or more inner loops representing holes. This is also reflected in the fact that SVG paths can have sub-paths. In such a case the inner loops must have opposite orientation than the outer envelope loop. The rule used to indicate which loops form holes and which are part of the shape is the default SVG <a href="https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule">non-zero</a> fill rule. Loops may also intersect each other, in the process possibly creating more than one disjoint shape. In the above example a single intersecting loop creates a shape with a hole. This brings us to the heart of the example, the <code>findMats</code> function. <pre><code class="language-typescript">let mats = findMats(bezierLoops, 3);</code></pre> The function extracts the Medial Axis Transforms of all shapes created by the the array of input bezier loops. It takes an additional parameter indicating the number of points on each bezier for which a MAT vertex 'point' should be calculated. A value of 3 is the default and is a reasonable compromise between speed and accuracy. A value of 15 would give highly accurate results. In the special case of a single non-intersecting closed loop the returned MAT array will be of length 1. Let us look at it in more detail. The returned MAT is essentially a tree data structure. Even if the shape contains holes it is a tree since the graph is snipped at so-called hole-closing maximal disks to form a tree. (It is still possible though to traverse the MAT as a non-tree graph if required). As in the example code above, we can traverse the tree to draw the Medial Axis (MA). This is done by utilizing the <code>traverseEdges</code> function. (Note that the MA is the MAT but without the maximal disk radius, etc. information encoded on it). This is accomplished by the <code>drawMats</code> function. The inner function, <code>f</code>, draws a single MA. First we select a tree node as the root of the MAT tree. One such node is given to us via <code>mat.cpNode</code>. The tree can now be traversed from this node outwards to the tree leaves just like in any other tree traversal. Each node, which is a class of type <code>CpNode</code> (for Contact Point Node), has several properties (see the docs). For our current purposes we only need the <code>matCurveToNextVertex</code> property. <code>matCurveToNextVertex</code> is a bezier curve (as defined previously with type <code>number[][]</code>) of order 1, 2 or 3 forming a part of the MA. In the example code we draw this curve on our orignal SVG. The <code>main</code> function concludes by finding the Scale Axis Transform of our found MAT and then drawing it on top of the MAT with a different css class (blue). <a href="#installation" id="installation" style="color: inherit; text-decoration: none;"> <h1>Installation</h1> </a> Whether your target is Node or the browser the library can be installed via <a href="https://www.npmjs.com/">npm</a>. (For the browser you can also download the <a href="https://raw.githubusercontent.com/FlorisSteenkamp/MAT/master/browser/index.min.js">minified.js</a> file - see below) So whatever your target, at the the command line: <pre><code class="language-cli">npm install flo-mat</code></pre> <a href="#node-with-javascript-or-the-browser-with-a-hrefhttpswebpackjsorgwebpacka-or-similar" id="node-with-javascript-or-the-browser-with-a-hrefhttpswebpackjsorgwebpacka-or-similar" style="color: inherit; text-decoration: none;"> <h2>Node with JavaScript (or the browser (with <a href="https://webpack.js.org/">webpack</a>) or similar)</h2> </a> In your project <pre><code class="language-javascript">let FloMat = require("flo-mat");</code></pre> or if you only want to require specific functionality: <pre><code class="language-javascript">let { findMats } = require('flo-mat');</code></pre> <a href="#typescript" id="typescript" style="color: inherit; text-decoration: none;"> <h2>TypeScript</h2> </a> In your project <pre><code class="language-typescript">import * as FloMat from "flo-mat";</code></pre> or for specific functionalities: <pre><code class="language-typescript">import { findMats } from "flo-mat";</code></pre> <a href="#browser-using-global-var" id="browser-using-global-var" style="color: inherit; text-decoration: none;"> <h2>Browser (using global var)</h2> </a> After the npm installation simply include the script in your project: <pre><code class="language-html"><script src='node_modules/flo-mat/browser/index.min.js'></script></code></pre> A new global object will available called <code>FloMat</code> representing the library. <a href="#usage" id="usage" style="color: inherit; text-decoration: none;"> <h1>Usage</h1> </a> Please see the documentation for the primary functions and classes: <a href="https://mat-demo.appspot.com/docs/modules/_find_mats_.html">findMats</a>, <a href="https://mat-demo.appspot.com/docs/modules/_to_scale_axis_.html">toScaleAxis</a> and <a href="https://mat-demo.appspot.com/docs/classes/_cp_node_.cpnode.html">CpNode</a>. <a href="#documentation" id="documentation" style="color: inherit; text-decoration: none;"> <h1>Documentation</h1> </a> For documentation and code examples please see the <a href="https://mat-demo.appspot.com/docs/index.html">documentation</a> <a href="#license" id="license" style="color: inherit; text-decoration: none;"> <h1>License</h1> </a> The MIT License (MIT) Copyright © 2018 Floris Steenkamp Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. </div> </div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class="globals "> <a href="globals.html">Globals</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_beziers_to_svg_path_str_.html">"beziers-to-svg-path-str"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_circle_.html">"circle"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_contact_point_.html">"contact-point"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_cp_node_.html">"cp-node"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_curve_.html">"curve"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_find_mats_.html">"find-mats"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_get_boundary_bezier_parts_to_next_.html">"get-boundary-bezier-parts-to-next"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_get_boundary_beziers_to_next_.html">"get-boundary-beziers-to-next"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_get_branches_.html">"get-branches"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_get_curve_to_next_.html">"get-curve-to-next"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_get_paths_from_str_.html">"get-paths-from-str"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_loop_.html">"loop"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_mat_.html">"mat"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_point_on_shape_.html">"point-on-shape"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_simplify_mat_.html">"simplify-mat"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_to_scale_axis_.html">"to-scale-axis"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_traverse_edges_.html">"traverse-edges"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_traverse_vertices_.html">"traverse-vertices"</a> </li> </ul> </nav> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> </ul> </nav> </div> </div> </div> <footer class="with-border-bottom"> <div class="container"> <h2>Legend</h2> <div class="tsd-legend-group"> <ul class="tsd-legend"> <li class="tsd-kind-module">Module</li> <li class="tsd-kind-object-literal">Object literal</li> <li class="tsd-kind-variable">Variable</li> <li class="tsd-kind-function">Function</li> <li class="tsd-kind-function tsd-has-type-parameter">Function with type parameter</li> <li class="tsd-kind-index-signature">Index signature</li> <li class="tsd-kind-type-alias">Type alias</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-enum">Enumeration</li> <li class="tsd-kind-enum-member">Enumeration member</li> <li class="tsd-kind-property tsd-parent-kind-enum">Property</li> <li class="tsd-kind-method tsd-parent-kind-enum">Method</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-interface">Interface</li> <li class="tsd-kind-interface tsd-has-type-parameter">Interface with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-interface">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-interface">Property</li> <li class="tsd-kind-method tsd-parent-kind-interface">Method</li> <li class="tsd-kind-index-signature tsd-parent-kind-interface">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-class">Class</li> <li class="tsd-kind-class tsd-has-type-parameter">Class with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-class">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-class">Property</li> <li class="tsd-kind-method tsd-parent-kind-class">Method</li> <li class="tsd-kind-accessor tsd-parent-kind-class">Accessor</li> <li class="tsd-kind-index-signature tsd-parent-kind-class">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited">Inherited constructor</li> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited">Inherited property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited">Inherited method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited">Inherited accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected">Protected property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected">Protected method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected">Protected accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-private">Private property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-private">Private method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private">Private accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-static">Static property</li> <li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static">Static method</li> </ul> </div> </div> </footer> <div class="container tsd-generator"> Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a> </div> <div class="overlay"></div> <script src="assets/js/main.js"></script> <script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script> </body> </html>