A Layout object provides some basic layout manipulation and query methods. For example, it provides a method
to retrieve shapes touching or overlapping a certain rectangular region of a cell. It also provides a clip method which
extracts a rectangular region from a layout
(<class_dochref="Layout#clip"/>, <class_dochref="Layout#clip_into"/>, <class_dochref="Layout#multi_clip"/>, <class_dochref="Layout#multi_clip_into"/>). It provides methods to delete cells and cell trees and (<class_dochref="Layout#delete_cell"/>, <class_dochref="Layout#delete_cell_rec"/>, <class_dochref="Layout#delete_cells"/>,
<class_dochref="Layout#prune_cell"/>, <class_dochref="Layout#prune_subcells"/>). There are also methods to manipulate layers (<class_dochref="Layout#clear_layer"/>, <class_dochref="Layout#copy_layer"/>, <class_dochref="Layout#move_layer"/>, <class_dochref="Layout#delete_layer"/>).
</p>
<p>
Some convenience functions are provide to read and write a layout from or to a file. The <class_dochref="Layout#read"/> method reads a
layout from a file. It basically merges the contents of the file with the layout so it's possible to
combine multiple files by using read more than once. The method comes in two flavors: a simple one and one
that allows specification of reader options with a <class_dochref="LoadLayoutOptions"/> object.
There is also a <class_dochref="Layout#write"/> method which writes the layout to a file. The simple form writes the layout to
a file and the file type is determined by the file extension. A full-featured version exists which allows
to specify the format and many more options with a <class_dochref="SaveLayoutOptions"/> object.
</p>
<p>
Layouts can also import cells from Libraries (<class_dochref="Library"/>). Such imported cells are basically
cells linked to another cell inside the library. Library cells are imported using the <class_dochref="Layout#add_lib_cell"/> method.
This method creates a "proxy" cell which is a copy of the library cell but is linked to the library. As long as
the library is present in the system, this link is maintained and stored in the layout files. If the link is lost
because the library is removed, the proxy cell becomes a normal cell.
Such proxy cells basically behave like normal cells but should not be manipulated.
</p>
<p>
Layout objects are also responsible for handling properties. Properties are basically arbitrary sets
of data (key/value pairs) attached to shapes, cells or instances. For efficiency, the property data is not
attached to every shape, cell or instance. Instead, the layout object manages different property sets and
associate each distinct set with an integer ID. The shape, cell or cell instance only stores that ID.
To create, query or change property sets, the layout object provides the <class_dochref="Layout#properties"/> and
<class_dochref="Layout#properties_id"/> methods. Since that is inconvenient, shapes, cells and instances provide
access to the properties by providing methods to set, get and delete properties from the set (for example <class_dochref="Shape#property"/>,
<class_dochref="Shape#delete_property"/> and <class_dochref="Shape#set_property"/>). Internally, these methods
create a new ID if necessary and assign that ID to the shape, cell or instance.
</p>
<p>
A layout can provide and import PCells. PCells are cells that provide it's geometry through program code
(for example written in Ruby) and provide parameters which can be adjusted to change the appearance of the
cell. For each PCell a "declaration" must be provided which basically contains the code for the
PCell and some information about the parameters provided by the PCell. PCells are stored in the layout
and are referred to by a PCell ID (an integer). PCells are added to a layout using <class_dochref="Layout#register_pcell"/> and
retrieved by ID or name using <class_dochref="Layout#pcell_declaration"/>. PCells are instantiated with a specific parameter set
using the <class_dochref="Layout#add_pcell_variant"/>. This method creates a cell representing the layout generated by the
PCell code for a particular set of parameters. The layout internally caches the PCell layouts so the PCell
code is executed only if a new parameter set is requested. Usually PCells are provided through libraries.
In that case, the library provides the PCell variant through <class_dochref="Layout#add_pcell_variant"/> which is imported into the
target layout through <class_dochref="Layout#add_lib_cell"/>. There is a overload of <class_dochref="Layout#add_pcell_variant"/> which combines both
steps.
</p>
<p>
The following code demonstrates how to create a PCell (in that case a "TEXT" cell from the "Basic" library):
</p>
<pre>ly = RBA::Layout.new
top = ly.add_cell("TOP")
# Find the lib
lib = RBA::Library.library_by_name("Basic")
lib || raise("Unknown lib 'Basic'")
# Find the pcell
pcell_decl = lib.layout.pcell_declaration("TEXT")
pcell_decl || raise("Unknown PCell 'TEXT'")
# Set the parameters (text string, layer to 10/0, magnification to 2.5)
<p>The previous sample changes the layer number for layer index 0 to 100. "add_missing_layers" and "remove_unused_layers" will create
new layer entries in the layer list and remove the entry for the previous layer.</p>
<p>For special purposes, special (temporary) layers can be created in the layout. Those layers basically behave like
normal layers but don't appear in the layer list and are not saved to a file. Special layers can be created using
<class_dochref="Layout#insert_special_layer"/> and <class_dochref="Layout#insert_special_layer_at"/>. <class_dochref="Layout#is_special_layer?"/> returns true if a given index
is a special layer.
</p>
<p>In addition, a layout contains a special layer which is used to implement the "guiding shape" feature of PCell's.
It is a special layer that serves as a container for shapes which parametrize PCells. The index of that layer can be
obtained with <class_dochref="Layout#guiding_shape_layer"/>.</p>
A cell that represents a cell imported from a library or a PCell variant (or both) is called a proxy cell.
For such cells, <class_dochref="Cell#is_proxy?"/> returns true. Such cells should not be manipulated since they may be refreshed
when required and the original state is restored. <class_dochref="Cell#is_library_cell?"/> and <class_dochref="Cell#is_pcell_variant?"/> deliver
a more detailed information about the nature of the proxy cell.
</p>
<p>
The layout that the cell lives in can be retrieved with the <class_dochref="Cell#layout"/> method. If the cell is
created standalone (without layout), this method returns nil. In that case, a cell is not named either.
</p>
<p>
A cell can be a "ghost cell". A ghost cell is an empty cell which is not written to a layout write and
created when a layout file is read with an unsatisfied reference. Unsatisfied references are present
in some GDS files which represent partial layouts. By simple merging of two GDS files, such references can be
made true instances, when another file contributes the cell for that reference. KLayout supports such
unsatisfied references by providing the "ghost cells" which serve as a instance target but are not written.
Ghost cells are simply cells where the <class_dochref="Cell#is_ghost_cell?"/> attribute is true. An empty cell can be made
a ghost cell by setting the <class_dochref="Cell#ghost_cell="/> property.
</p>
<p>
A cell has a bounding box which includes child cells as well. KLayout keeps a per-layer bounding box, so it's
very simple to tell whether a cell is empty in a certain layer (including the hierarchy below). In that case
the per-layer bounding box is an empty box. The overall bounding box can be derived with the <class_dochref="Cell#bbox"/> method.
The per-layer bounding box can be derived with the <class_dochref="Cell#bbox_per_layer"/> method.
</p>
<p>
Cells can be marked as "ghost cells" using the <class_dochref="Cell#ghost_cell="/>. Ghost cells
are not saved into GDS files (but their references are). Also, ghost cells act as "placeholders" for cells -
for example if a cell is pasted into a layout, it will replace any ghost cell with the same name.
If a normal cell with the same name exists, a copy will be created instead. A cell can be asked whether
it is a ghost cell using <class_dochref="Cell#is_ghost_cell?"/>.
</p>
<p>
Starting with version 0.23, cells can have properties as well, but writing cell properties to layout
files is subject to some restrictions. Properties are only written to GDS if a special option is enabled
because a potentially incompatible extension of GDS is used to store the properties. OASIS files
support cell properties without restrictions.
</p>
<h3>Cells and shapes</h3>
<p>
A cell carries a set of geometrical shapes, organised in layers. A layer is specified by a layer index. The layer index
is managed by the Layout object. It is basically an integer that identifies the layer in the layout.
The shapes are stored in containers of the <class_dochref="Shapes"/> class. Given a layer index, the
shapes object can be obtained from the cell through the <class_dochref="Cell#shapes"/> method:
</p>
<pre>shapes = cell.shapes(layer_index)
shapes.each do |shape|
puts shape.to_s
end</pre>
<p>
The same can be achieved by directly iterating over the shapes in the cell:
</p>
<pre>cell.each_shape(layer_index) do |shape|
puts shape.to_s
end</pre>
<p>
That iterator also allows specification of a filter so it delivers only a certain subset, i.e. only text objects.
See <class_dochref="Cell"/> and <class_dochref="Shapes"/> for more details.
</p>
<p>
There are iterators that deliver shapes within a rectangular region, either overlapping or touching that
region (<class_dochref="Cell#each_overlapping_shape"/>, <class_dochref="Cell#each_touching_shape"/>). They basically work like the "each_shape"
iterator. Please note that these iterators are not recursive, i.e. they don't deliver shapes from child cells.
Recursive iteration can be performed using Layout's "begin_shapes" method and the RecursiveShapeIterator object.
</p>
<p>
All shapes in a cell can be cleared using <class_dochref="Cell#clear_shapes"/>. A single layer can be cleared using the <class_dochref="Cell#clear"/> method
with the layer index to clear. Both methods are not recursive, i.e. they only clear the shapes on the given cell, not on
the child cells.
</p>
<p>Layers can be copied using the <class_dochref="Cell#copy"/> method. The shapes of a layer can be moved to another layer using the <class_dochref="Cell#move"/>
method. In both cases, the target layer is not overwritten, but the shapes from the source layer are added to the target layer.
<class_dochref="Cell#swap"/> will swap the shapes of two layers. In all these cases, the operation is local on the cell, i.e. child cells are
not affected.
</p>
<p>
Shapes within a cell are represented as <class_dochref="Shape"/> objects. A shape object is a generic object
which represents either a polygon, a box, a path, a text or an edge object. Shapes provide some generic methods
such as <class_dochref="Shape#bbox"/> to retrieve the bounding box or <class_dochref="Shape#transform"/>. Shapes
act as "pointers" to geometrical objects inside the database. Manipulating a shape will also manipulate the
database object.
</p>
<p>
To work with specific kind of shapes, the working classes such as <class_dochref="Polygon"/> are provided. Shapes
can be converted into these working objects. The working objects are not related to the layout object and not
having a connection to the layout makes them lightweight objects. A usual way of manipulating a shape is to
translate it to a working object, modify that and assign the working object back to the shape.
The direct children of a cell can be iterated with <class_dochref="Cell#each_child_cell"/>. That iterator delivers the cell index of
each child cell of the cell. Similar, there is a <class_dochref="Cell#each_parent_cell"/> iterator. It delivers the cell indexes of
all cells calling that cells. For a top cell that iterator delivers nothing. <class_dochref="Cell#is_leaf?"/> returns true, if the
cell does not have child cells. <class_dochref="Cell#is_top?"/> returns true, if the cell is top cell.
</p>
<p>
Cells and their children form a directed acyclic cell graph. That means, no cell may instantiate a cell which itself calls the
cell whether directly or indirectly. There is a set of cells called by a given cell, either directly or indirectly through
children of the cell. That set is the "called" cell set. That cell set can be obtained with the <class_dochref="Cell#called_cells"/> method in
form of an array of cell indexes.
</p>
<p>
Similar, there is a set of cells calling a cell, either directly or indirectly. That set of cells can be obtained with
the <class_dochref="Cell#caller_cells"/> method. For a top cell that set is empty.
</p>
<p>
The number of hierarchy levels can be obtained with <class_dochref="Cell#hierarchy_levels"/>. This method delivers the length of the longest path
to a leaf cell. A leaf cell has a hierarchy level count of 0.
</p>
<p>
A cell can be flattened using <class_dochref="Cell#flatten"/>.
Child cells can be removed using <class_dochref="Cell#prune_subcells"/>.
The cell can be removed with <class_dochref="Cell#delete"/> or <class_dochref="Cell#prune_cell"/>. The
latter will also remove any child cells which are not used otherwise.
</p>
<h3>Copying information between cells</h3>
<p>
Instances can be copied from one cell to another using <class_dochref="Cell#copy_instances"/>.
Shapes can be copied using <class_dochref="Cell#copy_shapes"/>. The latter method supports
layer conversions by employing a <class_dochref="LayerMapping"/> object to specify input and
output layers. In addition, shapes can be copied to another layout which automatically performs
database unit conversion if necessary.
</p>
<p>
A full cell tree can be copied using <class_dochref="Cell#copy_tree"/>. This method will
create a new hierarchy below the target cell matching the source cell's hierarchy and
copy all shapes from source to target using that new hierarchy. Source and target cell
may reside in different layouts and database unit conversion is done automatically.
</p>
<p>
The content of a cell can be copied to another cell hierarchically using <class_dochref="Cell#copy_tree_shapes"/>,
provided a cell mapping exists. A cell mapping specifies, how child cells of the source cell are identified
in the target, which can be a different layout. For the cell mapping a <class_dochref="CellMapping"/> object is
employed. In addition, a <class_dochref="LayerMapping"/> object can be used to specify layer mapping to
the target. If no cell mapping is provided, shapes are flattened into the next possible parent, which provides
a way to creating flat copies of cells.
"copy_tree" is a convenience method and is a special case of "copy_tree_shapes".
</p>
<p>
For all methods, "move" flavors are available (<class_dochref="Cell#move_instances"/>,
<class_dochref="Cell#move_shapes"/>, <class_dochref="Cell#move_tree"/> and <class_dochref="Cell#move_tree_shapes"/>),
which not only copy the information but also remove the respective objects in the source
cell. That somewhat reduces the memory required for such operations.
</p>
<h3>Cells and instances</h3>
<p>
A cell also plays a role as container for the instances. An instance describes a cell that is placed into another cell.
Technically an instance is a combination of a cell reference and a transformation. Raw instances are represented by <class_dochref="CellInstArray"/>
objects. Instances inside a cell are referred to by <class_dochref="Instance"/> objects.
An Instance object is basically a pointer into a CellInstArray stored inside a cell and associates properties with raw
instances for example.
</p>
<p>
Instances can be created by using the various <class_dochref="Cell#insert"/> methods of Cell. Instances can have properties, so a property ID
can be provided (see Layout class for a discussion about property ID's). Instances can be deleted using the <class_dochref="Cell#erase"/> method.
All instances of a cell can be deleted using the <class_dochref="Cell#clear_insts"/> method.
</p>
<p>
An instance can be replaced by another CellInstArray object using the <class_dochref="Cell#replace"/> method. The properties ID can be changed
using the <class_dochref="Cell#replace_prop_id"/> method. It is easier however to use the Instance object's "cell_inst=" or "prop_id=" method.
</p>
<p>
Instances can be iterated with <class_dochref="Cell#each_inst"/>. <class_dochref="Cell#each_overlapping_inst"/> and <class_dochref="Cell#each_touching_inst"/> delivers all
instances overlapping or touching a given rectangular region. That means, the instance's overall bounding box overlaps
or touches the search rectangle.
</p>
<p>
<class_dochref="Cell#each_parent_inst"/> delivers all parent instances. Parent instances are basically reverse instances represented
by the <class_dochref="ParentInstArray"/> object. A parent instance identifies are parent cell and
the instance of the given cell in that parent cell. This iterator allows deriving all instances of the given cell
in other cells.
</p>
<p>Instances can be transformed with a given transformation (either a orthogonal or a general complex transformation)
using the <class_dochref="Cell#transform"/> method. This method invalidates the Instance pointer given as the argument and returns a
<p>If a cell is a cell imported from a library, <class_dochref="Cell#is_library_cell?"/> will return true and it is possible to derive
the Library object from which this cell is imported using the <class_dochref="Cell#library"/> method. <class_dochref="Cell#library_cell_index"/> will
return the cell index of the cell in the library's local layout.
</p>
<p>If a cell is a PCell variant, either directly from the layout or from a library, <class_dochref="Cell#is_pcell_variant?"/> returns true.
This method can also be called on an Instance object in which case it delivers true if the instance is an instance of
a PCell. <class_dochref="Cell#pcell_id"/> returns the PCell declaration ID if the cell is a PCell variant. <class_dochref="Cell#pcell_declaration"/> will
return the PCell declaration object. There is also a overload of "pcell_declaration" that determines the PCell declaration
object for an Instance if it is a PCell instance. <class_dochref="Cell#pcell_parameters"/> delivers the PCell parameters for a cell (if it is
a PCell variant) or an instance (if it is a PCell instance). The PCell parameters are an array of <class_dochref="Variant"/> object
and the interpretation is dependent on the PCell implementation. The <class_dochref="PCellDeclaration"/> object
which can be obtained through "pcell_declaration" gives the necessary information about the interpretation of the
parameters.
</p>
<p>
Finally, <class_dochref="Cell#refresh"/> allows refreshing the layout of a proxy cell, i.e. transfer the current state of a library
cell into this cell or recompute the PCell layout.
Usually this method needs not to be called. When PCell parameters change for example, the layout is automatically
recomputed.
</p>
<h3>Cells and PCell instances</h3>
<p>
A cell can be a PCell variant as we've seen above. In addition, a cell can hold PCell instances.
The parameters of PCell instances can be modified from the cell using <class_dochref="Cell#change_pcell_parameter"/> for
individual parameters given by name or <class_dochref="Cell#change_pcell_parameters"/> for all parameters.
For changing all parameters it is required to know the parameter's order and meaning. The order can be
obtained from the PCell declaration class which itself can be retrieved from a PCell instance with <class_dochref="Cell#pcell_declaration"/>
(with the instance as the first argument).
</p>
<p>
The PCell parameters of a PCell instance can be obtained with <class_dochref="Cell#pcell_parameters"/> (with the
instance as the first argument). To get a specific parameter, use the PCell declaration object which lists the
parameters on the order they are delivered by the "pcell_parameters" method.
</p>
<h2>The CellInstArray class</h2>
<keywordname="CellInstArray"/>
<p>
Despite it's name, a <class_dochref="CellInstArray"/> object holds a cell reference which is
not only an array, but also a single instances. The object represents a raw instance, in contrast to the
Instance object which is basically a pointer to an instance inside the database. CellInstArray objects as raw instances can be created,
copied, modified and stored in the usual containers, but once they are stored inside the Cell object, they can
be addressed by the Instance object.
</p>
<p>
The CellInstArray object represents either single instances or array instances. Array instances correspond
to GDS AREF records and are regular, two-dimensional (not necessarily orthogonal) arrays of instances.
A single instance consist of a cell index, denoting the cell that is instantiated and a single transformation,
which can be either a simple, orthogonal affine transformation without a magnification (a Trans object, see
<class_dochref="Trans"/>) or a general affine transformation (a CplxTrans object, see
<class_dochref="CplxTrans"/>). A cell instance array in addition specifies two dimensions (na, nb) and shift
vectors (a, b). For each individual instance of the array, an additional displacement is added to the
transformation which is computed by the following formula:
</p>
<pre>d=i*a+j*b (i=0..na-1, j=0..nb-1)</pre>
<p>
A CellInstArray object that represents an array will return true on <class_dochref="CellInstArray#is_regular_array?"/>. In that case,
the <class_dochref="CellInstArray#a"/> and <class_dochref="CellInstArray#b"/> attributes are the basic vectors of the array and <class_dochref="CellInstArray#na"/> and <class_dochref="CellInstArray#nb"/> are
the dimensions of the array. <class_dochref="CellInstArray#size"/> is the number of instances in the array.
</p>
<p>
A CellInstArray with a simple transformation will return false on <class_dochref="CellInstArray#is_complex?"/> and the
<class_dochref="CellInstArray#trans"/> attributes gives the basic transformation of the instance. If the transformation is complex,
i.e. has a rotation angle which is not a multiple of 90 degree or a magnification, <class_dochref="CellInstArray#is_complex?"/>
will return true and <class_dochref="CellInstArray#cplx_trans"/> should be used instead of <class_dochref="CellInstArray#trans"/>. In any case, <class_dochref="CellInstArray#cplx_trans"/>
gives the correct transformation.
</p>
<p>The <class_dochref="CellInstArray#cell_index"/> attribute gets or sets the cell index. The <class_dochref="CellInstArray#bbox"/> and <class_dochref="CellInstArray#bbox_per_layer"/>
methods deliver the total bounding box of the instance including all instances for an array. <class_dochref="CellInstArray#bbox_per_layer"/>
gives the bounding box for a single layer. Since the instance only knows the cell index, these methods require
a Layout object in order to derive the actual cell's bounding box.
</p>
<p>
A CellInstArray object can be inverted using the <class_dochref="CellInstArray#invert"/> method. This method returns an array which
represents the ways the parent cell is seen from the child cell. A CellInstArray object can also be transformed
by a given transformation. The <class_dochref="CellInstArray#transform"/> method will (like <class_dochref="CellInstArray#invert"/>) transform the object in-place,
i.e. modify the object. <class_dochref="CellInstArray#transformed"/> will do the same, but leave the object it is called on and return
a modified copy (out-of-place). Various variants of the <class_dochref="CellInstArray#transform"/> and <class_dochref="CellInstArray#transformed"/> methods exist
taking different forms of transformations (simple, complex).
<class_dochref="Instance#cell_index"/>, <class_dochref="Instance#cell"/>, <class_dochref="Instance#is_complex?"/> or
<class_dochref="Instance#is_regular_array?"/>). The whole CellInstArray object can be read with the <class_dochref="Instance#cell_inst"/> method.
It is possible to copy (dup) and modify that object and replace the current CellInstArray with the new
one using <class_dochref="Instance#cell_inst="/>. Please note, that this operation may invalidate iterators and should not
be done inside a loop using "Cell::each_inst" for example.
</p>
<p>
The cell the Instance object lives in can be obtained with <class_dochref="Instance#cell"/>. <class_dochref="Instance#parent_cell_index"/> basically
renders the same information, but in form of a cell index. The layout the instance lives in can be
obtained with <class_dochref="Instance#layout"/>.
</p>
<p>
User properties can be accessed through the <class_dochref="Instance#prop_id"/> attribute or, more convenient, through the
<class_dochref="Instance#get_property"/>, <class_dochref="Instance#delete_property"/> or <class_dochref="Instance#set_property"/> methods. Please note that changing the
property ID or the property values may invalidate iterators as well.
</p>
<p>
An instance has an equality operator. That operator returns true, if the Instance objects point to
the same cell instance.
</p>
<h2>The Shapes class</h2>
<keywordname="Shapes"/>
<p>
The <class_dochref="Shapes"/> object is the basic container for geometrical shapes. It
stores geometrical primitives (Boxes, Polygons, Paths, Texts and Edges) either directly or
in compressed form to achieve a low memory usage. For example, OASIS shape arrays are stored
as compact arrays when KLayout is used in viewer mode.
The Shapes container provides a simplified view through the Shape object which is basically
a pointer to an individual instance of a geometrical primitive. The Shapes container provides
access to the primitives through Shape objects.
</p>
<p>
In editable mode (i.e. if a Shapes container lives in an editable Layout object), the
shapes can be modified or deleted after they have been inserted. In the opposite mode (viewer mode), shapes can be added, but not
modified nor deleted.
</p>
<p>
A Shapes container is usually obtained from a cell with a given layer index and is filled with
geometrical primitives using one of the <class_dochref="Shapes#insert"/> methods. Please note that the shapes
