Class Canvas

The Canvas class provides the 2D rendering context for the drawing images. It is used for drawing shapes, text, images, and other objects.

Constructors

constructor

new Canvas(width: number, height: number): Canvas
Initialize Canvas object.
Parameters
- width: number
  A width of the canvas. Must be positive. Float value will be truncated to integer.
- height: number
  A height of the canvas. Must be positive. Float value will be truncated to integer.
Returns Canvas

Properties

fillStyle

fillStyle: string | Gradient

The color, gradient, or pattern to use inside shapes.

Default Value

#000 (black)

Example

canvas.fillStyle = 'cyan' // Named colors
canvas.fillStyle = '#0ff' // Hex colors
canvas.fillStyle = 'rgb(0, 255, 255)' // RGB colors
canvas.fillStyle = 'rgba(0, 255, 255, 1)' // RGBA colors
canvas.fillStyle = 'hsla(210 60% 60%)' // HSLA colors
canvas.fillStyle = (() => { // Gradient
  const gradient = canvas.createLinearGradient(20, 70, 70, 70)
  gradient.addColorStop(0, 'rgb(255,0,0)')
  gradient.addColorStop(0.5, 'rgb(0,255,0)')
  gradient.addColorStop(1, 'rgb(0,0,255)')
  return gradient
})()

font

font: string

The current text style to use when drawing text. This string uses the same syntax as the CSS font specifier.

You can see the full list of available fonts with fc-list : family shell command.

Default Value

"12pt Helvetica"

See

Fonts included with macOS Monterey | Apple Support

globalAlpha

globalAlpha: number

The alpha (transparency) value that is applied to shapes and images before they are drawn onto the canvas.

Default Value

1.0

globalCompositeOperation

The type of compositing operation to apply when drawing new shapes.

Default Value

"source-over"

`Readonly`height

height: number

The height of the canvas.

lineCap

lineCap: "butt" | "round" | "square"

The shape used to draw the end points of lines.

Default Value

"butt"

lineDash

lineDash: number[]

The current line dash pattern.

Default Value

[]

lineJoin

lineJoin: "round" | "bevel" | "miter"

The shape used to join two line segments where they meet.

Default Value

"miter"

lineWidth

lineWidth: number

The thickness of lines.

Default Value

1.0

miterLimit

miterLimit: number

The miter limit ratio.

Default Value

0

shadowBlur

shadowBlur: number

The amount of blur applied to shadows.

Default Value

0 (no blur)

`Optional`shadowColor

shadowColor?: string

The color of shadows.

Default Value

undefined

shadowOffsetX

shadowOffsetX: number

The distance that shadows will be offset horizontally.

Default Value

0 (no horizontal offset)

shadowOffsetY

shadowOffsetY: number

The distance that shadows will be offset vertically..

Default Value

0 (no vertical offset)

strokeStyle

strokeStyle: string

The color, gradient, or pattern to use for the strokes (outlines) around shapes.

Default Value

#000 (black)

textAlign

textAlign: "left" | "right" | "center" | "start" | "end"

The current text alignment used when drawing text.

Default Value

"left"

textBaseline

textBaseline: "top" | "middle" | "alphabetic" | "bottom"

The current text baseline used when drawing text.

Default Value

"alphabetic"

`Readonly`width

width: number

The width of the canvas.

Methods

arc

arc(
    x: number,
    y: number,
    radius: number,
    startAngle: number,
    endAngle: number,
    counterclockwise?: boolean,
): void
Adds a circular arc to the current sub-path.
Parameters
- x: number
  The horizontal coordinate of the arc's center.
- y: number
  The vertical coordinate of the arc's center.
- radius: number
  The arc's radius. Must be positive.
- startAngle: number
  The angle at which the arc starts in radians, measured from the positive x-axis.
- endAngle: number
  The angle at which the arc ends in radians, measured from the positive x-axis.
- counterclockwise: boolean = false
  If true, draws the arc counter-clockwise between the start and end angles.
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.beginPath()
canvas.arc(100, 75, 50, 0, 2 * Math.PI)
canvas.stroke()
const output = new Output(canvas, 'arc.png')
output.addToQueue()
```

beginPath

beginPath(): void

Starts a new path by emptying the list of sub-paths. Call this method when you want to create a new path.

Returns void

bezierCurveTo

bezierCurveTo(
    cp1x: number,
    cp1y: number,
    cp2x: number,
    cp2y: number,
    x: number,
    y: number,
): void
Adds a cubic Bézier curve to the current sub-path. It requires three points: the first two are control points and the third one is the end point. The starting point is the latest point in the current path, which can be changed using Canvas.moveTo before creating the Bézier curve.
Parameters
- cp1x: number
  The x-axis coordinate of the first control point.
- cp1y: number
  The y-axis coordinate of the first control point.
- cp2x: number
  The x-axis coordinate of the second control point.
- cp2y: number
  The y-axis coordinate of the second control point.
- x: number
  The x-axis coordinate of the end point.
- y: number
  The y-axis coordinate of the end point.
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.moveTo(0, 0)
canvas.bezierCurveTo(60, 80, 90, 10, 100, 100)
canvas.stroke()
const output = new Output(canvas, 'bezierCurveTo.png')
output.addToQueue()
```

clearRect

clearRect(x: number, y: number, width: number, height: number): void
Erases the pixels in a rectangular area by setting them to transparent black.
Parameters
- x: number
- y: number
- width: number
- height: number
Returns void

clip

clip(): void

Turns the current or given path into the current clipping region. The previous clipping region, if any, is intersected with the current or given path to create the new clipping region.

Returns void

closePath

closePath(): void

Attempts to add a straight line from the current point to the start of the current sub-path. If the shape has already been closed or has only one point, this function does nothing.

Returns void

createImageData

createImageData(imageData: ImageData): ImageData
Creates a new, blank ImageData object with the specified dimensions. All of the pixels in the new object are transparent black.
Parameters
- imageData: ImageData
  An existing ImageData object from which to copy the width and height. The image itself is not copied.
Returns ImageData
createImageData(width: number, height: number): ImageData
Creates a new, blank ImageData object with the specified dimensions. All of the pixels in the new object are transparent black.
Parameters
- width: number
  The width to give the new ImageData object. A negative value flips the rectangle around the vertical axis.
- height: number
  The height to give the new ImageData object. A negative value flips the rectangle around the horizontal axis.
Returns ImageData

createLinearGradient

createLinearGradient(x0: number, y0: number, x1: number, y1: number): Gradient
Creates a gradient along the line connecting two given coordinates.
Parameters
- x0: number
  The x-axis coordinate of the start point.
- y0: number
  The y-axis coordinate of the start point.
- x1: number
  The x-axis coordinate of the end point.
- y1: number
  The y-axis coordinate of the end point.
Returns Gradient
Example
```
const canvas = new Canvas(150, 150)
const gradient = canvas.createLinearGradient(0, 0, 150, 150)
gradient.addColorStop(0, 'red')
gradient.addColorStop(0.5, 'green')
gradient.addColorStop(1, 'blue')
canvas.fillStyle = gradient
canvas.fillRect(0, 0, 150, 150)
const output = new Output(canvas, 'linearGradient.png')
output.addToQueue()
```

createPattern

createPattern(
image: Image,
style: "repeat" | "repeat-x" | "repeat-y" | "no-repeat",
): PatternObject
Creates a pattern using the specified image and repetition.

This method works but it seems that the use of PatternObject is still in-development. Neither of Canvas.fillStyle and Canvas.strokeStyle accept PatternObject as a value.
Parameters
- image: Image
- style: "repeat" | "repeat-x" | "repeat-y" | "no-repeat"
Returns PatternObject

createRadialGradient

createRadialGradient(
    x0: number,
    y0: number,
    r0: number,
    x1: number,
    y1: number,
    r1: number,
): Gradient
Creates a radial gradient using the size and coordinates of two circles.
Parameters
- x0: number
  The x-axis coordinate of the start circle.
- y0: number
  The y-axis coordinate of the start circle.
- r0: number
  The radius of the start circle. Must be non-negative and finite.
- x1: number
  The x-axis coordinate of the end circle.
- y1: number
  The y-axis coordinate of the end circle.
- r1: number
  The radius of the end circle. Must be non-negative and finite.
Returns Gradient
Example
```
const canvas = new Canvas(150, 150)
const gradient = canvas.createRadialGradient(75, 75, 10, 75, 75, 150)
gradient.addColorStop(0, 'red')
gradient.addColorStop(0.5, 'green')
gradient.addColorStop(1, 'blue')
canvas.fillStyle = gradient
canvas.fillRect(0, 0, 150, 150)
const output = new Output(canvas, 'radialGradient.png')
output.addToQueue()
```

drawImage

drawImage(image: Image): void

Provides different ways to draw an image onto the canvas.

Parameters

image: Image
The image to draw into the canvas.

Returns void

Example

// sips -j draw.js image.png
const canvas = new Canvas(100, 100)
canvas.drawImage(sips.images.pop())
const output = new Output(canvas, 'draw.png')
output.addToQueue()

drawImage(image: Image, dx: number, dy: number): void
Provides different ways to draw an image onto the canvas.
Parameters
- image: Image
  The image to draw into the canvas.
- dx: number
  Horizontal position (x coordinate) at which to place the image in the canvas.
- dy: number
  Vertical position (y coordinate) at which to place the image in the canvas.
Returns void
Example
```
// sips -j draw.js image.png
const canvas = new Canvas(100, 100)
canvas.drawImage(sips.images.pop(), 10, 10)
const output = new Output(canvas, 'draw.png')
output.addToQueue()
```
drawImage(
    image: Image,
    dx: number,
    dy: number,
    dWidth: number,
    dHeight: number,
): void
Provides different ways to draw an image onto the canvas.
Parameters
- image: Image
  The image to draw into the canvas.
- dx: number
  The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
- dy: number
  The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
- dWidth: number
  The width to draw the image in the destination canvas. This allows scaling of the drawn image.
- dHeight: number
  The height to draw the image in the destination canvas. This allows scaling of the drawn image.
Returns void
Example
```
// sips -j draw.js image.png
const canvas = new Canvas(100, 100)
canvas.drawImage(sips.images.pop(), 10, 10, 10, 10)
const output = new Output(canvas, 'draw.png')
output.addToQueue()
```
drawImage(
    image: Image,
    sx: number,
    sy: number,
    sWidth: number,
    sHeight: number,
    dx: number,
    dy: number,
    dWidth: number,
    dHeight: number,
): void
Provides different ways to draw an image onto the canvas.
Parameters
- image: Image
  The image to draw into the canvas.
- sx: number
  The x-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
- sy: number
  The y-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
- sWidth: number
  The width of the sub-rectangle of the source image to draw into the destination context.
- sHeight: number
  The height of the sub-rectangle of the source image to draw into the destination context.
- dx: number
  The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
- dy: number
  The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
- dWidth: number
  The width to draw the image in the destination canvas. This allows scaling of the drawn image.
- dHeight: number
  The height to draw the image in the destination canvas. This allows scaling of the drawn image.
Returns void
Example
```
// sips -j draw.js image.png
const canvas = new Canvas(100, 100)
canvas.drawImage(sips.images.pop(), 25, 25, 50, 50, 10, 10, 10, 10)
const output = new Output(canvas, 'draw.png')
output.addToQueue()
```

fill

fill(): void

Fills the current or given path with the current Canvas.fillStyle.

Returns void

fillRect

fillRect(x: number, y: number, width: number, height: number): void
Draws a rectangle that is filled according to the current Canvas.fillStyle.
Parameters
- x: number
- y: number
- width: number
- height: number
Returns void

fillText

fillText(text: string, x: number, y: number, maxWidth?: number): void
Draws a text string at the specified coordinates, filling the string's characters with the current Canvas.fillStyle. An optional parameter allows specifying a maximum width for the rendered text, which the user agent will achieve by condensing the text or by using a lower font size.
Parameters
- text: string
  The text string to render into canvas.
- x: number
  The x-axis coordinate of the point at which to begin drawing text, in pixels.
- y: number
  The y-axis coordinate of the point at which to begin drawing text, in pixels.
- maxWidth: number = Infinity
  The maximum number of pixels wide the text may be once rendered.
Returns void
Example
```
const canvas = new Canvas(100, 50)
canvas.font = '42pt Futura'
canvas.fillStyle = 'blue'
canvas.fillText('Hello', 0, 42)
const output = new Output(canvas, 'fillText.png')
output.addToQueue()
```

getContext

getContext(): this

A drawing context on the canvas.

Contrary to DOM API, Context object is identical to Canvas object. It always returns itself.

Returns this

getImageData

getImageData(sx?: number, sy?: number, sw?: number, sh?: number): ImageData
Returns an ImageData object representing the underlying pixel data for a specified portion of the canvas.
Parameters
- Optionalsx: number
  The x-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
- Optionalsy: number
  The y-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
- Optionalsw: number
  The width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left.
- Optionalsh: number
  The height of the rectangle from which the ImageData will be extracted. Positive values are down, and negative are up.
Returns ImageData

isPointInPath

isPointInPath(x: number, y: number): boolean
Reports whether or not the specified point is contained in the current path.
Parameters
- x: number
  The x-axis coordinate of the point to check, unaffected by the current transformation of the context.
- y: number
  The y-axis coordinate of the point to check, unaffected by the current transformation of the context.
Returns boolean
- A Boolean, which is true if the specified point is contained in the current or specified path, otherwise false.

lineTo

lineTo(x: number, y: number): void
Adds a straight line to the current sub-path by connecting the sub-path's last point to the specified (x, y) coordinates.
Parameters
- x: number
  The x-axis coordinate of the line's end point.
- y: number
  The y-axis coordinate of the line's end point.
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.moveTo(0, 0)
canvas.lineTo(100, 100)
canvas.stroke()
const output = new Output(canvas, 'lineTo.png')
output.addToQueue()
```

measureText

measureText(text: string): Size
Returns an object that contains size information about the measured text.
Parameters
- text: string
  The text string to measure.
Returns Size

moveTo

moveTo(x: number, y: number): void
Begins a new sub-path at the point specified by the given (x, y) coordinates.
Parameters
- x: number
  The x-axis (horizontal) coordinate of the point.
- y: number
  The y-axis (vertical) coordinate of the point.
Returns void

putImageData

putImageData(imageData: ImageData, dx: number, dy: number): void
Paints data from the given ImageData object onto the canvas. If a dirty rectangle is provided, only the pixels from that rectangle are painted. This method is not affected by the canvas transformation matrix.
Parameters
- imageData: ImageData
  An ImageData object containing the array of pixel values.
- dx: number
  Horizontal position (x coordinate) at which to place the image data in the destination canvas.
- dy: number
  Vertical position (y coordinate) at which to place the image data in the destination canvas.
Returns void

quadraticCurveTo

quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void
Adds a quadratic Bézier curve to the current sub-path. It requires two points: the first one is a control point and the second one is the end point. The starting point is the latest point in the current path, which can be changed using Canvas.moveTo before creating the quadratic Bézier curve.
Parameters
- cpx: number
  The x-axis coordinate of the control point.
- cpy: number
  The y-axis coordinate of the control point.
- x: number
  The x-axis coordinate of the end point.
- y: number
  The y-axis coordinate of the end point.
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.moveTo(0, 0)
canvas.quadraticCurveTo(0, 100, 100, 100)
canvas.stroke()
const output = new Output(canvas, 'quadraticCurveTo.png')
output.addToQueue()
```

rect

rect(x: number, y: number, width: number, height: number): void
Adds a rectangle to the current path.

Like other methods that modify the current path, this method does not directly render anything. To draw the rectangle onto a canvas, you can use the Canvas.fill or Canvas.stroke methods.
Parameters
- x: number
- y: number
- width: number
- height: number
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.rect(0, 0, 50, 50)
canvas.fillStyle = 'green'
canvas.fill()
const output = new Output(canvas, 'rect.png')
output.addToQueue()
```

restore

restore(): void

Restores the most recently saved canvas state by popping the top entry in the drawing state stack. If there is no saved state, this method does nothing.

Returns void

rotate

rotate(angle: number): void
Adds a rotation to the transformation matrix.
Parameters
- angle: number
  The rotation angle, clockwise in radians. You can use degree * Math.PI / 180 to calculate a radian from a degree.
Returns void
Example
```
const canvas = new Canvas(50, 50)
canvas.rotate(45 * Math.PI / 180)
canvas.fillRect(30, 0, 10, 10)
const output = new Output(canvas, 'rotate.png')
output.addToQueue()
```

save

save(): void

Saves the entire state of the canvas by pushing the current state onto a stack.

Returns void

scale

scale(x: number, y: number): void
Adds a scaling transformation to the canvas units horizontally and/or vertically.

By default, one unit on the canvas is exactly one pixel. A scaling transformation modifies this behavior. For instance, a scaling factor of 0.5 results in a unit size of 0.5 pixels; shapes are thus drawn at half the normal size. Similarly, a scaling factor of 2.0 increases the unit size so that one unit becomes two pixels; shapes are thus drawn at twice the normal size.
Parameters
- x: number
  Scaling factor in the horizontal direction. A negative value flips pixels across the vertical axis. A value of 1 results in no horizontal scaling.
- y: number
  Scaling factor in the vertical direction. A negative value flips pixels across the horizontal axis. A value of 1 results in no vertical scaling.
Returns void
Example
```
const canvas = new Canvas(50, 50)
canvas.scale(3, 4)
canvas.fillRect(0, 0, 10, 10)
const output = new Output(canvas, 'scale.png')
output.addToQueue()
```

setTransform

setTransform(
    a: number,
    b: number,
    c: number,
    d: number,
    e: number,
    f: number,
): void
Resets (overrides) the current transformation to the identity matrix, and then invokes a transformation described by the arguments of this method. This lets you scale, rotate, translate (move), and skew the context.
```
[ a c e
  b d f
  0 0 1 ]
```
Parameters
- a: number
  (m11) Horizontal scaling. A value of 1 results in no scaling.
- b: number
  (m12) Vertical scaling.
- c: number
  (m21) Horizontal scaling.
- d: number
  (m22) Vertical scaling. A value of 1 results in no scaling.
- e: number
  (dx) Horizontal translation (moving).
- f: number
  (dy) Vertical translation (moving).
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.setTransform(1, 0.2, 0.8, 1, 0, 0)
canvas.fillRect(0, 0, 50, 50)
const output = new Output(canvas, 'transform.png')
output.addToQueue()
```

stroke

stroke(): void

Strokes (outlines) the current or given path with the current Canvas.strokeStyle.

Returns void

strokeRect

strokeRect(x: number, y: number, width: number, height: number): void
Draws a rectangle that is stroked (outlined) according to the current Canvas.strokeStyle and other context settings.
Parameters
- x: number
- y: number
- width: number
- height: number
Returns void

strokeText

strokeText(text: string, x: number, y: number): void
Draws the outlines of the characters of a text string at the specified coordinates.
Parameters
- text: string
  The text string to render into canvas.
- x: number
  The x-axis coordinate of the point at which to begin drawing text, in pixels.
- y: number
  The y-axis coordinate of the point at which to begin drawing text, in pixels.
Returns void
Example
```
const canvas = new Canvas(100, 50)
canvas.font = '42pt Futura'
canvas.strokeStyle = 'blue'
canvas.strokeText('Hello', 0, 42)
const output = new Output(canvas, 'strokeText.png')
output.addToQueue()
```

transform

transform(
    a: number,
    b: number,
    c: number,
    d: number,
    e: number,
    f: number,
): void
Multiplies the current transformation with the matrix described by the arguments of this method. This lets you scale, rotate, translate (move), and skew the context.

The transformation matrix is described by:
```
[ a c e
  b d f
  0 0 1 ]
```
Parameters
- a: number
  (m11) Horizontal scaling. A value of 1 results in no scaling.
- b: number
  (m12) Vertical scaling.
- c: number
  (m21) Horizontal scaling.
- d: number
  (m22) Vertical scaling. A value of 1 results in no scaling.
- e: number
  (dx) Horizontal translation (moving).
- f: number
  (dy) Vertical translation (moving).
Returns void
Example
```
const canvas = new Canvas(100, 100)
canvas.transform(1, 0.2, 0.8, 1, 0, 0)
canvas.fillRect(0, 0, 50, 50)
const output = new Output(canvas, 'transform.png')
output.addToQueue()
```

translate

translate(x: number, y: number): void
Adds a translation transformation to the current matrix by moving the canvas and its origin x units horizontally and y units vertically on the grid.
Parameters
- x: number
  Distance to move in the horizontal direction. Positive values are to the right, and negative to the left.
- y: number
  Distance to move in the vertical direction. Positive values are down, and negative are up.
Returns void
Example
```
const canvas = new Canvas(50, 50)
canvas.translate(25, 25)
canvas.fillRect(0, 0, 10, 10)
const output = new Output(canvas, 'translate.png')
output.addToQueue()
```

Class Canvas

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Canvas

Properties

fillStyle

Default Value

Example

font

Default Value

See

globalAlpha

Default Value

globalCompositeOperation

Default Value

Readonlyheight

lineCap

Default Value

lineDash

Default Value

lineJoin

Default Value

lineWidth

Default Value

miterLimit

Default Value

shadowBlur

Default Value

OptionalshadowColor

Default Value

shadowOffsetX

Default Value

shadowOffsetY

Default Value

strokeStyle

Default Value

textAlign

Default Value

textBaseline

Default Value

Readonlywidth

Methods

arc

Parameters

Returns void

Example

beginPath

Returns void

bezierCurveTo

Parameters

Returns void

Example

clearRect

Parameters

Returns void

clip

Returns void

closePath

Returns void

createImageData

Parameters

Returns ImageData

Parameters

Returns ImageData

createLinearGradient

Parameters

Returns Gradient

Example

createPattern

Parameters

Returns PatternObject

createRadialGradient

Parameters

Returns Gradient

Example

`Readonly`height

`Optional`shadowColor

`Readonly`width