ExtendScript (.jsx) library for Photoshop.
JavaScript CoffeeScript
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
templates
.gitignore
Gruntfile.coffee
LICENSE
README.md
bower.json
bulk.full.jsx
bulk.jsx
package.json

README.md

bulk.jsx

ExtendScript (.jsx) library for Photoshop.

Example

#target "photoshop"
#include "bulk.full.jsx"

bulk(Folder.selectDialog('Select source folder.'), {filePattern: /\.(jpg|jpeg|png|gif|tif|tiff|psd)$/i})
  .mode({
    mode: ChangeMode.RGB
  })
  .resize({
    type: 'fit',
    width: 1000,
    height: 1000,
    expand: false
  })
  .jpg({
    dest: Folder.selectDialog('Select destination folder.'),
    filename: '<%= bulk.pad(index + 1, 3) %>-<%= basename %>-<%= Number(doc.width) %>x<%= Number(doc.height) %>.jpg',
    overwrite: 'ask',
    quality: 80
  })
  .exec();

Getting Started

Zip Download

  1. Download bulk.jsx and Unzip.
  2. Go to the unzipped folder bulk.jsx-master/templates and edit template.jsx (there are already some codes).
  3. Launch Photoshop and select menu: File > Scripts > Browse… then open template.jsx.
  4. Script runs.

npm

Install:

npm install bulk.jsx

Script:

#target "photoshop"
#include "node_modules/bulk.jsx/bulk.full.jsx"

// your code here

bower

Install:

bower install bulk.jsx

Script:

#target "photoshop"
#include "bower_components/bulk.jsx/bulk.full.jsx"

// your code here

Dependencies

API

bulk(src, options = null)

  • src Folder | File | String | Array | bulk Object | Function
    Source object:
    • Folder: Use all matched files inside the folder as task targets.
    • File: Use the file as task target.
    • String: Absolute file/folder path. Same as File(string).
    • Array: Dig items recursively. Folder, File, String or Array are accepted.
    • bulk Object: Same as bulk.src().
    • Function: Same as func().
  • options Object
    • options.filePattern RegExp | Function
      Filename pattern to specify targets. If null, all files are accepted. Default value: null
    • options.folderPattern RegExp | Function
      Folder name pattern to specify targets. If null, all folders are accepted. Default value: null
    • options.mask String
      Parameter passed to Folder.getFiles(mask). Default value: '*'.
    • options.deep Boolean
      Traverse deeply through files in folders. Default value: true.

Returns: bulk Object

bulk(Folder.selectDialog('Select folder.'), {filePattern: /\.jpg$/})
  .resize({type: 'fit', width: 1000, height: 1000})
  .save()
  .exec();

bulk.basename(filename)

  • filename String

Returns: String

bulk.basename('hello.jpg');
// => 'hello'

bulk.extension(filename)

  • filename String

Returns: String

bulk.extension('hello.jpg');
// => 'jpg'

bulk.noConflict()

Returns: bulk

bulk.pad(string, length, padString = '0', right = false)

  • string String
  • length Integer
  • padString String
  • right Boolean

Returns: String

bulk.pad('5', 3);
// => '005'

bulk.pixels(callback, context = null)

Shortcut of bulk.units(Units.PIXELS, callback, context).

  • callback Function
  • context Object

Returns: undefined

bulk.units(units, callback, context = null)

Set preference.rulerUnits to specified units, execute callback and reset to original units.

  • units Units
  • callback Function
  • context Object

Returns: undefined

bulk.units(Units.INCHES, function() {
  $.writeln('document width: ' + String(app.activeDocument.width) + ' inches');
  $.writeln('document height: ' + String(app.activeDocument.height) + ' inches');
});

bulk.walk(src, fileCallback, otherCallback, options = null)

Traverse through files in source, yield each file/other object to callback.

  • src Folder | File | String | Array
    Source object: Folder, File, String (Same as File(string)), Array (Parse recursively).
  • fileCallback Function(file)
    Callback for File objects.
  • otherCallback Function(otherObject)
    Callback for unknown objects.
  • options Object
    • options.filePattern RegExp | Function
      Filename pattern to specify targets. If null, all files are accepted. Default value: null
    • options.folderPattern RegExp | Function
      Folder name pattern to specify targets. If null, all folders are accepted. Default value: null
    • options.mask String
      Parameter passed to Folder.getFiles(mask). Default value: '*'.
    • options.deep Boolean
      Traverse deeply through files in folders. Default value: true.

