API reference - Class RecursiveShapeIteratorNotation used in Ruby API documentation 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. Public constructors
Public methods
Deprecated methods (protected, public, static, non-static and constructors)
Detailed description[const] bool !=(const RecursiveShapeIterator other)Description: Comparison of iterators - inequality Two iterators are not equal if they do not point to the same shape. [const] bool ==(const RecursiveShapeIterator other)Description: Comparison of iterators - equality Two iterators are equal if they point to the same shape. void _createDescription: 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. void _destroyDescription: 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. [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. [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. void _manageDescription: 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. void _unmanageDescription: 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. void assign(const RecursiveShapeIterator other)Description: Assigns another object to self [const] bool at_end?Description: End of iterator predicate Returns true, if the iterator is at the end of the sequence [const] const Cell ptr cellDescription: Gets the current cell's object This method has been introduced in version 0.23. [const] unsigned int cell_indexDescription: Gets the current cell's index void createDescription: Ensures the C++ object is created Use of this method is deprecated. Use _create instead void destroyDescription: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead [const] bool destroyed?Description: Returns a value indicating whether the object was already destroyed Use of this method is deprecated. Use _destroyed? instead [const] new RecursiveShapeIterator ptr dupDescription: Creates a copy of self [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 [const] ICplxTrans itransDescription: 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. This method delivers the integer version which is not accurate in the strict sense but delivers integer coordinate shapes. This method is somewhat slower than the 'trans' method. [const] unsigned int layerDescription: Returns the layer index where the current shape is coming from. This method has been introduced in version 0.23. [const] const Layout ptr layoutDescription: Gets the layout this iterator is connected to This method has been introduced in version 0.23. [const] int max_depthDescription: 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:The object exposes a readable attribute 'max_depth'. This is the getter. 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:The object exposes a writable attribute 'max_depth'. This is the setter. [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:This method is the default initializer of the object [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:This method is the default initializer of the object [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 is touching the search region are reported. This constructor has been introduced in version 0.23. Python specific notes:This method is the default initializer of the object [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 is touching the search region are reported. This constructor has been introduced in version 0.23. Python specific notes:This method is the default initializer of the object void nextDescription: Increment the iterator This moves the iterator to the next shape inside the search scope. 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:The object exposes a writable attribute 'overlapping'. This is the setter. [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:The object exposes a readable attribute 'overlapping'. This is the getter. [const] Box regionDescription: Gets the region that is iterator is using This method has been introduced in version 0.23. Python specific notes:The object exposes a readable attribute 'region'. This is the getter. void region=(const Box region)Description: Sets the region that is iterator is using This method has been introduced in version 0.23. Python specific notes:The object exposes a writable attribute 'region'. This is the setter. void resetDescription: Resets the iterator to the initial state This method has been introduced in version 0.23. void reset_selectionDescription: 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. void select_all_cellsDescription: 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. 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. 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. [const] Shape shapeDescription: 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. 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:The object exposes a writable attribute 'shape_flags'. This is the setter. [const] const Cell ptr top_cellDescription: Gets the top cell this iterator is connected to This method has been introduced in version 0.23. [const] CplxTrans transDescription: 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. void unselect_all_cellsDescription: 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. 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. 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. |