gm v1.9.0 GraphicsMagick for node.js

Manipulation
Getters
Drawing
Using Imagemagick

manipulation
- adjoin
```
gm("img.png").adjoin()
```
- affine
```
gm("img.png").affine(matrix)
```
- antialias
  By default all imgs are anti-aliased by GraphicsMagick. To disable it pass false.
```
gm("img.png").antialias(false)
```
- append
  Append a set of images
  
  img
  
  the path to another img
  
  ltr (optional)
  
  Boolean - specifies append direction
  true for left-to-right
  false for top-to-bottom (default)
```
gm("img.png").append(img [, img, ltr])

// appends another.jpg to img.png from left-to-right
gm("img.png").append("another.jpg").append(true)

// appends another.jpg to img.png from left-to-right
gm("img.png").append("another.jpg", true)

// appends another.jpg to img.png from top-to-bottom
gm("img.png").append("another.jpg")

// appends third.gif below another.jpg below img.png
gm("img.png").append("another.jpg").append("third.gif")

// appends third.gif below another.jpg below img.png
gm("img.png").append("another.jpg", "third.gif")

// appends third.gif to the right of another.jpg to the right to img.png
gm("img.png").append("another.jpg", "third.gif", true)
            
```
- authenticate
```
gm("img.png").authenticate(password)
```
- autoOrient
  Auto-orients the image according to its EXIF data.
  
  GraphicsMagick doesn't actually have the -auto-orient option but we emulate this by first reading the EXIF data and rotate/flip from there.
```
gm("img.jpg").autoOrient()
```
- average
```
gm("img.png").average()
```
- backdrop
```
gm("img.png").backdrop()
```
- bitdepth
  Specifies the number of bits of color to preserve in the image. See the docs for more detail.
```
gm("img.png").bitdepth(bits)
```
- blackThreshold
  pixels below `threshold` become black.
```
gm("img.png").blackThreshold(red [,green] [,blue] [,opacity])
```
- bluePrimary
```
gm("img.png").bluePrimary(x, x)
```
- blur
  Accepts a radius and optional sigma (standard deviation).
```
gm("img.png").blur(radius [, sigma])
```
- border
```
gm("img.png").border(width, height)
```
- borderColor
```
gm("img.png").borderColor(color)
```
- box
```
gm("img.png").box(color)
```
- channel
  
  type
  
  Red, Green, Blue, Opacity, Matte, Cyan, Magenta, Yellow, Black, or Gray
```
gm("img.png").channel(type)
```
- charcoal
  Simulates a charcoal drawing. Accepts a factor.
```
gm("img.png").charcoal(factor)
```
- chop
  Removes pixels from the interior of an image.
```
gm("img.png").chop(width, height, x, y)
```
- clip
```
gm("img.png").clip()
```
- coalesce
```
gm("img.png").coalesce()
```
- colorize
  Colorize the image with optionally separate red, green, and blue values.
```
gm("img.png").colorize(red [, green [, blue]])
```
- colorMap
  
  type
  
  shared or private
```
gm("img.png").colorMap(type)
```
- colors
  Sets the preferred number of colors for the image (color reduction).
```
gm("img.png").colors(int)
```
- colorspace
  Specifies the type of colorspace. See the GraphicsMagick docs for val details.
```
gm("img.png").colorspace(val)
```
- compose
```
gm("img.png").compose(operator)
```
- compress
  
  type
  
  None, BZip, Fax, Group4, JPEG, Lossless, LZW, RLE, Zip, or LZMA
```
gm("img.png").compress(type)
```
- comment
  Annotates an image. See the docs for more info.
```
gm("img.png").comment(text|format)
```
- contrast
  Increases or reduces the image contrast. Accepts a multiplier.
```
gm("img.png").contrast([+-]multiplier)
```
- convolve
```
gm("img.png").convolve(kernel)
```
- createDirectories
```
gm("img.png").createDirectories()
```
- crop
  Crops the image to the given width and height at the given x and y position.
