JavaScript API¶

Application¶

Top-level methods available from the global acorn object.

`acorn.currentDocument()`¶

Grab the frontmost Acorn document.

Returns: Document The current document, or null if there are no Acorn documents.

var doc = acorn.currentDocument();
if (doc) {
    print(doc.canvasSize().width + "x" + doc.canvasSize().height);
}

`acorn.setPreference_forKey(value, key)`¶

Sets a preference for given name. (defaults read com.flyingmeat.Acorn8 to find out what you’ve already changed)

Parameter	Type	Description
`value`	`id`	The value of the preference (NSNumber, String)
`key`	`String`	The preference name

acorn.setPreference_forKey(false, "drawMarchingAntsSelection");

`acorn.takeLayeredScreenshot()`¶

Takes a layered screenshot of all displays and returns a document for each display.

var documents = acorn.takeLayeredScreenshot();
for (var docIndex = 0; docIndex < documents.count(); docIndex++) {
    var doc = documents[docIndex];
    for (var layerIndex = 0; layerIndex < doc.layers().count(); layerIndex++) {
        print(doc.layers()[layerIndex].layerName());
    }
}

`acorn.toolPalette()`¶

Returns the tool palette for the current document, an ACToolPalette object.

var palette = acorn.toolPalette();
print(palette.frontColor());

Bitmap Layer¶

Bitmap layers are an extension of the Layer object and contain raster (bitmap) data.

`bitmapLayer.applyCIFilterNamed_withParameters(name, parameters)`¶

Applies a Core Image filter directly to the bitmap layer pixels. See also layer.appendFilterWithName. Visit cifilter.app for a nice resource on the various filters you can use.

Parameter	Type	Description
`name`	`String`	The Core Image filter name.
`parameters`	`Object`	Filter input values keyed by Core Image input name.

var layer = acorn.currentDocument().currentLayer();
layer.applyCIFilterNamed_withParameters("CIBoxBlur", {inputRadius: 40});

`bitmapLayer.applyCIImageFromFilter(image)`¶

Replaces the bitmap layer contents with a CIImage.

Parameter	Type	Description
`image`	`CIImage`	Image to apply to the layer.

var layer = acorn.currentDocument().currentLayer();
var image = layer.CIImage();
var filter = CIFilter.colorPosterizeFilter()
filter.inputImage = image;
filter.levels = 6;
var filteredImage = filter.outputImage();
layer.applyCIImageFromFilter(filteredImage);

`bitmapLayer.applyCIImageFromFilter_shouldClipToSelection(image, clipToSelection)`¶

Applies a CIImage to the bitmap layer, optionally clipping the change to the active selection.

Parameter	Type	Description
`image`	`CIImage`	Image to apply to the layer.
`clipToSelection`	`Boolean`	True to restrict the result to the selection.

var layer = acorn.currentDocument().currentLayer();
var image = layer.CIImage();
var filter = CIFilter.gaussianBlurFilter();
filter.inputImage = image;
filter.radius = 20;
layer.applyCIImageFromFilter_shouldClipToSelection(filter.outputImage(), true);

`bitmapLayer.colorAtPoint(point)`¶

Returns the color of the bitmap layer at a canvas point.

Parameter	Type	Description
`point`	`NSPoint`	Point in canvas coordinates.

Returns: NSColor The sampled color.

var layer = acorn.currentDocument().currentLayer();
var color = layer.colorAtPoint(NSMakePoint(10, 10));
print(color);

`bitmapLayer.fillWithColor_shouldClipToSelection(color, clipToSelection)`¶

Fills the bitmap layer, or the active selection, with a color.

Parameter	Type	Description
`color`	`NSColor`	Fill color.
`clipToSelection`	`Boolean`	True to restrict the fill to the active selection.

var layer = acorn.currentDocument().currentLayer();
layer.fillWithColor_shouldClipToSelection(NSColor.redColor(), true);

`bitmapLayer.floodFillAtPoint(point)`¶

Performs a flood fill on the bitmap layer at the given layer point.

Parameter	Type	Description
`point`	`NSPoint`	Point in layer coordinates.

var layer = acorn.currentDocument().currentLayer();
layer.floodFillAtPoint(NSMakePoint(25, 25));

`bitmapLayer.frame()`¶

Returns the bitmap layer frame in canvas coordinates.

Returns: NSRect The layer frame.

var layer = acorn.currentDocument().currentLayer();
print(NSStringFromRect(layer.frame()));

`bitmapLayer.frameOrigin()`¶

Returns the bitmap layer frame origin.

Returns: NSPoint The frame origin.

var layer = acorn.currentDocument().currentLayer();
print(NSStringFromPoint(layer.frameOrigin()));

`bitmapLayer.setFrameOrigin(point)`¶

Moves the bitmap layer frame origin.

Parameter	Type	Description
`point`	`NSPoint`	New frame origin.

var layer = acorn.currentDocument().currentLayer();
layer.setFrameOrigin(NSMakePoint(20, 20));

Document¶

A document is a general container for the whole image and allows access to varous IO routies, as well as the base group which holds layers.

`document.autoLevels()`¶

Adds a Levels filter to the current layer, and balances the levels automatically

var doc = acorn.currentDocument();
doc.autoLevels();

// or target a specific layer:
doc.undo();
var layer = doc.layers()[1];
layer.autoLevels()

`document.beginCroppingWithRect(rect)`¶

Starts an interactive crop operation with the given bounds.

Parameter	Type	Description
`rect`	`NSRect`	The crop rectangle in canvas coordinates.

 var doc = acorn.currentDocument();
 doc.beginCroppingWithRect(NSMakeRect(100, 100, 400, 300));

`document.bitsPerComponent()`¶

Returns the number of bits per color component.

Returns: Number 8, 16, or 32.

print(acorn.currentDocument().bitsPerComponent());

`document.bitsPerPixel()`¶

