![]() |
Shotgun Engine for Photoshop CCShotgun Integration for Photoshop CC |

Documentation
Interface Overview
Installation
Enabling the extension
Interface components
Context header
Favorites shelf
Command list
Context menu
Logging console
Configuration and technical details
PySide
CEP extension
Configuring favorites
Context fields display hook
Photoshop API
Examples
Environment variables
App Developer notes
Installation, Updates and Development
Configuration Options
Release Notes History
The Shotgun engine for Photoshop contains a standard platform for integrating the Shotgun Pipeline Toolkit apps into Photoshop CC. Once installed, it allows you to run the same apps that you have in Maya, Nuke and other applications. The full Photoshop API is exposed to app developers, which means that you can rapidly build Photoshop functionality using Python and Qt without having to compile anything or understand the details of how to build and deploy a Photoshop plugin.
Supported Application Versions
This item has been tested and is known to be working on the following application versions: 2015.5 - 2020. Please note that it is perfectly possible, even likely, that it will work with more recent releases, however it has not yet been formally tested with these versions.
Documentation
The Shotgun engine for Photoshop CC provides a platform for integrating Shotgun into your Photoshop CC workflow. It consists of a standard Shotgun Pipeline Toolkit engine and relies on the tk-framework-adobe (CEP).
Once enabled, a Shotgun panel becomes available in Photoshop CC. It displays information about the current Shotgun context as well as the commands that are registered for the apps installed in that context.

Interface Overview
The Shotgun extension panel uses the same color palette and basic layout as native Photoshop CC panels. It is comprised of five components:

- Context Header - Thumbnail and fields for the current context.
- Favorites Shelf - Designed to show the most commonly-used apps for the current context.
- Command List - All non-favorited commands for the current context.
- Context Menu - Additional context-related commands and debugging tools.
- Logging Console - A console overlay that displays logging output for debugging.
Installation
Installation of the Shotgun Engine for Photoshop CC follows the same protocol as the other Shotgun integrations. For information on installing engines and apps, see the Administering Toolkit article. In addition, you can reference the default toolkit config as an example of how to configure the integration.
Enabling the extension
Once the extension is installed, it will need to be launched via the extensions menu in Photoshop CC.

This will only need to be done once and the Shotgun extension panel can remain in the Photoshop CC layout without having to be enabled on subsequent launches.
Once enabled, and on future launches, the extension panel will display a loading screen while the Shotgun integration is bootstrapping.
This screen typically displays for a few seconds before the current context is determined and the commands are displayed.
Interface components
The following sections outline the components of the Shotgun Photoshop CC integration.
Context header
The context header is a customizable area which can display information about the current Shotgun context.

The context is determined by the currently-active document. Once the context is determined by the engine, the header will update to display the context's thumbnail field detail. The field information is controlled by a hook. For information on how to customize the field display, see the Context Fields Display Hook section below.
It should also be noted that since Photoshop CC is a multi-document interface, the context, and therefore the Shotgun extension, will update as you change the active document. It is important that artists understand this behavior, especially when working in multiple Shotgun contexts simultaneously.
Favorites shelf
The favorites shelf is similar to the menu favorites available in other Shotgun DCC integrations such as Maya and Houdini. This section of the interface makes the most commonly used Toolkit apps readily available and easy to find just under the context header.

The shelf displays the favorited commands as buttons that, when moused over, transition from grayscale to color and display their name in the label at the top. Tooltips for the buttons will show by hovering the mouse above them.
Clicking one of the buttons will trigger the callback for the registered command to execute.
For details on how to specify command favorites, see the Shelf Favorites section below.
Command list
The command list shows the other "regular" commands that are registered for the current context.

Typically, apps installed within a pipeline configuration will register one or more commands that are displayed here. If the commands are not identified as favorites, and are not identified as context-menu commands, they will display here.
The command list buttons behave in a manner similar to those in the favorites shelf. The only real difference is that they display as a list with the full name to the right of their icon.
Context menu
Any commands registered as context menu commands will show in the Shotgun extension panel's context menu.