```
gm("img.png").crop(width, height, x, y)
```
- cycle
  Displace the image colormap by amount. amount is the number of positions each colormap entry is shifted.
```
gm("img.png").cycle(amount)
```
- deconstruct
```
gm("img.png").deconstruct()
```
- define
```
gm("img.png").define()
```
- delay
  `amount` is in hundreths of a second.
```
gm("img.png").delay(amout)
```
- density
  This option specifies the image resolution to store while encoding a raster image or the canvas resolution while rendering (reading) vector formats into an image.
```
gm("img.png").density(width, height)
```
- despeckle
  Reduces the speckles within the image.
```
gm("img.png").despeckle()
```
- displace
  Shift image pixels as defined by a displacement map.
```
gm("img.png").displace(horizontal, vertical)
```
- display
```
gm("img.png").display(value)
```
- dispose
```
gm("img.png").dispose(method)
```
- dissolve
```
gm("img.png").dissolve(method)
```
- dither
  Applies Floyd/Steinberg error diffusion to the image. Pass false to disable dithering.
  Note: either .colors() or .monochrome() must be used for this to take effect.
```
gm("img.png").dither([bool])
```
- edge
  Emphasizes edges in an image. Takes an optional radius of the emphasis to apply.
```
gm("img.png").edge([radius])
```
- emboss
  Embosses the image. Takes an optional radius.
```
gm("img.png").emboss([radius])
```
- encoding
  
  type
  
  AdobeCustom, AdobeExpert, AdobeStandard, AppleRoman, BIG5, GB2312, Latin 2, None, SJIScode, Symbol, Unicode, Wansung
```
gm("img.png").encoding(type)
```
- endian
  
  type
  
  MSB, LSB, or Native
```
gm("img.png").endian(type)
```
- enhance
  Enhances the image.
```
gm("img.png").enhance()
```
- equalize
  Performs histogram equalization to the image.
```
gm("img.png").equalize()
```
- extent
  composite image on background color canvas image.
```
gm("img.png").extent([width, height, options])
```
- file
```
gm("img.png").file(filename)
```
- filter
  Specifies the filter to use when resizing. see link for available types.
```
gm("img.png").filter(type)
```
- flatten
```
gm("img.png").flatten()
```
- flip
  Creates a mirror image (vertically).
```
gm("img.png").flip()
```
- flop
  Creates a mirror image (horizontally).
```
gm("img.png").flop()
```
- foreground
```
gm("img.png").foreground(color)
```
- frame
```
gm("img.png").frame(width, height, outerBevelWidth, innerBevelWidth)
```
- fuzz
```
gm("img.png").fuzz(distance [,percent])
```
- gamma
  Adjusts the level of gamma correction.
```
gm("img.png").gamma(r, g, b)
```
- gaussian
```
gm("img.png").gaussian(radius [,sigma])
```
- geometry
```
gm("img.png").geometry(width, height [,arg])
```
- greenPrimary
```
gm("img.png").greenPrimary(x, y)
```
- gravity
  The direction the primitive gravitates to when annotating the image. Defaults to NorthWest.
  
  direction
  
  NorthWest|North|NorthEast|West|Center|East|SouthWest|South|SouthEast
```
gm("img.png").gravity(direction)
```
- highlightColor
```
gm("img.png").highlightColor(color)
```
- highlightStyle
```
gm("img.png").highlightStyle(color)
```
- iconGeometry
```
gm("img.png").iconGeometry(geometry)
```
- implode
  Implodes the image pixels around the center. Takes an optional factor.
```
gm("img.png").implode([factor])
```
- intent
  
  type
  
  Absolute, Perceptual, Relative, or Saturation
```
gm("img.png").intent(type)
```
- interlace
  Specifies the type of interlacing scheme. Defaults to None.
  
  type
  
  None|Line|Plane|Partition
```
gm("img.png").interlace(type)
```
- label
  Assigns a label to an image.
