Skip to content

Generate Image Assets Functional Spec

Jump to bottom
Cory McIlroy edited this page Nov 22, 2019 · 6 revisions

Status

  • [07/30/13] Initial stab, written by Tim Riot.
  • [08/08/13] The 808 state, revised by Tim Riot, based on feedback from Tom McRae and Yukie Takahashi.
  • [08/19/13] Changes to tagging by Tim Riot, based on feedback from Kyoko Itoda and Tom Attix.
  • [08/22/13] Joel added a whole bunch more examples of good and bad layer names
  • [04/09/14] Ian added information about new features slated for Photoshop 15.
  • [05/20/14] Joel added information about how layer visibility is handled.

Overview

For the initial release, most users will interact with the Generator technology via the user-facing feature, image asset generation.

The primary function of this feature is to expedite the creation and update of image assets. By creating a direct connection between the layer(s) that comprise an asset and the output itself, the time-consuming process of asset production can be greatly optimized.

Getting started

  1. Open a PSD, taking note of it's location
  2. Select the menu item File -> Generate -> Image Assets
  3. Tag layers or layer groups with names that end in any of the standard file extensions ( .png, .jpg, .gif )
  4. Use a file explorer to navigate to the folder where your PSD lives, then open the folder {PSD name}-assets

How to tag

BASIC

.png - Defaults to png 32. Supported flavors include: .png8, .png24, .png32

.jpg - Default quality is 9 (or 90%). Options include: .jpg(1-10), .jpg(1-100%)

.gif - Basic alpha transparency, no options

Basic Tagging Examples

  • rad.png24

  • middling.jpg5

  • oldschool.gif

  • subfolder/bbq.jpg

EXTENDED

____% - Percentage-based scaling

____ x ____ - Dimension-based scaling defaults to pixels, other units include: px, in, cm, mm

____, ____ - Commas create multiple files from a single group / layer: each tag must be properly formatted with a valid file extension

Extended Tagging Examples

  • 200% gorilla.png

  • 300 x 200 disproportionate.jpg or 50in x 10in gargantuan.png

  • 50% little/kooky.png, 1000% big/awesome.jpg

Where does the output go?

Assets are generated in a folder called {PSD name}-assets in the same directory as your PSD, once the menu item Generate -> Image Assets is enabled for your document and you've tagged a few layers / groups.

When creating assets from unsaved documents, a folder called Untitled-1-assets will be created on the desktop. Once the document is saved, a new {PSD name}-assets will be created next to the PSD wherever it was saved and Untitled-1-assets will be removed from the desktop.

If you specify that an asset should be generated into a subfolder, the subfolder will be created directly within the document's assets folder as described above.

If you are working with a Cloud Document, then assets will be saved within the "Photoshop Cloud Associates" directory:

  • WIN: C:\Users\yourname\Documents\Adobe\Photoshop Cloud Associates
  • MAC: /Users/yourname/Documents/Adobe/Photoshop Cloud Associates

What happens with layers that are invisible?

In Generator, we follow this simple rule: If a layer is invisible, it is not included in composites for parent layers. However, if a tagged layer is invisible, we still generate that layer as follows: We pretend it is visible and then, for any child layers, we determine their visibility appropriately (i.e. if the child layer would initially be invisible when the user made the parent layer visible, then we leave it invisible in the composite).

So, if you had a layer structure like this:

  • Foo.png (invisible)
    • Layer A (invisible even if layer "Foo.png" were visible)
    • Layer B (visible if layer "Foo.png" were visible)
    • Bar.png (invisible even if layer "Foo.png" were visible)

Then you would get two files generated. The file Foo.png would include only the content on the layer named "Layer B". The file Bar.png would include only the content on the layer named "Bar.png".

Asset generation is controlled on a per document basis

The generation of image assets is enabled on a per document basis and is off by default. However, once the user selects Generate -> Image Assets, the plug-in will remember that choice until the user disables image assets ( by selecting Generate -> Image Assets again ) for that document or disables Generator completely, via the preferences dialog.

On uniqueness

Because the Image Assets plug-in creates a direct connection between the tagged layer name and the output file name / type, it is important to create unique names for your assets. If two layers are tagged with exactly the same name, only the first layer ( in the visual stack order of the layers panel ) will be created.

How can I get layers and groups that bleed off the canvas to appear as complete assets?

Set configuration options clip-all-images-to-document-bounds and clip-all-images-to-artboard-bounds to false via a Generator Config file. Assets that extend beyond the dimensions of the canvas will now be exported at their full size.

To selectively create an asset that is cropped to the canvas with the above options set, Select -> All then create a mask for the asset's layer or group. The bounds of the mask will be used to determine the output dimensions of the asset. Keep in mind that a group mask will not affect that group's children without the include-ancestor-masks option enabled.

