Path

Extends Item, PathItem

The path item represents a path in a Paper.js project.

Constructors

Path([segments])

Creates a new path item and places it at the top of the active layer.

Parameters:

segments: Array of Segment objects — An array of segments (or points to be converted to segments) that will be added to the path — optional

Returns:

Path — the newly created path

Example:Create an empty path and add segments to it:

var path = new Path();
path.strokeColor = 'black';
path.add(new Point(30, 30));
path.add(new Point(100, 100));

Example:Create a path with two segments:

var segments = [new Point(30, 30), new Point(100, 100)];
var path = new Path(segments);
path.strokeColor = 'black';

Path(object)

Creates a new path item from an object description and places it at the top of the active layer.

Parameters:

object: Object — an object containing properties to be set on the path

Returns:

Path — the newly created path

Example:

Run

Example:

Run

Path(pathData)

Creates a new path item from SVG path-data and places it at the top of the active layer.

Parameters:

pathData: String — the SVG path-data that describes the geometry of this path

Returns:

Path — the newly created path

Example:

Run

Shaped Paths

Path.Line(from, to)

Path.Line(object)

Creates a linear path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Path.Circle(center, radius)

Path.Circle(object)

Creates a circular path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Path.Rectangle(rectangle[, radius])

Creates a rectangular path item, with optionally rounded corners.

Parameters:

rectangle: Rectangle — the rectangle object describing the geometry of the rectangular path to be created
radius: Size — the size of the rounded corners — optional, default: null

Returns:

Path — the newly created path

Example:

Run

Example:The same, with rounder corners

Run

Path.Rectangle(point, size)

Creates a rectangular path item from a point and a size object.

Parameters:

point: Point — the rectangle’s top-left corner.
size: Size — the rectangle’s size.

Returns:

Path — the newly created path

Example:

Run

Path.Rectangle(from, to)

Creates a rectangular path item from the passed points. These do not necessarily need to be the top left and bottom right corners, the constructor figures out how to fit a rectangle between them.

Parameters:

from: Point — the first point defining the rectangle
to: Point — the second point defining the rectangle

Returns:

Path — the newly created path

Example:

Run

Path.Rectangle(object)

Creates a rectangular path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Example:

Run

Example:

Run

Example:

Run

Path.Ellipse(rectangle)

Path.Ellipse(object)

Creates an elliptical path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Example:Placing by center and radius

Run

Path.Arc(from, through, to)

Creates a circular arc path item.

Parameters:

from: Point — the starting point of the circular arc
through: Point — the point the arc passes through
to: Point — the end point of the arc

Returns:

Path — the newly created path

Example:

Run

Path.Arc(object)

Creates an circular arc path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Path.RegularPolygon(center, sides, radius)

Creates a regular polygon shaped path item.

Parameters:

center: Point — the center point of the polygon
sides: Number — the number of sides of the polygon
radius: Number — the radius of the polygon

Returns:

Path — the newly created path

Example:

Run

Path.RegularPolygon(object)

Creates a regular polygon shaped path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Path.Star(center, points, radius1, radius2)

Creates a star shaped path item.

The largest of radius1 and radius2 will be the outer radius of the star. The smallest of radius1 and radius2 will be the inner radius.

Parameters:

center: Point — the center point of the star
points: Number — the number of points of the star
radius1: Number
radius2: Number

Returns:

Path — the newly created path

Example:

Run

Path.Star(object)

Creates a star shaped path item from the properties described by an object literal.

Parameters:

object: Object — an object containing properties describing the path’s attributes

Returns:

Path — the newly created path

Example:

Run

Properties

segments

firstSegment

lastSegment

curves

firstCurve

lastCurve

closed

length

area

fullySelected

Methods

add(...segment)

Adds one or more segments to the end of the segments array of this path.

Parameters:

segment: Segment⟋Point⟋Array of Numbers — the segment or point to be added.

Returns:

Segment⟋Array of Segment objects — the added segment(s). This is not necessarily the same object, e.g. if the segment to be added already belongs to another path.

Example:Adding segments to a path using point objects:

Run

Example:Adding segments to a path using arrays containing number pairs:

Run

Example:Adding segments to a path using objects:

Run

Example:Adding a segment with handles to a path:

Run

insert(index, segment)

Inserts one or more segments at a given index in the list of this path’s segments.

Parameters:

index: Number — the index at which to insert the segment
segment: Segment⟋Point — the segment or point to be inserted.

Returns:

Segment — the added segment. This is not necessarily the same object, e.g. if the segment to be added already belongs to another path

Example:Inserting a segment:

Run

Example:Inserting multiple segments:

Run

addSegments(segments)

Adds an array of segments (or types that can be converted to segments) to the end of the segments array.

Parameters:

segments: Array of Segment objects

Returns:

Array of Segment objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path

Example:Adding an array of Point objects:

Run

Example:Adding an array of [x, y] arrays:

Run

Example:Adding segments from one path to another:

Run

insertSegments(index, segments)

Inserts an array of segments at a given index in the path’s segments array.

Parameters:

index: Number — the index at which to insert the segments
segments: Array of Segment objects — the segments to be inserted

Returns:

Array of Segment objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path

removeSegment(index)

removeSegments()

removeSegments(from[, to])

Removes the segments from the specified from index to the to index from the path’s segments array.

Parameters:

from: Number — the beginning index, inclusive
to: Number — the ending index, exclusive — optional, default: segments.length