```
gm("img.png").label(name)
```
- lat
```
gm("img.png").lat(width, height, offset [,percent])
```
- level
```
gm("img.png").level(blackPoint, gamma, whitePoint [,percent])
```
- limit
  Sets resource limits.
  
  type
  
  disk|file|map|memory|pixels|threads
  
  val
  
  follows the same rules as specified in the GraphicsMagick docs
```
gm("img.png").limit(type, val)
```
- list
  
  type
  
  Color, Delegate, Format, Magic, Module, Resource, or Type
```
gm("img.png").list(type)
```
- log
  Specify format for debug log. See the docs for detail.
```
gm("img.png").log(format)
```
- loop
  See the docs for detail.
```
gm("img.png").loop(iterations)
```
- lower
  Creates a pseudo 3D lowering effect of the images edges.
```
gm("img.png").lower(width, height)
```
- magnify
  Magnifies the image factor times.
```
gm("img.png").magnify(factor)
```
- map
  See the docs for detail.
```
gm("img.png").map(filename)
```
- mask
  See the docs for detail.
```
gm("img.png").mask(filename)
```
- matte
  See the docs for detail.
```
gm("img.png").matte()
```
- matteColor
  See the docs for detail.
```
gm("img.png").matteColor(color)
```
- maximumError
  See the docs for detail.
```
gm("img.png").maximumError(limit)
```
- median
  Applies a median filter to the image. The optional param radius adjusts the weight of the effect.
```
gm("img.png").median([radius])
```
- minify
  Minifies the image factor times.
```
gm("img.png").minify(factor)
```
- mode
  See the docs for detail.
```
gm("img.png").mode(value)
```
- modulate
  Varies the brightness, saturation, and hue of the image.
```
gm("img.png").modulate(b [, s [, h]])
```
- monitor
  See the docs for detail.
```
gm("img.png").monitor()
```
- monochrome
  Transforms the image to black and white.
```
gm("img.png").monochrome()
```
- morph
  Morphs two images together.
  
  otherImg
  
  the path to another img
  
  outName
  
  the path where the image will be saved
  
  callback
  
  A function to be executed when morphing is complete. callback will be passed the standard args that .write() receives.
```
gm("img.png").morph(otherImg, outName, callback)
```
- mosaic
  See the docs for detail.
```
gm("img.png").mosaic()
```
- motionBlur
  See the docs for detail.
```
gm("img.png").motionBlur(radius [, sigma, angle])
```
- name
  See the docs for detail.
```
gm("img.png").name()
```
- negative
  Replaces every pixel with its complementary color.
```
gm("img.png").negative()
```
- noise
  Add or reduce noise in the image.
  radius|type
  To add noise pass one of the following:
  - uniform
  - gaussian
  - multiplicative
  - impulse
  - laplacian
  - poisson
  Otherwise the argument will be interpreted as a radius which adjusts the weight of the effect.
```
gm("img.png").noise(radius|type)
```
- noop
  See the docs for detail.
```
gm("img.png").noop()
```
- normalize
  See the docs for detail.
```
gm("img.png").normalize()
```
- opaque
  See the docs for detail.
```
gm("img.png").opaque(color)
```
- operator
  See the docs for detail.
```
gm("img.png").operator(channel, operator, rvalue [,percent])
```
- orderedDither
  See the docs for detail.
```
gm("img.png").orderedDither(channelType, NxN)
```
- outputDirectory
  See the docs for detail.
```
gm("img.png").outputDirectory(channelType, NxN)
```
- page
  See the docs for detail.
```
gm("img.png").page(width, height [,arg])
```
- pause
  See the docs for detail.
```
gm("img.png").pause(seconds)
```
- pen
  See the docs for detail.
```
gm("img.png").pen(color)
```
- ping
  See the docs for detail.
```
gm("img.png").ping()
```
- pointSize
  See the docs for detail.
```
gm("img.png").pointSize(value)
```
- noProfile
  Removes EXIF, ICM, etc profile data.
```
gm("img.png").noProfile()
```
- preview
  
  type
  
  See the docs for valid types.
```
gm("img.png").preview(type)
```
- paint
  Simulates an oil painting.