Returns the number of bits per pixel.

Returns: Number 32, 64, or 128.

print(acorn.currentDocument().bitsPerPixel());

`document.callFilterNamed(filterOrPlugin)`¶

Invokes a filter / plugin via the given string

Parameter	Type	Description
`filterOrPlugin`	`String`	The filter or plugin name

var doc = acorn.currentDocument();
doc.callFilterNamed("CIColorInvert");
doc.callFilterNamed("New Image With Curved Drop Shadow");

`document.canvasSize()`¶

Returns the size of the image.

Returns: NSSize The image size.

 var size = acorn.currentDocument().canvasSize();
 print(size.width + "x" + size.height);

`document.CIImage()`¶

Returns a Core Image composite of the document's visible layers.

Returns: CIImage The composited image.

 var doc = acorn.currentDocument();
 var image = doc.CIImage();
 print(image);

`document.colorSpace()`¶

Returns the document CGColorSpace.

Returns: CGColorSpaceRef The document color space.

var colorSpace = acorn.currentDocument().colorSpace();
print(colorSpace);

`document.copyMerged()`¶

Writes a composite of the image to the clipboard.

var doc = acorn.currentDocument();
doc.copyMerged();

`document.cropToRect(rect)`¶

Crops the document to the given rectangle.

Parameter	Type	Description
`rect`	`NSRect`	The crop rectangle in canvas coordinates.

var doc = acorn.currentDocument();
doc.cropToRect(NSMakeRect(100, 100, 400, 400));

`document.currentLayer()`¶

Returns the document's selected layer.

Returns: Layer The current layer.

var layer = acorn.currentDocument().currentLayer();
print(layer.layerName());

`document.DPI()`¶

Returns the document resolution in dots per inch.

Returns: double The document DPI.

 var dpi = acorn.currentDocument().DPI();
 print(dpi);

`document.duplicate()`¶

Duplicates the image

Returns: Document a copy of the invoked image.

var doc = acorn.currentDocument();
var newDoc = doc.duplicate();

`document.firstLayerWithName(layerName)`¶

Returns the first layer in the document with the given name.

Parameter	Type	Description
`layerName`	`String`	The layer name to find.

Returns: Layer The matching layer, or null if no layer matches.

var layer = acorn.currentDocument().firstLayerWithName("Background");
if (layer) {
    layer.setVisible(false);
}

`document.flipCanvasWithDirection(direction)`¶

Flips the canvas in the given direction.

Parameter	Type	Description
`direction`	`String`	either "vertical" or "horizontal"

var doc = acorn.currentDocument();
 doc.flipCanvasWithDirection("vertical");

`document.invertSelection()`¶

Inverts the current selection

var doc = acorn.currentDocument();
doc.selectFrame(NSMakeRect(100, 100, 400, 400));
doc.invertSelection();

`document.layers()`¶

Returns the document's top-level layers.

Returns: NSArray The top-level layers.

 var doc = acorn.currentDocument();
 for (var i = 0; i < doc.layers().count(); i++) {
 print(doc.layers()[i].layerName());
 }

`document.newCGImage()`¶

Creates a new CGImage containing the current composited document image.

Returns: CGImageRef A retained CGImage for the document composite.

 var doc = acorn.currentDocument();
 var image = doc.newCGImage();
 print(image);

`document.newLayerWithNSImage(image)`¶

Adds a new bitmap layer from an NSImage.

Parameter	Type	Description
`image`	`NSImage`	The image to place in the new layer.

 var image = NSImage.alloc().initWithContentsOfFile("/tmp/source.png");
 acorn.currentDocument().newLayerWithNSImage(image);

`document.replaceOccurrencesOfString_withString(target, replacement)`¶

Replaces matching text in the document's text shapes.

Parameter	Type	Description
`target`	`String`	The text to find.
`replacement`	`String`	The replacement text.

var doc = acorn.currentDocument();
doc.replaceOccurrencesOfString_withString("Draft", "Final");

`document.resizeImageToSize(size)`¶

Resizes the document canvas to the given size without scaling layer contents.

Parameter	Type	Description
`size`	`NSSize`	The new canvas size.

acorn.currentDocument().resizeImageToSize(NSMakeSize(1000, 1000));

`document.scaleCanvasToSize(size)`¶

Scales the canvas and all layers to the given size.

Parameter	Type	Description
`size`	`NSSize`	The new image size.

 var doc = acorn.currentDocument();
 doc.scaleCanvasToSize(NSMakeSize(800, 600));

`document.scaleImageToHeight(height)`¶

Scales the image proportionally to the given height.

Parameter	Type	Description
`height`	`Number`	The target height in pixels.

acorn.currentDocument().scaleImageToHeight(900);

`document.scaleImageToSize(size)`¶

Scales the image and all layers to the given size.

Parameter	Type	Description
`size`	`NSSize`	The new image size.

acorn.currentDocument().scaleImageToSize(NSMakeSize(1000, 1000));

`document.scaleImageToWidth(width)`¶

Scales the image proportionally to the given width.

Parameter	Type	Description
`width`	`Number`	The target width in pixels.

acorn.currentDocument().scaleImageToWidth(1600);

`document.scaleImageWithPercentage(scale)`¶

Scales the image by a multiplier.

Parameter	Type	Description
`scale`	`Number`	Scale multiplier, where 0.5 is 50 percent and 2.0 is 200 percent.

acorn.currentDocument().scaleImageWithPercentage(0.5);

`document.selectFrame(frame)`¶

Adds a rectangular selection to the image

Parameter	Type	Description
`frame`	`NSRect`	The selection bounds

var doc = acorn.currentDocument();
doc.selectFrame(NSMakeRect(100, 100, 400, 400));
doc.invertSelection();

`document.setBitsPerPixel(bitsPerPixel)`¶

Sets the document bit depth. Valid values are 32, 64, and 128.

