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:

    var path = new Path({
        segments: [[20, 20], [80, 80], [140, 20]],
        fillColor: 'black',
        closed: true
    });

    Example:

    var path = new Path({
        segments: [[20, 20], [80, 80], [140, 20]],
        strokeColor: 'red',
        strokeWidth: 20,
        strokeCap: 'round',
        selected: true
    });
  • 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:

    var pathData = 'M100,50c0,27.614-22.386,50-50,50S0,77.614,0,50S22.386,0,50,0S100,22.386,100,50';
    var path = new Path(pathData);
    path.fillColor = 'red';

Shaped Paths

  • Path.Line(from, to)

    Creates a linear path item from two points describing a line.

    • Parameters:

    • from: Point — the line’s starting point

    • to: Point — the line’s ending point

    • Returns:

    • Path — the newly created path

    Example:

    var from = new Point(20, 20);
    var to = new Point(80, 80);
    var path = new Path.Line(from, to);
    path.strokeColor = 'black';
  • 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:

    var path = new Path.Line({
        from: [20, 20],
        to: [80, 80],
        strokeColor: 'black'
    });
  • Path.Circle(center, radius)

    Creates a circular path item.

    • Parameters:

    • center: Point — the center point of the circle

    • radius: Number — the radius of the circle

    • Returns:

    • Path — the newly created path

    Example:

    var path = new Path.Circle(new Point(80, 50), 30);
    path.strokeColor = 'black';
  • 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:

    var path = new Path.Circle({
        center: [80, 50],
        radius: 30,
        strokeColor: 'black'
    });
  • 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:

    var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60));
    var path = new Path.Rectangle(rectangle);
    path.strokeColor = 'black';

    Example:The same, with rounder corners

    var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60));
    var cornerSize = new Size(10, 10);
    var path = new Path.Rectangle(rectangle, cornerSize);
    path.strokeColor = 'black';
  • 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:

    var point = new Point(20, 20);
    var size = new Size(60, 60);
    var path = new Path.Rectangle(point, size);
    path.strokeColor = 'black';
  • 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:

    var from = new Point(20, 20);
    var to = new Point(80, 80);
    var path = new Path.Rectangle(from, to);
    path.strokeColor = 'black';
  • 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:

    var path = new Path.Rectangle({
        point: [20, 20],
        size: [60, 60],
        strokeColor: 'black'
    });

    Example:

    var path = new Path.Rectangle({
        from: [20, 20],
        to: [80, 80],
        strokeColor: 'black'
    });

    Example:

    var path = new Path.Rectangle({
        rectangle: {
            topLeft: [20, 20],
            bottomRight: [80, 80]
        },
        strokeColor: 'black'
    });

    Example:

    var path = new Path.Rectangle({
     topLeft: [20, 20],
        bottomRight: [80, 80],
        radius: 10,
        strokeColor: 'black'
    });
  • Path.Ellipse(rectangle)

    Creates an elliptical path item.

    • Parameters:

    • rectangle: Rectangle — the rectangle circumscribing the ellipse

    • Returns:

    • Path — the newly created path

    Example:

    var rectangle = new Rectangle(new Point(20, 20), new Size(180, 60));
    var path = new Path.Ellipse(rectangle);
    path.fillColor = 'black';
  • 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:

    var path = new Path.Ellipse({
        point: [20, 20],
        size: [180, 60],
        fillColor: 'black'
    });

    Example:Placing by center and radius

    var shape = new Path.Ellipse({
        center: [110, 50],
        radius: [90, 30],
        fillColor: 'black'
    });
  • 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:

    var from = new Point(20, 20);
    var through = new Point(60, 20);
    var to = new Point(80, 80);
    var path = new Path.Arc(from, through, to);
    path.strokeColor = 'black';
  • 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:

    var path = new Path.Arc({
        from: [20, 20],
        through: [60, 20],
        to: [80, 80],
        strokeColor: 'black'
    });
  • 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:

    var center = new Point(50, 50);
    var sides = 3;
    var radius = 40;
    var triangle = new Path.RegularPolygon(center, sides, radius);
    triangle.fillColor = 'black';
  • 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:

    var triangle = new Path.RegularPolygon({
        center: [50, 50],
        sides: 10,
        radius: 40,
        fillColor: 'black'
    });
  • 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:

    var center = new Point(50, 50);
    var points = 12;
    var radius1 = 25;
    var radius2 = 40;
    var path = new Path.Star(center, points, radius1, radius2);
    path.fillColor = 'black';
  • 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:

    var path = new Path.Star({
        center: [50, 50],
        points: 12,
        radius1: 25,
        radius2: 40,
        fillColor: 'black'
    });