```
gm("img.png").paint(radius)
```
- process
  See the docs for detail.
```
gm("img.png").process(command)
```
- profile
  See the docs for detail.
```
gm("img.png").profile(filename)
```
- progress
  See the docs for detail.
```
gm("img.png").progress()
```
- randomThreshold
  See the docs for detail.
```
gm("img.png").randomThreshold(channelType, LOWxHIGH)
```
- quality
  Adjusts the jpeg|miff|png|tiff compression level. val ranges from 0 to 100 (best).
```
gm("img.png").quality(val)
```
- raise
  Creates a pseudo 3D raising effect of the images edges.
```
gm("img.png").raise(width, height)
```
- recolor
  See the docs for detail.
```
gm("img.png").recolor(matrix)
```
- redPrimary
  See the docs for detail.
```
gm("img.png").redPrimary(x, y)
```
- region
  Specifies that all following methods only apply to the area specified by width, height, x, y.
```
gm("img.png").region(width, height, x, y).sepia()
```
  In this case, the sepia effect would only be applied within the area specified by width, height, x, y.
- remote
  See the docs for detail.
```
gm("img.png").remote()
```
- render
  See the docs for detail.
```
gm("img.png").render()
```
- repage
  See the docs for detail.
```
gm("img.png").repage(width, height, xoff, yoff, arg)
```
- sample
  See the docs for detail.
```
gm("img.png").sample(geometry)
```
- samplingFactor
  See the docs for detail.
```
gm("img.png").samplingFactor(horizontalFactor, verticalFactor)
```
- rawSize
  See the docs for detail.
```
gm("img.png").rawSize(width, height, offset)
```
- resample
  Resamples the image to specified horizontal and vertical resolution.
```
gm("img.png").resample(horizontal, vertical)
```
- resize
  Resize the image.
  
  options
  
  %, @, !, < or > see the GraphicsMagick docs for details
```
gm("img.png").resize(width [, height [, options]])
```
  To resize an image to a width of 40px while maintaining aspect ratio: gm("img.png").resize(40)
  
  To resize an image to a height of 50px while maintaining aspect ratio: gm("img.png").resize(null, 50)
  
  To resize an image to a fit a 40x50 rectangle while maintaining aspect ratio: gm("img.png").resize(40, 50)
  
  To override the image's proportions and force a resize to 40x50: gm("img.png").resize(40, 50, "!")
- roll
  Rolls an image vertically or horizontally.
```
gm("img.png").roll(horizontalInt, verticalInt)
```
- rotate
  Rotates the image by degrees and fills the background with color.
```
gm("img.png").rotate(color, degrees)
```
- scene
  See the docs for detail.
```
gm("img.png").scene(value)
```
- scenes
  See the docs for detail.
```
gm("img.png").scenes(start, end)
```
- scale
  Scales the image.
```
gm("img.png").scale(width, height)
```
- screen
  See the docs for detail.
```
gm("img.png").screen()
```
- segment
  See the docs for detail.
```
gm("img.png").segment(clusterThreshold, smoothingThreshold)
```
- selectFrame
  Helpful if we process a large .gif so we don't load in memory each frame.
```
gm("img.png").selectFrame(0)
```
- sepia
  A convenience method to apply a sepia effect to the image.
```
gm("img.png").sepia()
```
- set
  See the docs for detail.
```
gm("img.png").set(attribute, value)
```
- setFormat
  Overriddes the output image format.
  
  Helpful if we are outputting an image with no extention but need to change formats.
```
gm("img.png").setFormat(format)
```
- shade
  See the docs for detail.
```
gm("img.png").shade(azimuth, elevation)
```
- shadow
  See the docs for detail.
```
gm("img.png").shadow(radius, sigma)
```
- sharedMemory
  See the docs for detail.
```
gm("img.png").sharedMemory()
```
- shave
  See the docs for detail.
```
gm("img.png").shave(width, height, percent)
```
- sharpen
  Sharpens the image.
```
gm("img.png").sharpen(radius [, sigma])
```
- shear
  See the docs for detail.
