# Layer Mapping Tables

Layer mapping tables are used to specify the behavior of the layout reader. Specifically, they define what actions are taken when a shape on a certain layer is encountered. They can be used to

- Filter layers
- Supply layer names for GDS layer and datatype combinations
- Map layers to different ones
- Combine different layers into the same layer

A layer mapping table consists of two specifications: a match expression and an optional target expression. If a shape is encountered, the reader looks up the shape's layer in the mapping table. If an entry is found whose match expression matches the layer of the shape, the shape is assigned a new layer given by the target expression if present. By assigning different match expressions the same target expressions, multiple input layers can be combined into a single one.

If no matching entry is found, the reader can be configured to either store the shape under the original layer or discard it. This option can be found in the reader options dialog as the "Read all layers" option. If that box is checked, the shapes are stored under their original layer and discarded if not.

A target expression can be used also to add information, specifically a layer name. In GDS there is no layer name but just a layer and datatype number. In OASIS, there is a layer name in addition. Other formats just use named layers and don't have the concept of layer number or datatype number. When the target expression specifies a layer name that name is used. That allows adding of OASIS layer names to GDS files for example. Layers with names are usually more useful than layers that just have a number.

The layer mapping table consists of lines, each specifying the match expression and optional target expression. The match and target expressions are separated by a colon. Each expression has the form "layer" (numeric), "layer/datatype" (both numberic), "name" (a string) or "name(layer)" or "name(layer/datatype)" (all specifications). When name and layer/datatype are specified in a match string, KLayout will first look for a matching layer/datatype and then for a matching layer name. The name match is case sensitive. For the numerical specifications, ranges are allowed using a hyphen for an interval and the comma for enumerations (see second example below).

Here are some examples:

1/0 or 1 | Matching layer 1, datatype 0
17/1-5,10 | Matching layer 17, datatypes 1 to 5 and 10
1/0:22 | Matching Layer 1, datatype 0. Shapes are shifted to layer 22, datatype 0
1/0:A | Matching layer 1, datatype 0. The name "A" is added to that layer
1/0:A(2/0) | Matching Layer 1, datatype 0 mapped. Shapes are shifted to layer 2, datatype 0 and name "A"
A | Matching named layer "A"
A:1/0 | Matching named layer "A". Shapes are shifted to layer 1, datatype 0

When the layer mapping is read from a file, each line corresponds to one entry. Blanks are ignored as are empty lines. Comments can be inserted using the "#" character in front of the comment.

## Wildcards

Source layers can be specified using wildcards. A wildcard is a "*" character matching "any layer". Examples for such expressions are:

10-*/0 | Matching layer 10 and above, datatype 0
*/10 | Matching datatype 10 of every layer
0-5,10-*/* | Matching layer 0 to 5 (inclusive) and above 10, all datatypes.

When ranges or wildcards are used as match expressions, the specified layers will be lumped together into a single layer. This layer will have the least permitted layer and datatype number. For example, with a match expression of "1-10/*", all these layers will be mapped to "1/0". This behavior can be modified using a target layer specification with wildcards.

## Wildcard expansion and relative layer mapping

If the match expression includes a numerical range or wildcards for the layer or datatype number, by default all these layers will be combined into a single one, where its layer or datatype number is derived from the least permitted number.

This behavior can be modified using wildcard expansion. This is a target layer which includes a "*" wildcard. This wildcard is substituted by the actual layer or datatype number:

10-*/0 : */10 | Maintain layers for layer 10 and above and map datatype to 10
10-*/0 : */* | Select layers 10 and above, datatype 0 and maintain these as individual layers
1/* : 2/* | Map layer number 1 to 2, maintain all datatypes

Relative layer mapping allows adding an offset to the layer or datatype numbers. This offset can be negative with undefined behavior when the resulting number goes below zero:

10-20/*: *+1000/* | Selects all layers between 10 and 20, all datatypes. These layers will be read into the original layers plus 1000 for the layer number.
10/10-*: */*-10 | Selects layer 10, datatypes 10 plus. The resulting datatypes will be 10 less starting from 0.

## Multi-mapping and unmapping

Layer mapping table support an advanced feature which is to duplicate input layers to a number of output layers (1:n) mapping. The feature is enabled by prepending a "+" to the mapping statement. The following statement will first select layer 5/0 and additionally copy it to layer 1000/0:

    5/0
    +5/0: 1000/0

Unmapping removes the mapping for a specific layer or range. It is specified by prepending "-" to the mapping expression. The following statement will map all datatypes of layer 5 to 0 except for datatype 10 which is not considered.

    5/*: 5/0
    -5/10

Unmapping cancels the mappings specified previously, so the order of statements becomes important when using unmapping and multi-mapping.

## Brackets

Square brackets can be used to imply mapping to the original layer. When putting square brackets around a mapping expression, the default target is "*/*", which means expansion to the original layer. Hence the following statements are identical:

    [1-10/*]
    1-10/* : */*

When combining this with "+" for multi-mapping, put "+" in front of the bracket.

You can put round brackets around mapping expressions for visual clarity, specifically when combining them with "-" (unmapping) or "+" (multi-mapping):

    -(1-10/*)
    +(17/0 : 1017/0)