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.
Install choppy
$ npm install choppy -g
Getting started
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.
Advantages
- 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.
Requirements
- Node + npm
- Photoshop (tested for Photoshop CC 2019)
Documentation
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 the nestLevel
& parent
property. - Props can be also be defined in brackets as well as comments. A prop declaration without a
:
will be added to the flags
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.
Image layer comp
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
and sd
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 - eg 100,33
or x100y33
. - 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 ''. The base
name of the layer comp's parent. Will be auto filled if nestLevel is set. This does not affect image publish. If set the x
and y
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 set placholder
property to true
.tf
If applied will set placholder
property to true
and output tfParams
(below).btn
An alias for tf
- tfParams (Object)
Default ''. If type
is set to tf
, 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 fieldfont
The PostScript font name, including the font and style. Eg. Arial-BoldMT
alpha
The opacity of the layercolor
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 the outputValueFactor
.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.
{reg} Layer
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.
{choppy} Layer comp
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.
Base config file
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.
Overriding
A config var with an important "!" at start will override descendants and also prevent ancestors from
overriding. Eg.
!cropToBounds: true
Templates
- 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.
Vars
- 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 for cropToBounds
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.
Constant Vars
- 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
Format
<img src="%src%" width="%width%" >
File parts
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 called parse
in a stand alone JSX script file to handle all variables injected into the template. The function takes 2 arguments propName
and propVal
. Eg:
function parse(propName, propVal){
if (typeof propVal === 'string'){
return propVal.toUpperCase();
}
return propVal;
}
Command line
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.
JSX Processing Scripts
Choppy can be extended with custom .jsx
scripts.
- Put scripts in
./jsx/
directory (next to .psd
) in the following subfolders:
- 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
pre
hook scripts
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 to true
abort processing immediately after script run
Available functions:
console.log(...)
Will output to the current terminal running Choppytrim(str)
,trimStart(str)
,trimEnd(str)
string trimming functionssetCommentProp(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 the pre
queue will try to convert each top-level layer to a layercomp. Top level {reg}
layers will be included with layer below.
post
hook scripts
Will run:
- after completing export of images, closing duplicate working PSD and exporting templates.
Available vars:
app.activeDocument
the current (original) PSDexportDirs
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.
standalone
scripts
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 local jsx/standalone
scripts. - Choppy will exit immediately after calling once, the publish will not occur.
Available vars/functions:
Release History
CHANGELOG.md