Raster
Extends [Item](Item%20eab4980134ff44238bc91e6d4a28d6f9.md)
The Raster item represents an image in a Paper.js project.
Constructors
Raster([source[, position]])
Creates a new raster item from the passed argument, and places it in the active layer.
source
can either be a DOM Image, a Canvas, or a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas).Parameters:
source:
HTMLImageElement
βHTMLCanvasElement
βString
β the source of the raster β optionalposition:
Point
β the center position at which the raster item is placed β optionalReturns:
Raster
Example:Creating a raster using a url
Example:Creating a raster using the id of a DOM Image:
Example:Creating a raster using a DOM Image:
Raster(size[, position])
Creates a new empty raster of the given size, and places it in the active layer.
Parameters:
size:
Size
β the size of the rasterposition:
Point
β the center position at which the raster item is placed β optionalReturns:
Raster
Example:Creating an empty raster and fill it with random pixels:
Raster(object)
Creates a new raster from an object description, and places it in the active layer.
Parameters:
object:
Object
β an object containing properties to be set on the rasterReturns:
Raster
Example:
Properties
size
3245`The size of the raster in pixels.
Type:
Size
width
The width of the raster in pixels.
Type:
Number
height
The height of the raster in pixels.
Type:
Number
loaded
The loading state of the raster image.
Read only.
Type:
Boolean
resolution
The resolution of the raster at its current size, in PPI (pixels per inch).
Read only.
Type:
Size
image
The HTMLImageElement or Canvas element of the raster, if one is associated. Note that for consistency, a
onLoad
event will be triggered on the raster even if the image has already finished loading before, or if we are setting the raster to a canvas.Type:
HTMLImageElement
βHTMLCanvasElement
canvas
The Canvas object of the raster. If the raster was created from an image, accessing its canvas causes the raster to try and create one and draw the image into it. Depending on security policies, this might fail, in which case
null
is returned instead.Type:
HTMLCanvasElement
context
The Canvas 2D drawing context of the raster.
Type:
CanvasRenderingContext2D
source
The source of the raster, which can be set using a DOM Image, a Canvas, a data url, a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas). Reading this property will return the url of the source image or a data-url. Note that for consistency, a
onLoad
event will be triggered on the raster even if the image has already finished loading before.Type:
HTMLImageElement
βHTMLCanvasElement
βString
Example:
Example:
crossOrigin
The crossOrigin value to be used when loading the image resource, in order to support CORS. Note that this needs to be set before setting the
source
property in order to always work (e.g. when the image is cached in the browser).Type:
String
Example:
smoothing
Specifies if the raster should be smoothed when scaled up or if the pixels should be scaled up by repeating the nearest neighboring pixels.
Default:
true
Type:
Boolean
Example:
Event Handlers
onLoad
The event handler function to be called when the underlying image has finished loading and is ready to be used. This is also triggered when the image is already loaded, or when a canvas is used instead of an image.
Type:
Function
βnull
Example:
onError
The event handler function to be called when there is an error loading the underlying image.
Type:
Function
βnull
Methods
getSubCanvas(rect)
Extracts a part of the Rasterβs content as a sub image, and returns it as a Canvas object.
Parameters:
rect:
Rectangle
β the boundaries of the sub image in pixel coordinatesReturns:
HTMLCanvasElement
β the sub image as a Canvas object
getSubRaster(rect)
Extracts a part of the raster itemβs content as a new raster item, placed in exactly the same place as the original content.
Parameters:
rect:
Rectangle
β the boundaries of the sub raster in pixel coordinatesReturns:
Raster
β the sub raster as a newly created raster item
toDataURL()
Returns a Base 64 encoded
data:
URL representation of the raster.Returns:
String
drawImage(image, point)
Draws an image on the raster.
Parameters:
image:
CanvasImageSource
point:
Point
β the offset of the image as a point in pixel coordinates
getAverageColor(object)
Calculates the average color of the image within the given path, rectangle or point. This can be used for creating raster image effects.
Parameters:
object:
Path
βRectangle
βPoint
Returns:
Color
β the average color contained in the area covered by the specified path, rectangle or point
Pixels
getPixel(x, y)
Gets the color of a pixel in the raster.
Parameters:
x:
Number
β the x offset of the pixel in pixel coordinatesy:
Number
β the y offset of the pixel in pixel coordinatesReturns:
Color
β the color of the pixel
getPixel(point)
Gets the color of a pixel in the raster.
Parameters:
point:
Point
β the offset of the pixel as a point in pixel coordinatesReturns:
Color
β the color of the pixel
setPixel(x, y, color)
Sets the color of the specified pixel to the specified color.
Parameters:
x:
Number
β the x offset of the pixel in pixel coordinatesy:
Number
β the y offset of the pixel in pixel coordinatescolor:
Color
β the color that the pixel will be set to
setPixel(point, color)
Sets the color of the specified pixel to the specified color.
Parameters:
point:
Point
β the offset of the pixel as a point in pixel coordinatescolor:
Color
β the color that the pixel will be set to
clear()
Clears the image, if it is backed by a canvas.
Image Data
createImageData(size)
Parameters:
size:
Size
Returns:
ImageData
getImageData(rect)
Parameters:
rect:
Rectangle
Returns:
ImageData
setImageData(data, point)
Parameters:
data:
ImageData
point:
Point
Properties inherited from Item
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:
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:
Example:Copying the style of another item:
Example:Applying the same style object to multiple items:
locked
Specifies whether the item is locked. When set to
true
, item interactions with the mouse are disabled.Default:
false
Type:
Boolean
Example:
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:
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:
opacity
The opacity of the item as a value between
0
and1
.Default:
1
Type:
Number
Example:Making an item 50% transparent:
selected
Specifies whether the item is selected. This will also return
true
forGroup
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:
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:
Example:
Example:
Example:
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βsbounds
rectangle.Type:
Point
Example:Changing the position of a path:
Example:Changing the x coordinate of an item's position:
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 tonull
, meaning therectangle.center
of the itemβsbounds
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 withapplyMatrix
set tofalse
, 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 withapplyMatrix
set tofalse
, 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 itsmatrix
property, or whether they are directly applied to its contents or children (passed on to the segments inPath
items, the children ofGroup
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:
Example:Setting the parent of the item to another item
Example:Setting the parent of an item in the constructor
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, useitem.removeChildren
(). To add items to the children list, useitem.addChild(item)
oritem.insertChild(index, item)
.Type:
Array of
Item
objects
Example:Accessing items in the children array:
Example:Accessing children by name:
Example:Passing an array of items to item.children:
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:
Number
Stroke Style
strokeColor
The color of the stroke.
Type:
Color
βnull
Example:Setting the stroke color of a path:
strokeWidth
The width of the stroke.
Type:
Number
Example:Setting an item's stroke width:
strokeCap
The shape to be used at the beginning and end of open
Path
items, when they have a stroke.Values:
'round'
,'square'
,'butt'
Default:
'butt'
Type:
String
Example:A look at the different stroke caps:
strokeJoin
The shape to be used at the segments and corners of
Path
items when they have a stroke.Values:
'miter'
,'round'
,'bevel'
Default:
'miter'
Type:
String
Example:A look at the different stroke joins:
dashOffset
The dash offset of the stroke.
Default:
0
Type:
Number
strokeScaling
Specifies whether the stroke is to be drawn taking the current affine transformation into account (the default behavior), or whether it should appear as a non-scaling stroke.
Default:
true
Type:
Boolean
dashArray
Specifies an array containing the dash and gap lengths of the stroke.
Default:
[]
Type:
Array of
Numbers
Example:
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 theitem.strokeWidth
of the path. The miterLimit imposes a limit on the ratio of the miter length to theitem.strokeWidth
.Default:
10
Type:
Number
Fill Style
fillColor
The fill color of the item.
Type:
Color
βnull
Example:Setting the fill color of a path to red:
fillRule
The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than
'nonzero'
.Values:
'nonzero'
,'evenodd'
Default:
'nonzero'
Type:
String
Shadow Style
shadowColor
The shadow color.
Type:
Color
βnull
Example:Creating a circle with a black shadow:
shadowBlur
The shadowβs blur radius.
Default:
0
Type:
Number
shadowOffset
The shadowβs offset.
Default:
0
Type:
Point
Selection Style
selectedColor
The color the item is highlighted with when selected. If the item does not specify its own color, the color defined by its layer is used instead.
Type:
Color
βnull
Event Handlers
onFrame
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 firedevent.time: Number
β the total amount of time passed since the first frame event in secondsevent.delta: Number
β the time passed in seconds since the last frame eventSee also:
view.onFrame
Example:Creating an animation:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseDown
Example:Press the mouse button down on the circle shaped path, to make it red:
Example:Press the mouse on the circle shaped paths to remove them:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseDrag
Example:Press and drag the mouse on the blue circle to move it:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseUp
Example:Release the mouse button over the circle shaped path, to make it red:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onClick
Example:Click on the circle shaped path, to make it red:
Example:Click on the circle shaped paths to remove them:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onDoubleClick
Example:Double click on the circle shaped path, to make it red:
Example:Double click on the circle shaped paths to remove them:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseMove
Example:Move over the circle shaped path, to change its opacity:
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseEnter
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.
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.
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 withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseLeave
Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:
Methods inherited from Item
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
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 totrue
, 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:
copyContent(source)
Copies the content of the specified item over to this item.
Parameters:
source:
Item
β the item to copy the content from
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 fromexcludeMatrix:
Boolean
β whether to exclude the transformation matrix when copying all attributes
rasterize([resolution[, insert]])
Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.
Parameters:
resolution:
Number
β the resolution of the raster in pixels per inch (DPI). If not specified, the value ofview.resolution
is used. β optional, default:view.resolution
insert:
Boolean
β specifies whether the raster should be inserted into the scene graph. When set totrue
, it is inserted above the original β optional, default:true
Returns:
Raster
β the newly created raster item
Example:Rasterizing an item:
Geometric Tests
contains(point)
Checks whether the itemβs geometry contains the given point.
Parameters:
point:
Point
β the point to check forReturns:
Boolean
Example:Click within and outside the star below Create a star shaped path:
isInside(rect)
Parameters:
rect:
Rectangle
β the rectangle to check againstReturns:
Boolean
intersects(item)
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
Hit-testing, Fetching and Matching Items
hitTest(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 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
.hitToleranceoptions.class: Function
β only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against whic