Skip to content

JavaScript API

Jump to bottom
thednp edited this page Oct 13, 2024 · 25 revisions

Instance Methods

The SVGPathCommander class comes with most useful public methods, intuitive and easy to use:

instance.getBBox()

Returns the path bounding box, equivalent to native path.getBBox().

instance.getTotalLength()

Returns the total path length, equivalent to native path.getTotalLength().

instance.getPointAtLength()

Returns a {x,y} point in path stroke at a given length, equivalent to native path.getPointAtLength().

instance.toRelative()

Converts all path commands of a shape with or without sub-path to relative values.

instance.toCurve()

Will convert all segments of a SVGPathElement to cubicBezier segments; this method will also remove unnecessary Z segments.

instance.reverse(onlySubpath: boolean | undefined)

Will reverse the shape draw direction by changing the order of all path segments and their coordinates; when the onlySubpath option is true, it will only reverse the draw direction of subpath shapes

instance.normalize()

Converts path command values to absolute and convert shorthand S, T, H, V to C, Q and L respectively.

instance.optimize()

Will execute an algorithm to find shorthand notation for eligible segments then will compute two PathArrays one with absolute and the other with relative values, then update the PathArray segments using the values that convert to shortest string.

instance.transform(transform: TransformObject)

Will normalize all path commands and apply a 2D transformation matrix to all path commands.

instance.flipX()

Will call the above transform() method to apply a 180deg rotation on the X axis.

instance.flipY()

Will call the above transform() method to apply a 180deg rotation on the Y axis.

instance.toString()

Will return the pathString of the current PathArray stored in the instance.segments object.

Instance Getters

instance.bbox

A new getter that returns the path bounding box.

instance.length

A new getter that returns the path total length.

Instance Options

  • round Number | "off" - option to enable/disable value rounding for the processing output; the default value is 4 but you can disable rounding the values with round: "off"
  • origin [Number, Number, Number] - option to set a transform origin for transformations; if not provided, the default value [0, 0, 0] will be used.

Static Methods

When using the distribution files, type in "SVGPathCommander." in your browser console and have a look, there are a wide range of tools to play with. Here are some notable utilities:

  • SVGPathCommander.isValidPath(pathString: string) - checks if a path string is valid;
  • SVGPathCommander.getSVGMatrix(transform: TransformObject): CSSMatrix returns the CSSMatrix (DOMMatrix compatible instance) for a given TransformObject (EG: { scale?: [x: number, y: number, z: number], translate: [x: number, y: number, z: number], ... })
  • SVGPathCommander.shapeToPath(element, replace) - returns a new <path> element from a given <line>, <polyline>, <polygon>, <rect>, <ellipse>, <circle> or <glyph> element; the newly created <path> element keeps all non-specific attributes like class, fill, etc.; when the replace parameter is true, it will replace the target element; you can also create <path> elements on the fly by providing the minimum required specific attributes: EG: SVGPathCommander.shapeToPath({type: 'circle', r: 5, cx: 15, cy:15});
  • SVGPathCommander.parsePathString(pathString: string) - returns a PathArray which is used by all of SVGPathCommander processing tools;
  • SVGPathCommander.pathToAbsolute(path: string | PathArray) - returns a new PathArray having all path commands as absolute coordinates;
  • SVGPathCommander.pathToRelative(path: string | PathArray) - returns a new PathArray having all path commands as relative coordinates;
  • SVGPathCommander.pathToCurve(path: string | PathArray) - returns a new PathArray having all path commands converted to cubicBezierTo (C) and absolute values;
  • SVGPathCommander.pathToString(path: PathArray, round: number) - converts any PathArray to string and returns it, also allowing you to set the amount of decimals to round values to;
  • SVGPathCommander.clonePath(path: PathArray) - returns a deep clone of a PathArray, which is the result of any of the above functions;
  • SVGPathCommander.roundPath(path: PathArray, round: number) - returns a new PathArray with all float path command values rounded to 4 decimals by default, or provide a number to be used as the amount of decimals to round values to; the round parameter allows you to disable rounding by using the value: "off";
  • SVGPathCommander.reversePath(path: string | PathArray) - returns a new PathArray with all path commands having absolute values and in reverse order, but only for a single M->Z shape, for paths having sub-path(s) you need to use the SVGPathCommander constructor itself;
  • SVGPathCommander.optimizePath(path: PathArray) - returns a new PathArray with all segments that have the shortest strings from either absolute or relative PathArray segments;
  • SVGPathCommander.transformPath(path: PathArray | string, transformObject: TransformObject) - returns a new PathArray with all segments transformed according to the properties defined in the transformObject;
  • SVGPathCommander.normalizePath(path: string | PathArray) - returns a new PathArray with all shorthand path command segments such as S, T are converted to C and Q respectively, V and H to L, all in absolute values; the utility is used by pathToCurve and reversePath;
  • SVGPathCommander.getDrawDirection(path: PathArray) - converts the PathArray to curve and returns TRUE if a shape draw direction is clockwise, it should work for shapes with sub-paths, but it might skew your results, so make sure you split your path and test each sub-path separately;
  • SVGPathCommander.getPathBBox(path: PathArray) - converts the PathArray to curve and returns the bounding box of a shape in the form of the following object: {x1,y1, x2,y2, width,height, cx,cy,cz}, where cx & cy are the shape's center point, cz is more of a transformOriginZ for 3D projections; for faster processing, you might want to split the path with sub-paths and return the bounding box you know is the largest;
  • SVGPathCommander.getTotalLength(path: PathArray | string) - will normalize the PathArray and return the total length of the shape; this is equivalent to SVGPathElement.prototype.getTotalLength() and should work in Node.js;
  • SVGPathCommander.getPointAtLength(path: PathArray | string, distance: number) - normalizes the PathArray and looks into each segment to return an {x,y} object which represents a point at the given distance;
  • SVGPathCommander.splitPath(path: PathArray) - returns an Array comprised of PathArray items;
  • SVGPathCommander.fixPath(path: string | PathArray) - checks if a PathArray has an unnecessary Z segment and returns a new PathArray without it;
  • SVGPathCommander.getPropertiesAtLength(path: PathArray | string, distance: number) - returns an object with the following properties: the segment in which the distance spans, the index of the segment, the length of the segment and length to the segment;
  • SVGPathCommander.getPropertiesAtPoint(path: PathArray | string, point: { x: number, y: number }) - returns an object with the following properties: the closest point in stroke, the distance to closest point and the segment which contains the closest point;
  • SVGPathCommander.getClosestPoint(path: PathArray | string, point: { x: number, y: number }) - returns an {x,y} object with the coordinates of a point that is closest to a given {x,y} point;
  • SVGPathCommander.isPointInStroke(path: PathArray | string, point: { x: number, y: number })* - checks if a given {x,y} point is along the stroke of a path;
  • SVGPathCommander.getSegmentOfPoint(path: PathArray | string, point: { x: number, y: number }) - returns the segment that contains a given {x,y} point;
  • SVGPathCommander.getSegmentAtLength(path: PathArray | string, distance: number) - returns the segment reached by a given distance.
Clone this wiki locally