API reference - Class RecursiveShapeIterator

Notation 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

new RecursiveShapeIterator ptrnew(const Layout layout,
const Cell cell,
unsigned int layer)
Creates a recursive, single-layer shape iterator.
new RecursiveShapeIterator ptrnew(const Layout layout,
const Cell cell,
unsigned int[] layers)
Creates a recursive, multi-layer shape iterator.
new RecursiveShapeIterator ptrnew(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 ptrnew(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 ptrnew(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 ptrnew(const Layout layout,
const Cell cell,
unsigned int[] layers,
const Region region,
bool overlapping)
Creates a recursive, multi-layer shape iterator with a region.

Public methods

[const]bool!=(const RecursiveShapeIterator other)Comparison of iterators - inequality
[const]bool==(const RecursiveShapeIterator other)Comparison of iterators - equality
void_createEnsures the C++ object is created
void_destroyExplicitly 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_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidassign(const RecursiveShapeIterator other)Assigns another object to self
[const]boolat_end?End of iterator predicate
[const]const Cell ptrcellGets the current cell's object
[const]unsigned intcell_indexGets the current cell's index
[const]Regioncomplex_regionGets the complex region that is iterator is using
voidconfine_region(const Box box_region)Confines the region that is iterator is iterating over
voidconfine_region(const Region complex_region)Confines the region that is iterator is iterating over
[const]DCplxTransdtransGets the transformation into the initial cell applicable for floating point types
[const]new RecursiveShapeIterator ptrdupCreates a copy of self
[const]unsigned intlayerReturns the layer index where the current shape is coming from.
[const]const Layout ptrlayoutGets the layout this iterator is connected to
[const]intmax_depthGets the maximum hierarchy depth
voidmax_depth=(int depth)Specify the maximum hierarchy depth to look into
voidnextIncrement the iterator
voidoverlapping=(bool region)Sets a flag indicating whether overlapping shapes are selected when a region is used
[const]booloverlapping?Gets a flag indicating whether overlapping shapes are selected when a region is used
[const]InstElement[]pathGets the instantatiation path of the shape addressed currently
[const]BoxregionGets the basic region that is iterator is using
voidregion=(const Box box_region)Sets the rectangular region that is iterator is iterating over
voidregion=(const Region complex_region)Sets the complex region that is iterator is using
voidresetResets the iterator to the initial state
voidreset_selectionResets the selection to the default state
voidselect_all_cellsSelects all cells.
voidselect_cells(unsigned int[] cells)Unselects the given cells.
voidselect_cells(string cells)Unselects the given cells.
[const]ShapeshapeGets the current shape
voidshape_flags=(unsigned int flags)Specifies the shape selection flags
[const]const Cell ptrtop_cellGets the top cell this iterator is connected to
[const]ICplxTranstransGets the current transformation by which the shapes must be transformed into the initial cell
voidunselect_all_cellsUnselects all cells.
voidunselect_cells(unsigned int[] cells)Unselects the given cells.
voidunselect_cells(string cells)Unselects the given cells.

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead
[const]ICplxTransitransUse of this method is deprecated. Use trans instead

Detailed description

!=

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:
The object exposes a readable attribute 'max_depth'. This is the getter.

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:
The object exposes a writable attribute 'max_depth'. This is the setter.

new

Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout,const Cell cell,unsigned int layer)

Description: Creates a recursive, single-layer shape iterator.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layer:The layer (index) from which the shapes are taken

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

Signature: [static] new RecursiveShapeIterator ptr new (const Layout layout,const Cell cell,unsigned int[] layers)

Description: Creates a recursive, multi-layer shape iterator.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layers:The layer indexes from which the shapes are taken

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

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.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layer:The layer (index) from which the shapes are taken
box:The search region
overlapping:If set to true, shapes overlapping the search region are reported, otherwise touching is sufficient

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:
This method is the default initializer of the object

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.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layer:The layer (index) from which the shapes are taken
region:The search region
overlapping:If set to true, shapes overlapping the search region are reported, otherwise touching is sufficient

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:
This method is the default initializer of the object

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.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layers:The layer indexes from which the shapes are taken
box:The search region
overlapping:If set to true, shapes overlapping the search region are reported, otherwise touching is sufficient

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:
This method is the default initializer of the object

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.

layout:The layout which shall be iterated
cell:The initial cell which shall be iterated (including it's children)
layers:The layer indexes from which the shapes are taken
region:The search region
overlapping:If set to true, shapes overlapping the search region are reported, otherwise touching is sufficient

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:
This method is the default initializer of the object

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:
The object exposes a writable attribute 'overlapping'. This is the setter.

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:
The object exposes a readable attribute 'overlapping'. This is the getter.

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:
The object exposes a readable attribute 'region'. This is the getter.

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:
The object exposes a writable attribute 'region'. This is the setter.

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:
The object exposes a writable attribute 'region'. This is the setter.

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:
The object exposes a writable attribute 'shape_flags'. This is the setter.

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.