# ofn3-interleave-layers

## Purpose

This script creates a new image by interleaving layers between layers of the current image. It covers two different modes of operations:

- Layers from the current image are interleaved with another set of layers from another image. This is typically used to combine two animations.
- Layers from the current image are interleaved with copies of single layer which is placed above or under them. This is typically used to add a fixed image part (such as a title) to all frames in an animation, or a fixed background over an animated object (sprite).

The top layer of each pair can be merged to the underlying layer with a given transparency and layer mode. The first set of layers comes from the calling image (the one through which the script is called).

In multiple-layer mode, the inserted layers come from another image already loaded in Gimp.

In single layer mode, the inserted layer can come from any loaded image (including the one used as a source for the base layers)

The script uses the selected layers in the calling image, and will not be enabled in the menus if there is only one selected layer. For multiple-layer mode both layer sets should hold the same number of layers.

The script only works on full-RGB or grayscale images.

## Usage

The script is started by the `Image > Interleave layers` menus. This menu is disabled if: * The image is color indexed (GIF, and sometimes PNG). You need to convert the image to full-RGB or grayscale mode first. * There are no selected layers or only one selected layer in the image (this script expects multiple layers as input)

### Parameters

- Image (multiple-layer mode): The image from which the inserted layers are obtained. This is another image also opened in Gimp, not an image file from the disk. For the time being (Gimp 3.00RC1) there is no widget to select an image so you use a widget to select any layer in the source image.
- Layer (single-layer mode): The layer which is interleaved with the current image layers. This is a layer from the current image or from another image already opened in Gimp.
- Position: Wether the inserted layers are over or under the layers in the calling image.
- Opacity: An opacity to be applied to the top layer of each pair.
- Mode: A layer mode to be applied to the top layer of each pair.
- Merge: If true, the top layers of each pair are directly merged into the other layers, using the specified opacity and layer mode. The resulting layer is given the name of its component from the source image.

## Usage hints

### Input image

If you deal with animations (in particular, GIFs) make sure that the images are not optimized (layers marked with `(combine)`). If so, de-optimize the image with `Filters > Animation > Unoptimize`. You can re-optimize them later.

If the image is color-indexed you have to convert it to full-RGB or grayscale before using the script.

### Use of groups

Groups are supported in both the calling and the source image. They are copied verbatim, and flattened if you use the `merge` option.

Warning: selecting a layer group is not the same as selecting a layer group and its child layers. In the first case you have one frame to copy, in the second you have three.

### Output image

The output image is created with the same dimensions, type, and precision/encoding as the calling image. So the difference between interleaving layers from `A` above layers in `B`, and interleaving layers from `B` under layers in `A` is that in the first case the output image inherits its characteristics from `B` and in the second case it inherits them from `A`.

### Positioning the merged layers in the result

The layers are copied to the output image with the size and offsets from their origin image.

Here is how you can easily achieve two frequent use cases:

#### Combining two animations

- Compute the total size of the canvas (add the widths if side-y-side or the heights if on top of each other)
- In each animation image: `Image > Canvas size`, and:
  - Set the canvas dimensions
  - Use the position widget to indicate where the current image will be in the bigger canvas. You probably want to pull one image to a side and the other to the opposite side if combining them side-by-side.
  - You can then merge the two animations

#### Positioning an animation over a background

- Open the background image
- Use `File > Open as layers` to load all the animation layers
- In the Layers list, do a multiple selection on the animation layers (the fastest way is often to use `[Ctrl-A]` to select all layers, and then to remove a few layers (for instance the ones from the background) by Ctrl-clicking them).
- With the Move tools set to `Move selected layers` you can now move all the animations layersone of the layers, this will move all the chained layers. as a whole.
- Keeping the same layers selected, you can invoke `Interleave layers` to insert the background image under each layer of the animation.