Returns:

Array of Segment objects — an array containing the removed segments

Example:Removing segments from a path:

Run

hasHandles()

clearHandles()

divideAt(location)

Divides the path on the curve at the given offset or location into two curves, by inserting a new segment at the given location.

Parameters:

location: Number⟋CurveLocation — the offset or location on the path at which to divide the existing curve by inserting a new segment

Returns:

Segment — the newly inserted segment if the location is valid, null otherwise

Parameters:

location: Number⟋CurveLocation — the offset or location at which to split the path

Returns:

Path — the newly created path after splitting, if any

Example:

Run

Example:Splitting an open path Draw a V shaped path:

Run

Example:Splitting a closed path

Run

join(path[, tolerance])

Joins the path with the other specified path, which will be removed in the process. They can be joined if the first or last segments of either path lie in the same location. Locations are optionally compare with a provide tolerance value.

If null or this is passed as the other path, the path will be joined with itself if the first and last segment are in the same location.

Parameters:

path: Path — the path to join this path with; null or this to join the path with itself
tolerance: Number — the tolerance with which to decide if two segments are to be considered the same location when joining — optional, default: 0

Example:Joining two paths:

Run

Example:Joining two paths that share a point at the start or end of their segments array:

Run

Example:Joining two paths that connect at two points:

Run

reduce(options)

toShape([insert])

Attempts to create a new shape item with same geometry as this path item, and inherits all settings from it, similar to item.clone().

Parameters:

insert: Boolean — specifies whether the new shape should be inserted into the scene graph. When set to true, it is inserted above the path item — optional, default: true

Returns:

Shape — the newly created shape item with the same geometry as this path item if it can be matched, null otherwise

Positions on Paths and Curves

getLocationOf(point)

getOffsetOf(point)

getLocationAt(offset)

Returns the curve location of the specified offset on the path.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

CurveLocation — the curve location at the specified offset

getPointAt(offset)

Calculates the point on the path at the given offset.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Point — the point at the given offset

Example:Finding the point on a path at a given offset:

Run

Example:Iterating over the length of a path:

Run

getTangentAt(offset)

Calculates the normalized tangent vector of the path at the given offset.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Point — the normalized tangent vector at the given offset

Example:Working with the tangent vector at a given offset:

Run

Example:Iterating over the length of a path:

Run

getNormalAt(offset)

Calculates the normal vector of the path at the given offset.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Point — the normal vector at the given offset

Example:Working with the normal vector at a given offset:

Run

Example:Iterating over the length of a path:

Run

getWeightedTangentAt(offset)

Calculates the weighted tangent vector of the path at the given offset.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Point — the weighted tangent vector at the given offset

getWeightedNormalAt(offset)

Calculates the weighted normal vector of the path at the given offset.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Point — the weighted normal vector at the given offset

getCurvatureAt(offset)

Calculates the curvature of the path at the given offset. Curvatures indicate how sharply a path changes direction. A straight line has zero curvature, where as a circle has a constant curvature. The path’s radius at the given offset is the reciprocal value of its curvature.

Parameters:

offset: Number — the offset on the path, where 0 is at the beginning of the path and path.length at the end

Returns:

Number — the normal vector at the given offset

getOffsetsWithTangent(tangent)

Calculates path offsets where the path is tangential to the provided tangent. Note that tangents at the start or end are included. Tangents at segment points are returned even if only one of their handles is collinear with the provided tangent.

Parameters:

tangent: Point — the tangent to which the path must be tangential

Returns:

Array of Numbers — path offsets where the path is tangential to the provided tangent

Properties inherited from `Item`

id

className

name

style

The path style of the item.

Type:

Style

Example:Applying several styles to an item in one go, by passing an object to its style property:

Run

Example:Copying the style of another item:

Run

Example:Applying the same style object to multiple items:

Run

locked

visible

blendMode

The blend mode with which the item is composited onto the canvas. Both the standard canvas compositing modes, as well as the new CSS blend modes are supported. If blend-modes cannot be rendered natively, they are emulated. Be aware that emulation can have an impact on performance.

Values:

'normal', 'multiply', 'screen', 'overlay', 'soft-light', 'hard- light', 'color-dodge', 'color-burn', 'darken', 'lighten', 'difference', 'exclusion', 'hue', 'saturation', 'luminosity', 'color', 'add', 'subtract', 'average', 'pin-light', 'negation', 'source-over', 'source-in', 'source-out', 'source-atop', 'destination-over', 'destination-in', 'destination-out', 'destination-atop', 'lighter', 'darker', 'copy', 'xor'

Default:

'normal'

Type:

String

Example:Setting an item's blend mode:

Run

opacity

selected

Specifies whether the item is selected. This will also return true for Group items if they are partially selected, e.g. groups containing selected or partially selected paths.

Paper.js draws the visual outlines of selected items on top of your project. This can be useful for debugging, as it allows you to see the construction of paths, position of path curves, individual segment points and bounding boxes of symbol and raster items.

Default:

false

Type:

Boolean

Example:Selecting an item:

Run

clipMask

data

A plain javascript object which can be used to store arbitrary data on the item.

Type:

Object

Example:

var path = new Path();
path.data.remember = 'milk';

Example:

var path = new Path();
path.data.malcolm = new Point(20, 30);
console.log(path.data.malcolm.x); // 20

Example:

var path = new Path();
path.data = {
    home: 'Omicron Theta',
    found: 2338,
    pets: ['Spot']
};
console.log(path.data.pets.length); // 1

Example:

var path = new Path({
    data: {
        home: 'Omicron Theta',
        found: 2338,
        pets: ['Spot']
    }
});
console.log(path.data.pets.length); // 1

Position and Bounding Boxes

position

The item’s position within the parent item’s coordinate system. By default, this is the rectangle.center of the item’s bounds rectangle.

Type:

Point

Example:Changing the position of a path:

Run

Example:Changing the x coordinate of an item's position:

Run

pivot

The item’s pivot point specified in the item coordinate system, defining the point around which all transformations are hinging. This is also the reference point for position. By default, it is set to null, meaning the rectangle.center of the item’s bounds rectangle is used as pivot.

Default:

null

Type:

Point

bounds

strokeBounds

handleBounds

internalBounds

rotation

scaling

matrix

globalMatrix

viewMatrix

applyMatrix

Controls whether the transformations applied to the item (e.g. through transform(matrix), rotate(angle), scale(scale), etc.) are stored in its matrix property, or whether they are directly applied to its contents or children (passed on to the segments in Path items, the children of Group items, etc.).

Default:

true

Type:

Boolean

Project Hierarchy

project

view

layer

parent

The item that this item is contained within.

Type:

Item

Example:

var path = new Path();

// New items are placed in the active layer:
console.log(path.parent == project.activeLayer); // true

var group = new Group();
group.addChild(path);

// Now the parent of the path has become the group:
console.log(path.parent == group); // true

Example:Setting the parent of the item to another item

var path = new Path();

// New items are placed in the active layer:
console.log(path.parent == project.activeLayer); // true

var group = new Group();
path.parent = group;

// Now the parent of the path has become the group:
console.log(path.parent == group); // true

// The path is now contained in the children list of group:
console.log(group.children[0] == path); // true

Example:Setting the parent of an item in the constructor

var group = new Group();

var path = new Path({
    parent: group
});

// The parent of the path is the group:
console.log(path.parent == group); // true

// The path is contained in the children list of group:
console.log(group.children[0] == path); // true

children

The children items contained within this item. Items that define a name can also be accessed by name.

Please note: The children array should not be modified directly using array functions. To remove single items from the children list, use item.remove(), to remove all items from the children list, use item.removeChildren(). To add items to the children list, use item.addChild(item) or item.insertChild(index, item).

Type:

Array of Item objects

Example:Accessing items in the children array:

Run

Example:Accessing children by name:

Run

Example:Passing an array of items to item.children:

Run

firstChild

lastChild

nextSibling

previousSibling

index

Stroke Style

strokeColor

strokeWidth

strokeCap

strokeJoin

dashOffset

strokeScaling

dashArray

miterLimit

The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for item.strokeJoin, it is possible for the miter to extend far beyond the item.strokeWidth of the path. The miterLimit imposes a limit on the ratio of the miter length to the item.strokeWidth.

Default:

10

Type:

Number

Item level handler function to be called on each frame of an animation. The function receives an event object which contains information about the frame event:

Type:

Function⟋null

Options:

event.count: Number — the number of times the frame event was fired
event.time: Number — the total amount of time passed since the first frame event in seconds
event.delta: Number — the time passed in seconds since the last frame event

Example:Creating an animation:

Run

onMouseDown

The function to be called when the mouse button is pushed down on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Press the mouse button down on the circle shaped path, to make it red:

Run

Example:Press the mouse on the circle shaped paths to remove them:

Run

onMouseDrag

The function to be called when the mouse position changes while the mouse is being dragged over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Press and drag the mouse on the blue circle to move it:

Run

onMouseUp

The function to be called when the mouse button is released over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Release the mouse button over the circle shaped path, to make it red:

Run

onClick

The function to be called when the mouse clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Click on the circle shaped path, to make it red:

Run

Example:Click on the circle shaped paths to remove them:

Run

onDoubleClick

The function to be called when the mouse double clicks on the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Double click on the circle shaped path, to make it red:

Run

Example:Double click on the circle shaped paths to remove them:

Run

onMouseMove

The function to be called repeatedly while the mouse moves over the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Move over the circle shaped path, to change its opacity:

Run

onMouseEnter

The function to be called when the mouse moves over the item. This function will only be called again, once the mouse moved outside of the item first. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.

Run

Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.

Run

onMouseLeave

The function to be called when the mouse moves out of the item. The function receives a MouseEvent object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped with event.stopPropagation() or by returning false from the handler.

Type:

Function⟋null

Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:

Run

Methods inherited from `Item`

set(props)

Sets the properties of the passed object literal on this item to the values defined in the object literal, if the item has property of the given name (or a setter defined for it).

Parameters:

props: Object

Returns:

Item — the item itself

Example:Setting properties through an object literal

Run

clone([options])

Clones the item within the same project and places the copy above the item.

Options:

insert: undefined — specifies whether the copy should be inserted into the scene graph. When set to true, it is inserted above the original — default: true
deep: undefined — specifies whether the item’s children should also be cloned — default: true

Parameters:

options: Object — optional, default: { insert: true, deep: true }

Returns:

Item — the newly cloned item

Example:Cloning items:

Run

copyContent(source)

copyAttributes(source, excludeMatrix)

Copies all attributes of the specified item over to this item. This includes its style, visibility, matrix, pivot, blend-mode, opacity, selection state, data, name, etc.