```
gm("img.png").shear(xDegrees, yDegrees)
```
- silent
  See the docs for detail.
```
gm("img.png").silent()
```
- snaps
  See the docs for detail.
```
gm("img.png").snaps(value)
```
- solarize
  Negates all pixels above threshold percent.
```
gm("img.png").solarize(threshold)
```
- spread
  Desplaces pixels by a random amount.
```
gm("img.png").spread(amount)
```
- stegano
  See the docs for detail.
```
gm("img.png").stegano(offset)
```
- stereo
  See the docs for detail.
```
gm("img.png").stereo()
```
- strip
  Strips the image of any profiles or comments.
  
  Similar to noProfile() but removes both profile and comment data. only works with imageMagick.
```
gm("img.png").strip()
```
- swirl
  Swirls pixels arount the center of the image. degrees specifies the tightness of the swirl.
```
gm("img.png").swirl(degrees)
```
- textFont
  See the docs for detail.
```
gm("img.png").textFont(font)
```
- texture
  See the docs for detail.
```
gm("img.png").texture(font)
```
- threshold
  See the docs for detail.
```
gm("img.png").threshold(value [, percent])
```
- thumb
  Creates a thumbnail based on minimum sizes.
  
  width
  
  the minimum width of the thumbnail
  
  height
  
  the minimum height of the thumbnail
  
  outName
  
  the path where the image will be saved
  
  quality
  
  Adjusts the image compression level. Ranges from 0 to 100 (best).
  
  callback
  
  called after the thumbnail is written. receives the same args that .write(err, stdout, stderr, command) receives.
```
gm("img.png").thumb(width, height, outName, quality, callback)
```
- tile
  See the docs for detail.
```
gm("img.png").tile(filename)
```
- title
  See the docs for detail.
```
gm("img.png").title(string)
```
- transform
  See the docs for detail.
```
gm("img.png").transform(color)
```
- transparent
  See the docs for detail.
```
gm("img.png").transparent(color)
```
- treeDepth
  See the docs for detail.
```
gm("img.png").treeDepth(color)
```
- trim
  Trim an image by removing any edges that are exactly the same color as the corner pixels.
```
gm("img.png").trim()
```
- type
  Specifies the image type.
  type
  Can be one of the following:
  - Bilevel
  - Grayscale
  - Palette
  - PaletteMatte
  - TrueColor
  - TrueColorMatte
  - ColorSeparation
  - ColorSeparationMatte
  - Optimize
```
gm("img.png").type(type)
```
- update
  See the docs for detail.
```
gm("img.png").update(seconds)
```
- units
  See the docs for detail.
```
gm("img.png").units(type)
```
- unsharp
  See the docs for detail.
```
gm("img.png").unsharp(radius [, sigma, amount, threshold])
```
- usePixmap
  See the docs for detail.
```
gm("img.png").usePixmap()
```
- view
  See the docs for detail.
```
gm("img.png").view()
```
- virtualPixel
  See the docs for detail.
```
gm("img.png").virtualPixel(method)
```
- visual
  See the docs for detail.
```
gm("img.png").visual(type)
```
- watermark
  See the docs for detail.
```
gm("img.png").watermark(brightness, saturation)
```
- wave
  See the docs for detail.
```
gm("img.png").wave(amplitude, wavelength)
```
- whitePoint
  See the docs for detail.
```
gm("img.png").whitePoint(x, y)
```
- whiteThreshold
  See the docs for detail.
```
gm("img.png").whiteThreshold(red, green, blue, opacity)
```
- window
  See the docs for detail.
```
gm("img.png").window(id)
```
- windowGroup
  See the docs for detail.
```
gm("img.png").windowGroup()
```
getters

All getters have the same signature:
```
gm("image.png").size(function(err, value){
  // note : value may be undefined
})
```
- size - returns the size (WxH) of the image
- format - returns the image format (gif, jpeg, png, etc)
- depth - returns the image color depth
- color - returns the number of colors
- res - returns the image resolution
- filesize - returns image filesize
- identify - returns all image data available
- orientation - returns the EXIF orientation of the image
Drawing Primitives

