mirror of https://github.com/KLayout/klayout.git
Updated documentation.
This commit is contained in:
Matthias Koefferlein
parent
d6ca13f220
commit
5b6b800e9d
|
|
@ -112,6 +112,15 @@ layout.write("my_layout.gds")</pre>
|
|||
in every cell and inside a cell, a shape storage for each layer is provided.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Inside the layout object, shapes are kept with integer coordinates. The physical units can be obtained
|
||||
by multiplying the integer coordinates with the database unit. The integer type objects are <class_doc href="Box"/>, <class_doc href="Polygon"/>
|
||||
etc. Most objects also support floating-point coordinate objects (<class_doc href="DBox"/>, <class_doc href="DPolygon"/> etc.).
|
||||
These objects are then given in micrometer units - i.e. already multiplied by the database unit.
|
||||
If using these objects, keep in mind that internally they are still integer-type objects. This means,
|
||||
rounding to the database will happen and if you change the database unit, the objects will effectively scale.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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
|
||||
|
|
@ -222,9 +231,26 @@ non_editable_layout = RBA::Layout.new(false)</pre>
|
|||
created, the editable mode cannot be changed.
|
||||
</p>
|
||||
|
||||
<h3>Meta information</h3>
|
||||
|
||||
<p>A layout object can keep arbitrary meta data in the form of key/value pairs. This meta data is
|
||||
extracted during the reading of a layout and will reflect special properties of the layout file.
|
||||
For example, the GDS2 library name is available as meta information with key "libname".
|
||||
</p>
|
||||
|
||||
<p>The layout object offers methods to retrieve that information: <class_doc href="Layout#each_meta_info"/> will
|
||||
iterate over the meta data (returning a <class_doc href="LayoutMetaInfo"/> object). <class_doc href="Layout#meta_info_value"/>
|
||||
will get the value for a given name. <class_doc href="Layout#add_meta_info"/> will add a new meta information object
|
||||
and <class_doc href="Layout#remove_meta_info"/> will delete one.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Meta information is a different concept than properties.
|
||||
</p>
|
||||
|
||||
<h3>Cell related methods</h3>
|
||||
|
||||
<p>Cells can be created using the <class_doc href="Layout#create_cell"/> or method. This method expects a cell name. If a cell with that
|
||||
<p>Cells can be created using the <class_doc href="Layout#create_cell"/> method. This method expects a cell name. If a cell with that
|
||||
name already exists, a new name is generated by appending a suffix. The method returns the Cell object of the new
|
||||
cell. <class_doc href="Layout#rename_cell"/> or <class_doc href="Cell#name="/> can be used to change the name of a cell.
|
||||
The Cell object for a given name can be obtained with <class_doc href="Layout#cell"/> which returns the Cell
|
||||
|
|
@ -299,6 +325,10 @@ lv.remove_unused_layers</pre>
|
|||
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_doc href="Layout#guiding_shape_layer"/>.</p>
|
||||
|
||||
<p>A list of the indexes for all layers inside the layout can be obtained with <class_doc href="Layout#layer_indexes"/>.
|
||||
A corresponding list of LayerInfo objects can be obtained with <class_doc href="Layout#layer_infos"/>.
|
||||
</p>
|
||||
|
||||
<h3>Recursive full or region queries</h3>
|
||||
|
||||
<p>
|
||||
|
|
@ -480,6 +510,11 @@ shape.set_property(1, "NewValue")</pre>
|
|||
number are specified, the name matches exactly.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
LayerInfo objects supply a hash value (<class_doc href="LayerInfo#hash"/>) and can therefore be used as
|
||||
keys in Ruby hashes.
|
||||
</p>
|
||||
|
||||
<h2>The Cell class</h2>
|
||||
|
||||
<keyword name="Cell"/>
|
||||
|
|
@ -499,6 +534,12 @@ shape.set_property(1, "NewValue")</pre>
|
|||
and PCell parameters as well and can be used as a descriptive title for the cell in user interfaces.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
If the cell is a library cell (a "proxy"), it will have a database name (something like "TEXT$1") and a qualified
|
||||
name which states the library and the cell name separated with a dot (i.e. "Basic.TEXT"). The qualified name
|
||||
is not neccessarily unique. The qualified name of the cell can be obtained with <class_doc href="Cell#qname"/>.
|
||||
</p>
|
||||
|
||||
<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_doc href="Cell#is_proxy?"/> returns true. Such cells should not be manipulated since they may be refreshed
|
||||
|
|
@ -603,6 +644,14 @@ end</pre>
|
|||
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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Interfaces to floating-point working classes such as <class_doc href="DPolygon"/> are provided too. By convention
|
||||
such objects represent shapes in micrometer units. If such an object is requested from the shapes container it
|
||||
is converted from an integer-type object in database units to a floating-point type object in micrometer units
|
||||
by multiplying with the database unit. When sending such an object to the Shapes container the same happens in
|
||||
reverse. Internally, the integer type is used.
|
||||
</p>
|
||||
|
||||
<h3>Cells and hierarchy</h3>
|
||||
|
||||
|
|
@ -710,6 +759,14 @@ end</pre>
|
|||
new Instance pointer to the new cell instance.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A floating-point integer class exists too (<class_doc href="DCellInstArray"/>). By convention
|
||||
this object represent an instance in micrometer units. If such an object is requested from the cell it
|
||||
is converted from an integer-type object in database units to a floating-point type object in micrometer units
|
||||
by multiplying with the database unit. When sending such an object to the cell the same happens in
|
||||
reverse. Internally, the integer type is used.
|
||||
</p>
|
||||
|
||||
<h3>Cells, libraries and PCells</h3>
|
||||
|
||||
<p>If a cell is a cell imported from a library, <class_doc href="Cell#is_library_cell?"/> will return true and it is possible to derive
|
||||
|
|
@ -804,6 +861,11 @@ end</pre>
|
|||
a modified copy (out-of-place). Various variants of the <class_doc href="CellInstArray#transform"/> and <class_doc href="CellInstArray#transformed"/> methods exist
|
||||
taking different forms of transformations (simple, complex).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The floating-point variant (<class_doc href="DCellInstArray"/>) behaves the same way, except that by convention the
|
||||
unit of coordinates is micrometers.
|
||||
</p>
|
||||
|
||||
<h2>The Instance class</h2>
|
||||
|
||||
|
|
@ -864,8 +926,8 @@ end</pre>
|
|||
<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_doc href="Shapes#insert"/> methods. Please note that the shapes
|
||||
are specified in integer coordinates and the micron dimensions have to be obtained by multiplying
|
||||
them with the database unit:
|
||||
are specified in integer coordinates when you use the integer type objects and micrometer
|
||||
units when using the floating-point type objects (whose classes start with "D"):
|
||||
</p>
|
||||
|
||||
<pre># cell = a Cell object
|
||||
|
|
@ -873,6 +935,15 @@ end</pre>
|
|||
shapes = cell.shapes(layer_index)
|
||||
shapes.insert(RBA::Box::new(0, 0, 1000, 2000))</pre>
|
||||
|
||||
<p>
|
||||
With floating-point objects:
|
||||
</p>
|
||||
|
||||
<pre># cell = a Cell object
|
||||
# layer_index = the index of a the layer
|
||||
shapes = cell.shapes(layer_index)
|
||||
shapes.insert(RBA::DBox::new(0.0, 0.0, 1.0, 2.0))</pre>
|
||||
|
||||
<p>
|
||||
A Shapes object can also be created without a cell:
|
||||
</p>
|
||||
|
|
@ -1040,7 +1111,13 @@ end</pre>
|
|||
</p>
|
||||
|
||||
<p>
|
||||
The layer index a shape is on can be derived with <class_doc href="Shape#layer"/>.
|
||||
Floating-point objects are supported too. For example, <class_doc href="Shape#dbox"/> is equivalent to <class_doc href="Shape#box"/>,
|
||||
but delivers the object in micrometer units. <class_doc href="Shape#dbox="/> receives a micrometer-unit object.
|
||||
<class_doc href="Shape#box_dp1"/> is equivalent to <class_doc href="Shape#box_p1"/>, but gets the first point of the box in micrometer units.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The layer index a shape is on can be obtained with <class_doc href="Shape#layer"/>.
|
||||
A shape can be moved to a different layer by assigning a different layer index with <class_doc href="Shape#layer="/>.
|
||||
In that context, layers can also be addressed by layer/datatype or name using a <class_doc href="LayerInfo"/> object.
|
||||
The respective methods to address a shape's layer then are <class_doc href="Shape#layer_info"/> and
|
||||
|
|
@ -1060,6 +1137,10 @@ end</pre>
|
|||
<class_box href="Shape#box_p2"/> and <class_box href="Shape#box_p2="/> get or modify individual aspects of the
|
||||
box.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the floating-point equivalents in micrometer units see the <class_doc href="Shape"/>.
|
||||
</p>
|
||||
|
||||
<h3>Methods applying for polygon and simple polygon shapes</h3>
|
||||
|
||||
|
|
@ -1086,6 +1167,10 @@ end</pre>
|
|||
given new one.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the floating-point equivalents in micrometer units see the <class_doc href="Shape"/>.
|
||||
</p>
|
||||
|
||||
<h3>Methods applying for path shapes</h3>
|
||||
|
||||
<p>A Shape object represents a path if it returns true on <class_doc href="Shape#is_path?"/>.
|
||||
|
|
@ -1107,6 +1192,10 @@ end</pre>
|
|||
used to obtain the path's contour.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the floating-point equivalents in micrometer units see the <class_doc href="Shape"/>.
|
||||
</p>
|
||||
|
||||
<h3>Methods applying for text shapes</h3>
|
||||
|
||||
<p>A Shape object represents a text object if it returns true on <class_doc href="Shape#is_text?"/>.
|
||||
|
|
@ -1129,6 +1218,10 @@ end</pre>
|
|||
shape with the given Text object.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the floating-point equivalents in micrometer units see the <class_doc href="Shape"/>.
|
||||
</p>
|
||||
|
||||
<h3>Methods applying for edge shapes</h3>
|
||||
|
||||
<p>
|
||||
|
|
@ -1142,6 +1235,10 @@ end</pre>
|
|||
getter and <class_doc href="Shape#edge="/> setter.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the floating-point equivalents in micrometer units see the <class_doc href="Shape"/>.
|
||||
</p>
|
||||
|
||||
</doc>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -35,6 +35,35 @@
|
|||
methods. The <b>*</b> operator used with a factor as the second operand will scale both the x and y coordinates.
|
||||
</p>
|
||||
|
||||
<h2>Points and vectors</h2>
|
||||
|
||||
<keyword name="Point"/>
|
||||
<p>
|
||||
Next to points there is a corresponding vector class (<class_doc href="Vector"/>).
|
||||
A vector is basically the difference between two points.
|
||||
It is meant to describe the distance and direction between two points.
|
||||
The following rules therefore apply:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Subtracting a point from a point renders a vector</li>
|
||||
<li>Adding a vector to a point renders a point</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
As points, vectors have an x and a y component which can be accessed with <class_doc href="Vector#x"/> and <class_doc href="Vector#y"/>.
|
||||
Vectors offer two functions to compute the vector product (<class_doc href="Vector#vprod"/>) and the scalar product
|
||||
(<class_doc href="Vector#sprod"/>). For some applications it's sufficient to know the sign of the product. You can
|
||||
get that with <class_doc href="Vector#vprod_sign"/> and <class_doc href="Vector#sprod_sign"/> respectively.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Vectors don't transform the same way than points. On transformation, only rotation, mirror and scaling (if applicable)
|
||||
is applied. Displacement is not applied. This way, the following two forms are equivalent:
|
||||
</p>
|
||||
|
||||
<pre>(p1 - p2).transformed(t) == p1.transformed(t) - p2.transformed(t)</pre>
|
||||
|
||||
<h2>The Box class</h2>
|
||||
|
||||
<keyword name="Box"/>
|
||||
|
|
@ -105,11 +134,11 @@
|
|||
|
||||
<pre># Wrong result
|
||||
box = RBA::Box::new(0, 0, 100, 200)
|
||||
transformed_box = box.transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Point::new))
|
||||
transformed_box = box.transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
|
||||
# -> (-141,0;71,212)
|
||||
|
||||
# Correct result
|
||||
transformed_box_as_polygon = RBA::Polygon::new(box).transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Point::new))
|
||||
transformed_box_as_polygon = RBA::Polygon::new(box).transformed_cplx(RBA::ICplxTrans::new(1, 45, false, RBA::Vector::new))
|
||||
# -> (0,0;-141,141;-71,212;71,71)</pre>
|
||||
</li>
|
||||
|
||||
|
|
@ -119,9 +148,16 @@ transformed_box_as_polygon = RBA::Polygon::new(box).transformed_cplx(RBA::ICplxT
|
|||
|
||||
</ul>
|
||||
|
||||
<p>The class method <class_doc href="Box#from_dbox"/> creates a integer-coordinate type Box object from a floating-point coordinate type DBox
|
||||
object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.
|
||||
<p>A box object can be constructed from a floating-point object (for floating-point objects see below).
|
||||
Lacking a database unit, no conversion from micrometer units
|
||||
to database units is performed. Instead, the floating-point coordinates are rounded to the nearest integer coordinates:
|
||||
</p>
|
||||
|
||||
<pre>dbox = RBA::DBox::new(2.1, 3.1, 10.7, 11.8)
|
||||
box = RBA::Box::new(dbox)
|
||||
# -> (2,3;11,12)</pre>
|
||||
|
||||
<p>An integer box can be turned into a floating-point unit box using <class_doc href="Box#to_dtype"/></p>
|
||||
|
||||
<h2>The SimplePolygon class</h2>
|
||||
|
||||
|
|
@ -389,22 +425,28 @@ a == b
|
|||
# -> 0.0999999999999999916733</pre>
|
||||
|
||||
<p>
|
||||
Because of that, operations that depend on the equality of coordinates (like "box.touches(other_box)") may not work as
|
||||
expected unless the coordinates can be expressed precisely.
|
||||
For the same reason, some operations which are implemented on integer coordinates (like the removal of holes in polygons)
|
||||
Because of that, direct comparison of coordinate values should be avoided.
|
||||
The internal precision used is 0.00001. By convention, floating-point type objects are supposed to
|
||||
be used for micrometer-unit objects, hence this precision corresponds to 0.01 nm which corresponds to
|
||||
the tenth of an atom and should be well below physical tolerances.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Some operations which are implemented on integer coordinates (like the removal of holes in polygons)
|
||||
are not available for the floating-point type objects.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
All floating-point type objects have class methods like "from_i.." (i.e. <class_doc href="DBox#from_ibox"/>) which convert integer-coordinate
|
||||
type objects to floating-point type ones without loss of precision. The reverse path is opened by using the "from_d.." class
|
||||
methods of the integer-type objects (i.e. <class_doc href="Box#from_dbox"/>). These methods however require some rounding and are therefore
|
||||
responsible for a potential distortion of the geometry of the object.
|
||||
All floating-point type objects have a "to_itype" method (i.e. <class_doc href="DBox#to_itype"/>) which convert the floating-point
|
||||
type object to the integer-coordinate type object. This method can be given a database unit for scaling from micrometer units.
|
||||
Integer-coordinate type objects can be converted to floating-point type objects the same way through the "to_dtype" method (i.e.
|
||||
<class_doc href="Box#to_dtype"/>. A database unit can be passed to this method too for conversion to micrometer units.
|
||||
These methods however require some rounding and are therefore responsible for a potential distortion of the geometry of the object.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For the point object there is also a floating-point equivalent (DPoint, see <class_doc href="DPoint"/>). Is behaves like
|
||||
the integer-coordinate point.
|
||||
For the point and vector object there is also a floating-point equivalent (<class_doc href="DPoint"/> and <class_doc href="DVector"/>).
|
||||
Both behaves like their integer-coordinate equivalent.
|
||||
</p>
|
||||
|
||||
<h2>Transformations</h2>
|
||||
|
|
@ -414,20 +456,23 @@ a == b
|
|||
<keyword name="DCplxTrans"/>
|
||||
<keyword name="CplxTrans"/>
|
||||
<keyword name="ICplxTrans"/>
|
||||
<keyword name="VCplxTrans"/>
|
||||
|
||||
<p>
|
||||
Transformations in KLayout are restricted affine transformations which lack shear transformations and the ability to apply
|
||||
an anisotropic scaling. A transformation in KLayout follows the conventions implied by the GDS2 and OASIS formats and include in that order:
|
||||
Transformations in KLayout are restricted affine transformations. Shear transformations and anisotropic scaling is not
|
||||
supported.
|
||||
All transformation in KLayout follows the conventions implied by the GDS2 and OASIS formats and include in that order:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Mirroring around the x axis</li>
|
||||
<li>Mirroring around the x axis (optional)</li>
|
||||
<li>Rotation</li>
|
||||
<li>Scaling</li>
|
||||
<li>Displacement</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
For memory performance, unless necessary a restricted version of that transformation is used. In that restricted version, the
|
||||
For memory performance, a restricted version of that transformation is used if possible. In that restricted version, the
|
||||
rotation angles are confined to a multiple of 90 degree and scaling is not supported. This restricted affine transformation
|
||||
is provided through the <class_doc href="Trans"/> class. The 8 possible rotation/mirror variants can be coded in
|
||||
a single rotation/mirror code which is used frequently throughout KLayout (see <link href="/about/transformations.xml"/>).
|
||||
|
|
@ -435,30 +480,62 @@ a == b
|
|||
|
||||
<p>
|
||||
For transforming floating-point coordinates, the <class_doc href="DTrans"/> object is provided. The basic difference
|
||||
is that the displacement uses floating-point coordinates (by employing a DPoint object).
|
||||
is that the displacement uses floating-point coordinates (by employing a DVector object).
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To support more complex affine transformations include arbitrary-angle rotations and scaling, the complex transformation objects
|
||||
are provided. The precise representation of a coordinate transformed with such a transformation requires floating-point
|
||||
precision. Since that is not practical, different versions of transformations exists which render different output types and
|
||||
work on different input types:
|
||||
are provided. In addition, the complex transformation object can translate between integer and floating-point coordinate types.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><class_doc href="CplxTrans"/>: takes integer coordinates and delivers floating-point coordinates.
|
||||
Therefore it uses a DPoint for the displacement.
|
||||
Therefore it uses a DVector for the displacement. The inverse of this transformation is a VCplxTrans
|
||||
class (see below).
|
||||
</li>
|
||||
<li><class_doc href="DCplxTrans"/>: takes floating-point coordinates and delivers floating-point coordinates.
|
||||
Therefore it also uses a DPoint for the displacement.
|
||||
Therefore it also uses a DVector for the displacement.
|
||||
</li>
|
||||
<li><class_doc href="ICplxTrans"/>: takes integer coordinates and delivers integer coordinates.
|
||||
Therefore it uses a Point for the displacement. This transformation is convenient to provide complex transformations
|
||||
Therefore it uses a Vector for the displacement. This transformation is convenient to provide complex transformations
|
||||
for database operations but implies rounding errors due to rounding to integer coordinates on output. It is safe to use however
|
||||
for integer-factor scaling operations for example.
|
||||
</li>
|
||||
<li><class_doc href="VCplxTrans"/>: takes floating-point coordinates and integer coordinates.
|
||||
Therefore it also uses a Vector for the displacement. The inverse of this transformation is a
|
||||
CplxTrans object.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Multiplication of a transformation with an object renders the transformed object:
|
||||
</p>
|
||||
|
||||
<pre>t = ... # a transformation
|
||||
p = ... # some point
|
||||
|
||||
# compute the transformed point:
|
||||
q = t * p</pre>
|
||||
|
||||
<p>
|
||||
Multiplication of two transformations corresponds to concatenation of two transformations:
|
||||
</p>
|
||||
|
||||
<pre>t1 = ... # a transformation
|
||||
t2 = ... # another transformation
|
||||
|
||||
# Multiplication of t2 and t1 renders an equivalent transformation
|
||||
# that corresponds to "apply t1 first and then t2":
|
||||
(t2 * t1) * p == t2 * (t1 * p)</pre>
|
||||
|
||||
<p>
|
||||
When multiplying two complex transformations, the resulting transformation type will
|
||||
have the corresponding input and output types. For example when multiplying a VCplxTrans with
|
||||
a CplxTrans, a ICplxTrans object will be created. This is because the first transformation
|
||||
takes integers and the second one delivers integers. Hence the resulting transformation
|
||||
is ICplxTrans.
|
||||
</p>
|
||||
|
||||
<h2>The Region class</h2>
|
||||
|
||||
<keyword name="Region"/>
|
||||
|
|
|
|||
Loading…
Reference in New Issue