Parameter	Type	Description
`bitsPerPixel`	`Number`	The target bits per pixel.

acorn.currentDocument().setBitsPerPixel(64);

`document.setCanvasSize(size)`¶

Changes the canvas size without scaling layer contents, anchored at the lower-left corner.

Parameter	Type	Description
`size`	`NSSize`	The new canvas size.

 var doc = acorn.currentDocument();
 doc.setCanvasSize(NSMakeSize(1200, 800));

`document.setCanvasSize_usingAnchor(size, anchor)`¶

Changes the canvas size without scaling layer contents, with an argument to anchor the existing image to a corner.

Parameter	Type	Description
`size`	`NSSize`	The new canvas size.
`anchor`	`NSString`	The area to anchor to. Valid values are "bottom center", "bottom left", "bottom right", "middle center", "middle left", "middle right", "top center", "top left", "top right"

var doc = acorn.currentDocument();
doc.setCanvasSize_usingAnchor(NSMakeSize(1000, 1000), "top left");

`document.setDPI(dpi)`¶

Sets the document resolution in dots per inch.

Parameter	Type	Description
`dpi`	`double`	The new document DPI.

 acorn.currentDocument().setDPI(144);

`document.setSelectedLayer(layer)`¶

Sets the actively selected layer.

Parameter	Type	Description
`layer`	`Layer`	The layer to select

var doc = acorn.currentDocument();
var bitmapLayer = doc.baseGroup().addBitmapLayer();
doc.setSelectedLayer(bitmapLayer);

`document.trim()`¶

Trims the edge colors out of the image.

var doc = acorn.currentDocument();
doc.trim();

`document.writeToFile_withUTI(path, uti)`¶

Writes the document to a file using the given Uniform Type Identifier.

Parameter	Type	Description
`path`	`String`	Destination file path.
`uti`	`String`	Uniform Type Identifier for the output format.

Returns: Boolean True when the write succeeds.

var doc = acorn.currentDocument();
doc.writeToFile_withUTI("/tmp/export.png", "public.png");

Graphics¶

`bezierAnchor.hasLeftSegment()`¶

Returns whether the anchor has a segment to its left.

Returns: Boolean True when a left segment exists.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(anchor.hasLeftSegment());

`bezierAnchor.hasRightSegment()`¶

Returns whether the anchor has a segment to its right.

Returns: Boolean True when a right segment exists.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(anchor.hasRightSegment());

`bezierAnchor.leftCP()`¶

Returns the left control point for the anchor.

Returns: NSPoint The left control point.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(NSStringFromPoint(anchor.leftCP()));

`bezierAnchor.leftSegmentType()`¶

Returns the NSBezierPathElement type for the segment to the left of the anchor.

Returns: Number The segment type.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(anchor.leftSegmentType());

`bezierAnchor.location()`¶

Returns the anchor location.

Returns: NSPoint The anchor location.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
var anchor = path.anchors()[0];
print(NSStringFromPoint(anchor.location()));

`bezierAnchor.rightCP()`¶

Returns the right control point for the anchor.

Returns: NSPoint The right control point.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(NSStringFromPoint(anchor.rightCP()));

`bezierAnchor.rightSegmentType()`¶

Returns the NSBezierPathElement type for the segment to the right of the anchor.

Returns: Number The segment type.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
print(anchor.rightSegmentType());

`bezierAnchor.setLeftCP(point)`¶

Sets the left control point for the anchor.

Parameter	Type	Description
`point`	`NSPoint`	The new left control point.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
anchor.setLeftCP(NSMakePoint(25, 50));

`bezierAnchor.setLeftSegmentType(type)`¶

Sets the NSBezierPathElement type for the segment to the left of the anchor.

Parameter	Type	Description
`type`	`Number`	The segment type.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
anchor.setLeftSegmentType(NSBezierPathElementLineTo);

`bezierAnchor.setLocation(point)`¶

Moves the anchor to a new location.

Parameter	Type	Description
`point`	`NSPoint`	The new anchor location.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
path.anchors()[0].setLocation(NSMakePoint(50, 50));

`bezierAnchor.setRightCP(point)`¶

Sets the right control point for the anchor.

Parameter	Type	Description
`point`	`NSPoint`	The new right control point.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
anchor.setRightCP(NSMakePoint(75, 50));

`bezierAnchor.setRightSegmentType(type)`¶

Sets the NSBezierPathElement type for the segment to the right of the anchor.

Parameter	Type	Description
`type`	`Number`	The segment type.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
anchor.setRightSegmentType(NSBezierPathElementLineTo);

`bezierAnchor.translateBy(delta)`¶

Moves the anchor and its control points by a delta.

Parameter	Type	Description
`delta`	`NSPoint`	Translation delta.

var anchor = acorn.currentDocument().currentLayer().graphics()[0].path().anchors()[0];
anchor.translateBy(NSMakePoint(10, 0));

`bezierGraphic.ACBezierPath()`¶

Returns the Acorn Bezier path for a Bezier graphic.

Returns: BezierPath The graphic's Bezier path.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
print(bezier.ACBezierPath().anchorCount());

`bezierGraphic.movePointAtIndex_toPoint(index, point)`¶

Moves a Bezier path point to a new location.

Parameter	Type	Description
`index`	`Number`	Point index.
`point`	`NSPoint`	New point location.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
bezier.movePointAtIndex_toPoint(0, NSMakePoint(50, 50));

`bezierGraphic.path()`¶

Returns the Bezier path for a Bezier graphic.

Returns: BezierPath The graphic's Bezier path.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
print(bezier.path().anchorCount());

`bezierGraphic.pointOfElementAtIndex(index)`¶

Returns the point for a Bezier path element.

Parameter	Type	Description
`index`	`Number`	Element index.

Returns: NSPoint The element point.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
print(NSStringFromPoint(bezier.pointOfElementAtIndex(0)));

`bezierGraphic.setACBezierPath(path)`¶

