ofn3-export-layers

# ofn-export-layers

This script is used to export all the image layers as separate files.

- The layers are saved at their actual size and are not resized to the canvas size if they are smaller.
- A name pattern is used to create the file names for the layers
- A directory hierarchy can be used to follow the layer group hierarchy

This script is called via the menu entry `File > Export all layers`.

### Parameters

- `Directory`: the directory where the layer images will be exported.
- `Output`: how layers and groups are exported:
  - `Directory hierarchy`: a subdirectory is created for each group to hold the layers in the group.
  - `Single directory`: all layers are exported to a single directory. If necessary the group structure can be retained in names using the `hierarchy` formatting value.
  - `Top-level only`: all layers and groups are exported to a single directory, with top-level groups flattened to a single image.
- `Layer name`: a pattern that defines the file name of the saved layers or groups. This pattern should include an image format extension (png, gif, jpg…) since it will be used by Gimp to determine how to save the layer.
- `Hierarchy separator`: the characters(s) used when creating the `hierarchy` string.
  - With one single character, the character is used as an inner separator and is also added at the end.
  - With two characters, the first is used as an inner separator and the second is added at the end.

### File name pattern

The file name pattern specifies how the layer files are named using specific layer data. In the pattern, names in braces are replaced by the values of these data for the layer. For instance, a pattern of `Layer-{numDown1}.png` will produce the name `Layer-2.png` for the 2nd layer from the top.

The available values are:

- `imageName`: the base name of the image (original name, stripped of its directory and extension). If the image has not been saved yet the value is `Untitled` (or whatever name Gimp uses for unnamed images in your language).
- `count`,`imageCount`: the number of layers in the image
- `groupCount`: the number of layers in the same group
- `name`: the name of the layer, with any extension stripped. If the layer has been duplicated and auto-renamed by Gimp, the “`copy`” or “`copy #n`” at the end of the extension is transferred to the name, so for instance for a layer named “`image22.jpg copy #1`” the `name` will be “`image22 copy #1`”.
- `rawName`: the name of the layer, without any changes
- `width`: the width of the saved layer
- `height`: the height of the saved layer
- `offsetX`: the offset of the layer from the left canvas border
- `offsetY`: the offset of the layer from the top canvas border
- `numUp0`, `numUp1`, `numDown0`, `numDown1`, `imageNumUp0`, `imageNumUp1`, `imageNumDown0`, `imageNumDown1`, `groupNumUp0`, `groupNumUp1`, `groupNumDown0`, `groupNumDown1`, : the position of the layer in the stack.
  - The `num...` and `imageNum...` values are identical, and are a layer index in the image. No two layers will have this same index so this can be used to differentiate layers when exporting all layers in the same directory.
  - The `groupNum...` values are a layer index in its parent group (or in the base image if not in a group)
  - Values ending with `0` start at 0 (as computers count), while those ending with `1` start at `1` (as humans count).
  - The `...Up...` values count from the bottom (so number 0 or 1 is the “background” layer), while `...Down...` values count from the top (so number 0 or 1 is the top layer).
- `parent`: the name of the parent group
- `hierarchy`: a string representing the group hierarchy, which is all the parent groups names concatenated with the hierarchy separator, and followed with the hierarchy terminator. The hierarchy string is empty for top-level layers. This value is best used when the image is not exported to directories.

### Hints:

The name pattern is actually directly used as a Python format specification, so modifiers can be used. The most useful modifier for numbers is the ability to define a minimal length with zero-padding. This is done by adding `:0Nd` to the variable name in the braces, for instance `{numDown1:03d}` will insert the row number on at least three digits, with zeroes added to the left if necessary: `001`, `013`, `099`, `100`.

### Examples

Given an image with this layer structure:

- The `Directory hierarchy` export with pattern `{name.png}` yields:

    .
    ├── Group1
    │   ├── Layer2.png
    │   ├── Layer4.png
    │   └── SubGroup
    │       └── Layer3.png
    ├── Group2
    │   └── Layer5.png
    ├── Layer1.png
    └── Layer6.png

- The `Single directory` export with pattern `{hierarchy}{name}.png` and separator `-#` yields:

    .
    ├── Group1#Layer2.png
    ├── Group1#Layer4.png
    ├── Group1-SubGroup#Layer3.png
    ├── Group2#Layer5.png
    ├── Layer1.png
    └── Layer6.png

- The `Top-level` export with pattern `{hierarchy}{name}.png` and separator `-#` yields:

    .
    ├── Group1.png
    ├── Group2.png
    ├── Layer1.png
    └── Layer6.png

where `Group1` is the contents of `Layer2+Layer3+Layer4` and `Group2` is the contents of `Layer5`