Generator scares me and I want it to leave me alone

To disable Generator for ALL documents, go to Photoshop -> Preferences -> Plug-ins and uncheck "Enable Generator". The Image Assets plug-in will not generate assets until Generator is re-enabled in the Preferences dialog.

Exhaustive examples of layer names

JPEG quality examples

Good examples for JPGs with a quality parameter

  • foo.jpg-1
  • foo.jpg4
  • foo.jpg-10
  • foo.jpg-1%
  • foo.jpg42%
  • foo.jpg-100%

Bad examples for JPGs with a quality parameter

  • foo.jpg-0
  • foo.jpg-11
  • foo.jpg-0%
  • foo.jpg-101%

PNG bits per channel examples

Good examples for PNGs with a bits per channel parameter

  • foo.png-8
  • foo.png24
  • foo.png-32
  • foo.png24a (24a bits per channel on PNG is the same as 32)

Bad example for a PNG with a bits per channel parameter

  • foo.png-42

Relative scaling examples

Good examples for a scale factor

  • 1% foo.png
  • 42% foo.png
  • 100% foo.png
  • 142% foo.png
  • 33.33% foo.png

Bad examples for a scale factor

  • 0% foo.png

Absolute scaling examples

Good examples of absolute scaling

  • 100x80 foo.png (simple absolute scaling)
  • 80 x 100px foo.png (spaces between lengths)
  • 4in x100 foo.png (mix of units and no units)
  • 90mm x120cm foo.png (mix of different units)
  • 100x? foo.png (wild card)
  • ?x60in foo.png (wild card at beginning)

Bad examples of absolute scaling

  • 100x100foo.png (no space before file name)
  • 80x100 60% foo.png (mix of absolute and relative scaling)
  • 50% 80x100 foo.png (mix of absolute and relative scaling)
  • 20in cm x50cm foo.png (multiple units)
  • 30nm x20 nano.png (invalid unit)

Formatting and separating multiple files

Good examples

  • Layer 1.png (Space in file name is allowed -- results in a single file called "Layer 1.png")
  • Layer 1.png,Layer 2.jpg (Comma as separator)
  • Layer 1.png, Layer 2.jpg (Comma followed by space(s) as separator)
  • Layer 1.png+Layer 2.jpg (Plus as separator)
  • Layer 1.png + Layer 2.jpg (Plus followed by space(s) as separator)

Putting it all together

100% Delicious, 42% Layer 1.png24 + 100x100 Layer.jpg-90% , 250% Quux/Foo Bar Baz.gif results in three files (the "100% Delicious" string is ignored, because it's not a filename):

  • Layer 1.png, at 42% scale, as a 24-bit png
  • Layer.jpg, as an absolute size of 100x100 pixels, as a 90% quality jpg
  • Foo Bar Baz.gif in subfolder Quux, at 250% scale, as a gif.

Default asset specifications

From Photoshop 15, it is possible to specify document-wide default asset specifications using the default keyword. This changes the manner in which assets are generated throughout the document.

Suppose you are working in a document named test.psd that has a layer with a name like foo.png. As an example of how to use default asset specifications in test.psd, create an empty layer anywhere in the document with the following name:

  • default hi-res/

The default layer here specifies that all assets should be generated into a subfolder called hi-res. (Don't forget the trailing slash!) So the resulting generated asset will be at test-assets/hi-res/foo.png.

Next, change the default layer name to the following:

  • default hi-res/@2x

This default layer specifies both a subfolder into which assets should be generated and a filename suffix. So the result generated asset will now be at test-assets/hi-res/foo@2x.png.

Besides subfolders and filename suffixes, it's also possible to specify relative scaling factors with default layers. As an example, change the default layer name to the following:

  • default 50% lo-res/

This specifies both that assets should generated into the lo-res subfolder---in this case, test-assets/lo-res/foo.png---and also that they should be scaled down to half size. Default scaling factors can be overridden by explicitly specifying scaling factors on individual layer names. So if there is a another layer with a name like 25% bar.jpg, those assets will still be generated at 25% scale instead of the default 50% scale.

Finally, just as with regular layer asset specifications, it's possible to combine multiple default asset specifications using the + or , operators. As an example, we can use a pair of default specifications (in a single layer name) to indicate that, for each specified layer asset, a high-resolution asset should be generated with an @2x suffix into the hi-res subfolder, and a low-resolution asset should be generated without a suffix into the lo-res subfolder:

  • default hi-res/@2x + 50% lo-res/

This results in the generation of test-assets/hi-res/foo@2x.png and test-assets/lo-res/foo.png, the latter of which is half size.

Clone this wiki locally