Replaces a Bezier graphic's Acorn Bezier path.

Parameter	Type	Description
`path`	`BezierPath`	The replacement path.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
var path = bezier.ACBezierPath();
bezier.setACBezierPath(path);

`bezierGraphic.setPath(path)`¶

Replaces the Bezier path for a Bezier graphic.

Parameter	Type	Description
`path`	`BezierPath`	The replacement path.

var bezier = acorn.currentDocument().currentLayer().graphics()[0];
var path = bezier.path();
bezier.setPath(path);

`bezierPath.anchorAtIndex(index)`¶

Returns the anchor at the given index.

Parameter	Type	Description
`index`	`Number`	Anchor index.

Returns: BezierAnchor The anchor object.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
var anchor = path.anchorAtIndex(0);
print(NSStringFromPoint(anchor.location()));

`bezierPath.anchorCount()`¶

Returns the number of anchors in the Bezier path.

Returns: Number The anchor count.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
print(path.anchorCount());

`bezierPath.anchors()`¶

Returns the anchors in the Bezier path.

Returns: NSArray The path anchors.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
for (var i = 0; i < path.anchors().count(); i++) {
    print(NSStringFromPoint(path.anchors()[i].location()));
}

`bezierPath.locationForAnchorAtIndex(index)`¶

Returns the location for an anchor at the given index.

Parameter	Type	Description
`index`	`Number`	Anchor index.

Returns: NSPoint The anchor location.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
print(NSStringFromPoint(path.locationForAnchorAtIndex(0)));

`bezierPath.resetAnchors()`¶

Converts curve anchors to straight line anchors by resetting their control points.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
path.resetAnchors();

`bezierPath.setLocation_forAnchorAtIndex(point, index)`¶

Moves the anchor at the given index to a new location.

Parameter	Type	Description
`point`	`NSPoint`	New anchor location.
`index`	`Number`	Anchor index.

var path = acorn.currentDocument().currentLayer().graphics()[0].path();
path.setLocation_forAnchorAtIndex(NSMakePoint(50, 50), 0);

`graphic.bezierPath()`¶

Returns the graphic as an NSBezierPath.

Returns: NSBezierPath The graphic path.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
var path = graphic.bezierPath();
print(path.bounds());

`graphic.bounds()`¶

Returns the graphic bounds.

Returns: NSRect The graphic bounds.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(NSStringFromRect(graphic.bounds()));

`graphic.drawsFill`¶

Gets or sets whether the graphic draws its fill.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(graphic.drawsFill());
graphic.setDrawsFill(true);

`graphic.fillColor()`¶

Returns the graphic fill color.

Returns: NSColor The fill color.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(graphic.fillColor());

`graphic.scaleXBy_yBy(xScale, yScale)`¶

Scales a graphic's bounds, stroke, and shadow by the given multipliers.

Parameter	Type	Description
`xScale`	`Number`	Horizontal scale multiplier.
`yScale`	`Number`	Vertical scale multiplier.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
graphic.scaleXBy_yBy(2.0, 2.0);

`graphic.setFillColor(color)`¶

Sets the graphic fill color.

Parameter	Type	Description
`color`	`NSColor`	The new fill color.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
graphic.setFillColor(NSColor.redColor());

`graphic.setStrokeColor(color)`¶

Sets the graphic stroke color.

Parameter	Type	Description
`color`	`NSColor`	The new stroke color.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
graphic.setStrokeColor(NSColor.blueColor());

`graphic.setStrokeLineWidth(width)`¶

Alias for graphic.setStrokeWidth.

Parameter	Type	Description
`width`	`Number`	The new stroke width.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
graphic.setStrokeLineWidth(4);

`graphic.setStrokeWidth(width)`¶

Sets the graphic stroke width.

Parameter	Type	Description
`width`	`Number`	The new stroke width.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
graphic.setStrokeWidth(4);

`graphic.setTextStroke(width)`¶

Sets the text stroke width for a text graphic.

Parameter	Type	Description
`width`	`Number`	The new text stroke width.

var text = acorn.currentDocument().currentLayer().graphics()[0];
text.setTextStroke(2);

`graphic.strokeColor()`¶

Returns the graphic stroke color.

Returns: NSColor The stroke color.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(graphic.strokeColor());

`graphic.strokeLineWidth()`¶

Alias for graphic.strokeWidth.

Returns: Number The stroke width.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(graphic.strokeLineWidth());

`graphic.strokeWidth()`¶

Returns the graphic stroke width.

Returns: Number The stroke width.

var graphic = acorn.currentDocument().currentLayer().graphics()[0];
print(graphic.strokeWidth());

`graphic.textFillColor()`¶

Returns the text fill color for a text graphic.

Returns: NSColor The text fill color.

var text = acorn.currentDocument().currentLayer().graphics()[0];
print(text.textFillColor());

`graphic.textStrokeColor()`¶

Returns the text stroke color for a text graphic.

Returns: NSColor The text stroke color.

var text = acorn.currentDocument().currentLayer().graphics()[0];
print(text.textStrokeColor());

`polygonGraphic.scaleXBy_yBy(xScale, yScale)`¶

Scales a polygon graphic by the given multipliers.

Parameter	Type	Description
`xScale`	`Number`	Horizontal scale multiplier.
`yScale`	`Number`	Vertical scale multiplier.

var polygon = acorn.currentDocument().currentLayer().graphics()[0];
polygon.scaleXBy_yBy(1.5, 1.5);

`starGraphic.scaleXBy_yBy(xScale, yScale)`¶

Scales a star graphic by the given multipliers.

Parameter	Type	Description
`xScale`	`Number`	Horizontal scale multiplier.
`yScale`	`Number`	Vertical scale multiplier.

var star = acorn.currentDocument().currentLayer().graphics()[0];
star.scaleXBy_yBy(1.5, 1.5);

`textGraphic.setHTMLString(html)`¶