Returns: undefined

bulk.walk(Folder.selectDialog('Select folder.'), function(file) {
  $.writeln(file.name); // log filename
}, null, {
  filePattern: /\.txt$/
});

.crop(options = null)

Task: crop document.

  • options Object
    • options.width UnitValue
    • options.height UnitValue
    • options.anchor AnchorPosition
      Default value: AnchorPosition.MIDDLECENTER.

Returns: bulk Object

bulk(src, options)
  .crop({
    width: 100,
    height: 100,
    anchor: AnchorPosition.TOPCENTER
  })
  .save()
  .exec();

.exec(options = null)

Actually execute bulk object. Specifying ruler units.

  • options Object
    • options.units Units
      Default value: Units.PIXELS

Returns: bulk Object

.export(options = null)

Task: export document.

  • options Object
    • options.dest Folder | String | Template String | Function
      Destination folder for output file. Default value: null.
      • Folder: Passed folder.
      • String: Passed to underscore’s .template function with bulk.DocInfo object: _.template(string, docInfo). Then, evaluated as an absolute path, or a relative path to parent folder of the original file.
      • Function: Use return value of func.call(docInfo).
      • null: Same folder with the original file.
    • options.filename String | Template String | Function
      Filename for output file. Default value: null.
      • String: Passed to underscore’s .template function with bulk.DocInfo object: _.template(string, docInfo).
      • Function: Use return value of func.call(docInfo).
      • null: Same name with the original file.
    • options.overwrite Boolean | 'ask'
      Define behavior in case a filename already exists. Default value: 'ask'.
      • true: Overwrite file.
      • false: Cancel saving document.
      • 'ask': Popup confirm dialog.
    • options.exportType ExportType
    • options.exportOptions ExportOptions

Returns: bulk Object

var exportOptions = new ExportOptionsSaveForWeb();
exportOptions.format = SaveDocumentType.JPEG;
exportOptions.quality = 50;

bulk(src, options)
  .export({
    dest: Folder.selectDialog('Select destination folder.'),
    filename: '<%= basename %>-low.<%= extension %>',
    overwrite: false,
    exportType: ExportType.SAVEFORWEB,
    exportOptions: exportOptions
  })
  .exec();

.jpg(options = null)

Task: export document as JPEG for web.

  • options Object
    • options.dest Folder | String | Template String | Function
      See .export().
    • options.filename String | Template String | Function
      See .export().
    • options.overwrite Boolean | 'ask'
      See .export().
    • options.quality Number (0100)
      Default value: 100

Returns: bulk Object

.log(options = null)

Task: output document/file information to JavaScript console of ExtendScript Toolkit.

  • options Object
    • options.template String | Template String
      Passed to underscore’s .template function with bulk.DocInfo object: _.template(string, docInfo). Default value: '<%= filename %>'.
    • options.opensDoc Boolean
      Set true if you want to use <% doc ... %> inside template string. If false, file never opens as document, unless the other tasks require doc. Default value: true.

Returns: bulk Object

bulk(src, options)
  .log({
    template: '<%= bulk.pad(index + 1, 3) %>: <%= filename %>',
    opensDoc: false
  })
  .exec();

Example output:

001: hello.jpg
002: world.jpg
…

.mode(options = null)

Task: change color mode of document.

  • options Object
    • options.mode ChangeMode
      Default value: ChangeMode.RGB.

Returns: bulk Object

bulk(src, options)
  .mode({
    mode: ChangeMode.CMYK
  })
  .exec();

.opensDoc()

Internal method: get opensDoc property, whether or not bulk object’s tasks need to open file as Photoshop document.

Returns: Boolean

.opensDoc(opens)

Internal method: set opensDoc property. Once it is set true, unable to change it.

  • opens Boolean

Returns: bulk Object

.options()

Get options object passed to bulk().

Returns: Object

.pass(callbacks...)

Pass bulk object to all callbacks as this. You can use this method to fork tasks.

  • callbacks... Function

