Notation used in Ruby API documentation
Module: db
Description: An iterator delivering shapes that touch or overlap the given region recursively
The iterator can be obtained from a layout, specifying a starting cell, a layer and optionally a region. It simplifies retrieval of shapes from a geometrical region while considering subcells as well. Some options can be specified, i.e. the level to which to look into or shape classes and shape properties. The shapes are retrieved by using the shape method, next moves to the next shape and at_end tells, if the iterator has move shapes to deliver.
This is some sample code:
# print the polygon-like objects as seen from the initial cell "cell"
iter = layout.begin_shapes(cell_index, layer)
while !iter.at_end?
if iter.shape.renders_polygon?
polygon = iter.shape.polygon.transformed(iter.itrans)
puts "In cell #{iter.cell.name}: " + polyon.to_s
end
iter.next
end
Layout offers three methods to get these iterators: begin_shapes, begin_shapes_touching and begin_shapes_overlapping. Layout#begin_shapes will deliver a standard recursive shape iterator which starts from the given cell and iterates over all child cells. Layout#begin_shapes_touching delivers a RecursiveShapeIterator which delivers the shapes whose bounding boxed touch the given search box. Layout#begin_shapes_overlapping delivers all shapes whose bounding box overlaps the search box.
A RecursiveShapeIterator object can also be created explicitly. This allows some more options, i.e. using multiple layers. A multi-layer recursive shape iterator can be created like this:
iter = RBA::RecursiveShapeIterator::new(layout, cell, [ layer_index1, layer_index2 .. ])
"layout" is the layout object, "cell" the RBA::Cell object of the initial cell. layer_index1 etc. are the layer indexes of the layers to get the shapes from. While iterating, RecursiveShapeIterator#layer delivers the layer index of the current shape.
The recursive shape iterator can be confined to a maximum hierarchy depth. By using max_depth=, the iterator will restrict the search depth to the given depth in the cell tree.
In addition, the recursive shape iterator supports selection and exclusion of subtrees. For that purpose it keeps flags per cell telling it for which cells to turn shape delivery on and off. The select_cells method sets the "start delivery" flag while unselect_cells sets the "stop delivery" flag. In effect, using unselect_cells will exclude that cell plus the subtree from delivery. Parts of that subtree can be turned on again using select_cells. For the cells selected that way, the shapes of these cells and their child cells are delivered, even if their parents was unselected.
To get shapes from a specific cell, i.e. "MACRO" plus its child cells, unselect the top cell first and the select the desired cell again:
# deliver all shapes inside "MACRO" and the sub-hierarchy:
iter = RBA::RecursiveShapeIterator::new(layout, cell, layer)
iter.unselect_cells(cell.cell_index)
iter.select_cells("MACRO")
Note that if "MACRO" uses library cells for example which are used otherwise as well, the iterator will only deliver the shapes for those instances belonging to "MACRO" (directly or indirectly), not those for other instances of these library cells.
The unselect_all_cells and select_all_cells methods turn on the "stop" and "start" flag for all cells respectively. If you use unselect_all_cells and use select_cells for a specific cell, the iterator will deliver only the shapes of the selected cell, not its children. Those are still unselected by unselect_all_cells:
# deliver all shapes of "MACRO" but not of child cells:
iter = RBA::RecursiveShapeIterator::new(layout, cell, layer)
iter.unselect_all_cells
iter.select_cells("MACRO")
Cell selection is done using cell indexes or glob pattern. Glob pattern are equivalent to the usual file name wildcards used on various command line shells. For example "A*" matches all cells starting with an "A". The curly brace notation and character classes are supported as well. For example "C{125,512}" matches "C125" and "C512" and "[ABC]*" matches all cells starting with an "A", a "B" or "C". "[^ABC]*" matches all cells not starting with one of that letters.
The RecursiveShapeIterator class has been introduced in version 0.18 and has been extended substantially in 0.23.
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int layer) | Creates a recursive, single-layer shape iterator. |
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int[] layers) | Creates a recursive, multi-layer shape iterator. |
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int layer, const Box box, bool overlapping) | Creates a recursive, single-layer shape iterator with a region. |
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int layer, const Region region, bool overlapping) | Creates a recursive, single-layer shape iterator with a region. |
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int[] layers, const Box box, bool overlapping) | Creates a recursive, multi-layer shape iterator with a region. |
| new RecursiveShapeIterator ptr | new | (const Layout layout, const Cell cell, unsigned int[] layers, const Region region, bool overlapping) | Creates a recursive, multi-layer shape iterator with a region. |
| [const] | bool | != | (const RecursiveShapeIterator other) | Comparison of iterators - inequality |
| [const] | bool | == | (const RecursiveShapeIterator other) | Comparison of iterators - equality |
| 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 RecursiveShapeIterator other) | Assigns another object to self | |
| [const] | bool | at_end? | End of iterator predicate | |
| [const] | const Cell ptr | cell | Gets the current cell's object | |
| [const] | unsigned int | cell_index | Gets the current cell's index | |
| [const] | Region | complex_region | Gets the complex region that is iterator is using | |
| void | confine_region | (const Box box_region) | Confines the region that is iterator is iterating over | |
| void | confine_region | (const Region complex_region) | Confines the region that is iterator is iterating over | |
| [const] | DCplxTrans | dtrans | Gets the transformation into the initial cell applicable for floating point types | |
| [const] | new RecursiveShapeIterator ptr | dup | Creates a copy of self | |
| [const] | unsigned int | layer | Returns the layer index where the current shape is coming from. | |
| [const] | const Layout ptr | layout | Gets the layout this iterator is connected to | |
| [const] | int | max_depth | Gets the maximum hierarchy depth | |
| void | max_depth= | (int depth) | Specify the maximum hierarchy depth to look into | |
| void | next | Increment the iterator | ||
| void | overlapping= | (bool region) | Sets a flag indicating whether overlapping shapes are selected when a region is used | |
| [const] | bool | overlapping? | Gets a flag indicating whether overlapping shapes are selected when a region is used | |
| [const] | InstElement[] | path | Gets the instantatiation path of the shape addressed currently | |
| [const] | Box | region | Gets the basic region that is iterator is using | |
| void | region= | (const Box box_region) | Sets the rectangular region that is iterator is iterating over | |
| void | region= | (const Region complex_region) | Sets the complex region that is iterator is using | |
| void | reset | Resets the iterator to the initial state | ||
| void | reset_selection | Resets the selection to the default state | ||
| void | select_all_cells | Selects all cells. | ||
| void | select_cells | (unsigned int[] cells) | Unselects the given cells. | |
| void | select_cells | (string cells) | Unselects the given cells. | |
| [const] | Shape | shape | Gets the current shape | |
| void | shape_flags= | (unsigned int flags) | Specifies the shape selection flags | |
| [const] | const Cell ptr | top_cell | Gets the top cell this iterator is connected to | |
| [const] | ICplxTrans | trans | Gets the current transformation by which the shapes must be transformed into the initial cell | |
| void | unselect_all_cells | Unselects all cells. | ||
| void | unselect_cells | (unsigned int[] cells) | Unselects the given cells. | |
| void | unselect_cells | (string cells) | Unselects the given cells. |
| 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] | ICplxTrans | itrans | Use of this method is deprecated. Use trans instead |
!= | Signature: [const] bool != (const RecursiveShapeIterator other) Description: Comparison of iterators - inequality Two iterators are not equal if they do not point to the same shape. | |||||||||
== | Signature: [const] bool == (const RecursiveShapeIterator other) Description: Comparison of iterators - equality Two iterators are equal if they point to the same shape. | |||||||||
_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 RecursiveShapeIterator other) Description: Assigns another object to self | |||||||||
at_end? | Signature: [const] bool at_end? Description: End of iterator predicate Returns true, if the iterator is at the end of the sequence | |||||||||
cell | Signature: [const] const Cell ptr cell Description: Gets the current cell's object This method has been introduced in version 0.23. | |||||||||
cell_index | Signature: [const] unsigned int cell_index Description: Gets the current cell's index | |||||||||
complex_region | Signature: [const] Region complex_region Description: Gets the complex region that is iterator is using The complex region is the effective region (a Region object) that the iterator is selecting from the layout layers. This region can be a single box or a complex region. This method has been introduced in version 0.25. | |||||||||
confine_region | Signature: void confine_region (const Box box_region) Description: Confines the region that is iterator is iterating over This method is similar to setting the region (see region=), but will confine any region (complex or simple) already set. Essentially it does a logical AND operation between the existing and given region. Hence this method can only reduce a region, not extend it. This method has been introduced in version 0.25. | |||||||||
Signature: void confine_region (const Region complex_region) Description: Confines the region that is iterator is iterating over This method is similar to setting the region (see region=), but will confine any region (complex or simple) already set. Essentially it does a logical AND operation between the existing and given region. Hence this method can only reduce a region, not extend it. This method has been introduced in version 0.25. | ||||||||||
create | Signature: void create Description: Ensures the C++ object is created Use of this method is deprecated. Use _create instead | |||||||||
destroy | Signature: void destroy Description: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead | |||||||||
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 | |||||||||
dtrans | Signature: [const] DCplxTrans dtrans Description: Gets the transformation into the initial cell applicable for floating point types This transformation corresponds to the one deliverd by trans, but is applicable for the floating-point shape types in micron unit space. This method has been introduced in version 0.25.3. | |||||||||
dup | Signature: [const] new RecursiveShapeIterator ptr dup Description: Creates a copy of self | |||||||||
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 | |||||||||
itrans | Signature: [const] ICplxTrans itrans Description: Gets the current transformation by which the shapes must be transformed into the initial cell Use of this method is deprecated. Use trans instead | |||||||||
layer | Signature: [const] unsigned int layer Description: Returns the layer index where the current shape is coming from. This method has been introduced in version 0.23. | |||||||||
layout | Signature: [const] const Layout ptr layout Description: Gets the layout this iterator is connected to This method has been introduced in version 0.23. | |||||||||
max_depth | Signature: [const] int max_depth Description: Gets the maximum hierarchy depth See max_depth= for a description of that attribute. This method has been introduced in version 0.23. Python specific notes: | |||||||||
max_depth= | Signature: void max_depth= (int depth) Description: Specify the maximum hierarchy depth to look into A depth of 0 instructs the iterator to deliver only shapes from the initial cell. The depth must be specified before the shapes are being retrieved. Setting the depth resets the iterator. Python specific notes: | |||||||||
new | Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int layer) Description: Creates a recursive, single-layer shape iterator.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layer given by the layer index in the "layer" parameter. This constructor has been introduced in version 0.23. Python specific notes: | |||||||||
Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int[] layers) Description: Creates a recursive, multi-layer shape iterator.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layers given by the layer indexes in the "layers" parameter. While iterating use the layer method to retrieve the layer of the current shape. This constructor has been introduced in version 0.23. Python specific notes: | ||||||||||
Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int layer, const Box box, bool overlapping) Description: Creates a recursive, single-layer shape iterator with a region.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layer given by the layer index in the "layer" parameter. The search is confined to the region given by the "box" parameter. If "overlapping" is true, shapes whose bounding box is overlapping the search region are reported. If "overlapping" is false, shapes whose bounding box touches the search region are reported. This constructor has been introduced in version 0.23. Python specific notes: | ||||||||||
Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int layer, const Region region, bool overlapping) Description: Creates a recursive, single-layer shape iterator with a region.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layer given by the layer index in the "layer" parameter. The search is confined to the region given by the "region" parameter. The region needs to be a rectilinear region. If "overlapping" is true, shapes whose bounding box is overlapping the search region are reported. If "overlapping" is false, shapes whose bounding box touches the search region are reported. This constructor has been introduced in version 0.25. Python specific notes: | ||||||||||
Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int[] layers, const Box box, bool overlapping) Description: Creates a recursive, multi-layer shape iterator with a region.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layers given by the layer indexes in the "layers" parameter. While iterating use the layer method to retrieve the layer of the current shape. The search is confined to the region given by the "box" parameter. If "overlapping" is true, shapes whose bounding box is overlapping the search region are reported. If "overlapping" is false, shapes whose bounding box touches the search region are reported. This constructor has been introduced in version 0.23. Python specific notes: | ||||||||||
Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout, const Cell cell, unsigned int[] layers, const Region region, bool overlapping) Description: Creates a recursive, multi-layer shape iterator with a region.
This constructor creates a new recursive shape iterator which delivers the shapes of the given cell plus it's children from the layers given by the layer indexes in the "layers" parameter. While iterating use the layer method to retrieve the layer of the current shape. The search is confined to the region given by the "region" parameter. The region needs to be a rectilinear region. If "overlapping" is true, shapes whose bounding box is overlapping the search region are reported. If "overlapping" is false, shapes whose bounding box touches the search region are reported. This constructor has been introduced in version 0.23. Python specific notes: | ||||||||||
next | Signature: void next Description: Increment the iterator This moves the iterator to the next shape inside the search scope. | |||||||||
overlapping= | Signature: void overlapping= (bool region) Description: Sets a flag indicating whether overlapping shapes are selected when a region is used If this flag is false, shapes touching the search region are returned. This method has been introduced in version 0.23. Python specific notes: | |||||||||
overlapping? | Signature: [const] bool overlapping? Description: Gets a flag indicating whether overlapping shapes are selected when a region is used This method has been introduced in version 0.23. Python specific notes: | |||||||||
path | Signature: [const] InstElement[] path Description: Gets the instantatiation path of the shape addressed currently This attribute is a sequence of InstElement objects describing the cell instance path from the initial cell to the current cell containing the current shape. This method has been introduced in version 0.25. | |||||||||
region | Signature: [const] Box region Description: Gets the basic region that is iterator is using The basic region is the overall box the region iterator iterates over. There may be an additional complex region that confines the region iterator. See complex_region for this attribute. This method has been introduced in version 0.23. Python specific notes: | |||||||||
region= | Signature: void region= (const Box box_region) Description: Sets the rectangular region that is iterator is iterating over See region for a description of this attribute. Setting a simple region will reset the complex region to a rectangle and reset the iterator to the beginning of the sequence. This method has been introduced in version 0.23. Python specific notes: | |||||||||
Signature: void region= (const Region complex_region) Description: Sets the complex region that is iterator is using See complex_region for a description of this attribute. Setting the complex region will reset the basic region (see region) to the bounding box of the complex region and reset the iterator to the beginning of the sequence. This method overload has been introduced in version 0.25. Python specific notes: | ||||||||||
reset | Signature: void reset Description: Resets the iterator to the initial state This method has been introduced in version 0.23. | |||||||||
reset_selection | Signature: void reset_selection Description: Resets the selection to the default state In the initial state, the top cell and it's children are selected. Child cells can be switched on and off together with their sub-hierarchy using select_cells and unselect_cells. This method will also reset the iterator. This method has been introduced in version 0.23. | |||||||||
select_all_cells | Signature: void select_all_cells Description: Selects all cells. This method will set the "selected" mark on all cells. The effect is that subsequent calls of unselect_cells will unselect only the specified cells, not their children, because they are still unselected. This method will also reset the iterator. This method has been introduced in version 0.23. | |||||||||
select_cells | Signature: void select_cells (unsigned int[] cells) Description: Unselects the given cells. This method will sets the "selected" mark on the given cells. That means that these cells or their child cells are visited, unless they are marked as "unselected" again with the unselect_cells method. The cells are given as a list of cell indexes. This method will also reset the iterator. This method has been introduced in version 0.23. | |||||||||
Signature: void select_cells (string cells) Description: Unselects the given cells. This method will sets the "selected" mark on the given cells. That means that these cells or their child cells are visited, unless they are marked as "unselected" again with the unselect_cells method. The cells are given as a glob pattern. A glob pattern follows the syntax of file names on the shell (i.e. "A*" are all cells starting with a letter "A"). This method will also reset the iterator. This method has been introduced in version 0.23. | ||||||||||
shape | Signature: [const] Shape shape Description: Gets the current shape Returns the shape currently referred to by the recursive iterator. This shape is not transformed yet and is located in the current cell. | |||||||||
shape_flags= | Signature: void shape_flags= (unsigned int flags) Description: Specifies the shape selection flags The flags are the same then being defined in Shapes (the default is RBA::Shapes::SAll). The flags must be specified before the shapes are being retrieved. Settings the shapes flags will reset the iterator. Python specific notes: | |||||||||
top_cell | Signature: [const] const Cell ptr top_cell Description: Gets the top cell this iterator is connected to This method has been introduced in version 0.23. | |||||||||
trans | Signature: [const] ICplxTrans trans Description: Gets the current transformation by which the shapes must be transformed into the initial cell The shapes delivered are not transformed. Instead, this transformation must be applied to get the shape in the coordinate system of the top cell. Starting with version 0.25, this transformation is a int-to-int transformation the 'itrans' method which was providing this transformation before is deprecated. | |||||||||
unselect_all_cells | Signature: void unselect_all_cells Description: Unselects all cells. This method will set the "unselected" mark on all cells. The effect is that subsequent calls of select_cells will select only the specified cells, not their children, because they are still unselected. This method will also reset the iterator. This method has been introduced in version 0.23. | |||||||||
unselect_cells | Signature: void unselect_cells (unsigned int[] cells) Description: Unselects the given cells. This method will sets the "unselected" mark on the given cells. That means that these cells or their child cells will not be visited, unless they are marked as "selected" again with the select_cells method. The cells are given as a list of cell indexes. This method will also reset the iterator. This method has been introduced in version 0.23. | |||||||||
Signature: void unselect_cells (string cells) Description: Unselects the given cells. This method will sets the "unselected" mark on the given cells. That means that these cells or their child cells will not be visited, unless they are marked as "selected" again with the select_cells method. The cells are given as a glob pattern. A glob pattern follows the syntax of file names on the shell (i.e. "A*" are all cells starting with a letter "A"). This method will also reset the iterator. This method has been introduced in version 0.23. |