Project
A Project object in Paper.js is what usually is referred to as the document: The top level object that holds all the items contained in the scene graph. As the term document is already taken in the browser context, it is called Project.
Projects allow the manipulation of the styles that are applied to all newly created items, give access to the selected items, and will in future versions offer ways to query for items in the scene graph defining specific requirements, and means to persist and load from different formats, such as SVG and PDF.
The currently active project can be accessed through the paperScope.project
variable.
An array of all open projects is accessible through the paperScope.projects
variable.
Constructors
Project(element)
Creates a Paper.js project containing one empty
Layer
, referenced byproject.activeLayer
.Note that when working with PaperScript, a project is automatically created for us and the
paperScope.project
variable points to it.Parameters:
element:
HTMLCanvasElement
βString
βSize
β the HTML canvas element that should be used as the element for the view, or an ID string by which to find the element, or the size of the canvas to be created for usage in a web worker.Returns:
Project
Properties
view
The reference to the projectβs view.
Read only.
Type:
View
currentStyle
The currently active path style. All selected items and newly created items will be styled with this style.
Type:
Style
Example:
Example:
index
The index of the project in the
paperScope.projects
list.Read only.
Type:
Number
Project Content
layers
The layers contained within the project.
Read only.
Type:
Array of
Layer
objects
activeLayer
The layer which is currently active. New items will be created on this layer by default.
Read only.
Type:
Layer
symbolDefinitions
The symbol definitions shared by all symbol items contained place ind project.
Read only.
Type:
Array of
SymbolDefinition
objects
selectedItems
The selected items contained within the project.
Read only.
Type:
Array of
Item
objects
Methods
activate()
Activates this project, so all newly created items will be placed in it.
clear()
Clears the project by removing all
project.layers
.isEmpty()
Checks whether the project has any content or not.
Returns:
Boolean
remove()
Removes this project from the
paperScope.projects
list, and also removes its view, if one was defined.selectAll()
Selects all items in the project.
deselectAll()
Deselects all selected items in the project.
Hierarchy Operations
addLayer(layer)
Adds the specified layer at the end of the this projectβs
layers
list.Parameters:
layer:
Layer
β the layer to be added to the projectReturns:
Layer
β the added layer, ornull
if adding was not possible
insertLayer(index, layer)
Inserts the specified layer at the specified index in this projectβs
layers
list.Parameters:
index:
Number
β the index at which to insert the layerlayer:
Layer
β the layer to be inserted in the projectReturns:
Layer
β the added layer, ornull
if adding was not possible
Hit-testing, Fetching and Matching Items
hitTest(point[, options])
Performs a hit-test on the items contained within the project at the location of the specified point.
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
.hitToleranceoptions.class: Function
β only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which aninstanceof
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: Returntrue
to return the result,false
to keep searchingoptions.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 forsegment.point
ofPath
items β default:true
options.curves: Boolean
β hit-test the curves of path items, without taking the stroke color or width into accountoptions.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 itemsoptions.position: Boolean
β hit-test theitem.position
of of items, which depends on the setting ofitem.pivot
options.center: Boolean
β hit-test therectangle.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 haveItem#guide
set totrue
options.selected: Boolean
β only hit selected itemsParameters:
point:
Point
β the point where the hit-test should be performedoptions:
Object
β optional, default:{ fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }
Returns:
HitResult
β a hit result object that contains more information about what exactly was hit ornull
if nothing was hit
hitTestAll(point[, options])
Performs a hit-test on the item and its children (if it is a
Group
orLayer
) 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 performedoptions:
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 ornull
if nothing was hitSee also:
hitTest(point[, options])
;
getItems(options)
Fetch items contained within the project whose properties match the criteria in the specified object.
Extended matching of properties is possible by providing a comparator function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for
item.data
.Matching items against a rectangular area is also possible, by setting either
options.inside
oroptions.overlapping
to a rectangle describing the area in which the items either have to be fully or partly contained.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 thematch
objectoptions.class: Function
β the constructor function of the item type to match againstoptions.inside: Rectangle
β the rectangle in which the items need to be fully containedoptions.overlapping: Rectangle
β the rectangle with which the items need to at least partly overlapParameters:
options:
Object
βFunction
β the criteria to match againstReturns:
Array of Item
objects β the list of matching items contained in the projectSee also:
item.matches(options)
item.getItems(options)
Example:Fetch all selected path items:
Example:Fetch all items with a specific fill color:
Example:Fetch items at a specific position:
Example:Fetch items using a comparator function:
Example:Fetch items using a comparator function (2):
Example:Match (nested) properties of the data property:
Example:Match strings using regular expressions:
getItem(options)
Fetch the first item contained within the project whose properties match the criteria in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for
item.data
.See
getItems(options)
for a selection of illustrated examples.Parameters:
options:
Object
βFunction
β the criteria to match againstReturns:
Item
β the first item in the project matching the given criteria
Importing / Exporting JSON and SVG
exportJSON([options])
Exports (serializes) the project with all its layers and child items to a JSON data object or string.
Options:
options.asString: Boolean
β whether the JSON is returned as aObject
or aString
β default:true
options.precision: Number
β the amount of fractional digits in numbers used in JSON data β default:5
Parameters:
options:
Object
β the serialization options β optionalReturns:
String
β the exported JSON data
importJSON(json)
Imports (deserializes) the stored JSON data into the project. Note that the project is not cleared first. You can call
project.clear
() to do so.Parameters:
json:
String
β the JSON data to import fromReturns:
Item
β the imported item
exportSVG([options])
Exports the project with all its layers and child items as an SVG DOM, all contained in one top level SVG group node.
Options:
options.bounds: String
βRectangle
β the bounds of the area to export, either as a string (βviewβ
,contentβ
), or aRectangle
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: Ifoptions.bounds
is set to'view'
,paper.view.matrix
is used, for all other settings ofoptions.bounds
the identity matrix is used. β default:paper.view.matrix
options.asString: Boolean
β whether a SVG node or aString
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 β optionalReturns:
SVGElement
βString
β the project converted to an SVG node or aString
depending onoption.asString
value
importSVG(svg[, options])
Converts the provided SVG content into Paper.js items and adds them to the active layer of this project. Note that the project is not cleared first. You can call
project.clear
() 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 converteditem
and the originalsvg
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 project thatimportSVG()
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
.applyMatrixParameters:
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 β optionalReturns:
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 active layer of this project. Note that the project is not cleared first. You can call
project.clear
() 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 converteditem
and the originalsvg
data as a string. Only required when loading from external files.Returns:
Item
β the newly created Paper.js item containing the converted SVG content