Properties

  • segments

    The segments contained within the path.

    • Type:

    • Array of Segment objects

  • firstSegment

    The first Segment contained within the path.

    Read only.

    • Type:

    • Segment

  • lastSegment

    The last Segment contained within the path.

    Read only.

    • Type:

    • Segment

  • curves

    The curves contained within the path.

    Read only.

    • Type:

    • Array of Curve objects

  • firstCurve

    The first Curve contained within the path.

    Read only.

    • Type:

    • Curve

  • lastCurve

    The last Curve contained within the path.

    Read only.

    • Type:

    • Curve

  • closed

    Specifies whether the path is closed. If it is closed, Paper.js connects the first and last segments.

    • Type:

    • Boolean

    Example:

    var myPath = new Path();
    myPath.strokeColor = 'black';
    myPath.add(new Point(50, 75));
    myPath.add(new Point(100, 25));
    myPath.add(new Point(150, 75));
    
    // Close the path:
    myPath.closed = true;
  • length

    The approximate length of the path.

    Read only.

    • Type:

    • Number

  • area

    The area that the path’s geometry is covering. Self-intersecting paths can contain sub-areas that cancel each other out.

    Read only.

    • Type:

    • Number

  • fullySelected

    Specifies whether the path and all its segments are selected. Cannot be true on an empty path.

    • Type:

    • Boolean

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

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    path.fullySelected = true;
    
    var path2 = new Path.Circle({
        center: [180, 50],
        radius: 35
    });
    
    // Deselect the second segment of the second path:
    path2.segments[1].selected = false;
    
    // If the path is fully selected (which it is),
    // set its fill color to red:
    if (path.fullySelected) {
        path.fillColor = 'red';
    }
    
    // If the second path is fully selected (which it isn't, since we just
    // deselected its second segment),
    // set its fill color to red:
    if (path2.fullySelected) {
        path2.fillColor = 'red';
    }