Replaces a text graphic's contents with HTML.

Parameter	Type	Description
`html`	`String`	HTML string to use as text contents.

var text = acorn.currentDocument().currentLayer().graphics()[0];
text.setHTMLString("<b>Hello</b> from JavaScript");

`textGraphic.setString(string)`¶

Replaces a text graphic's plain string contents.

Parameter	Type	Description
`string`	`String`	New text contents.

var text = acorn.currentDocument().currentLayer().graphics()[0];
text.setString("Hello from JavaScript");

Group Layer¶

A group layer contains zero or more sub-layers, as well as possibly containing additional group layers which can contain their own layers. Group layer extends Layer.

`groupLayer.addBitmapLayer()`¶

Adds a new bitmap layer to the group.

Returns: BitmapLayer The new bitmap layer.

var bitmapLayer = acorn.currentDocument().baseGroup().addBitmapLayer();
bitmapLayer.fillWithColor_shouldClipToSelection(NSColor.redColor(), false);

`groupLayer.addGroupLayer()`¶

Adds a new group layer to the group.

Returns: GroupLayer The new group layer.

var group = acorn.currentDocument().baseGroup().addGroupLayer();
group.setLayerName("Generated Group");

`groupLayer.addShapeLayer()`¶

Adds a new shape layer to the group.

Returns: ShapeLayer The new shape layer.

var shapeLayer = acorn.currentDocument().baseGroup().addShapeLayer();
shapeLayer.setLayerName("Generated Shapes");

`groupLayer.insertCGImage_atIndex_withName(image, index, layerName)`¶

Inserts a CGImage into the group as a bitmap layer.

Parameter	Type	Description
`image`	`CGImageRef`	Image to insert.
`index`	`Number`	Insertion index.
`layerName`	`String`	Name for the new layer.

Returns: BitmapLayer The inserted bitmap layer.

var doc = acorn.currentDocument();
var image = doc.newCGImage();
doc.baseGroup().insertCGImage_atIndex_withName(image, 0, "Composite Copy");

`groupLayer.insertCIImage_atIndex_withName(image, index, layerName)`¶

Inserts a CIImage into the group as a bitmap layer.

Parameter	Type	Description
`image`	`CIImage`	Image to insert.
`index`	`Number`	Insertion index.
`layerName`	`String`	Name for the new layer.

Returns: BitmapLayer The inserted bitmap layer.

var doc = acorn.currentDocument();

var filter = CIFilter.checkerboardGeneratorFilter();
filter.setDefaults();
filter.color0 = CIColor.redColor();
filter.color1 = CIColor.blueColor();
filter.width = 25;
filter.sharpness = 1.0;

var img = filter.outputImage();
var canvasSize = doc.canvasSize();
img = img.imageByCroppingToRect(CGRectMake(0, 0, canvasSize.width, canvasSize.height));

doc.baseGroup().insertCIImage_atIndex_withName(img, 1, "Checkerboard");

`groupLayer.insertImageWithPath_atIndex_withName(path, index, layerName)`¶

Inserts an image file into the group as a bitmap layer.

Parameter	Type	Description
`path`	`String`	Path to the image file.
`index`	`Number`	Insertion index.
`layerName`	`String`	Name for the new layer.

Returns: BitmapLayer The inserted bitmap layer.

var group = acorn.currentDocument().baseGroup();
var layer = group.insertImageWithPath_atIndex_withName("/tmp/source.png", 0, "Imported Image");
print(layer.layerName());

`document.insertLayerWithImagePath_atIndex(imagePath, index)`¶

Adds a new layer with the image from imagePath, and inserts it at the given index.

Parameter	Type	Description
`imagePath`	`String`	Path to the image file.
`index`	`Number`	Insertion index.

Returns: BitmapLayer The inserted bitmap layer.

var doc = acorn.open("/Volumes/srv/Users/gus/Pictures/MyImage.acorn");
var layer = doc.layers()[0];
doc.setSelectedLayer(layer);

// 0 puts it at the bottom. 1 or higher would put it on top..
var newLayer = doc.baseGroup().insertLayerWithImagePath_atIndex("/Volumes/srv/Users/gus/Pictures/AnotherImage.png", 3)

Layer¶

A base class that all layer types (bitmap, shape, and group) inherit from.

`layer.addMask()`¶

Adds a mask to the layer. If a selection exists, the mask is initialized from it.

var layer = acorn.currentDocument().currentLayer();
layer.addMask();

`layer.appendFilterWithName(name)`¶

Appends a Core Image filter to the layer's filter chain. This will also bring up the filter palette where you can change the various settings for this filter. Visit cifilter.app for a nice resource on the various filters you can use.

Parameter	Type	Description
`name`	`String`	The Core Image filter name.

var layer = acorn.currentDocument().currentLayer();
layer.appendFilterWithName("CIGaussianBlur");

`layer.appendFilterWithName_parameters(name, parameters)`¶

Appends a Core Image filter to the layer's filter chain and applies input parameters.

Parameter	Type	Description
`name`	`String`	The Core Image filter name.
`parameters`	`Object`	Filter input values keyed by Core Image input name.

var layer = acorn.currentDocument().currentLayer();
layer.appendFilterWithName_parameters("CIGaussianBlur", {inputRadius: 8});

`layer.autoLevels()`¶

Adds a Levels filter to the given layer, and balances the levels automatically

var doc = acorn.currentDocument();
var layer = doc.layers()[0];
layer.autoLevels()

`layer.bounds()`¶

Returns the layer bounds.

Returns: NSRect The layer bounds.

var layer = acorn.currentDocument().currentLayer();
print(NSStringFromRect(layer.bounds()));

`layer.compositingMode`¶

Gets or sets the layer compositing mode as a CGBlendMode value.

var layer = acorn.currentDocument().currentLayer();
print(layer.compositingMode());
layer.setCompositingMode(kCGBlendModeMultiply);