Parameters:

source: Item — the item to copy the attributes from
excludeMatrix: Boolean — whether to exclude the transformation matrix when copying all attributes

rasterize([options])

Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.

Options:

resolution: Number — the desired resolution to be used when rasterizing, in pixels per inch (DPI). If not specified, the value of view.resolution is used by default. — default: view.resolution
raster: Raster — specifies a raster to be reused when rasterizing. If the raster has the desired size already, then the underlying canvas is reused and no new memory needs to be allocated. If no raster is provided, a new raster item is created and returned instead. — default: null
insert: Boolean — specifies whether the raster should be inserted into the scene graph. When set to true, it is inserted above the rasterized item. — default: true

Parameters:

options: Object — the rasterization options — optional, default: {}

Returns:

Raster — the reused raster or the newly created raster item

Example:Rasterizing an item:

Run

Geometric Tests

contains(point)

isInside(rect)

intersects(item)

Hit-testing, Fetching and Matching Items

hitTest(point[, options])

Performs a hit-test on the item and its children (if it is a Group or Layer) at the location of the specified point, returning the first found hit.

The options object allows you to control the specifics of the hit- test and may contain a combination of the following values:

Options:

options.tolerance: Number — the tolerance of the hit-test — default: paperScope.settings.hitTolerance
options.class: Function — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an instanceof check is performed: Group, Layer, Path, CompoundPath, Shape, Raster, SymbolItem, PointText, …
options.match: Function — a match function to be called for each found hit result: Return true to return the result, false to keep searching
options.fill: Boolean — hit-test the fill of items — default: true
options.stroke: Boolean — hit-test the stroke of path items, taking into account the setting of stroke color and width — default: true
options.segments: Boolean — hit-test for segment.point of Path items — default: true
options.curves: Boolean — hit-test the curves of path items, without taking the stroke color or width into account
options.handles: Boolean — hit-test for the handles (segment.handleIn / segment.handleOut) of path segments.
options.ends: Boolean — only hit-test for the first or last segment points of open path items
options.position: Boolean — hit-test the item.position of of items, which depends on the setting of item.pivot
options.center: Boolean — hit-test the rectangle.center of the bounding rectangle of items (item.bounds)
options.bounds: Boolean — hit-test the corners and side-centers of the bounding rectangle of items (item.bounds)
options.guides: Boolean — hit-test items that have Item#guide set to true
options.selected: Boolean — only hit selected items

Parameters:

point: Point — the point where the hit-test should be performed (in global coordinates system).
options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }

Returns:

HitResult — a hit result object describing what exactly was hit or null if nothing was hit

hitTestAll(point[, options])

Performs a hit-test on the item and its children (if it is a Group or Layer) at the location of the specified point, returning all found hits.

The options object allows you to control the specifics of the hit- test. See hitTest(point[, options]) for a list of all options.

Parameters:

point: Point — the point where the hit-test should be performed (in global coordinates system).
options: Object — optional, default: { fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }

Returns:

Array of HitResult objects — hit result objects for all hits, describing what exactly was hit or null if nothing was hit

Parameters:

options: Object⟋Function — the criteria to match against

Returns:

Boolean — true if the item matches all the criteria, false otherwise

Parameters:

name: String — the name of the state to match against
compare: Object — the value, function or regular expression to compare against

Returns:

Boolean — true if the item matches the state, false otherwise

Options:

options.recursive: Boolean — whether to loop recursively through all children, or stop at the current level — default: true
options.match: Function — a match function to be called for each item, allowing the definition of more flexible item checks that are not bound to properties. If no other match properties are defined, this function can also be passed instead of the options object
options.class: Function — the constructor function of the item type to match against
options.inside: Rectangle — the rectangle in which the items need to be fully contained
options.overlapping: Rectangle — the rectangle with which the items need to at least partly overlap

Parameters:

options: Object⟋Function — the criteria to match against

Returns:

Array of Item objects — the list of matching descendant items

Parameters:

options: Object⟋Function — the criteria to match against

Returns:

Item — the first descendant item matching the given criteria

Importing / Exporting JSON and SVG

exportJSON([options])

Exports (serializes) the item with its content and child items to a JSON data string.

Options:

options.asString: Boolean — whether the JSON is returned as a Object or a String — default: true
options.precision: Number — the amount of fractional digits in numbers used in JSON data — default: 5

Parameters:

options: Object — the serialization options — optional

Returns:

String — the exported JSON data

importJSON(json)

Imports (deserializes) the stored JSON data into this item. If the data describes an item of the same class or a parent class of the item, the data is imported into the item itself. If not, the imported item is added to this item’s item.children list. Note that not all type of items can have children.

Parameters:

json: String — the JSON data to import from

Returns:

Item

exportSVG([options])

Exports the item with its content and child items as an SVG DOM.

Options:

options.bounds: String⟋Rectangle — the bounds of the area to export, either as a string (‘view’, content’), or a Rectangle object: 'view' uses the view bounds, 'content' uses the stroke bounds of all content — default: ‘view’
options.matrix: Matrix — the matrix with which to transform the exported content: If options.bounds is set to 'view', paper.view.matrix is used, for all other settings of options.bounds the identity matrix is used. — default: paper.view.matrix
options.asString: Boolean — whether a SVG node or a String is to be returned — default: false
options.precision: Number — the amount of fractional digits in numbers used in SVG data — default: 5
options.matchShapes: Boolean — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: false
options.embedImages: Boolean — whether raster images should be embedded as base64 data inlined in the xlink:href attribute, or kept as a link to their external URL. — default: true

