Swap drawings easily with the QuickSwap

Library View script for Toon Boom Harmony

Download - QuickSwap v.1.0.6

(for Harmony 15: see details here)

You can download the QuickSwap script for Toon Boom Harmony here.

Download

Help - Table Of Contents

1. Introduction:

What is QuickSwap?

How to use the QuickSwap script

One important thing to know

2. All About Thumbnails:

Two different types of thumbnails

When to use which thumbnail type

Make better use of native thumbnails with QuickSwap 1.0.6 in Harmony 15

How to create the missing thumbnails (Harmony 15) - (contains videos)

How to create the missing thumbnails (Harmony 14 and older)

What is the best minimum drawing size when using native thumbnails?

3. More Knowledge:

Displayed Image Order

More features

4. Miscellaneous:

Changelog

Compatibility

Acknowledgments

QuickSwap is a free script for Toon Boom Harmony making swapping drawing substitutions like hands or mouths (for lip syncing) easier. It allows you to display up to 20 substitution images of your drawing library all at once. And this in several different ways.

Select a drawing layer and click on the 'Load' button.

You're done, the buttons will display the thumbnails of the layer's substitution images.

Now, you can directly swap to the drawing substitution that you want by picking it from the QuickSwap view.

If you are making cut-out animation in Toon Boom Harmony, QuickSwap will speed up your workflow and will especially make the lip sync process more comfortable.

QuickSwap will only display the thumbnails of the SAVED drawings. So, before loading or reloading the drawing substitution images, don't forget to save your scene in order to be sure to see the thumbnails show the latest version of your drawings.

QuickSwap is able to display 2 different types of thumbnails.

Thumbnails created via QuickSwap:

Tumbnails of the first type are created via QuickSwap every time the user clicks on the the "Load Drawings" button and the "Display existing native thumbnails" checkbox is unticked.

Unfortunately, these images can't show drawing elements of the Overlay and Underlay layers.

These thumbnails have a tranparent background.

Native Harmony thumbnails:

Thumbnails of the second type are the thumbnails that are created by Harmony.

These are the thumbnails that Harmony displays in the "Substitution Library" view and which it uses for the the timeline thumbnails introduced in Harmony 15.

In order to display native Harmony thumbnails tick the "Display existing native thumbnails" checkbox.

Native Harmony thumbnails display Overlay, Line Art, Color Art and Underlay layers

The background colour of these thumbnails is white .

The answer to this question depends on your priorities and on your usage of Overlay and Underlay layers.

In order to decide which thumbnail type to use have a look at the following list of the pros and cons of each thumbnail type.

QuickSwap thumbnails:

PROS:

Thumbnails use full button size to display image

CONS:

Thumbnails only display Line Art and Color Art layers (no Overlay and Underlay layers)

Thumnails must be recreated by QuickSwap every time the drawing is reloaded by the script. This makes the process a bit slower.

Native Harmony thumbnails:

PROS:

garantees that Overlay, Line Art, Color Art and Underlay layers are displayed properly

CONS:

Displayed button thumbnails may be very small for small drawings*.

But, you can prevent this problem by preparing your work. (see What is the best minimum drawing size when using native thumbnails?)
* An interesting background information: Thumbnails generated for templates from the library view are cropped to the size of the drawing!!!!! But we unfortunatly cannot benefit from that here.

It requires some extra clicks to get them (espacially in versions prior to Harmony 15)

If your drawings were created in Harmony 15 their native thumbnails will be displayed on the QuickSwap buttons witout any problem.

If your drawings were created in a previous version of Harmony, the displayed result might look like this.

Harmony 15 creates a new thumbnail image once a drawing is created or modified and updates it at latest when the scene file is saved.

The program will create or update the tumbnails it at latest when the scene file is saved.

Harmony 15 also creates and updates a thumbnail when the drawing is displayed:

in the 'Substitution Library' view

in the timeline when the drawing layer is set to timeline thumbnails mode.

Previous versions of Harmony 15 didn't create thumbnails in this sytematic way. That's why images created in an older version may not have their corresponding native thumbnail yet.

In order to create the thumbnails for these substitution drawings and to make them available for QuickSwap, these drawings must be exposed at least once in the current scene.

Here are several methods you can use to create native thumbnails for your drawings in Harmony 15:

For a single drawing layer:

Expose every substitution drawing once on the same frame, using the drawing substitution slider. (You don't need to release the curser.)*

Expose every missing substitution drawing once by clicking on the corresponding QuickSwap button.*

Expose every substitution drawing once, using QuickSwap's "Expose All Drawing Substitutions" function**. (You can undo that action using CTRL+Z/CMD+Z.)
Move the timeline curser over every exposed drawing frame once. (You don't need to release the curser.) Be sure that your drawing layer is still selected.*

Expose every substitution drawing once using the keyboard
shortcuts '[' and ']' *

Display temporarely the timeline thumbnails of the selected layer

and

SAVE the scene file!

For several drawing layers:

Expose every substitution drawing once, using QuickSwap's "Expose All Drawing Substitutions" function**. This function can be run on several layers at the same time. (You can undo that action using CTRL+Z/CMD+Z.)
Display temporarely the timeline thumbnails of the layers or use the "Show/Hide All Thumbnails" button in the Layers toolbar of the Timeline view.
Browse and pan through your timeline to make sure that the timeline thumbnails of your targeted layers are displayed at least temporarely in the visible area of the timeline.

and

SAVE the scene file!

*(Be sure that the image is displayed in the 'Substitution Library' view.)

**(A similar script for this function called Expose All Drawings was made in 2014 by William Saito of www.toonboomscripts.com. Unfortunately, the script's download link is broken for instance.)

When you reload the image to QuickSwap (by clicking the 'Load Drawings' button) the thumbnails will be displayed properly.

These steps are necessary at the moment when you migrate your scene from an older version of Harmony to Harmony 15.

They also may become usefull when you have changed a drawing without the image being displayed in the 'Substitution Library' or as a timeline thumbnail.

e.g. palette colour change

When saving the file, Harmony 15 creates and updates the thumbnails of every drawing created or modified in the scene. So, you won't have to manually create any other drawing thumbnails for this scene very often later.

P.S. Of course, the best solution would be if Harmony had a built in scripting command like this:

IF (the drawing doesn't have a thumbnail yet OR IF it was changed)

{

create_a_thumbnail_NOW.()

}

If you read this message and if you know about a hidden scripting command like this, let me know!!!!!! :)

This would help to get rid of the previously described manual steps.

Unfortunately, by default, QuickSwap will only be able to preview the Line Art and Colour Art layers of your drawings.

Overlay and Underlay layers can't be accessed that way via scripting.

But there is a workaround requiring a few extra clicks (Harmony 14 and older):

Thumbnails generated directly via Toon Boom Hamony contain the Overlay and Underlay layers.

In order to use these thumbnails to be displayed in QickSwap you would have to do the following:

1. Generate these thumbnails from the library explorer by right-clicking on the drawing's folder and selecting 'Generate Thumbnails' in the drop down menu. Alternatively, you can also select 'Refresh' or hit 'F5'.

2. Hit the 'Load' button as usual.

Buttons displaying thumbnails generated via QuickSwap

3. Tick the checkbox to replace QuickSwap's thumbnails with those generated via the library explorer.

Ticked checkbox loading native Harmony thumbnails displaying Overlay,

Line Art, Color Art and Underlay layers

(backgrounds of thumbnails generated via TB Harmony are white)

Let's take as an example a drawing layer with 15 substitution drawings of a growing square.

The loaded thumbnails are displayed like this:

We can see that the thumbnails of the drawings before image number 8 don't use the maximum surface of the button.

Whereas the thumbnails of the following drawings don't get considerably larger than the one of image number 8.

So, we can conclude that if you want to be sure that your drawing thumbnail will make a good use of the button surface, your drawing should not be smaller than drawing number 8.

You can download the Harmony file of the example here (Harmony 14 & 15).

Be sure to use a consistent number of digits when numbering images of a contiguous set of images. In other words, fill empty spaces with zeros.

E.g., a set of happy mouth images that are named 'happy_01', 'happy_02', ..., 'happy_10' will be displayed in the right order.

(this image, indeed, doesn't show happy mouth images)

Whereas, images named 'happy_1', 'happy_2', ..., 'happy_10' will be displayed in the following order: 'happy_1', 'happy_10', 'happy_2', ...

1. Scalable user interface:

The 'Zoom' function allows you to display the thumbnails at a bigger size.

2. QuickSwap stays connected to the loaded layer:

Once you've loaded the drawing substitutions of a layer, you'll be able to swap that layer's images, even when you have selected another one.

3. Use QuickSwap on several layers at the same time:

You can open the script several times which allows you to swap the drawings of different layers in parallel.

Version 1.0.2:

- Added page numbers

Version 1.0.3:

- Added scalable GUI

- Added function to replace QuickSwap thumbnails with native Toon Boom Harmony thumbnails

Version 1.0.3.1:

- last used GUI settings are restored at script relaunch

Version 1.0.3.2:

- fixed GUI settings reload issue that occured at script start up

Version 1.0.3.3:

- now also works with Harmony Server

Version 1.0.4:

- fixed Sync Layer bug causing that thumbnails of the master layer were diplayed instead of those of the selected Sync Layer

Version 1.0.5:

- changed script's behaviour for QuickSwap running in Harmony 15, when using Harmony's native thumbnails (in order benefit of the new way native thumbnails are created in Harmony 15)

- added 'Expose All Drawings' function for QuickSwap running in Harmony 15

Version 1.0.6:

- bugfix: there still was an issue with Sync Layers.

Now, the script displays properly the thumbnails of the selected Sync Layer.

The QuickSwap script should run in the versions 10, 11, 12, 14 and 15 of Toon Boom Harmony.

It works in Offline (Stand Alone) and Online mode (when working with Harmony Server).

Many thanks to William Saito for his website www.toonboomscripts.com and the scripts he provides there.

His website is one of the rare places in the under-developed world additional scripts for Toon Boom Harmony.

A piece of QuickSwap's code (the one allowing to place all resource files into the same directory) is based on William's script Selection Sets 2.0.