`layer.layerName`¶

Gets or sets the layer name.

var layer = acorn.currentDocument().currentLayer();
print(layer.layerName());
layer.setLayerName("Updated Layer Name");

`layer.layerType()`¶

Returns the layer type constant.

Returns: Number The layer type, such as ACBitmapLayer, ACShapeLayer, ACGroupLayer, or ACMaskLayer.

var layer = acorn.currentDocument().currentLayer();

if (layer.layerType() == ACBitmapLayer) {
  print("It’s a bitmap layer");
}
else if (layer.layerType() == ACShapeLayer) {
  print("It’s a shape layer");
}
else if (layer.layerType() == ACGroupLayer) {
  print("It’s a group layer");
}
else if (layer.layerType() == ACMaskLayer) {
  print("It’s a mask layer");
}

print(layer.layerType());

`layer.loadFilterPresetWithName(name)`¶

Loads a saved layer filter preset onto the layer.

Parameter	Type	Description
`name`	`String`	The filter preset name.

var layer = acorn.currentDocument().currentLayer();
layer.loadFilterPresetWithName("Checkered Brush");

`layer.mask()`¶

Returns the layer mask.

Returns: MaskLayer The mask layer, or null if the layer has no mask.

var mask = acorn.currentDocument().currentLayer().mask();
if (mask) {
    print(NSStringFromRect(mask.frame()));
}

`layer.maskIsLinked()`¶

Returns whether the layer mask moves with the layer. See also setMaskIsLinked

Returns: Boolean True when the mask is linked to the layer.

var layer = acorn.currentDocument().currentLayer();
print(layer.maskIsLinked());

`layer.opacity`¶

Gets or sets the layer opacity as a floating-point value from 0.0 to 1.0.

var layer = acorn.currentDocument().currentLayer();
print(layer.opacity());
layer.setOpacity(0.5);

`layer.opaqueFrame()`¶

Returns the layer's opaque bounds in canvas coordinates. You could use these bounds to trim the image, or start a crop.

Returns: NSRect The opaque layer frame.

var layer = acorn.currentDocument().currentLayer();
print(NSStringFromRect(layer.opaqueFrame()));

acorn.currentDocument().beginCroppingWithRect(layer.opaqueFrame());

`layer.renderedCIImage()`¶

Returns a Core Image rendering of the layer with opacity, filters, mask, and blending applied.

Returns: CIImage The rendered layer image.

var layer = acorn.currentDocument().currentLayer();
var image = layer.renderedCIImage();
print(image.extent());

`layer.setBlendMode(blendString)`¶

Changes the blend (composite) mode of the layer. Valid values are: "passThrough", "normal", "multiply", "screen", "overlay", "darken", "lighten", "colorDodge", "colorBurn", "softLight", "hardLight", "difference", "exclusion", "hue", "saturation", "color", "luminosity", "clear", "copy", "copyOpaqueOnly", "sourceIn", "sourceOut", "sourceAtop", "destinationOver", "destinationIn", "destinationOut", "destinationAtop", "xor", "plusDarker", "plusLighter", "divide", "linearBurn", "linearDodge", "lighterColor", "darkerColor", "subtract", "hardmix", "mask", "pinLight", "vividLight", "linearLight"

Parameter	Type	Description
`blendString`	`String`	A string representing the blend (composite) mode.

var layer = acorn.currentDocument().currentLayer();
layer.setBlendMode('linearDodge');

`layer.setLayerMaskImage(image)`¶

Sets the layer mask from a CIImage, creating a mask if needed.

Parameter	Type	Description
`image`	`CIImage`	The image to use for the mask.

var layer = acorn.currentDocument().currentLayer();
var maskImage = CIImage.imageWithContentsOfURL(NSURL.fileURLWithPath("/tmp/mask.png"));
layer.setLayerMaskImage(maskImage);

`layer.setLayerMaskWithImageAtPath(path)`¶

Sets the layer mask from an image file path, creating a mask if needed.

Parameter	Type	Description
`path`	`String`	Path to the mask image.

var layer = acorn.currentDocument().currentLayer();
layer.setLayerMaskWithImageAtPath("/tmp/mask.png");

`layer.setLayerMaskWithImageAtURL(url)`¶

Sets the layer mask from an image URL, creating a mask if needed.

Parameter	Type	Description
`url`	`NSURL`	URL for the mask image.

var layer = acorn.currentDocument().currentLayer();
var url = NSURL.fileURLWithPath("/tmp/mask.png");
layer.setLayerMaskWithImageAtURL(url);

`layer.setMaskIsLinked(linked)`¶

Sets whether the layer mask moves with the layer.

Parameter	Type	Description
`linked`	`Boolean`	True to link the mask to the layer.

var layer = acorn.currentDocument().currentLayer();
layer.setMaskIsLinked(false);

`layer.visible`¶

Gets or sets the visibility of a layer.

var doc = acorn.currentDocument();
var layer = doc.currentLayer();

// find the current visibility:
var v = layer.visible();
// toggle it
layer.setVisible(!v);

`layer.writeToFile_withUTI_properties(path, uti, dict)`¶

Writes the layer to a file using the given Uniform Type Identifier. Use this method to export or save a single layer.

Parameter	Type	Description
`path`	`String`	Destination file path.
`uti`	`String`	Uniform Type Identifier for the output format.
`properties`	`Dictionary`	A dictionary of image properties. The properties are passed to CGImageDestinationAddImage as the properties dictionary.

Returns: Boolean True when the write succeeds.

var doc = acorn.currentDocument();
var layer = doc.currentLayer();
var properties = {
   [kCGImagePropertyDPIWidth]: 143,
   [kCGImagePropertyDPIHeight]: 143,

   [kCGImagePropertyPNGDictionary]: {
     [kCGImagePropertyPNGSoftware]: "It’s Acorn of course."
   }
}
layer.writeToFile_withUTI_properties("/tmp/export.png", "public.png", properties);