Take a look at drawing.js for examples.
- draw
  Annotate an image with one or more graphic primitives (shapes, text, transformations, pixel operations). Used internally for all drawing methods.
```
gm("img.png").draw(args)
```
- drawArc
  Inscribe an elliptical arc within a rectangle. Requires a start and end point as well as the degrees of rotation.
```
gm("img.png").drawArc(x0, y0, x1, y1, r0, r1)
```
- drawBezier
  Draw a Bezier curve.
```
gm("img.png").drawBezier([x0, y0], ... [xn, yn])
```
- drawCircle
  Draws a Circle.
```
gm("img.png").drawCircle(x0, y0, x1, y1)
```
- drawEllipse
  Draws an Ellipse.
```
gm("img.png").drawEllipse(x0, y0, r0, ry, r0, r1)
```
- drawLine
  Draws a Line.
```
gm("img.png").drawLine(x0, y0, x1, y1)
```
- drawPoint
  Draws a Point.
```
gm("img.png").drawPoint(x, y)
```
- drawPolygon
  Draws a Polygon.
```
gm("img.png").drawPolygon([x0, y0] ... [xn, yn])
```
- drawPolyline
  Draws a Polyline.
```
gm("img.png").drawPolyline([x0, y0] ... [xn, yn])
```
- drawRectangle
  Draws a Rectangle. wc and hc are optional and add roundness to the corners.
```
gm("img.png").drawRectangle(x0, y0, x1, y1 [, wc, hc])
```
- drawText
  Draws text on an image at x/y coordinates.
```
gm("img.png").drawText(x, y, text [, gravity])
```
- fill
  Specifies the color to use when filling a drawn shape.
```
gm("img.png").fill(color)
```
- font
  Specifies the font to use when you drawText.
```
gm("img.png").font(name)
```
- fontSize
  Specifies the font size to use when you drawText.
```
gm("img.png").fontSize(size)
```
- stroke
  Specifies the color to use when stroking a drawn shape.
```
gm("img.png").stroke(color [, width])
```
- strokeWidth
  Specifies the stroke width to use when stroking a drawn shape.
```
gm("img.png").strokeWidth(width)
```
- setDraw
  Sets drawing properties. property can be either "color" or "matte".
```
gm("img.png").setDraw(property, x, y, method)
```
Image comparisons

Both GraphicsMagick and ImageMagick support image comparisons which are exposed through gm.compare().

Currently both path1 and path2 must be strings (no Buffers or Streams). Optionally pass a custom tolerance level if 0.4 (the default) is too lax for your use case.

Your callback will be passed four arguments:
```
gm.compare(path1, path2, function (err, isEqual, equality, raw) {
  if (err) throw err;
  console.log('The images are equal: %s', isEqual);
  console.log('Actual equality: %d', equality)
  console.log('Raw output was: %j', raw);
});
```
You can also output a diff image of the two images by passing a configuration object in place of the tolerance:
```
var options = {
  highlightColor: 'yellow', // optional. Defaults to red
  file: './diff.png' // required
};
gm.compare(path1, path2, options, function (err) {
  if (err) throw err;
});
```
Using ImageMagick

We have compatibility with ImageMagick too. Just subclass the gm constructor passing the imageMagick option.
```
var imageMagick = gm.subClass({ imageMagick: true });
```
Then use imageMagick the same way you'd normally use gm.
```
imageMagick("img.png").autoOrient().write('/path', callback);
```
ImageMagick Options

Unlike GraphicsMagick, ImageMagick supports the WebP format. However, you must compile ImageMagick with the WebP option. To do so on OS X, install ImageMagick with the following command using Homebrew:
```
brew install imagemagick --with-webp
```
If you have already installed ImageMagick, you would have to uninstall it then reinstall it.

gm v1.9.0 GraphicsMagick for node.js

manipulation

getters

Drawing Primitives

Image comparisons

Using ImageMagick

ImageMagick Options