Like the other command areas, these commands will change along with the context. Commands such as Jump to Shotgun and Jump to Filesystem will always be available here.
Logging console
The logging console shows all of the logging output from both the CEP Javascript interpreter and Toolkit's Python process.

If there are any issues with the extension that require support, the logging console output is extremely useful for helping the Shotgun support team debug the problem.
Configuration and technical details
The following sections outline some of the more technical aspects of the integration to help configure the integration to the specific needs of your studio pipeline.
PySide
The Shotgun engine for Photoshop CC relies on PySide. Please see the official instructions for Installing Pyside.
CEP extension
The extension itself is bundled with the engine and the engine handles installation automatically on the first launch of Photoshop CC. The extension is installed on the artist's local machine in the standard, OS-specific CEP extension directories:
# Windows > C:\Users\[user name]\AppData\Roaming\Adobe\CEP\extensions\ # OS X > ~/Library/Application Support/Adobe/CEP/extensions/
Each time Photoshop CC is launched, the engine bootstrap code will check the version of the extension that is bundled with the engine against the version that is installed on the machine. This means that after an engine update, assuming a new version of the extension came with it, the installed extension will be automatically updated to the newly-bundled version.
Configuring favorites
The Favorites Shelf can be configured to display any of the
registered commands for your installed apps. To do this, simply add the
shelf_favorites
setting to the tk-photoshopcc
section of your environment
configuration. Here's an example:
shelf_favorites: - {app_instance: tk-multi-workfiles2, name: File Save...} - {app_instance: tk-multi-workfiles2, name: File Open...} - {app_instance: tk-multi-publish, name: Publish...} - {app_instance: tk-multi-snapshot, name: Snapshot...}
The value of the setting is a list of dictionaries identifying a registered
command provided by one of the installed apps in the configuration. The
app_instance
key identifies a particular installed app and the name
key
matches the command's display name registered by that app. In the example above, you can
see four favorited commands: the file open and save dialogs from the
tk-multi-workfiles2
app as well as the standard Toolkit publish and snapshot
dialogs. These four commands will now show in the favorites shelf.
Context fields display hook
The engine comes with a hook to control the fields displayed in the Context Header section of the panel. There are two methods in the hook that can be overridden to customize what is displayed.
The first method is the get_entity_fields()
method. This method accepts an
entity type representing the current Shotgun context. The expected return value
is a list of fields for that entity that should be queried for display. The
engine itself handles querying the data asynchronously.
Once the data has been queried from Shotgun, the second method in the hook is
called. This method, get_context_html()
, receives the context entity
dictionary populated with the queried fields specified by the
get_entity_fields()
method. The expected return value is a string containing
formatted HTML to display the queried entity fields.
The default hook implementation is a good reference as to what is required by these methods.
It should be noted that the engine will always display the entity thumbnail if one is available.
Photoshop API
The engine exposes the Javascript API for Photoshop CC to Python. The full docs for this API can be found here.
The Photoshop API object is exposed as engine.adobe
. The examples
below show how it is possible to directly manipulate the Photoshop DOM from
within Toolkit apps and hooks. The standard Toolkit apps also contain working
examples of how to interact with Photoshop documents.
Examples
Load a file:
f = adobe.File('/Path/To/File.jpeg') adobe.app.load(f)
Set the ruler units to PIXELS:
pixels = adobe.Units.PIXELS adobe.app.preferences.rulerUnits = pixels
Export the current doc for the web with default options:
temp_thumb_file = adobe.File(out_path) save_for_web = adobe.ExportType.SAVEFORWEB export_options = adobe.ExportOptionsSaveForWeb() adobe.app.activeDocument.exportDocument(temp_thumb_file, save_for_web, export_options)
Export each layer as a separate file:
doc = adobe.app.activeDocument layers = doc.artLayers layers = [layers[i] for i in xrange(layers.length)] original_visibility = [layer.visible for layer in layers] save_for_web = adobe.ExportType.SAVEFORWEB export_options = adobe.ExportOptionsSaveForWeb() for layer in layers: layer.visible = False for layer in layers: layer.visible = True out_file = adobe.File("c:/layer.%s.jpg" % str(layer.name)) doc.exportDocument( out_file, save_for_web, export_options, ) layer.visible = False for (i, layer) in enumerate(layers): layer.visible = original_visibility[i]
Environment variables
To aid in debugging, there are a set of environment variables that change some of the engine's default values:
SHOTGUN_ADOBE_HEARTBEAT_INTERVAL
- The Python heartbeat interval in seconds (default is 1 second). The legacy environment variable
SGTK_PHOTOSHOP_HEARTBEAT_INTERVAL
is also respected if set.
SHOTGUN_ADOBE_HEARTBEAT_TOLERANCE
- The number of heartbeat errors before
quitting (default is 2). The legacy environment variable
SGTK_PHOTOSHOP_HEARTBEAT_TOLERANCE
is also respected if set.
SHOTGUN_ADOBE_NETWORK_DEBUG
- Include additional networking debug messages
when logging output. The legacy environment variable
SGTK_PHOTOSHOP_NETWORK_DEBUG
is also respected if set.
SHOTGUN_ADOBE_PYTHON
- The path to the Python executable to use when launching the
engine. If not set, the system Python is used. If Photoshop is launched from a Python process, like Shotgun Desktop or via the tk-shell engine, the Python used by that process will be used by the Photoshop integration.
Note: Additional environment variables exist in the Adobe Framework. For details, please see the developer documentation.
App Developer notes
- Because the python process is separate from the Photoshop CC process, there is some work done within the engine to try to make the app windows show above the Photoshop window in as clean a manner as possible. One gotcha with this setup is the default option to use native OS windows for
QFileDialog
. If you are developing an app for use with this engine, be sure to set the option to not use the native dialog. See an example of this in the tk-multi-pythonconsole app.
Installation and Updates
Adding this Engine to the Shotgun Pipeline Toolkit
If you want to add this engine to Project XYZ, and an environment named asset, execute the following command:
> tank Project XYZ install_engine asset tk-photoshopcc
Updating to the latest version
If you already have this item installed in a project and you want to get the latest
version, you can run the update
command. You can either navigate to the
tank command that comes with that specific project, and run it there:
> cd /my_tank_configs/project_xyz > ./tank updates
Alternatively, you can run your studio tank
command and specify the project
name to tell it which project to run the update check for:
> tank Project XYZ updates
Collaboration and Evolution
![]() |
If you have access to the Shotgun Pipeline Toolkit, you also have access to the source code for all apps, engines and frameworks in Github where we store and manage them. Feel free to evolve these items; use them as a base for further independent development, make changes (and submit pull requests back to us!) or simply tinker with them to see how they have been built and how the toolkit works. You can access this code repository at https://github.com/shotgunsoftware/tk-photoshopcc. |
Special Requirements
- You need Shotgun Pipeline Toolkit Core API version v0.19.18 or higher to use this.
Configuration
Below is a summary of all the configuration settings used. These settings need to be defined in the environment file where you want to enable this App or Engine.
automatic_context_switch
Type: bool
Default Value: True
Description: Controls whether an active document change causes a context change.
shelf_favorites
Type: list
Description: Controls the registered commands that show up in the favorites shelf in the Shotgun panel. This is a list where each item is a dictionary with keys 'app_instance' and 'name'. The 'app_instance' key connects this entry to a particular app instance defined in the environment configuration file. The 'name' is a command name to make a favorite.
debug_logging
Type: bool
Description: Controls whether debug messages should be emitted to the logger
context_fields_display_hook
Type: hook
Default Value: {self}/context_fields_display.py
Description: Hook which controls how context fields are queried and displayed in the context header.
Release Notes
Welcome to the release notes for this Engine. Below you will find an overview of all the changes we did for each release. We try to be as detailed as possible and include all bugs we have fixed, features we have added and things that may have changed. If you have questions about a particular release, don't hesitate to contact our support team!
v1.8.2
2020-Dec-8
Switches from using the support email alias to pointing to the support site
v1.8.1
2020-Apr-21
A small fix for an issue that was stopping Shotgun Create being launched from Photoshop in Python 3.
v1.8.0
2020-Mar-12
Python 3 support added.
v1.7.5
2019-Dec-12
Fixes a bug with opening a file on the launch of Photoshop specifically on Windows.
Details:
Previous to the fix, launching Photoshop through Shotgun and passing a file, would not open the file if Photoshop was already running on Windows.
v1.7.4
2019-Nov-26
Supports Adobe's new installation path convention for 2020+ releases.
v1.7.3
2019-Nov-26
Added support for opening a file on startup.
Details:
When using this update, and the v0.3.1 release of tk-shotgun-launchpublish
you can now use the Toolkit action "Open In Associated Application" on a Photoshop PublishedFile
entity via the Shotgun site, to launch Photoshop CC with the Shotgun integration and open the chosen PublishedFile
.
v1.7.2
2019-Apr-11
Fixes a regression in export_as_jpeg
which caused generate_thumbnail
to fail.
v1.7.1
2019-Mar-18
Upgraded required core to be 0.18.164
v1.7.0
2019-Mar-14
Now utilizes a shared adobe framework.
Details:
This large refactor moves most of the business logic out of this engine and into a framework, shared between all adobe engines.
v1.6.3
2018-Sep-04
Reduces considerably the risk of a filename length issue on Windows.
v1.6.2
2018-Jun-14
Fixes post-launch context when a file is opened during engine initialization.
Details:
If a document was opened before the engine completed its initialization, Toolkit wouldn't know about the need to change the context. Since the context changing is based on document change events fired by Photoshop, if one is missed during init, we never receive it. The solution is a one-time check post engine initialization to ensure we're in the correct context, after which point we can rely entirely on the event-driven functionality.
v1.6.0
2018-May-17
Fixes for window parenting on Windows when PySide2/Qt5 is in use.
Details:
If the integration is making use of a Python environment that contains PySide2 on Windows, we're required to take a different approach to setting up window parenting for Toolkit apps. The way window ids work in Qt5 is different than in Qt4, and PySide2 does no expose the necessary pieces of the framework to be able to map from a Qt window id to an HWND. As such, we have to take a different approach to getting the HWND of our proxy parent widget than we do when Qt4/PySide is being used.
v1.5.3
2018-May-14
Now ensures that the work file folder exists when versioning up the work file during publishing.
Details:
This fix will make sure that the destination folder exists before saving the file. This mainly was an issue if your template had dynamic folders between the workarea and the actual file. For example, if you had a template that used a version folder like this: .../work/photoshop/{version}/{name}.{version}.psd
.
v1.5.2
2018-Apr-12
Bug fix addendum to pyside2 support in v1.5.1 - fixes unicode display issues.
v1.5.1
2018-Apr-05
PySide2 support and cleaner shutdown.
Details:
- The engine can now be used with either PySide2 or PySide.
- The engine shutdown has been improved to avoid potential crashes with threads deletion when quitting Photoshop.
v1.5.0
2018-Feb-23
Implements comparison logic for RPC proxy objects.
Details:
Comparison of ProxyWrapper objects previously didn't do anything useful. This implements equal (==) and not-equal (!=) magic methods for ProxyWrapper and adds the associated RPC logic to compare the wrapped objects in the remote interpreter.
v1.4.0
2018-Feb-01
Better supports roaming user profiles on Windows networks.
Details:
- When roaming user profiles are used on a Windows network, using the CEP api to get the path to the extension's root folder returns the path with any $ characters encoded as %24. We work around this issue in our code now to ensure that the extension initializes properly.
- The extension is now more fault tolerant to a missing .version file. This issue arises rarely, but was not handled gracefully.
- Publishing documents using tk-multi-publish2 no longer forces the use of the .psd extension. This was particularly a problem for clients that make use of .psb files in their pipeline.
v1.3.0
2017-Dec-22
Performance bug fixed and adds a helper method.
Details:
-
A performance problem existed when the active document was a file being read from network storage and resided in a deep filesystem structure. This was due to the activeDocument change polling that was used to trigger context changes in the panel extension. Instead of polling, we're now triggering context changes based on events fired by CEP.
-
Adds a helper method for getting the active document and active document path.
v1.2.1
2017-Dec-11
Bug fix:
- Uploaded Versions will now include the full filename as the Version name. Prior to this, the version number would be stripped.
v1.2.0
2017-Nov-08
Now houses publish2 plugin hooks and supports template-based worklfows
v1.1.7
2017-Sep-06
Improved jpeg exports.
Details:
- A new
export_as_jpeg
method is now available at the engine level. - Some problems with
generate_thumbnail
are now fixed by callingexport_as_jpeg
: - Documents are converted to 8 bits during the export.
- Documents size is now correctly retrieved and thumbnails are not generated anymore with the original document size.
- Photoshop native dialogs are disabled during the export.
- These improvements are available to any app already leveraging the
generate_thumbnail
method, e.g. tk-multi-publish2.
v1.1.5
2017-May-27
fixes saveAs typo
v1.1.4
2017-May-27
Adds additional save methods to engine to prevent context switching and to preserve the active document state
v1.1.3
2017-May-26
Wraps save as into active document setting
v1.1.2
2017-May-12
Rebuilt plugin at version 1.1.2
v1.1.1
2017-May-12
bumps required core version to v0.18.45
v1.1.0
2017-May-10
zero config updates
v1.0.17
2017-Mar-17
Converts active document paths that are unicode into utf-8 strings. This will better handle file paths that contain special characters.
v1.0.16
2017-Mar-16
Renames "context_follows_document" engine setting to "automatic_context_switch" to match that of the Houdini and Maya engines.
v1.0.15
2017-Mar-15
Adds "context_follows_document" engine setting.
Details:
Setting this to true will disable context changes when the active document is changed in Photoshop. Note that context changes will still occur as a result of loading a file with the workfiles app.
v1.0.13
2017-Mar-13
Fix for a bug related to context cache clearing on initial startup of SGTK.
v1.0.12
2017-Mar-09
Fix for a context cache bug that resulted in data missing from the cache when it shouldn't have been.
Details:
The complete fix for this bug in v1.0.11 will require v0.9.2 of tk-multi-workfiles2 in addition to the engine update here. This is a minor bug, though, which is tied to an edge case that most artist users will never encounter.
v1.0.11
2017-Mar-08
Refactors context caching to resolve inconsistent behavior during CEP extension restarts.
v1.0.10
2017-Feb-24
Engine startup active document fix, context header polish, and adds a getter method to the Adobe bridge class for getting the active document path.
Details:
The AdobeBridge getter helps resolve the issue surrounding attempted lookups of active document paths when the active document is "new" and has not been saved. The new getter properly handles that situation and returns None, rather than raising a RuntimeError and causing nasty log messages to be printed.
v1.0.4
2017-Feb-16
Panel console polish
v1.0.3
2017-Feb-07
Corrects the path delimiter used when adding to PYTHONPATH from javascript.
v1.0.2
2017-Feb-06
Reduces lag in py console and uses rpc when logging from py to js
v1.0.1
2017-Jan-31
Clickable command rows and minor polish.
v1.0.0
2017-Jan-30
Passed QA and ready for release!
v0.0.1
2017-Jan-20
First release candidate for the tk-photoshopcc engine!