Methods

  • add(...segment)

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

    • Parameters:

    • segment: SegmentPoint⟋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:

    var path = new Path({
        strokeColor: 'black'
    });
    
    // Add a segment at {x: 30, y: 75}
    path.add(new Point(30, 75));
    
    // Add two segments in one go at {x: 100, y: 20}
    // and {x: 170, y: 75}:
    path.add(new Point(100, 20), new Point(170, 75));

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

    var path = new Path({
        strokeColor: 'black'
    });
    
    // Add a segment at {x: 30, y: 75}
    path.add([30, 75]);
    
    // Add two segments in one go at {x: 100, y: 20}
    // and {x: 170, y: 75}:
    path.add([100, 20], [170, 75]);

    Example:Adding segments to a path using objects:

    var path = new Path({
        strokeColor: 'black'
    });
    
    // Add a segment at {x: 30, y: 75}
    path.add({x: 30, y: 75});
    
    // Add two segments in one go at {x: 100, y: 20}
    // and {x: 170, y: 75}:
    path.add({x: 100, y: 20}, {x: 170, y: 75});

    Example:Adding a segment with handles to a path:

    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(30, 75));
    
    // Add a segment with handles:
    var point = new Point(100, 20);
    var handleIn = new Point(-50, 0);
    var handleOut = new Point(50, 0);
    var added = path.add(new Segment(point, handleIn, handleOut));
    
    // Select the added segment, so we can see its handles:
    added.selected = true;
    
    path.add(new Point(170, 75));
  • 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: SegmentPoint — 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:

    var myPath = new Path();
    myPath.strokeColor = 'black';
    myPath.add(new Point(50, 75));
    myPath.add(new Point(150, 75));
    
    // Insert a new segment into myPath at index 1:
    myPath.insert(1, new Point(100, 25));
    
    // Select the segment which we just inserted:
    myPath.segments[1].selected = true;

    Example:Inserting multiple segments:

    var myPath = new Path();
    myPath.strokeColor = 'black';
    myPath.add(new Point(50, 75));
    myPath.add(new Point(150, 75));
    
    // Insert two segments into myPath at index 1:
    myPath.insert(1, [80, 25], [120, 25]);
    
    // Select the segments which we just inserted:
    myPath.segments[1].selected = true;
    myPath.segments[2].selected = true;
  • 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:

    var path = new Path({
        strokeColor: 'black'
    });
    var points = [new Point(30, 50), new Point(170, 50)];
    path.addSegments(points);

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

    var path = new Path({
        strokeColor: 'black'
    });
    var array = [[30, 75], [100, 20], [170, 75]];
    path.addSegments(array);

    Example:Adding segments from one path to another:

    var path = new Path({
        strokeColor: 'black'
    });
    path.addSegments([[30, 75], [100, 20], [170, 75]]);
    
    var path2 = new Path();
    path2.strokeColor = 'red';
    
    // Add the second and third segments of path to path2:
    path2.add(path.segments[1], path.segments[2]);
    
    // Move path2 30pt to the right:
    path2.position.x += 30;
  • 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)

    Removes the segment at the specified index of the path’s segments array.

    • Parameters:

    • index: Number — the index of the segment to be removed

    • Returns:

    • Segment — the removed segment

    Example:Removing a segment from a path:

    // Create a circle shaped path at { x: 80, y: 50 }
    // with a radius of 35:
    var path = new Path.Circle({
        center: new Point(80, 50),
        radius: 35,
        strokeColor: 'black'
    });
    
    // Remove its second segment:
    path.removeSegment(1);
    
    // Select the path, so we can see its segments:
    path.selected = true;
  • removeSegments()

    Removes all segments from the path’s segments array.

    • Returns:

    • Array of Segment objects — an array containing the removed segments

  • 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:

    // Create a circle shaped path at { x: 80, y: 50 }
    // with a radius of 35:
    var path = new Path.Circle({
        center: new Point(80, 50),
        radius: 35,
        strokeColor: 'black'
    });
    
    // Remove the segments from index 1 till index 2:
    path.removeSegments(1, 2);
    
    // Select the path, so we can see its segments:
    path.selected = true;
  • hasHandles()

    Checks if any of the curves in the path have curve handles set.

    • Returns:

    • Booleantrue if the path has curve handles set, false otherwise

    • See also:

    • segment.hasHandles()

    • curve.hasHandles()

  • clearHandles()

    Clears the path’s handles by setting their coordinates to zero, turning the path into a polygon (or a polyline if it isn’t closed).

  • 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: NumberCurveLocation — 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

    • See also:

    • curve.divideAt(location)

  • splitAt(location)

    Splits the path at the given offset or location. After splitting, the path will be open. If the path was open already, splitting will result in two paths.

    • Parameters:

    • location: NumberCurveLocation — the offset or location at which to split the path

    • Returns:

    • Path — the newly created path after splitting, if any

    Example:

    var path = new Path.Circle({
        center: view.center,
        radius: 40,
        strokeColor: 'black'
    });
    
    var pointOnCircle = view.center + {
        length: 40,
        angle: 30
    };
    
    var location = path.getNearestLocation(pointOnCircle);
    
    path.splitAt(location);
    path.lastSegment.selected = true;

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

    var path = new Path([20, 20], [50, 80], [80, 20]);
    path.strokeColor = 'black';
    
    // Split the path half-way:
    var path2 = path.splitAt(path.length / 2);
    
    // Give the resulting path a red stroke-color
    // and move it 20px to the right:
    path2.strokeColor = 'red';
    path2.position.x += 20;

    Example:Splitting a closed path

    var path = new Path.Rectangle({
        from: [20, 20],
        to: [80, 80],
        strokeColor: 'black'
    });
    
    // Split the path half-way:
    path.splitAt(path.length / 2);
    
    // Move the first segment, to show where the path
    // was split:
    path.firstSegment.point.x += 20;
    
    // Select the first segment:
    path.firstSegment.selected = true;
  • 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:

    var path = new Path({
        segments: [[30, 25], [30, 75]],
        strokeColor: 'black'
    });
    
    var path2 = new Path({
        segments: [[200, 25], [200, 75]],
        strokeColor: 'black'
    });
    
    // Join the paths:
    path.join(path2);

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

    var path = new Path({
        segments: [[30, 25], [30, 75]],
        strokeColor: 'black'
    });
    
    var path2 = new Path({
        segments: [[30, 25], [80, 25]],
        strokeColor: 'black'
    });
    
    // Join the paths:
    path.join(path2);
    
    // After joining, path with have 3 segments, since it
    // shared its first segment point with the first
    // segment point of path2.
    
    // Select the path to show that they have joined:
    path.selected = true;

    Example:Joining two paths that connect at two points:

    var path = new Path({
        segments: [[30, 25], [80, 25], [80, 75]],
        strokeColor: 'black'
    });
    
    var path2 = new Path({
        segments: [[30, 25], [30, 75], [80, 75]],
        strokeColor: 'black'
    });
    
    // Join the paths:
    path.join(path2);
    
    // Because the paths were joined at two points, the path is closed
    // and has 4 segments.
    
    // Select the path to show that they have joined:
    path.selected = true;
  • reduce(options)

    Reduces the path by removing curves that have a length of 0, and unnecessary segments between two collinear flat curves.

    • Parameters:

    • options:

    • Returns:

    • Path — the reduced path

  • 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

    • See also:

    • shape.toPath(insert)