Parameters:

options: Object — the export options — optional

Returns:

SVGElement⟋String — the item converted to an SVG node or a String depending on option.asString value

importSVG(svg[, options])

Converts the provided SVG content into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.

Options:

options.expandShapes: Boolean — whether imported shape items should be expanded to path items — default: false
options.onLoad: Function — the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted item and the original svg data as a string. Only required when loading from external resources.
options.onError: Function — the callback function to call if an error occurs during loading. Only required when loading from external resources.
options.insert: Boolean — whether the imported items should be added to the item that importSVG() is called on — default: true
options.applyMatrix: Boolean — whether the imported items should have their transformation matrices applied to their contents or not — default: paperScope.settings.applyMatrix

Parameters:

svg: SVGElement⟋String — the SVG content to import, either as a SVG DOM node, a string containing SVG content, or a string describing the URL of the SVG file to fetch.
options: Object — the import options — optional

Returns:

Item — the newly created Paper.js item containing the converted SVG content

importSVG(svg, onLoad)

Imports the provided external SVG file, converts it into Paper.js items and adds them to the this item’s children list. Note that the item is not cleared first. You can call item.removeChildren() to do so.

Parameters:

svg: SVGElement⟋String — the URL of the SVG file to fetch.
onLoad: Function — the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted item and the original svg data as a string. Only required when loading from external files.

Returns:

Item — the newly created Paper.js item containing the converted SVG content

Hierarchy Operations

addChild(item)

Adds the specified item as a child of this item at the end of the its children list. You can use this function for groups, compound paths and layers.

Parameters:

item: Item — the item to be added as a child

Returns:

Item — the added item, or null if adding was not possible

insertChild(index, item)

Inserts the specified item as a child of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.

Parameters:

index: Number — the index at which to insert the item
item: Item — the item to be inserted as a child

Returns:

Item — the inserted item, or null if inserting was not possible

addChildren(items)

Adds the specified items as children of this item at the end of the its children list. You can use this function for groups, compound paths and layers.

Parameters:

items: Array of Item objects — the items to be added as children

Returns:

Array of Item objects — the added items, or null if adding was not possible

insertChildren(index, items)

Inserts the specified items as children of this item at the specified index in its children list. You can use this function for groups, compound paths and layers.

Parameters:

index: Number
items: Array of Item objects — the items to be appended as children

Returns:

Array of Item objects — the inserted items, or null if inserted was not possible

insertAbove(item)

insertBelow(item)

sendToBack()

bringToFront()

addTo(owner)

copyTo(owner)

Clones the item and adds it to the specified owner, which can be either a Item or a Project.

Parameters:

owner: Project⟋Layer⟋Group⟋CompoundPath — the item or project to copy the item to

Returns:

Item — the new copy of the item, if it was successfully added

remove()

replaceWith(item)

removeChildren()

removeChildren(start[, end])

Removes the children from the specified start index to and excluding the end index from the parent’s children array.

Parameters:

start: Number — the beginning index, inclusive
end: Number — the ending index, exclusive — optional, default: children.length

Returns:

Array of Item objects — an array containing the removed items

reverseChildren()

Tests

isEmpty([recursively])

Specifies whether the item has any content or not. The meaning of what content is differs from type to type. For example, a Group with no children, a TextItem with no text content and a Path with no segments all are considered empty.

Parameters:

recursively: Boolean — whether an item with children should be considered empty if all its descendants are empty — optional, default: false

Returns:

Boolean

Style Tests

hasFill()

hasStroke()

hasShadow()

Hierarchy Tests

hasChildren()

isInserted()

isAbove(item)

isBelow(item)

isParent(item)

isChild(item)

isDescendant(item)

isAncestor(item)

isSibling(item)

isGroupedWith(item)

Transform Functions

translate(delta)

rotate(angle[, center])

Rotates the item by a given angle around the given center point.

Angles are oriented clockwise and measured in degrees.

Parameters:

angle: Number — the rotation angle
center: Point — optional, default: item.position

Example:Rotating an item:

Run

Example:Rotating an item around a specific point:

Run

scale(scale[, center])

Scales the item by the given value from its center point, or optionally from a supplied point.

Parameters:

scale: Number — the scale factor
center: Point — optional, default: item.position

Example:Scaling an item from its center point:

Run

Example:Scaling an item from a specific point:

Run

scale(hor, ver[, center])

Scales the item by the given values from its center point, or optionally from a supplied point.

Parameters:

hor: Number — the horizontal scale factor
ver: Number — the vertical scale factor
center: Point — optional, default: item.position

Example:Scaling an item horizontally by 300%:

Run

shear(shear[, center])

Shears the item by the given value from its center point, or optionally by a supplied point.

Parameters:

shear: Point — the horizontal and vertical shear factors as a point
center: Point — optional, default: item.position

Parameters:

hor: Number — the horizontal shear factor
ver: Number — the vertical shear factor
center: Point — optional, default: item.position

Parameters:

skew: Point — the horizontal and vertical skew angles in degrees
center: Point — optional, default: item.position

Parameters:

hor: Number — the horizontal skew angle in degrees
ver: Number — the vertical sskew angle in degrees
center: Point — optional, default: item.position

Parameters:

rectangle: Rectangle
fill: Boolean — optional, default: false