Shape Layer¶

Shape layers are an extension of the Layer object, and contain vector graphics (aka - Graphic objects)

`shapeLayer.addBezierPath(path)`¶

Adds a Bezier path graphic to the shape layer.

Parameter	Type	Description
`path`	`NSBezierPath`	Path to add as a shape.

Returns: BezierGraphic The new Bezier graphic.

var path = NSBezierPath.bezierPathWithRect(NSMakeRect(25, 25, 100, 75));
var shapeLayer = acorn.currentDocument().baseGroup().addShapeLayer();
shapeLayer.addBezierPath(path);

`shapeLayer.addOvalWithBounds(bounds)`¶

Adds an oval graphic to the shape layer.

Parameter	Type	Description
`bounds`	`NSRect`	Oval bounds in canvas coordinates.

Returns: Graphic The new oval graphic.

var shapeLayer = acorn.currentDocument().baseGroup().addShapeLayer();
var oval = shapeLayer.addOvalWithBounds(NSMakeRect(25, 25, 100, 75));
print(oval.bounds());

`shapeLayer.addRectangleWithBounds(bounds)`¶

Adds a rectangle graphic to the shape layer.

Parameter	Type	Description
`bounds`	`NSRect`	Rectangle bounds in canvas coordinates.

Returns: Graphic The new rectangle graphic.

var shapeLayer = acorn.currentDocument().baseGroup().addShapeLayer();
var rect = shapeLayer.addRectangleWithBounds(NSMakeRect(25, 25, 100, 75));
print(rect.bounds());

`shapeLayer.addTextWithBounds(bounds)`¶

Adds a text graphic to the shape layer.

Parameter	Type	Description
`bounds`	`NSRect`	Text bounds in canvas coordinates.

Returns: TextGraphic The new text graphic.

var shapeLayer = acorn.currentDocument().baseGroup().addShapeLayer();
var text = shapeLayer.addTextWithBounds(NSMakeRect(25, 25, 200, 80));

// Set plain text
// text.setString("Hello from JavaScript");

// Set HTML
text.setHTMLString('<span style="font-size: 40px; font-weight: bold">Hello!</span><br/> <i>from JavaScript</i>');

`shapeLayer.graphics()`¶

Returns the vector graphics contained by a shape layer. This method will work on a base layer object, but it is only on shape layers that the array will be filled with anything.

Returns: NSArray The layer graphics.

var layer = acorn.currentDocument().currentLayer();
var graphics = layer.graphics();
for (var i = 0; i < graphics.count(); i++) {
    print(graphics[i].bounds());
}

`shapeLayer.moveGraphic_toIndex(graphic, index)`¶

Moves a graphic to a new index in the shape layer.

Parameter	Type	Description
`graphic`	`Graphic`	The graphic to move.
`index`	`Number`	The destination index.

 // Move the last object to the front
var layer = acorn.currentDocument().currentLayer();
var graphic = layer.graphics().lastObject();
layer.moveGraphic_toIndex(graphic, 0);

`shapeLayer.selectedGraphics()`¶

Returns the selected graphics on a shape layer.

Returns: NSArray The selected graphics.

var layer = acorn.currentDocument().currentLayer();
var selected = layer.selectedGraphics();
print(selected.count());

Tool Palette¶

Methods for reading and changing the current tool palette colors. You can get the current tool palette by calling acorn.toolPalette(). Note - an image must be open for it to return a value, as each document has its own palette. (In the past there was a single global palette, but that is no more… for the most part).

`toolPalette.backColor()`¶

Returns the current back color.

Returns: NSColor The back color.

var palette = acorn.toolPalette();
print(palette.backColor());

`toolPalette.frontColor()`¶

Returns the current front color.

Returns: NSColor The front color.

var palette = acorn.toolPalette();
print(palette.frontColor());

`toolPalette.setBackColor(color)`¶

Sets the current back color.

Parameter	Type	Description
`color`	`NSColor`	The new back color.

var palette = acorn.toolPalette();
palette.setBackColor(NSColor.whiteColor());

`toolPalette.setFrontColor(color)`¶

Sets the current front color.

Parameter	Type	Description
`color`	`NSColor`	The new front color.

var palette = acorn.toolPalette();
palette.setFrontColor(NSColor.blueColor());

JavaScript API¶

Application¶

acorn.currentDocument()¶

acorn.setPreference_forKey(value, key)¶

acorn.takeLayeredScreenshot()¶

acorn.toolPalette()¶

Bitmap Layer¶

bitmapLayer.applyCIFilterNamed_withParameters(name, parameters)¶

bitmapLayer.applyCIImageFromFilter(image)¶

bitmapLayer.applyCIImageFromFilter_shouldClipToSelection(image, clipToSelection)¶

bitmapLayer.colorAtPoint(point)¶

bitmapLayer.fillWithColor_shouldClipToSelection(color, clipToSelection)¶

bitmapLayer.floodFillAtPoint(point)¶

bitmapLayer.frame()¶

bitmapLayer.frameOrigin()¶

bitmapLayer.setFrameOrigin(point)¶

Document¶

document.autoLevels()¶

document.beginCroppingWithRect(rect)¶

document.bitsPerComponent()¶

document.bitsPerPixel()¶

document.callFilterNamed(filterOrPlugin)¶

document.canvasSize()¶

document.CIImage()¶

document.colorSpace()¶

document.copyMerged()¶

document.cropToRect(rect)¶

document.currentLayer()¶

document.DPI()¶

document.duplicate()¶

document.firstLayerWithName(layerName)¶

document.flipCanvasWithDirection(direction)¶

document.invertSelection()¶

document.layers()¶

document.newCGImage()¶

document.newLayerWithNSImage(image)¶

document.replaceOccurrencesOfString_withString(target, replacement)¶

document.resizeImageToSize(size)¶