Positions on Paths and Curves

  • getLocationOf(point)

    Returns the curve location of the specified point if it lies on the path, null otherwise.

    • Parameters:

    • point: Point — the point on the path

    • Returns:

    • CurveLocation — the curve location of the specified point

  • getOffsetOf(point)

    Returns the length of the path from its beginning up to up to the specified point if it lies on the path, null otherwise.

    • Parameters:

    • point: Point — the point on the path

    • Returns:

    • Number — the length of the path up to the specified 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:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    // We're going to be working with a third of the length
    // of the path as the offset:
    var offset = path.length / 3;
    
    // Find the point on the path:
    var point = path.getPointAt(offset);
    
    // Create a small circle shaped path at the point:
    var circle = new Path.Circle({
        center: point,
        radius: 3,
        fillColor: 'red'
    });

    Example:Iterating over the length of a path:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    var amount = 5;
    var length = path.length;
    for (var i = 0; i < amount + 1; i++) {
        var offset = i / amount * length;
    
        // Find the point on the path at the given offset:
        var point = path.getPointAt(offset);
    
        // Create a small circle shaped path at the point:
        var circle = new Path.Circle({
            center: point,
            radius: 3,
            fillColor: 'red'
        });
    }
  • 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:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    // We're going to be working with a third of the length
    // of the path as the offset:
    var offset = path.length / 3;
    
    // Find the point on the path:
    var point = path.getPointAt(offset);
    
    // Find the tangent vector at the given offset
    // and give it a length of 60:
    var tangent = path.getTangentAt(offset) * 60;
    
    var line = new Path({
        segments: [point, point + tangent],
        strokeColor: 'red'
    })

    Example:Iterating over the length of a path:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    var amount = 6;
    var length = path.length;
    for (var i = 0; i < amount + 1; i++) {
        var offset = i / amount * length;
    
        // Find the point on the path at the given offset:
        var point = path.getPointAt(offset);
    
        // Find the tangent vector on the path at the given offset
        // and give it a length of 60:
        var tangent = path.getTangentAt(offset) * 60;
    
        var line = new Path({
            segments: [point, point + tangent],
            strokeColor: 'red'
        })
    }
  • 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:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    // We're going to be working with a third of the length
    // of the path as the offset:
    var offset = path.length / 3;
    
    // Find the point on the path:
    var point = path.getPointAt(offset);
    
    // Find the normal vector on the path at the given offset
    // and give it a length of 30:
    var normal = path.getNormalAt(offset) * 30;
    
    var line = new Path({
        segments: [point, point + normal],
        strokeColor: 'red'
    });

    Example:Iterating over the length of a path:

    // Create an arc shaped path:
    var path = new Path({
        strokeColor: 'black'
    });
    
    path.add(new Point(40, 100));
    path.arcTo(new Point(150, 100));
    
    var amount = 10;
    var length = path.length;
    for (var i = 0; i < amount + 1; i++) {
        var offset = i / amount * length;
    
        // Find the point on the path at the given offset:
        var point = path.getPointAt(offset);
    
        // Find the normal vector on the path at the given offset
        // and give it a length of 30:
        var normal = path.getNormalAt(offset) * 30;
    
        var line = new Path({
            segments: [point, point + normal],
            strokeColor: 'red'
        });
    }
  • 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

    The unique id of the item.

    Read only.

    • Type:

    • Number

  • className

    The class name of the item as a string.

    • Values:

    • 'Group', 'Layer', 'Path', 'CompoundPath', 'Shape', 'Raster', 'SymbolItem', 'PointText'

    • Type:

    • String

    name

    The name of the item. If the item has a name, it can be accessed by name through its parent’s children list.

    • Type:

    • String

    Example:

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    // Set the name of the path:
    path.name = 'example';
    
    // Create a group and add path to it as a child:
    var group = new Group();
    group.addChild(path);
    
    // The path can be accessed by name:
    group.children['example'].fillColor = 'red';
  • 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:

    var circle = new Path.Circle({
        center: [80, 50],
        radius: 30
    });
    circle.style = {
        fillColor: 'blue',
        strokeColor: 'red',
        strokeWidth: 5
    };

    Example:Copying the style of another item:

    var path = new Path.Circle({
        center: [50, 50],
        radius: 30,
        fillColor: 'red'
    });
    
    var path2 = new Path.Circle({
        center: new Point(180, 50),
        radius: 20
    });
    
    // Copy the path style of path:
    path2.style = path.style;

    Example:Applying the same style object to multiple items:

    var myStyle = {
        fillColor: 'red',
        strokeColor: 'blue',
        strokeWidth: 4
    };
    
    var path = new Path.Circle({
        center: [50, 50],
        radius: 30
    });
    path.style = myStyle;
    
    var path2 = new Path.Circle({
        center: new Point(150, 50),
        radius: 20
    });
    path2.style = myStyle;
  • locked

    Specifies whether the item is locked. When set to true, item interactions with the mouse are disabled.

    • Default:

    • false

    • Type:

    • Boolean

    Example:

    var unlockedItem = new Path.Circle({
        center: view.center - [35, 0],
        radius: 30,
        fillColor: 'springgreen',
        onMouseDown: function() {
            this.fillColor = Color.random();
        }
    });
    
    var lockedItem = new Path.Circle({
        center: view.center + [35, 0],
        radius: 30,
        fillColor: 'crimson',
        locked: true,
        // This event won't be triggered because the item is locked.
        onMouseDown: function() {
            this.fillColor = Color.random();
        }
    });
    
    new PointText({
        content: 'Click on both circles to see which one is locked.',
        point: view.center - [0, 35],
        justification: 'center'
    });
  • visible

    Specifies whether the item is visible. When set to false, the item won’t be drawn.

    • Default:

    • true

    • Type:

    • Boolean

    Example:Hiding an item:

    var path = new Path.Circle({
        center: [50, 50],
        radius: 20,
        fillColor: 'red'
    });
    
    // Hide the path:
    path.visible = false;
  • 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:

    // Create a white rectangle in the background
    // with the same dimensions as the view:
    var background = new Path.Rectangle(view.bounds);
    background.fillColor = 'white';
    
    var circle = new Path.Circle({
        center: [80, 50],
        radius: 35,
        fillColor: 'red'
    });
    
    var circle2 = new Path.Circle({
        center: new Point(120, 50),
        radius: 35,
        fillColor: 'blue'
    });
    
    // Set the blend mode of circle2:
    circle2.blendMode = 'multiply';
  • opacity

    The opacity of the item as a value between 0 and 1.

    • Default:

    • 1

    • Type:

    • Number

    Example:Making an item 50% transparent:

    var circle = new Path.Circle({
        center: [80, 50],
        radius: 35,
        fillColor: 'red'
    });
    
    var circle2 = new Path.Circle({
        center: new Point(120, 50),
        radius: 35,
        fillColor: 'blue',
        strokeColor: 'green',
        strokeWidth: 10
    });
    
    // Make circle2 50% transparent:
    circle2.opacity = 0.5;
  • 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

    • See also:

    • project.selectedItems

    • segment.selected

    • curve.selected

    • point.selected

    Example:Selecting an item:

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    path.selected = true; // Select the path
  • clipMask

    Specifies whether the item defines a clip mask. This can only be set on paths and compound paths, and only if the item is already contained within a clipping group.

    • Default:

    • false

    • Type:

    • Boolean

  • 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:

    // Create a circle at position { x: 10, y: 10 }
    var circle = new Path.Circle({
        center: new Point(10, 10),
        radius: 10,
        fillColor: 'red'
    });
    
    // Move the circle to { x: 20, y: 20 }
    circle.position = new Point(20, 20);
    
    // Move the circle 100 points to the right and 50 points down
    circle.position += new Point(100, 50);

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

    // Create a circle at position { x: 20, y: 20 }
    var circle = new Path.Circle({
        center: new Point(20, 20),
        radius: 10,
        fillColor: 'red'
    });
    
    // Move the circle 100 points to the right
    circle.position.x += 100;
  • 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

    The bounding rectangle of the item excluding stroke width.

    • Type:

    • Rectangle

  • strokeBounds

    The bounding rectangle of the item including stroke width.

    • Type:

    • Rectangle

  • handleBounds

    The bounding rectangle of the item including handles.

    • Type:

    • Rectangle

  • internalBounds

    The bounding rectangle of the item without any matrix transformations.

    Typical use case would be drawing a frame around the object where you want to draw something of the same size, position, rotation, and scaling, like a selection frame.

    • Type:

    • Rectangle

  • rotation

    The current rotation angle of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false, meaning they do not directly bake transformations into their content.

    • Type:

    • Number

  • scaling

    The current scale factor of the item, as described by its matrix. Please note that this only returns meaningful values for items with applyMatrix set to false, meaning they do not directly bake transformations into their content.

    • Type:

    • Point

  • matrix

    The item’s transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.

    • Type:

    • Matrix

  • globalMatrix

    The item’s global transformation matrix in relation to the global project coordinate space. Note that the view’s transformations resulting from zooming and panning are not factored in.

    Read only.

    • Type:

    • Matrix

  • viewMatrix

    The item’s global matrix in relation to the view coordinate space. This means that the view’s transformations resulting from zooming and panning are factored in.

    Read only.

    • Type:

    • Matrix

  • 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

    The project that this item belongs to.

    Read only.

    • Type:

    • Project

  • view

    The view that this item belongs to.

    Read only.

    • Type:

    • View

  • layer

    The layer that this item is contained within.

    Read only.

    • Type:

    • 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:

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    
    // Create a group and move the path into it:
    var group = new Group();
    group.addChild(path);
    
    // Access the path through the group's children array:
    group.children[0].fillColor = 'red';

    Example:Accessing children by name:

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    // Set the name of the path:
    path.name = 'example';
    
    // Create a group and move the path into it:
    var group = new Group();
    group.addChild(path);
    
    // The path can be accessed by name:
    group.children['example'].fillColor = 'orange';

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

    var path = new Path.Circle({
        center: [80, 50],
        radius: 35
    });
    
    var group = new Group();
    group.children = [path];
    
    // The path is the first child of the group:
    group.firstChild.fillColor = 'green';
  • firstChild

    The first item contained within this item. This is a shortcut for accessing item.children[0].

    Read only.

    • Type:

    • Item

  • lastChild

    The last item contained within this item.This is a shortcut for accessing item.children[item.children.length - 1].

    Read only.

    • Type:

    • Item

  • nextSibling

    The next item on the same level as this item.

    Read only.

    • Type:

    • Item

  • previousSibling

    The previous item on the same level as this item.

    Read only.

    • Type:

    • Item

  • index

    The index of this item within the list of its parent’s children.

    Read only.

    • Type: