Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 341 lines (231 sloc) 10.24 kB
2ddcf97 @TooTallNate Readme: fix subheading size
TooTallNate authored
1 node-canvas
475943b @TooTallNate Readme: ocd
TooTallNate authored
2 ===========
2ddcf97 @TooTallNate Readme: fix subheading size
TooTallNate authored
3 ### Canvas graphics API backed by Cairo
96a1b00 @TooTallNate Readme: add Travis-CI badge
TooTallNate authored
4 [![Build Status](https://travis-ci.org/Automattic/node-canvas.svg?branch=master)](https://travis-ci.org/Automattic/node-canvas)
11a034e @TooTallNate Readme: remove Gemnasium badge, use SVG for npm badge
TooTallNate authored
5 [![NPM version](https://badge.fury.io/js/canvas.svg)](http://badge.fury.io/js/canvas)
3a9d122 @tj Initial commit
tj authored
6
96a1b00 @TooTallNate Readme: add Travis-CI badge
TooTallNate authored
7 node-canvas is a [Cairo](http://cairographics.org/) backed Canvas implementation for [NodeJS](http://nodejs.org).
cac74dd @tj Docs
tj authored
8
9 ## Authors
10
78ddc7e @javiercejudo Update TJ Holowaychuk's username in the readme
javiercejudo authored
11 - TJ Holowaychuk ([tj](http://github.com/tj))
97f2f1a @TooTallNate Readme: adding more authors
TooTallNate authored
12 - Nathan Rajlich ([TooTallNate](http://github.com/TooTallNate))
13 - Rod Vagg ([rvagg](http://github.com/rvagg))
14 - Juriy Zaytsev ([kangax](http://github.com/kangax))
cac74dd @tj Docs
tj authored
15
207ae02 @tj Docs
tj authored
16 ## Installation
17
76af51f @TooTallNate Readme: fix `bash` code samples
TooTallNate authored
18 ```bash
19 $ npm install canvas
20 ```
207ae02 @tj Docs
tj authored
21
b381dd6 @tj make wiki more obvious
tj authored
22 Unless previously installed you'll _need_ __Cairo__. For system-specific installation view the [Wiki](https://github.com/LearnBoost/node-canvas/wiki/_pages).
0a19dec @tj Added cairoVersion test
tj authored
23
c451997 @niftylettuce Updated dependencies and added one liner for install on OSX
niftylettuce authored
24 You can quickly install Cairo and its dependencies for OS X using the one liner below:
25
26 ```bash
76af51f @TooTallNate Readme: fix `bash` code samples
TooTallNate authored
27 $ wget https://raw.githubusercontent.com/LearnBoost/node-canvas/master/install -O - | sh
c451997 @niftylettuce Updated dependencies and added one liner for install on OSX
niftylettuce authored
28 ```
29
2077911 @tonylukasavage Add one-liner MacPorts install to docs
tonylukasavage authored
30 or if you use MacPorts
31
32 ```bash
33 sudo port install pkgconfig libpng giflib freetype libpixman cairo
34 ```
35
d1804e7 @tj Added screencast link
tj authored
36 ## Screencasts
37
38 - [Introduction](http://screenr.com/CTk)
39
207ae02 @tj Docs
tj authored
40 ## Example
41
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
42 ```javascript
43 var Canvas = require('canvas')
1961e52 @TooTallNate Readme: add `Image` variable example
TooTallNate authored
44 , Image = Canvas.Image
bfc6561 @dodekeract Fix Typo
dodekeract authored
45 , canvas = new Canvas(200, 200)
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
46 , ctx = canvas.getContext('2d');
47
48 ctx.font = '30px Impact';
49 ctx.rotate(.1);
50 ctx.fillText("Awesome!", 50, 100);
51
52 var te = ctx.measureText('Awesome!');
53 ctx.strokeStyle = 'rgba(0,0,0,0.5)';
54 ctx.beginPath();
55 ctx.lineTo(50, 102);
56 ctx.lineTo(50 + te.width, 102);
57 ctx.stroke();
58
59 console.log('<img src="' + canvas.toDataURL() + '" />');
60 ```
207ae02 @tj Docs
tj authored
61
62 ## Non-Standard API
63
dd9430e @tj Added more global composite operator support
tj authored
64 node-canvas extends the canvas API to provide interfacing with node, for example streaming PNG data, converting to a `Buffer` instance, etc. Among the interfacing API, in some cases the drawing API has been extended for SSJS image manipulation / creation usage, however keep in mind these additions may fail to render properly within browsers.
207ae02 @tj Docs
tj authored
65
73666af @tj docs
tj authored
66 ### Image#src=Buffer
67
68 node-canvas adds `Image#src=Buffer` support, allowing you to read images from disc, redis, etc and apply them via `ctx.drawImage()`. Below we draw scaled down squid png by reading it from the disk with node's I/O.
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
69
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
70 ```javascript
71 fs.readFile(__dirname + '/images/squid.png', function(err, squid){
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
72 if (err) throw err;
73 img = new Image;
74 img.src = squid;
75 ctx.drawImage(img, 0, 0, img.width / 4, img.height / 4);
76 });
77 ```
73666af @tj docs
tj authored
78
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
79 Below is an example of a canvas drawing it-self as the source several time:
73666af @tj docs
tj authored
80
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
81 ```javascript
82 var img = new Image;
83 img.src = canvas.toBuffer();
84 ctx.drawImage(img, 0, 0, 50, 50);
85 ctx.drawImage(img, 50, 0, 50, 50);
86 ctx.drawImage(img, 100, 0, 50, 50);
87 ```
73666af @tj docs
tj authored
88
f39dc4d @c-spencer Add readme entry for Image.dataMode
c-spencer authored
89 ### Image#dataMode
90
91 node-canvas adds `Image#dataMode` support, which can be used to opt-in to mime data tracking of images (currently only JPEGs).
92
93 When mime data is tracked, in PDF mode JPEGs can be embedded directly into the output, rather than being re-encoded into PNG. This can drastically reduce filesize, and speed up rendering.
94
95 ```javascript
96 var img = new Image;
97 img.dataMode = Image.MODE_IMAGE; // Only image data tracked
98 img.dataMode = Image.MODE_MIME; // Only mime data tracked
99 img.dataMode = Image.MODE_MIME | Image.MODE_IMAGE; // Both are tracked
100 ```
101
102 If image data is not tracked, and the Image is drawn to an image rather than a PDF canvas, the output will be junk. Enabling mime data tracking has no benefits (only a slow down) unless you are generating a PDF.
103
0d39dae @tj add Canvas#{png,jpeg}Stream() alias of create* legacy methods
tj authored
104 ### Canvas#pngStream()
207ae02 @tj Docs
tj authored
105
0d39dae @tj add Canvas#{png,jpeg}Stream() alias of create* legacy methods
tj authored
106 To create a `PNGStream` simply call `canvas.pngStream()`, and the stream will start to emit _data_ events, finally emitting _end_ when finished. If an exception occurs the _error_ event is emitted.
207ae02 @tj Docs
tj authored
107
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
108 ```javascript
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
109 var fs = require('fs')
110 , out = fs.createWriteStream(__dirname + '/text.png')
0d39dae @tj add Canvas#{png,jpeg}Stream() alias of create* legacy methods
tj authored
111 , stream = canvas.pngStream();
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
112
113 stream.on('data', function(chunk){
114 out.write(chunk);
115 });
116
117 stream.on('end', function(){
118 console.log('saved png');
119 });
120 ```
207ae02 @tj Docs
tj authored
121
191ff72 @tj Docs
tj authored
122 Currently _only_ sync streaming is supported, however we plan on supporting async streaming as well (of course :) ). Until then the `Canvas#toBuffer(callback)` alternative is async utilizing `eio_custom()`.
123
ca8045d @danielbeardsley Readme: update docs for canvas.jpegStream()
danielbeardsley authored
124 ### Canvas#jpegStream() and Canvas#syncJPEGStream()
93f2145 updated documentation for createJPEGStream
Elijah Hamovitz authored
125
ca8045d @danielbeardsley Readme: update docs for canvas.jpegStream()
danielbeardsley authored
126 You can likewise create a `JPEGStream` by calling `canvas.jpegStream()` with
127 some optional parameters; functionality is otherwise identical to
128 `pngStream()`. See `examples/crop.js` for an example.
129
130 _Note: At the moment, `jpegStream()` is the same as `syncJPEGStream()`, both
131 are synchronous_
132
133 ```javascript
8c499a0 @clickblipclick Fixed case on Readme Canvas#jpegStream() example (canvas.jpegStream, …
clickblipclick authored
134 var stream = canvas.jpegStream({
be45018 @kangax Add dependencies badge to README
kangax authored
135 bufsize: 4096 // output buffer size in bytes, default: 4096
ca8045d @danielbeardsley Readme: update docs for canvas.jpegStream()
danielbeardsley authored
136 , quality: 75 // JPEG quality (0-100) default: 75
137 , progressive: false // true for progressive compression, default: false
138 });
139 ```
93f2145 updated documentation for createJPEGStream
Elijah Hamovitz authored
140
207ae02 @tj Docs
tj authored
141 ### Canvas#toBuffer()
142
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
143 A call to `Canvas#toBuffer()` will return a node `Buffer` instance containing all of the PNG data.
207ae02 @tj Docs
tj authored
144
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
145 ```javascript
146 canvas.toBuffer();
147 ```
f8901ce @tj Docs
tj authored
148
a219caa @tj docs
tj authored
149 ### Canvas#toBuffer() async
baea57b @tj Docs
tj authored
150
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
151 Optionally we may pass a callback function to `Canvas#toBuffer()`, and this process will be performed asynchronously, and will `callback(err, buf)`.
baea57b @tj Docs
tj authored
152
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
153 ```javascript
154 canvas.toBuffer(function(err, buf){
f8901ce @tj Docs
tj authored
155
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
156 });
157 ```
f8901ce @tj Docs
tj authored
158
a219caa @tj docs
tj authored
159 ### Canvas#toDataURL() async
baea57b @tj Docs
tj authored
160
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
161 Optionally we may pass a callback function to `Canvas#toDataURL()`, and this process will be performed asynchronously, and will `callback(err, str)`.
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
162
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
163 ```javascript
298db52 @TooTallNate spacing
TooTallNate authored
164 canvas.toDataURL(function(err, str){
165
166 });
ac0b2ad @tj doc typo
tj authored
167 ```
f8901ce @tj Docs
tj authored
168
169 or specify the mime type:
170
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
171 ```javascript
172 canvas.toDataURL('image/png', function(err, str){
298db52 @TooTallNate spacing
TooTallNate authored
173
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
174 });
175 ```
baea57b @tj Docs
tj authored
176
8d52459 @tj docs for patternQuality
tj authored
177 ### CanvasRenderingContext2d#patternQuality
178
179 Given one of the values below will alter pattern (gradients, images, etc) render quality, defaults to _good_.
180
181 - fast
182 - good
183 - best
a1fa149 @mojodna Add 'nearest' and 'bilinear' to patternQuality
mojodna authored
184 - nearest
185 - bilinear
8d52459 @tj docs for patternQuality
tj authored
186
18e3edf @c-spencer Add textDrawingMode context property.
c-spencer authored
187 ### CanvasRenderingContext2d#textDrawingMode
188
189 Can be either `path` or `glyph`. Using `glyph` is much faster than `path` for drawing, and when using a PDF context will embed the text natively, so will be selectable and lower filesize. The downside is that cairo does not have any subpixel precision for `glyph`, so this will be noticeably lower quality for text positioning in cases such as rotated text. Also, strokeText in `glyph` will act the same as fillText, except using the stroke style for the fill.
190
3dfb4e0 @c-spencer Add note on default value of textDrawingMode
c-spencer authored
191 Defaults to _path_.
192
18e3edf @c-spencer Add textDrawingMode context property.
c-spencer authored
193 This property is tracked as part of the canvas state in save/restore.
194
8dc36f0 @mojodna CanvasRenderingContext2d#filter
mojodna authored
195 ### CanvasRenderingContext2d#filter
196
197 Like `patternQuality`, but applies to transformations effecting more than just patterns. Defaults to _good_.
198
199 - fast
200 - good
201 - best
202 - nearest
203 - bilinear
204
dd9430e @tj Added more global composite operator support
tj authored
205 ### Global Composite Operations
206
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
207 In addition to those specified and commonly implemented by browsers, the following have been added:
dd9430e @tj Added more global composite operator support
tj authored
208
209 - multiply
210 - screen
211 - overlay
212 - hard-light
213 - soft-light
214 - hsl-hue
215 - hsl-saturation
216 - hsl-color
217 - hsl-luminosity
218
12e2681 @tj Added Context2d#antialias=
tj authored
219 ## Anti-Aliasing
220
dc19ed6 @tj Anti-Aliasing example
tj authored
221 Set anti-aliasing mode
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
222
12e2681 @tj Added Context2d#antialias=
tj authored
223 - default
224 - none
225 - gray
226 - subpixel
227
dc19ed6 @tj Anti-Aliasing example
tj authored
228 For example:
0aae15e @kkaefer Marked up JavaScript code to be syntax highlighted
kkaefer authored
229
230 ```javascript
231 ctx.antialias = 'none';
232 ```
dc19ed6 @tj Anti-Aliasing example
tj authored
233
55a7ae8 @tj docs for pdf
tj authored
234 ## PDF Support
235
236 Basic PDF support was added in 0.11.0. Make sure to install cairo with `--enable-pdf=yes` for the PDF backend. node-canvas must know that it is creating
237 a PDF on initialization, using the "pdf" string:
238
239 ```js
240 var canvas = new Canvas(200, 500, 'pdf');
241 ```
242
be45018 @kangax Add dependencies badge to README
kangax authored
243 An additional method `.addPage()` is then available to create
55a7ae8 @tj docs for pdf
tj authored
244 multiple page PDFs:
245
246 ```js
247 ctx.font = '22px Helvetica';
248 ctx.fillText('Hello World', 50, 80);
ac9d442 @tj docs
tj authored
249 ctx.addPage();
55a7ae8 @tj docs for pdf
tj authored
250
251 ctx.font = '22px Helvetica';
252 ctx.fillText('Hello World 2', 50, 80);
ac9d442 @tj docs
tj authored
253 ctx.addPage();
55a7ae8 @tj docs for pdf
tj authored
254
255 ctx.font = '22px Helvetica';
256 ctx.fillText('Hello World 3', 50, 80);
ac9d442 @tj docs
tj authored
257 ctx.addPage();
55a7ae8 @tj docs for pdf
tj authored
258 ```
259
79f1d42 @espadrine Offer SVG output.
espadrine authored
260 ## SVG support
261
262 Just like PDF support, make sure to install cairo with `--enable-svg=yes`.
263 You also need to tell node-canvas that it is working on SVG upon its initialization:
264
265 ```js
266 var canvas = new Canvas(200, 500, 'svg');
267 // Use the normal primitives.
268 fs.writeFile('out.svg', canvas.toBuffer());
269 ```
270
5c78b36 @tj Benchmarks
tj authored
271 ## Benchmarks
272
373e045 @tj Typo
tj authored
273 Although node-canvas is extremely new, and we have not even begun optimization yet it is already quite fast. For benchmarks vs other node canvas implementations view this [gist](https://gist.github.com/664922), or update the submodules and run `$ make benchmark` yourself.
5c78b36 @tj Benchmarks
tj authored
274
ebf8d1f @tj Docs
tj authored
275 ## Contribute
276
277 Want to contribute to node-canvas? patches for features, bug fixes, documentation, examples and others are certainly welcome. Take a look at the [issue queue](https://github.com/LearnBoost/node-canvas/issues) for existing issues.
278
298a21e @tj Docs
tj authored
279 ## Examples
280
281 Examples are placed in _./examples_, be sure to check them out! most produce a png image of the same name, and others such as _live-clock.js_ launch an http server to be viewed in the browser.
282
d1c675f @tj Docs for testing
tj authored
283 ## Testing
284
216497b @tj Added express/jade submodules
tj authored
285 If you have not previously, init git submodules:
9342396 @tj Docs
tj authored
286
216497b @tj Added express/jade submodules
tj authored
287 $ git submodule update --init
288
6ba110b @joefreeman Update the readme (node modules need to be installed before 'node-gyp…
joefreeman authored
289 Install the node modules:
290
291 $ npm install
292
216497b @tj Added express/jade submodules
tj authored
293 Build node-canvas:
d1c675f @tj Docs for testing
tj authored
294
c8c6f09 @espadrine Readme update: node-gyp.
espadrine authored
295 $ node-gyp rebuild
d1c675f @tj Docs for testing
tj authored
296
216497b @tj Added express/jade submodules
tj authored
297 Unit tests:
d1c675f @tj Docs for testing
tj authored
298
299 $ make test
300
216497b @tj Added express/jade submodules
tj authored
301 Visual tests:
06a5a44 @tj Docs
tj authored
302
4d61b7b @tj Added `make test-server`
tj authored
303 $ make test-server
06a5a44 @tj Docs
tj authored
304
823e093 @tj Mention node / cairo versions tested with
tj authored
305 ## Versions
306
cf8e9df @tj node 0.4.2
tj authored
307 Tested with and designed for:
823e093 @tj Mention node / cairo versions tested with
tj authored
308
cf8e9df @tj node 0.4.2
tj authored
309 - node 0.4.2
823e093 @tj Mention node / cairo versions tested with
tj authored
310 - cairo 1.8.6
311
434a964 @tj docs
tj authored
312 For node 0.2.x `node-canvas` <= 0.4.3 may be used,
313 0.5.0 and above are designed for node 0.4.x only.
314
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
315 ## License
3a9d122 @tj Initial commit
tj authored
316
317 (The MIT License)
318
68d89c5 @TooTallNate Readme: update copyright
TooTallNate authored
319 Copyright (c) 2010 LearnBoost, and contributors &lt;dev@learnboost.com&gt;
abc2896 @TooTallNate Readme: spacing
TooTallNate authored
320
68d89c5 @TooTallNate Readme: update copyright
TooTallNate authored
321 Copyright (c) 2014 Automattic, Inc and contributors &lt;dev@automattic.com&gt;
3a9d122 @tj Initial commit
tj authored
322
323 Permission is hereby granted, free of charge, to any person obtaining
324 a copy of this software and associated documentation files (the
325 'Software'), to deal in the Software without restriction, including
326 without limitation the rights to use, copy, modify, merge, publish,
327 distribute, sublicense, and/or sell copies of the Software, and to
328 permit persons to whom the Software is furnished to do so, subject to
329 the following conditions:
330
331 The above copyright notice and this permission notice shall be
332 included in all copies or substantial portions of the Software.
333
334 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
335 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
336 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
337 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
338 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
339 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
d2947da @gabrielfalcao fixing an example in readme.md
gabrielfalcao authored
340 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.