document.scaleCanvasToSize(size)¶

document.scaleImageToHeight(height)¶

document.scaleImageToSize(size)¶

document.scaleImageToWidth(width)¶

document.scaleImageWithPercentage(scale)¶

document.selectFrame(frame)¶

document.setBitsPerPixel(bitsPerPixel)¶

document.setCanvasSize(size)¶

document.setCanvasSize_usingAnchor(size, anchor)¶

document.setDPI(dpi)¶

document.setSelectedLayer(layer)¶

document.trim()¶

document.writeToFile_withUTI(path, uti)¶

Graphics¶

bezierAnchor.hasLeftSegment()¶

bezierAnchor.hasRightSegment()¶

bezierAnchor.leftCP()¶

bezierAnchor.leftSegmentType()¶

bezierAnchor.location()¶

bezierAnchor.rightCP()¶

bezierAnchor.rightSegmentType()¶

bezierAnchor.setLeftCP(point)¶

bezierAnchor.setLeftSegmentType(type)¶

bezierAnchor.setLocation(point)¶

bezierAnchor.setRightCP(point)¶

bezierAnchor.setRightSegmentType(type)¶

bezierAnchor.translateBy(delta)¶

bezierGraphic.ACBezierPath()¶

bezierGraphic.movePointAtIndex_toPoint(index, point)¶

bezierGraphic.path()¶

bezierGraphic.pointOfElementAtIndex(index)¶

bezierGraphic.setACBezierPath(path)¶

bezierGraphic.setPath(path)¶

bezierPath.anchorAtIndex(index)¶

bezierPath.anchorCount()¶

bezierPath.anchors()¶

bezierPath.locationForAnchorAtIndex(index)¶

bezierPath.resetAnchors()¶

bezierPath.setLocation_forAnchorAtIndex(point, index)¶

graphic.bezierPath()¶

graphic.bounds()¶

graphic.drawsFill¶

`acorn.currentDocument()`¶

`acorn.setPreference_forKey(value, key)`¶

`acorn.takeLayeredScreenshot()`¶

`acorn.toolPalette()`¶

`bitmapLayer.applyCIFilterNamed_withParameters(name, parameters)`¶

`bitmapLayer.applyCIImageFromFilter(image)`¶

`bitmapLayer.applyCIImageFromFilter_shouldClipToSelection(image, clipToSelection)`¶

`bitmapLayer.colorAtPoint(point)`¶

`bitmapLayer.fillWithColor_shouldClipToSelection(color, clipToSelection)`¶

`bitmapLayer.floodFillAtPoint(point)`¶

`bitmapLayer.frame()`¶

`bitmapLayer.frameOrigin()`¶

`bitmapLayer.setFrameOrigin(point)`¶

`document.autoLevels()`¶

`document.beginCroppingWithRect(rect)`¶

`document.bitsPerComponent()`¶

`document.bitsPerPixel()`¶

`document.callFilterNamed(filterOrPlugin)`¶

`document.canvasSize()`¶

`document.CIImage()`¶

`document.colorSpace()`¶

`document.copyMerged()`¶

`document.cropToRect(rect)`¶

`document.currentLayer()`¶

`document.DPI()`¶

`document.duplicate()`¶

`document.firstLayerWithName(layerName)`¶

`document.flipCanvasWithDirection(direction)`¶

`document.invertSelection()`¶

`document.layers()`¶

`document.newCGImage()`¶

`document.newLayerWithNSImage(image)`¶

`document.replaceOccurrencesOfString_withString(target, replacement)`¶

`document.resizeImageToSize(size)`¶

`document.scaleCanvasToSize(size)`¶

`document.scaleImageToHeight(height)`¶

`document.scaleImageToSize(size)`¶

`document.scaleImageToWidth(width)`¶

`document.scaleImageWithPercentage(scale)`¶

`document.selectFrame(frame)`¶

`document.setBitsPerPixel(bitsPerPixel)`¶

`document.setCanvasSize(size)`¶

`document.setCanvasSize_usingAnchor(size, anchor)`¶

`document.setDPI(dpi)`¶

`document.setSelectedLayer(layer)`¶

`document.trim()`¶

`document.writeToFile_withUTI(path, uti)`¶

`bezierAnchor.hasLeftSegment()`¶

`bezierAnchor.hasRightSegment()`¶

`bezierAnchor.leftCP()`¶

`bezierAnchor.leftSegmentType()`¶

`bezierAnchor.location()`¶

`bezierAnchor.rightCP()`¶

`bezierAnchor.rightSegmentType()`¶

`bezierAnchor.setLeftCP(point)`¶

`bezierAnchor.setLeftSegmentType(type)`¶

`bezierAnchor.setLocation(point)`¶

`bezierAnchor.setRightCP(point)`¶

`bezierAnchor.setRightSegmentType(type)`¶

`bezierAnchor.translateBy(delta)`¶

`bezierGraphic.ACBezierPath()`¶

`bezierGraphic.movePointAtIndex_toPoint(index, point)`¶

`bezierGraphic.path()`¶

`bezierGraphic.pointOfElementAtIndex(index)`¶

`bezierGraphic.setACBezierPath(path)`¶

`bezierGraphic.setPath(path)`¶

`bezierPath.anchorAtIndex(index)`¶

`bezierPath.anchorCount()`¶

`bezierPath.anchors()`¶

`bezierPath.locationForAnchorAtIndex(index)`¶

`bezierPath.resetAnchors()`¶

`bezierPath.setLocation_forAnchorAtIndex(point, index)`¶

`graphic.bezierPath()`¶

`graphic.bounds()`¶

`graphic.drawsFill`¶

`graphic.fillColor()`¶

`graphic.scaleXBy_yBy(xScale, yScale)`¶

`graphic.setFillColor(color)`¶

`graphic.setStrokeColor(color)`¶

`graphic.setStrokeLineWidth(width)`¶