Choppy is a command line node script to perform image slicing and exporting from Photoshop using layer comp configuration. It runs on the PSD currently open in Photoshop.
$ npm install choppy -g
Open a PSD and add a layer comp for each image to be outputted.
Eg. 'output/mypic.png'
Run choppy in command line:
$ choppy
An image called 'mypic.png' will be saved to the 'output/' directory.
- Website images and game sprite assets can usually be broken up into separate psds that
follow logical groupings. Eg. "share-icons.psd", "player-sprites.psd".
This way you aren't left with a giant psd with 100s of slices, often hidden or only applicable to one layer comp in the design psd. You also avoid the opposite problem, where you have a separate PSD for every asset. - Slices in Photoshop are combersome to make, difficult to maintain and often hidden. Being able to output layer comps by their bounds means you don't have to drag dimension handles ever again.
- Design psds tend to messy and bloated with the process of design. An output-specific psd can still include site / game context while still focusing on assets at hand. These lean psds can then be added to source control without wasting space.
- The ability to output html / json / or custom wrapping text as well as images means alt text and dimension data can be configured in one place and updated automatically on output.
- Node + npm
- Photoshop (tested for Photoshop CC 2019)
Basic example
Eg. Layer comp called
img/mypic.png
with comment:
alt: A pic I took
cropToBounds: true
Layer comp naming format
[-][<relativePath>]<base>[.][<ext>|<type>][(<flag>,<propName>:<propValue>,...)]
- Layers prefixed with
-
indicate parent/nest level of the layer comp. Multiple levels supported (eg.--
,---
). This will inform thenestLevel
&parent
property. - Props can be also be defined in brackets as well as comments. A prop declaration without a
:
will be added to theflags
list.
Layer comp comment format
Configuration variables are set in the layer comp comment in the following format:
[<alt>]
<prop_name_1>: <prop_value_1>
<prop_name_2>: <prop_value_2>
...
Check out the PSD files in /examples/ to see choppy in action.
Each output image is represented by a layer comp named as the output filepath relative to the global |basePath|. Eg. "img/mypic.jpg"
The extension, if set, will define the file format of the outputted file.
If the layer comp begins with a backtick char (`
) it will be ignored.
Variables:
-
alt (string)
The alternate text to be outputted for the image. If the comment area hasn't got variables then the text will be assumed as alt text. -
cropToBounds (boolean)
If true then the output image dimensions will be informed by the bounds of the layer comp rather than the PSD dimensions. -
boundsComp (string)
Default blank. Specify another layer comp, by name, to be used for the bounds of this
clip. May be a comment comp (beginning with a backtick) or another comp. Will
automatically enable |cropToBounds| if set. Also accepts
{prev}
and{next}
to reference previous/next layer comps. This is preferable as it doesn't break if layer comps are renamed. -
ext (string)
Optional extension to be applied. This will only apply if there is no extension in the layer comp name. Valid entries are jpg, gif or png. -
flipX, flipY (boolean)
Flip the output horizontally / vertically. Default is false. -
relativePath (string)
Optional output path relative to |basePath|. This will only apply if there is no path defined in the image layer comp itself. -
basePath (string)
The relative path from the PSD to the output directory. It's recommended to use .choppy instead for defining this variable. -
quality (integer)
Image output quality for jpgs only. 0-100. Default is 80. -
matte (string)
Set the matte color for gif as a hex string. Eg. #FF3300. Hash optional, case insensitive. -
colors (integer)
Set the number of colors for a gif. 1-256. - forceW and forceH (integer) After being cropped to bounds and before applying scaling, the canvas will be resized to these pixel dimensions. Default is -1 which will not be applied.
-
forceGrid (integer)
Provide a grid size (eg. 16) and all outputted images will be cropped to whole tiles relative to document origin. -
scale (float)
Scale the output. Default 1.0. Eg 0.5 will output 50% size.
Optionally enter simple expressions to be evaluated. Eg. 2/3 -
sizes (string)
Output multiple sizes of the same image.
Format: filename:scale,filename:scale Eg.@2x:1,sd:.5
will output 2 files and inject@2x
andsd
into the filename before the extension.
Optionally put {s} in your file name / path to customize where the file size is placed in the output.
If size set then any scale props will be overwritten and ignored. All sizes will be added to the output as if additional layercomps were created for each size. -
sizeDef%Name% (string)
Optionally define individual sizes or groups of sizes by shorthand name. These can reference other sizes. Eg:
sizeDefSD: sd:1/2
sizeDefRETINA: @2x:1,SD
sizes: RETINA
Although this example uses uppercase the shorthand name is case insensitive.
Size definitions can be placed in the .choppy config file for use across multiple files.
-
reg (string)
Override the reg point for the image. Default is top left. Input values are 2 characters: the first represents vertical space, the second horizontal. Eg.TL
= top left,BR
= bottom right,C
= centered both dimensions,CR
= centered vert + right aligned,TC
= top aligned + centered horizontally. Alternatively enter coords relative to document origin - eg100,33
orx100y33
. -
outputValueFactor (float)
Default 1. All values sent to output templates will be multiplied by this factor. It doesn't affect the size of images exported, just the values written for |x|, |y|, |regX|, |regY|, |width| and |height| in the template output. -
roundOutputValues (boolean)
Default false. All values sent to output templates will be rounded to integer values. It doesn't affect the size of images exported, just the values written for |x|, |y|, |regX|, |regY|, |width| and |height| in the template output. -
outputOriginX and outputOriginX (integer)
Default 0. Sets the virtual origin point of the document to output. These values will be removed from the |x| and |y| properties supplied to the output template. Will not affect images exported, just the |x| and |y| values displayed. -
outputOriginLayer (string) Layer name
Default null. Optionally provide a layer name whose top left bounds will be set to the |outputOriginX| and |outputOriginY|. It's assumed the layer name is unique to the document and on the top level. -
placeholder (boolean)
Default false. If set to true will not output an image though all other processing will occur. -
nestlevel (int)
Default 0. The nest level of the layer comp. Can be set by prefixing layer comp name with-
,--
etc. -
parent (string)
Default ''. Thebase
name of the layer comp's parent. Will be auto filled if nestLevel is set. This does not affect image publish. If set thex
andy
coords will be relative to the parent's origin point. -
type (string)
Default ''. General property that allows extended functionality. Can optionally be set like an extension in the layer comp name. Eg.basename.<type>
. Built in types include:-
div
If applied will setplacholder
property totrue
. -
tf
If applied will setplacholder
property totrue
and outputtfParams
(below). -
btn
An alias fortf
-
-
tfParams (Object)
Default ''. Iftype
is set totf
, the style properties of the first visible text field will be set to this field encoded to a JSON string.-
align
The horizontal alignment of the text field (left
|center
|right
) -
text
The text content of the field -
font
The PostScript font name, including the font and style. Eg.Arial-BoldMT
-
alpha
The opacity of the layer -
color
The hex representation of the text color (Eg.#FF3300
) -
fontStyle
The font style of the text field (Eg.Regular
,Bold
,Italic
etc.) -
fontName
The font name, without style. (Eg.Arial
) -
fontSize
The font size, in pts. This value will take into account theoutputValueFactor
. -
visBoundsTLX
,visBoundsTLY
,visBoundsW
,visBoundsH
The visible bounds of the text field, position is relative to the layer.
-
- prefix (string) Will be added to start of layer comp names at start of string. Default ''.
- suffix (string) Will be added to end of layer comp names at start of string. Default ''.
-
flags (string)
Default ''. A comma separated string list. General property that allows extended functionality. Can optionally be set in the layer comp name within brackets. Eg.basename.png(flag1,flag2 etc)
. -
makeDir (boolean)
If set to true will attempt to create the export directory if it doesn't exist. Only the last directory in path will be made.
If a layer named {reg} is visible in a layer comp it will be hidden and used as a marker for the registration point. Will override reg value if present.
Optionally define the default settings for all output images in the current PSD.
All image vars above can be set and will be used as defaults if they are not set in the image layer comps.
The {choppy} layer comp also supports the following variables:
-
template (string)
Either custom raw template string or the slug of a template file. Default is "img".
This can also be defined per comp. Comma separate template slugs for multiple output. Also requires comma-separation of {choppy} comp vars |outputFilePath|, |outputTagStart| and |outputTagEnd| if present. -
outputFilePath (string)
If set the string result will be saved to the specified file path, relative to the base path. Variables can be included in this string and they will be swapped out.
Comma separate if multiple templates specified otherwise 1st entry will be used to pad out list. -
outputTagStart, outputTagEnd (string)
When |outputFilePath| is true, the result string will be inserted between
these tags if found in the output file.
Comma separate if multiple templates specified otherwise 1st entry will be used to pad out list. Escaped hyphens will prevent PS from merging multiple in a row:\-
. -
reverseOrder (boolean)
Default false. If set to true will reverse the layer comp order. If |boundsComp| is specified with{next}
or{prev}
this will not be affected, only output. The output prop |index| will output in ascending order whether reversed or not. -
wipeRelativePath (boolean)
If set to a relative path, all images at this location will be deleted before running the output. Also accepts a comma separated list. -
pre, post (string)
Optionally set a comma separated list of JSX command names (see
JSX Processing Scripts
below). -
postExecutePath (string)
Will execute file located at path provided, relative to PSD doc. This will be called after any post jsx commands. Accepts comma separated list.
Optionally place a file called '.choppy' in the same dir as your PSDs to direct to the base url for all.
{
"basePath": "../_source/"
}
This is better than defining basePath in the PSD documents as if the source dir is moved the basePath will need to be updated in each PSD. This way it only needs to be updated in the one place.
Any other layer comp props can be defined here, though is not usually necessary.
A config var with an important "!" at start will override descendants and also prevent ancestors from overriding. Eg.
!cropToBounds: true
- Defined by template var
- Templates reside in
./tpl/
directory. - Custom templates can be defined in a
./tpl/
dir in the same folder as the PSD. - Default template is "img".
- Templates can be of any extension.
-
src
The output image source path relative to config settings. -
width
The output image width. -
height
The output image height. -
base
The base filename of the image without extension. -
alt
Alt tag. -
ext
File extension without a preceeding ".". -
index
The layer comp index. -
x + y
The position of the pic relative to the containing doc, useful for forcropToBounds
output. Will be top left by default, unless registration point is defined, in which case the reg point will be used instead. The output scale will be applied to this value. -
regX + regY
The reg point relative to the top left of the pic bounds. Eg. If set to top left then will be (0,0), if bottom right will be the same as (pic.width, pic.height). The output scale will be applied to this value. -
tlX + tlY
The position of the top left of the pic regardless of registration point position. Respects |outputOriginLayer|, |scale| -
regPercX + regPercY
The relative reg point as a percentage value of the pic dimensions. Eg. (0,0) is top left, (1,1) is bottom right. - Any other unreserved vars set anywhere in the config chain.
-
psdBase
The base filename of the current PSD doc. - psdWidth, psdHeight The width of the PSD (in pixels)
-
pubtime (string)
The publish date and time, eg.2018-8-3 11:12:40
- %varname%
<img src="%src%" width="%width%" >
-
mytemplate.txt
Required. The main template, used for each image outputted, where mytemplate is the name of the template. -
mytemplate.header.txt
Optional. Will be added to the top of the output text. Suitable for instructions, global styles etc. Does not swap out variables. -
mytemplate.footer.txt
Optional. Will be added to the bottom of the output text. Does not swap out variables. -
mytemplate.inter.txt
Optional. Will be added between items. Does not swap out variables. -
mytemplate.parse.jsx
Optional. Declare a function calledparse
in a stand alone JSX script file to handle all variables injected into the template. The function takes 2 argumentspropName
andpropVal
. Eg:
// mytemplate.parse.jsx
function parse(propName, propVal){
if (typeof propVal === 'string'){
return propVal.toUpperCase();
}
return propVal;
}
Template and text output will still perform.
Add psd file/s to the arg to be published
$ choppy path/to/mypics.psd
Multiples supported:
$ choppy path/to/mypicsA.psd path/to/mypicsB.psd path/to/mypicsC.psd
Wildcards supported:
$ choppy path/**/mypics*.psd
Paths can be relative to pwd or absolute
Command line environment variables:
$ choppy varA="foo" varB="bar"
These will be saved to the envVars
object that is accessible to jsx scripts.
Choppy can be extended with custom .jsx
scripts.
- Put scripts in
./jsx/
directory (next to.psd
) in the following subfolders:pre/
post/
standalone/
- Queue scripts to run by defining
pre
,post
properties in either.choppy
config file or{choppy}
config layer. These are defined in run order as comma separated string, without.jsx
extension. Eg.pre: script1,script2,script3
Will run:
- after working copy PSD duplication
-
after loading the
{choppy}
layer comp data -
after deleting
{choppy}
layer comp and comment layer comps - after comps are cleaned up: white-space removed, duplicate comment props removed, empty comment lines removed
-
after comp names have resolved to be the same as the comp
base
- before processing other layer comps
Available vars:
-
app.activeDocument
the current PSD (a working duplicate version) -
halt
for debugging, set totrue
abort processing immediately after script run
Available functions:
-
console.log(...)
Will output to the current terminal running Choppy -
trim(str)
,trimStart(str)
,trimEnd(str)
string trimming functions -
setCommentProp(layerComp, propName, propVal)
will edit supplied layerComp.comment with property declaration, will overwrite prop if it already exists. -
getCommentProp(layerComp, propName)
will return prop defined in layerComp.comment, will return null if not set. -
deleteCommentProp(layerComp. propName)
will remove prop from layerComp.comment, if found.
Built in scripts:
-
layers-to-comps
If added to thepre
queue will try to convert each top-level layer to a layercomp. Top level{reg}
layers will be included with layer below.
Will run:
- after completing export of images, closing duplicate working PSD and exporting templates.
Available vars:
-
app.activeDocument
the current (original) PSD -
exportDirs
an array of string paths to each directory that images were saved to during publishing.
Available functions:
-
console.log(...)
Will output to the current terminal running Choppy. -
getGlobalProp(propName)
will return globally defined property.
Can be called from command line using:
$ choppy %standalone_script_name_1% [%standalone_script_name_2%]
- Global
standalone
scripts can be called without a PSD open, though a PSD needs to be open to use localjsx/standalone
scripts. - Choppy will exit immediately after calling once, the publish will not occur.
Available vars/functions:
- None