Understanding Layer IDs and Layer Indices

In the result from a Generator.prototype.getDocumentInfo, layers have both "id" fields and "index" fields. The layer ID does not change when the layer moves around in the layer tree — it stays with the layer for the life of the layer. The layer index represents the layer's position in the layer tree. So, if you move a layer, its ID will stay the same, but its index will change.

Starting with version 3.1 of generator-core, the layerSpec parameter in the Generator.prototype.getPixmap method has two different forms. In the simpler form, the caller can pass in just a layer ID (not index) as a single number, and that layer will be rendered. If that layer happens to be a group, the group will be composited using the current visibility settings of all its children. This is the "old" form of the getPixmap method, and operates as it always has since version 1.0.

The new form takes an object that specifies layer ranges and layers to hide. This form operates on layer indexes, not on layer IDs. The object has two required parameters: firstLayerIndex and lastLayerIndex. These ranges are inclusive: both firstLayerIndex and lastLayerIndex will appear in the output. The object also has an optional property, hidden, which is an array of layer indices to hide in the output. If this is not specified, all layers will end up in the pixmap (regardless of whether they are shown or hidden in the document).

Indices are a bit complicated with respect to groups. Every group has a "hidden" layer at the end of the group that gets its own index. This is because, internally in PS, the layer tree is stored as a 1-dimensional array. These hidden layers are what are used to determine when a group ends and the hierarchy should go up one level for the next layer. In Generator's getDocumentInfo method, we return a tree structure for layers. So, these hidden layers are not present.

If a caller wants to hide a group in a call to getPixmap, the caller needs to pass in all of the indices involved in that group, including: the index of the start of the group, the indices of all actual layers in the group, and the index of the "hidden" layer that ends the group. Depending on the layer configuration (e.g. clipping masks, etc.), failing to specify all of these indices might lead to unexpected results.

As an example, consider a layer structure like this:

• Layer 6
• Group 1
  • Layer 5
  • Group 2
    • Layer 4
    • Layer 3
  • Layer 2
• Layer 1
• Background

This would have the following indices (adding hidden layers):

• Layer 6 : index 10
• Group 1 : index 9
  • Layer 5 : index 8
  • Group 2 : index 7
    • Layer 4 : index 6
    • Layer 3 : index 5
    • [Hidden layer ending Group 2] : index 4
  • Layer 2 : index 3
  • [Hidden layer ending Group 1] : index 2
• Layer 1 : index 1
• Background : index 0

To hide all of Group 1 (including Group 2), the caller would specify this layerSpec:

layerSpec = {
  firstLayerIndex: 0,
  lastLayerIndex: 10,
  hidden: [9,8,7,6,5,4,3,2]
};

To hide only Group 2, the caller would specify this layerSpec:

layerSpec = {
  firstLayerIndex: 0,
  lastLayerIndex: 10,
  hidden: [7,6,5,4]
};