Modularise JS source in 'lib' subdirectory.

Generate public API documention via jsdoc comments.
lovell · Nov 1, 2016 · f6d81db · f6d81db
1 parent 693f77e
commit f6d81db
Show file tree

Hide file tree

Showing 62 changed files with 3,384 additions and 2,779 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -62,6 +62,17 @@ A method to be removed should be deprecated in the next major version then remov
 
 By way of example, the [bilinearInterpolation method](https://github.com/lovell/sharp/blob/v0.6.0/index.js#L155) present in v0.5.0 was deprecated in v0.6.0 and removed in v0.7.0.
 
+## Documentation
+
+The public API is documented with [JSDoc](http://usejsdoc.org/) annotated comments.
+These can be converted to Markdown by running:
+
+```sh
+npm run docs
+```
+
+Please include documentation updates in any Pull Request that modifies the public API.
+
 ## Run the tests
 
 ### Functional tests and static code analysis

diff --git a/docs/api-channel.md b/docs/api-channel.md
@@ -0,0 +1,72 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# extractChannel
+
+Extract a single channel from a multi-channel image.
+
+**Parameters**
+
+-   `channel` **([Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** zero-indexed band number to extract, or `red`, `green` or `blue` as alternative to `0`, `1` or `2` respectively.
+
+**Examples**
+
+```javascript
+sharp(input)
+  .extractChannel('green')
+  .toFile('input_green.jpg', function(err, info) {
+    // info.channels === 1
+    // input_green.jpg contains the green channel of the input image
+   });
+```
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid channel
+
+Returns **Sharp** 
+
+# joinChannel
+
+Join one or more channels to the image.
+The meaning of the added channels depends on the output colourspace, set with `toColourspace()`.
+By default the output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
+Channel ordering follows vips convention:
+
+-   sRGB: 0: Red, 1: Green, 2: Blue, 3: Alpha.
+-   CMYK: 0: Magenta, 1: Cyan, 2: Yellow, 3: Black, 4: Alpha.
+
+Buffers may be any of the image formats supported by sharp: JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data.
+For raw pixel input, the `options` object should contain a `raw` attribute, which follows the format of the attribute of the same name in the `sharp()` constructor.
+
+**Parameters**
+
+-   `images` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Buffer](https://nodejs.org/api/buffer.html))** one or more images (file paths, Buffers).
+-   `Object`  image options, see `sharp()` constructor.
+-   `options`  
+
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
+
+# bandbool
+
+Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image.
+
+**Parameters**
+
+-   `boolOp` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively.
+
+**Examples**
+
+```javascript
+sharp('3-channel-rgb-input.png')
+  .bandbool(sharp.bool.and)
+  .toFile('1-channel-output.png', function (err, info) {
+    // The output will be a single channel image where each pixel `P = R & G & B`.
+    // If `I(1,1) = [247, 170, 14] = [0b11110111, 0b10101010, 0b00001111]`
+    // then `O(1,1) = 0b11110111 & 0b10101010 & 0b00001111 = 0b00000010 = 2`.
+  });
+```
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
diff --git a/docs/api-colour.md b/docs/api-colour.md
@@ -0,0 +1,71 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# background
+
+Set the background for the `embed`, `flatten` and `extend` operations.
+The default background is `{r: 0, g: 0, b: 0, a: 1}`, black without transparency.
+
+Delegates to the _color_ module, which can throw an Error
+but is liberal in what it accepts, clipping values to sensible min/max.
+The alpha value is a float between `0` (transparent) and `1` (opaque).
+
+**Parameters**
+
+-   `rgba` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameter
+
+Returns **Sharp** 
+
+# greyscale
+
+Convert to 8-bit greyscale; 256 shades of grey.
+This is a linear operation. If the input image is in a non-linear colour space such as sRGB, use `gamma()` with `greyscale()` for the best results.
+By default the output image will be web-friendly sRGB and contain three (identical) color channels.
+This may be overridden by other sharp operations such as `toColourspace('b-w')`,
+which will produce an output image containing one color channel.
+An alpha channel may be present, and will be unchanged by the operation.
+
+**Parameters**
+
+-   `greyscale` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]**  (optional, default `true`)
+
+Returns **Sharp** 
+
+# grayscale
+
+Alternative spelling of `greyscale`.
+
+**Parameters**
+
+-   `grayscale` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]**  (optional, default `true`)
+
+Returns **Sharp** 
+
+# toColourspace
+
+Set the output colourspace.
+By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
+
+**Parameters**
+
+-   `colourspace` **\[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/jcupitt/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568)
+
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
+
+# toColorspace
+
+Alternative spelling of `toColourspace`.
+
+**Parameters**
+
+-   `colorspace` **\[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** output colorspace.
+
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
diff --git a/docs/api-composite.md b/docs/api-composite.md
@@ -0,0 +1,47 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# overlayWith
+
+Overlay (composite) an image over the processed (resized, extracted etc.) image.
+
+The overlay image must be the same size or smaller than the processed image.
+If both `top` and `left` options are provided, they take precedence over `gravity`.
+
+**Parameters**
+
+-   `overlay` **([Buffer](https://nodejs.org/api/buffer.html) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** Buffer containing image data or String containing the path to an image file.
+-   `options` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** 
+    -   `options.gravity` **\[[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** gravity at which to place the overlay. (optional, default `'centre'`)
+    -   `options.top` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** the pixel offset from the top edge.
+    -   `options.left` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** the pixel offset from the left edge.
+    -   `options.tile` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** set to true to repeat the overlay image across the entire image with the given `gravity`. (optional, default `false`)
+    -   `options.cutout` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** set to true to apply only the alpha channel of the overlay image to the input image, giving the appearance of one image being cut out of another. (optional, default `false`)
+    -   `options.raw` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** describes overlay when using raw pixel data.
+        -   `options.raw.width` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+        -   `options.raw.height` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+        -   `options.raw.channels` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+
+**Examples**
+
+```javascript
+sharp('input.png')
+  .rotate(180)
+  .resize(300)
+  .flatten()
+  .background('#ff6600')
+  .overlayWith('overlay.png', { gravity: sharp.gravity.southeast } )
+  .sharpen()
+  .withMetadata()
+  .quality(90)
+  .webp()
+  .toBuffer()
+  .then(function(outputBuffer) {
+    // outputBuffer contains upside down, 300px wide, alpha channel flattened
+    // onto orange background, composited with overlay.png with SE gravity,
+    // sharpened, with metadata, 90% quality WebP image data. Phew!
+  });
+```
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
diff --git a/docs/api-constructor.md b/docs/api-constructor.md
@@ -0,0 +1,81 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# 
+
+**Parameters**
+
+-   `input` **\[([Buffer](https://nodejs.org/api/buffer.html) \| [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))]** if present, can be
+     a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or
+     a String containing the path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file.
+     JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when null or undefined.
+-   `options` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** if present, is an Object with optional attributes.
+    -   `options.density` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** integral number representing the DPI for vector images. (optional, default `72`)
+    -   `options.raw` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** describes raw pixel image data. See `raw()` for pixel ordering.
+        -   `options.raw.width` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+        -   `options.raw.height` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+        -   `options.raw.channels` **\[[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** 
+
+**Examples**
+
+```javascript
+sharp('input.jpg')
+  .resize(300, 200)
+  .toFile('output.jpg', function(err) {
+    // output.jpg is a 300 pixels wide and 200 pixels high image
+    // containing a scaled and cropped version of input.jpg
+  });
+```
+
+```javascript
+// Read image data from readableStream,
+// resize to 300 pixels wide,
+// emit an 'info' event with calculated dimensions
+// and finally write image data to writableStream
+var transformer = sharp()
+  .resize(300)
+  .on('info', function(info) {
+    console.log('Image height is ' + info.height);
+  });
+readableStream.pipe(transformer).pipe(writableStream);
+```
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid parameters
+
+Returns **Sharp** 
+
+# queue
+
+An EventEmitter that emits a `change` event when a task is either:
+
+-   queued, waiting for _libuv_ to provide a worker thread
+-   complete
+
+**Examples**
+
+```javascript
+sharp.queue.on('change', function(queueLength) {
+  console.log('Queue contains ' + queueLength + ' task(s)');
+});
+```
+
+# format
+
+An Object containing nested boolean values representing the available input and output formats/methods.
+
+**Examples**
+
+```javascript
+console.log(sharp.format());
+```
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
+
+# versions
+
+An Object containing the version numbers of libvips and its dependencies.
+
+**Examples**
+
+```javascript
+console.log(sharp.versions);
+```
diff --git a/docs/api-input.md b/docs/api-input.md
@@ -0,0 +1,86 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+# clone
+
+Take a "snapshot" of the Sharp instance, returning a new instance.
+Cloned instances inherit the input of their parent instance.
+This allows multiple output Streams and therefore multiple processing pipelines to share a single input Stream.
+
+**Examples**
+
+```javascript
+const pipeline = sharp().rotate();
+pipeline.clone().resize(800, 600).pipe(firstWritableStream);
+pipeline.clone().extract({ left: 20, top: 20, width: 100, height: 100 }).pipe(secondWritableStream);
+readableStream.pipe(pipeline);
+// firstWritableStream receives auto-rotated, resized readableStream
+// secondWritableStream receives auto-rotated, extracted region of readableStream
+```
+
+Returns **Sharp** 
+
+# metadata
+
+Fast access to image metadata without decoding any compressed image data.
+A Promises/A+ promise is returned when `callback` is not provided.
+
+-   `format`: Name of decoder used to decompress image data e.g. `jpeg`, `png`, `webp`, `gif`, `svg`
+-   `width`: Number of pixels wide
+-   `height`: Number of pixels high
+-   `space`: Name of colour space interpretation e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/jcupitt/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568)
+-   `channels`: Number of bands e.g. `3` for sRGB, `4` for CMYK
+-   `density`: Number of pixels per inch (DPI), if present
+-   `hasProfile`: Boolean indicating the presence of an embedded ICC profile
+-   `hasAlpha`: Boolean indicating the presence of an alpha transparency channel
+-   `orientation`: Number value of the EXIF Orientation header, if present
+-   `exif`: Buffer containing raw EXIF data, if present
+-   `icc`: Buffer containing raw [ICC](https://www.npmjs.com/package/icc) profile data, if present
+
+**Parameters**
+
+-   `callback` **\[[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)]** called with the arguments `(err, metadata)`
+
+**Examples**
+
+```javascript
+const image = sharp(inputJpg);
+image
+  .metadata()
+  .then(function(metadata) {
+    return image
+      .resize(Math.round(metadata.width / 2))
+      .webp()
+      .toBuffer();
+  })
+  .then(function(data) {
+    // data contains a WebP image half the width and height of the original JPEG
+  });
+```
+
+Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | Sharp)** 
+
+# limitInputPixels
+
+Do not process input images where the number of pixels (width _ height) exceeds this limit.
+Assumes image dimensions contained in the input metadata can be trusted.
+The default limit is 268402689 (0x3FFF _ 0x3FFF) pixels.
+
+**Parameters**
+
+-   `limit` **([Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) \| [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean))** an integral Number of pixels, zero or false to remove limit, true to use default limit.
+
+
+-   Throws **[Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** Invalid limit
+
+Returns **Sharp** 
+
+# sequentialRead
+
+An advanced setting that switches the libvips access method to `VIPS_ACCESS_SEQUENTIAL`.
+This will reduce memory usage and can improve performance on some systems.
+
+**Parameters**
+
+-   `sequentialRead` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]**  (optional, default `true`)
+
+Returns **Sharp**