Returns: bulk Object

bulk(src, options)
  .resize({
    type: 'fit',
    width: 1000,
    height: 1000
  })
  .pass(
    function() {
      this.jpg({
          dest: destForJpg,
          filename: '<%= basename %>.jpg'
        })
        .exec();
    },
    function() {
      this.crop({
          width: 100,
          height: 100
        })
        .png({
          dest: destForPng,
          filename: '<%= basename %>.png'
        })
        .exec();
    }
  );

.png(options = null)

Task: export document as 24-bit PNG for web.

  • options Object
    • options.dest Folder | String | Template String | Function
      See .export().
    • options.filename String | Template String | Function
      See .export().
    • options.overwrite Boolean | 'ask'
      See .export().

Returns: bulk Object

.push(task, opensDoc = true)

Push task to bulk object and returns clone bulk object. See “Create Custom Task” section.

  • task Function
    Task function executed for each document/file. this in the function is set to bulk.DocInfo.
  • opensDoc Boolean
    If true, bulk object opens file as document.

Returns: bulk Object

.resize(options = null)

Taks: resize document.

  • options (Object)
    • options.type 'fit' | 'fill' | 'remain' | 'stretch' | Function(space, rect, options)
      Resize method. Default value: 'fit'.
      • 'fit': Resize document to fit into space.
      • 'fill': Resize document to fill space.
      • 'remain': Keep document size.
      • 'stretch': Resize document stretched into the same size with space. (Doesn’t keep aspect ratio)
      • Function: Custom resize function. See rebounds.js for detail.
    • options.width UnitValue
    • options.height UnitValue
    • options.reduce Boolean
      Allow size reduction of document. Default value: true
    • options.expand Boolean
      Allow size expansion of document. Default value: true
    • options.resolution Number
      Default value: 72.
    • options.resampleMethod ResampleMethod
      Default value: ResampleMethod.BICUBICSHARPER.

Returns bulk Object

bulk(src, options)
  .resize({
    type: 'fit',
    width: 1000,
    height: 1000,
    reduce: true,
    expand: false,
    resolution: 96,
    resampleMethod: ResampleMethod.BICUBIC
  })
  .save()
  .exec();

.save()

Task: save document.

Returns: bulk Object

bulk(src, options)
  .mode({
    mode: ChangeMode.RGB
  })
  .save()
  .exec();

.src()

Source object passed to bulk().

Returns: Folder | File | String | Array | bulk Object | Function

.tasks()

Internal method: task functions added to the bulk object.

Returns: Function Array

.tasks(tasks)

Internal method: set tasks to the bulk object.

Returns: bulk Object

bulk.DocInfo

Document and File information class. Its instances are passed to task functions as this objects.

Properties:

  • basename String
    Basename of the File. (example: 'hello' if filename is 'hello.jpg')
  • data Object
    Shared data.
  • doc Document
    Target Document object.
  • extension String
    Extension of the File. (example: 'jpg' if filename is 'hello.jpg')
  • file File
    File object of the target Document.
  • filename String
    Filename of the File.
  • index Integer
    Current index in sources.

Create Custom Task

To create task logSize for example:

bulk.fn.logSize = function(options) {
  // options
  var filename = !!options.filename;
  var prefix = options.prefix || 'document ';
  var suffix = options.suffix || ' pixels';
  
  // push task and return cloned bulk object
  return this.push(function() {
    // - `$.writeln()` is log function in ExtendScript
    // - `this` is current bulk.DocInfo object
    
    if (filename) {
      $.writeln(String(this.index) + ' filename: ' + this.file.name);
    }
    $.writeln(prefix + 'width: ' + String(this.doc.width) + suffix);
    $.writeln(prefix + 'height: ' + String(this.doc.height) + suffix);
    $.writeln('-');
  });
};

To use:

bulk(src, options)
  .logSize({
    filename: true,
    prefix: 'my document ',
    suffix: 'px'
  })
  .exec();

Example output:

0 filename: hello.jpg
my document width: 500px
my document height: 350px
-
1 filename: world.jpg
my document width: 550px
my document height: 200px
-
2 filename: salt.jpg
my document width: 1024px
my document height: 768px
-

License

MIT License