Example:Fitting an item to the bounding rectangle of another item's bounding rectangle:

Run

Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true:

Run

Example:Fitting an item to the bounding rectangle of the view

Run

Event Handling

on(type, function)

Attaches an event handler to the item.

Parameters:

type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
function: Function — the function to be called when the event occurs, receiving a MouseEvent or Event object as its sole argument

Returns:

Item — this item itself, so calls can be chained

Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.

Run

on(object)

Attaches one or more event handlers to the item.

Parameters:

object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave

Returns:

Item — this item itself, so calls can be chained

Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.

Run

Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set black.

Run

off(type, function)

Detach an event handler from the item.

Parameters:

type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
function: Function — the function to be detached

Returns:

Item — this item itself, so calls can be chained

off(object)

Detach one or more event handlers to the item.

Parameters:

object: Object — an object containing one or more of the following properties: frame, mousedown, mouseup, mousedrag, click, doubleclick, mousemove, mouseenter, mouseleave

Returns:

Item — this item itself, so calls can be chained

emit(type, event)

Emit an event on the item.

Parameters:

type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’
event: Object — an object literal containing properties describing the event

Returns:

Boolean — true if the event had listeners, false otherwise

responds(type)

Check if the item has one or more event handlers of the specified type.

Parameters:

type: String — the type of event: ‘frame’, mousedown’, ‘mouseup’, ‘mousedrag’, ‘click’, ‘doubleclick’, ‘mousemove’, ‘mouseenter’, ‘mouseleave’

Returns:

Boolean — true if the item has one or more event handlers of the specified type, false otherwise

Remove On Event

removeOn(options)

Removes the item when the events specified in the passed options object occur.

Options:

options.move: undefined — {Boolean) remove the item when the next tool.onMouseMove event is fired.
options.drag: undefined — {Boolena) remove the item when the next tool.onMouseDrag event is fired.
options.down: undefined — {Boolean) remove the item when the next tool.onMouseDown event is fired.
options.up: undefined — {Boolean) remove the item when the next tool.onMouseUp event is fired.

Parameters:

options: Object

Example:Click and drag below:

Run

removeOnMove()

removeOnDown()

removeOnDrag()

removeOnUp()

Tweening Functions

tween(from, to, options)

Tween item between two states.

Options:

options.duration: Number — the duration of the tweening
options.easing: Function⟋String — an easing function or the type of the easing: ‘linear’ ‘easeInQuad’ ‘easeOutQuad’ ‘easeInOutQuad’ ‘easeInCubic’ ‘easeOutCubic’ ‘easeInOutCubic’ ‘easeInQuart’ ‘easeOutQuart’ ‘easeInOutQuart’ ‘easeInQuint’ ‘easeOutQuint’ ‘easeInOutQuint’ — default: ‘linear’
options.start: Boolean — whether to start tweening automatically — default: true

Parameters:

from: Object — the state at the start of the tweening
to: Object — the state at the end of the tweening
options: Object⟋Number — the options or the duration

Returns:

Tween

Example:Tween fillColor:

Run

Example:Tween rotation:

Run

tween(to, options)

Tween item to a state.

Parameters:

to: Object — the state at the end of the tweening
options: Object⟋Number — the options or the duration

Returns:

Tween

Example:Tween a nested property with relative values

Run

tween(options)

tweenTo(to, options)

tweenFrom(from, options)

Tween item from a state to its state before the tweening.

Parameters:

from: Object — the state at the start of the tweening
options: Object⟋Number — the options or the duration

Returns:

Tween

Example:Tween fillColor from red to the path's initial fillColor:

Run

Properties inherited from `PathItem`

interiorPoint

clockwise

Specifies whether the path as a whole is oriented clock-wise, by looking at the path’s area. Note that self-intersecting paths and sub-paths of different orientation can result in areas that cancel each other out.

Type:

Boolean

Methods inherited from `PathItem`

Boolean Path Operations

unite(path[, options])

Unites the geometry of the specified path with this path’s geometry and returns the result as a new path item.

Options:

options.insert: Boolean — whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation — default: true

Parameters:

path: PathItem — the path to unite with
options: Object — the boolean operation options — optional

Returns:

PathItem — the resulting path item

intersect(path[, options])

Intersects the geometry of the specified path with this path’s geometry and returns the result as a new path item.

Options:

options.insert: Boolean — whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation — default: true
options.trace: Boolean — whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections, keeping the parts of the curves that intersect with the area of the second path. — default: true

Parameters:

path: PathItem — the path to intersect with
options: Object — the boolean operation options — optional

Returns:

PathItem — the resulting path item

subtract(path[, options])

Subtracts the geometry of the specified path from this path’s geometry and returns the result as a new path item.

Options:

options.insert: Boolean — whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation — default: true
options.trace: Boolean — whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections, removing the parts of the curves that intersect with the area of the second path. — default: true

Parameters:

path: PathItem — the path to subtract
options: Object — the boolean operation options — optional

Returns:

PathItem — the resulting path item

exclude(path[, options])

Excludes the intersection of the geometry of the specified path with this path’s geometry and returns the result as a new path item.

Options:

options.insert: Boolean — whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation — default: true

Parameters:

path: PathItem — the path to exclude the intersection of
options: Object — the boolean operation options — optional

Returns:

PathItem — the resulting path item

divide(path[, options])

