Notation used in Ruby API documentation
Module: db
Description: An object representing an arbitrary mapping of physical layers to logical layers
"Physical" layers are stream layers or other separated layers in a CAD file. "Logical" layers are the layers present in a Layout object. Logical layers are represented by an integer index while physical layers are given by a layer and datatype number or name. A logical layer is created automatically in the layout on reading if it does not exist yet.
The mapping describes an association of a set of physical layers to a set of logical ones, where multiple physical layers can be mapped to a single logical one, which effectively merges the layers.
For each logical layer, a target layer can be specified. A target layer is the layer/datatype/name combination as which the logical layer appears in the layout. By using a target layer different from the source layer renaming a layer can be achieved while loading a layout. Another use case for that feature is to assign layer names to GDS layer/datatype combinations which are numerical only.
LayerMap objects are used in two ways: as input for the reader (inside a LoadLayoutOptions class) and as output from the reader (i.e. Layout::read method). For layer map objects used as input, the layer indexes (logical layers) can be consecutive numbers. They do not need to correspond with real layer indexes from a layout object. When used as output, the layer map's logical layers correspond to the layer indexes inside the layout that the layer map was used upon.
This is a sample how to use the LayerMap object. It maps all datatypes of layers 1, 2 and 3 to datatype 0 and assigns the names 'ONE', 'TWO' and 'THREE' to these layout layers:
lm = RBA::LayerMap::new
lm.map("1/0-255 : ONE (1/0)")
lm.map("2/0-255 : TWO (2/0)")
lm.map("3/0-255 : THREE (3/0)")
# read the layout using the layer map
lo = RBA::LoadLayoutOptions::new
lo.layer_map.assign(lm)
ly = RBA::Layout::new
ly.read("input.gds", lo)
1:n mapping is supported: a physical layer can be mapped to multiple logical layers using 'mmap' instead of 'map'. When using this variant, mapping acts additive. The following example will map layer 1, datatypes 0 to 255 to logical layer 0, and layer 1, datatype 17 to logical layers 0 plus 1:
lm = RBA::LayerMap::new
lm.map("1/0-255", 0) # (can be 'mmap' too)
lm.mmap("1/17", 1)
'unmapping' allows removing a mapping. This allows creating 'holes' in mapping ranges. The following example maps layer 1, datatypes 0 to 16 and 18 to 255 to logical layer 0:
lm = RBA::LayerMap::new
lm.map("1/0-255", 0)
lm.unmap("1/17")
The LayerMap class has been introduced in version 0.18. Target layer have been introduced in version 0.20. 1:n mapping and unmapping has been introduced in version 0.27.
| new LayerMap ptr | new | Creates a new object of this class |
| [const] | LayerMap ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly destroys the object | ||
| [const] | bool | _destroyed? | Returns a value indicating whether the object was already destroyed | |
| [const] | bool | _is_const_object? | Returns a value indicating whether the reference is a const reference | |
| void | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | assign | (const LayerMap other) | Assigns another object to self | |
| void | clear | Clears the map | ||
| [const] | new LayerMap ptr | dup | Creates a copy of self | |
| [const] | bool | is_mapped? | (const LayerInfo layer) | Check, if a given physical layer is mapped |
| [const] | unsigned int[] | logicals | (const LayerInfo layer) | Returns the logical layers for a given physical layer.n@param layer The physical layer specified with an LayerInfo object. |
| void | map | (const LayerInfo phys_layer, unsigned int log_layer) | Maps a physical layer to a logical one | |
| void | map | (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer) | Maps a physical layer to a logical one with a target layer | |
| void | map | (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer) | Maps a physical layer interval to a logical one | |
| void | map | (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties) | Maps a physical layer interval to a logical one with a target layer | |
| void | map | (string map_expr, int log_layer = -1) | Maps a physical layer given by a string to a logical one | |
| [const] | LayerInfo | mapping | (unsigned int log_layer) | Returns the mapped physical (or target if one is specified) layer for a given logical layer |
| [const] | string | mapping_str | (unsigned int log_layer) | Returns the mapping string for a given logical layer |
| void | mmap | (const LayerInfo phys_layer, unsigned int log_layer) | Maps a physical layer to a logical one and adds to existing mappings | |
| void | mmap | (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer) | Maps a physical layer to a logical one, adds to existing mappings and specifies a target layer | |
| void | mmap | (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer) | Maps a physical layer from the given interval to a logical one and adds to existing mappings | |
| void | mmap | (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties) | Maps a physical layer from the given interval to a logical one, adds to existing mappings and specifies a target layer | |
| void | mmap | (string map_expr, int log_layer = -1) | Maps a physical layer given by an expression to a logical one and adds to existing mappings | |
| [const] | string | to_string | Converts a layer mapping object to a string | |
| void | unmap | (const LayerInfo phys_layer) | Unmaps the given layer | |
| void | unmap | (const LayerInfo pl_start, const LayerInfo pl_stop) | Unmaps the layers from the given interval | |
| void | unmap | (string expr) | Unmaps the layers from the given expression |
| LayerMap | from_string | (string s) | Creates a layer map from the given string |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead | |
| [const] | int | logical | (const LayerInfo layer) | Use of this method is deprecated |
_const_cast | Signature: [const] LayerMap ptr _const_cast Description: Returns a non-const reference to self. Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects. This method has been introduced in version 0.29.6. | |||||||
_create | Signature: void _create Description: Ensures the C++ object is created Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. | |||||||
_destroy | Signature: void _destroy Description: Explicitly destroys the object Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. | |||||||
_destroyed? | Signature: [const] bool _destroyed? Description: Returns a value indicating whether the object was already destroyed This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. | |||||||
_is_const_object? | Signature: [const] bool _is_const_object? Description: Returns a value indicating whether the reference is a const reference This method returns true, if self is a const reference. In that case, only const methods may be called on self. | |||||||
_manage | Signature: void _manage Description: Marks the object as managed by the script side. After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required. Usually it's not required to call this method. It has been introduced in version 0.24. | |||||||
_unmanage | Signature: void _unmanage Description: Marks the object as no longer owned by the script side. Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur. Usually it's not required to call this method. It has been introduced in version 0.24. | |||||||
assign | Signature: void assign (const LayerMap other) Description: Assigns another object to self | |||||||
clear | Signature: void clear Description: Clears the map | |||||||
create | Signature: void create Description: Ensures the C++ object is created Use of this method is deprecated. Use _create instead Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. | |||||||
destroy | Signature: void destroy Description: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. | |||||||
destroyed? | Signature: [const] bool destroyed? Description: Returns a value indicating whether the object was already destroyed Use of this method is deprecated. Use _destroyed? instead This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. | |||||||
dup | Signature: [const] new LayerMap ptr dup Description: Creates a copy of self Python specific notes: | |||||||
from_string | Signature: [static] LayerMap from_string (string s) Description: Creates a layer map from the given string The format of the string is that used in layer mapping files: one mapping entry per line, comments are allowed using '#' or '//'. The format of each line is that used in the 'map(string, index)' method. This method has been introduced in version 0.23. | |||||||
is_const_object? | Signature: [const] bool is_const_object? Description: Returns a value indicating whether the reference is a const reference Use of this method is deprecated. Use _is_const_object? instead This method returns true, if self is a const reference. In that case, only const methods may be called on self. | |||||||
is_mapped? | Signature: [const] bool is_mapped? (const LayerInfo layer) Description: Check, if a given physical layer is mapped
| |||||||
logical | Signature: [const] int logical (const LayerInfo layer) Description: Returns the logical layer (the layer index in the layout object) for a given physical layer.n@param layer The physical layer specified with an LayerInfo object.
Use of this method is deprecated This method is deprecated with version 0.27 as in this version, layers can be mapped to multiple targets which this method can't capture. Use logicals instead. | |||||||
logicals | Signature: [const] unsigned int[] logicals (const LayerInfo layer) Description: Returns the logical layers for a given physical layer.n@param layer The physical layer specified with an LayerInfo object.
This method has been introduced in version 0.27. | |||||||
map | (1) Signature: void map (const LayerInfo phys_layer, unsigned int log_layer) Description: Maps a physical layer to a logical one
In general, there may be more than one physical layer mapped to one logical layer. This method will add the given physical layer to the mapping for the logical layer. | |||||||
(2) Signature: void map (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer) Description: Maps a physical layer to a logical one with a target layer
In general, there may be more than one physical layer mapped to one logical layer. This method will add the given physical layer to the mapping for the logical layer. This method has been added in version 0.20. | ||||||||
(3) Signature: void map (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer) Description: Maps a physical layer interval to a logical one
This method maps an interval of layers l1..l2 and datatypes d1..d2 to the mapping for the given logical layer. l1 and d1 are given by the pl_start argument, while l2 and d2 are given by the pl_stop argument. | ||||||||
(4) Signature: void map (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties) Description: Maps a physical layer interval to a logical one with a target layer
This method maps an interval of layers l1..l2 and datatypes d1..d2 to the mapping for the given logical layer. l1 and d1 are given by the pl_start argument, while l2 and d2 are given by the pl_stop argument. This method has been added in version 0.20. | ||||||||
(5) Signature: void map (string map_expr, int log_layer = -1) Description: Maps a physical layer given by a string to a logical one
The string expression is constructed using the syntax: "list[/list][;..]" for layer/datatype pairs. "list" is a sequence of numbers, separated by comma values or a range separated by a hyphen. Examples are: "1/2", "1-5/0", "1,2,5/0", "1/5;5/6". layer/datatype wildcards can be specified with "*". When "*" is used for the upper limit, it is equivalent to "all layer above". When used alone, it is equivalent to "all layers". Examples: "1 / *", "* / 10-*" Named layers are specified simply by specifying the name, if necessary in single or double quotes (if the name begins with a digit or contains non-word characters). layer/datatype and name descriptions can be mixed, i.e. "AA;1/5" (meaning: name "AA" or layer 1/datatype 5). A target layer can be specified with the ":<target>" notation, where target is a valid string for a LayerProperties() object. A target can include relative layer/datatype specifications and wildcards. For example, "1-10/0: *+1/0" will add 1 to the original layer number. "1-10/0-50: * / *" will use the original layers. If the logical layer is negative or omitted, the method will select the next available one. Target mapping has been added in version 0.20. The logical layer is optional since version 0.28. | ||||||||
mapping | Signature: [const] LayerInfo mapping (unsigned int log_layer) Description: Returns the mapped physical (or target if one is specified) layer for a given logical layer
In general, there may be more than one physical layer mapped to one logical layer. This method will return a single one of them. It will return the one with the lowest layer and datatype. | |||||||
mapping_str | Signature: [const] string mapping_str (unsigned int log_layer) Description: Returns the mapping string for a given logical layer
The mapping string is compatible with the string that the "map" method accepts. | |||||||
mmap | (1) Signature: void mmap (const LayerInfo phys_layer, unsigned int log_layer) Description: Maps a physical layer to a logical one and adds to existing mappings This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping. Multi-mapping has been added in version 0.27. | |||||||
(2) Signature: void mmap (const LayerInfo phys_layer, unsigned int log_layer, const LayerInfo target_layer) Description: Maps a physical layer to a logical one, adds to existing mappings and specifies a target layer This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping. Multi-mapping has been added in version 0.27. | ||||||||
(3) Signature: void mmap (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer) Description: Maps a physical layer from the given interval to a logical one and adds to existing mappings This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping. Multi-mapping has been added in version 0.27. | ||||||||
(4) Signature: void mmap (const LayerInfo pl_start, const LayerInfo pl_stop, unsigned int log_layer, const LayerInfo layer_properties) Description: Maps a physical layer from the given interval to a logical one, adds to existing mappings and specifies a target layer This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping. Multi-mapping has been added in version 0.27. | ||||||||
(5) Signature: void mmap (string map_expr, int log_layer = -1) Description: Maps a physical layer given by an expression to a logical one and adds to existing mappings This method acts like the corresponding 'map' method, but adds the logical layer to the receivers of the given physical one. Hence this method implements 1:n mapping capabilities. For backward compatibility, 'map' still substitutes mapping. If the logical layer is negative or omitted, the method will select the next available one. Multi-mapping has been added in version 0.27. The logical layer is optional since version 0.28. | ||||||||
new | Signature: [static] new LayerMap ptr new Description: Creates a new object of this class Python specific notes: | |||||||
to_string | Signature: [const] string to_string Description: Converts a layer mapping object to a string This method is the inverse of the from_string method. This method has been introduced in version 0.23. | |||||||
unmap | (1) Signature: void unmap (const LayerInfo phys_layer) Description: Unmaps the given layer Unmapping will remove the specific layer from the mapping. This method allows generating 'mapping holes' by first mapping a range and then unmapping parts of it. This method has been introduced in version 0.27. | |||||||
(2) Signature: void unmap (const LayerInfo pl_start, const LayerInfo pl_stop) Description: Unmaps the layers from the given interval This method has been introduced in version 0.27. | ||||||||
(3) Signature: void unmap (string expr) Description: Unmaps the layers from the given expression This method has been introduced in version 0.27. |