Splits the geometry of this path along the geometry of the specified path returns the result as a new group item. This is equivalent to calling subtract(path) and intersect(path) and putting the results into a new group.

Options:

options.insert: Boolean — whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation — default: true
options.trace: Boolean — whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections. — default: true

Parameters:

path: PathItem — the path to divide by
options: Object — the boolean operation options — optional

Returns:

PathItem — the resulting path item

reorient([nonZero[, clockwise]])

Fixes the orientation of the sub-paths of a compound-path, assuming that non of its sub-paths intersect, by reorienting them so that they are of different winding direction than their containing paths, except for disjoint sub-paths, i.e. islands, which are oriented so that they have the same winding direction as the the biggest path.

Parameters:

nonZero: Boolean — controls if the non-zero fill-rule is to be applied, by counting the winding of each nested path and discarding sub-paths that do not contribute to the final result — optional, default: false
clockwise: Boolean — if provided, the orientation of the root paths will be set to the orientation specified by clockwise, otherwise the orientation of the largest root child is used. — optional

Returns:

PathItem — a reference to the item itself, reoriented

Path Intersections and Locations

getIntersections(path[, include])

Returns all intersections between two PathItem items as an array of CurveLocation objects. CompoundPath items are also supported.

Parameters:

path: PathItem — the other item to find the intersections with
include: Function — a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall return true to include a location, false otherwise. — optional

Returns:

Array of CurveLocation objects — the locations of all intersection between the paths

Example:Finding the intersections between two paths

Run

getCrossings(path)

Returns all crossings between two PathItem items as an array of CurveLocation objects. CompoundPath items are also supported. Crossings are intersections where the paths actually are crossing each other, as opposed to simply touching.

Parameters:

path: PathItem — the other item to find the crossings with

Returns:

Array of CurveLocation objects — the locations of all crossings between the paths

Parameters:

point: Point — the point for which we search the nearest location

Returns:

CurveLocation — the location on the path that’s the closest to the specified point

getNearestPoint(point)

Returns the nearest point on the path item to the specified point.

Parameters:

point: Point — the point for which we search the nearest point

Returns:

Point — the point on the path that’s the closest to the specified point

Example:

Run

Path Manipulation

reverse()

flatten([flatness])

Flattens the curves in path items to a sequence of straight lines, by subdividing them enough times until the specified maximum error is met.

Parameters:

flatness: Number — the maximum error between the flattened lines and the original curves — optional, default: 0.25

Example:Flattening a circle shaped path:

Run

smooth([options])

Smooths the path item without changing the amount of segments in the path or moving the segments’ locations, by smoothing and adjusting the angle and length of the segments’ handles based on the position and distance of neighboring segments.

Smoothing works both for open paths and closed paths, and can be applied to the full path, as well as a sub-range of it. If a range is defined using the options.from and options.to properties, only the curve handles inside that range are touched. If one or both limits of the range are specified in negative indices, the indices are wrapped around the end of the curve. That way, a smoothing range in a close path can even wrap around the connection between the last and the first segment.

Four different smoothing methods are available:

'continuous' smooths the path item by adjusting its curve handles so that the first and second derivatives of all involved curves are continuous across their boundaries.

This method tends to result in the smoothest results, but does not allow for further parametrization of the handles.
'asymmetric' is based on the same principle as 'continuous' but uses different factors so that the result is asymmetric. This used to the only method available until v0.10.0, and is currently still the default when no method is specified, for reasons of backward compatibility. It will eventually be removed.
'catmull-rom' uses the Catmull-Rom spline to smooth the segment.

The optionally passed factor controls the knot parametrization of the algorithm:
- 0.0: the standard, uniform Catmull-Rom spline
- 0.5: the centripetal Catmull-Rom spline, guaranteeing no self-intersections
- 1.0: the chordal Catmull-Rom spline
'geometric' use a simple heuristic and empiric geometric method to smooth the segment’s handles. The handles were weighted, meaning that big differences in distances between the segments will lead to probably undesired results.

The optionally passed factor defines the tension parameter (0…1), controlling the amount of smoothing as a factor by which to scale each handle.

Options:

options.type: String — the type of smoothing method: ‘continuous’, ‘asymmetric’, ‘catmull-rom’, ‘geometric’ — default: ‘asymmetric’
options.factor: Number — the factor parameterizing the smoothing method — default: 0.5 for 'catmull-rom', 0.4 for 'geometric'
options.from: Number⟋Segment⟋Curve — the segment or curve at which to start smoothing, if not the full path shall be smoothed (inclusive). This can either be a segment index, or a segment or curve object that is part of the path. If the passed number is negative, the index is wrapped around the end of the path.
options.to: Number⟋Segment⟋Curve — the segment or curve to which the handles of the path shall be processed (inclusive). This can either be a segment index, or a segment or curve object that is part of the path. If the passed number is negative, the index is wrapped around the end of the path.

Parameters:

options: Object — the smoothing options — optional

Example:Smoothing a closed shape:

Run

Example:

Run

Example:Smoothing ranges of paths, using segments, curves or indices:

Run

simplify([tolerance])

Fits a sequence of as few curves as possible through the path’s anchor points, ignoring the path items’s curve-handles, with an allowed maximum error. When called on CompoundPath items, each of the nested paths is simplified. On Path items, the path.segments array is processed and replaced by the resulting sequence of fitted curves.

This method can be used to process and simplify the point data received from a mouse or touch device.

Parameters:

tolerance: Number — the allowed maximum error when fitting the curves through the segment points — optional, default: 2.5

Returns:

Boolean — true if the method was capable of fitting curves through the path’s segment points, false otherwise

Example:Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify():

Run

interpolate(from, to, factor)

Interpolates between the two specified path items and uses the result as the geometry for this path item. The number of children and segments in the two paths involved in the operation should be the same.

Parameters:

from: PathItem — the path item defining the geometry when factor is 0
to: PathItem — the path item defining the geometry when factor is 1
factor: Number — the interpolation coefficient, typically between 0 and 1, but extrapolation is possible too

compare(path)

Compares the geometry of two paths to see if they describe the same shape, detecting cases where paths start in different segments or even use different amounts of curves to describe the same shape, as long as their orientation is the same, and their segments and handles really result in the same visual appearance of curves.

Parameters:

path: PathItem — the path to compare this path’s geometry with

Returns:

Boolean — true if two paths describe the same shape, false otherwise

Postscript Style Drawing Commands

moveTo(point)

lineTo(point)

arcTo(through, to)

Adds an arc from the position of the last segment in the path, passing through the specified through point, to the specified to point, by adding one or more segments to the path.

Parameters:

through: Point — the point where the arc should pass through
to: Point — the point where the arc should end

Example:

Run

Example:Interactive example. Click and drag in the view below:

Run

arcTo(to[, clockwise])

Adds an arc from the position of the last segment in the path to the specified point, by adding one or more segments to the path.

Parameters:

to: Point — the point where the arc should end
clockwise: Boolean — specifies whether the arc should be drawn in clockwise direction — optional, default: true

Example:

Run

Example:Interactive example. Click and drag in the view below:

Run

curveTo(through, to[, time])

Adds a curve from the last segment in the path through the specified through point, to the specified destination point by adding one segment to the path.

Parameters:

through: Point — the point through which the curve should pass
to: Point — the destination point of the newly added curve
time: Number — the curve-time parameter at which the through point is to be located — optional, default: 0.5

Example:Interactive example. Move your mouse around the view below:

Run

cubicCurveTo(handle1, handle2, to)

Adds a cubic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by two specified handles.

Parameters:

handle1: Point — the location of the first handle of the newly added curve in absolute coordinates, out of which the relative values for segment.handleOut of its first segment are calculated
handle2: Point — the location of the second handle of the newly added curve in absolute coordinates, out of which the relative values for segment.handleIn of its second segment are calculated
to: Point — the destination point of the newly added curve

quadraticCurveTo(handle, to)

Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle.

Note that Paper.js only stores cubic curves, so the handle is actually converted.

Parameters:

handle: Point — the location of the handle of the newly added quadratic curve in absolute coordinates, out of which the relative values for segment.handleOut of the resulting cubic curve’s first segment and segment.handleIn of its second segment are calculated
to: Point — the destination point of the newly added curve

closePath()

Closes the path. When closed, Paper.js connects the first and last segment of the path with an additional curve. The difference to setting path.closed to true is that this will also merge the first segment with the last if they lie in the same location.

Relative Drawing Commands

moveBy(to)

lineBy(point)

Adds a straight curve to the path, from the the last segment in the path to the to vector specified relatively to it.

Parameters:

point: Point — the vector describing the destination of the newly added straight curve

Example:

Run

Example:Drawing a spiral using lineBy:

Run

arcBy(through, to)

Adds an arc from the position of the last segment in the path, passing through the specified through vector, to the specified to vector, all specified relatively to it by these given vectors, by adding one or more segments to the path.

Parameters:

through: Point — the vector where the arc should pass through
to: Point — the vector where the arc should end

arcBy(to[, clockwise])

Adds an arc from the position of the last segment in the path to the to vector specified relatively to it, by adding one or more segments to the path.

Parameters:

to: Point — the vector where the arc should end
clockwise: Boolean — specifies whether the arc should be drawn in clockwise direction — optional, default: true

curveBy(through, to[, time])

Adds a curve from the last segment in the path through the specified through vector, to the specified to vector, all specified relatively to it by these given vectors, by adding one segment to the path.

Parameters:

through: Point — the vector through which the curve should pass
to: Point — the destination vector of the newly added curve
time: Number — the curve-time parameter at which the through point is to be located — optional, default: 0.5

cubicCurveBy(handle1, handle2, to)

Adds a cubic bezier curve to the path, from the last segment to the to the specified to vector, with the curve itself defined by two specified handles.

Parameters:

handle1: Point — the location of the first handle of the newly added curve
handle2: Point — the location of the second handle of the newly added curve
to: Point — the destination point of the newly added curve

quadraticCurveBy(handle, to)

Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle.

Note that Paper.js only stores cubic curves, so the handle is actually converted.

Parameters:

handle: Point — the handle of the newly added quadratic curve out of which the values for segment.handleOut of the resulting cubic curve’s first segment and segment.handleIn of its second segment are calculated
to: Point — the destination point of the newly added curve

Path

Constructors

Parameters:

Returns:

Example:Create an empty path and add segments to it:

Example:Create a path with two segments:

Parameters:

Returns:

Example:

Example:

Parameters:

Returns:

Example:

Shaped Paths

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Example:The same, with rounder corners

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Example:

Example:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Example:Placing by center and radius

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Parameters:

Returns:

Example:

Properties

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Example:

Type:

Type:

Type:

Example:A path is fully selected, if all of its segments are selected: