From 5b6b800e9d566d53898368ebc16fcfb35fb8c8cb Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Sat, 5 Aug 2017 22:13:00 +0200 Subject: [PATCH] Updated documentation. --- src/lay/doc/programming/database_api.xml | 105 ++++++++++++++++++- src/lay/doc/programming/geometry_api.xml | 125 ++++++++++++++++++----- 2 files changed, 202 insertions(+), 28 deletions(-) diff --git a/src/lay/doc/programming/database_api.xml b/src/lay/doc/programming/database_api.xml index 56aedf83f..a6b01b89d 100644 --- a/src/lay/doc/programming/database_api.xml +++ b/src/lay/doc/programming/database_api.xml @@ -112,6 +112,15 @@ layout.write("my_layout.gds") in every cell and inside a cell, a shape storage for each layer is provided.

+

+ 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 , + etc. Most objects also support floating-point coordinate objects (, 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. +

+

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) created, the editable mode cannot be changed.

+

Meta information

+ +

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". +

+ +

The layout object offers methods to retrieve that information: will + iterate over the meta data (returning a object). + will get the value for a given name. will add a new meta information object + and will delete one. +

+ +

+ Meta information is a different concept than properties. +

+

Cell related methods

-

Cells can be created using the or method. This method expects a cell name. If a cell with that +

Cells can be created using the 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. or can be used to change the name of a cell. The Cell object for a given name can be obtained with which returns the Cell @@ -299,6 +325,10 @@ lv.remove_unused_layers It is a special layer that serves as a container for shapes which parametrize PCells. The index of that layer can be obtained with .

+

A list of the indexes for all layers inside the layout can be obtained with . + A corresponding list of LayerInfo objects can be obtained with . +

+

Recursive full or region queries

@@ -480,6 +510,11 @@ shape.set_property(1, "NewValue") number are specified, the name matches exactly.

+

+ LayerInfo objects supply a hash value () and can therefore be used as + keys in Ruby hashes. +

+

The Cell class

@@ -499,6 +534,12 @@ shape.set_property(1, "NewValue") and PCell parameters as well and can be used as a descriptive title for the cell in user interfaces.

+

+ 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 . +

+

A cell that represents a cell imported from a library or a PCell variant (or both) is called a proxy cell. For such cells, returns true. Such cells should not be manipulated since they may be refreshed @@ -603,6 +644,14 @@ end 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.

+ +

+ Interfaces to floating-point working classes such as 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. +

Cells and hierarchy

@@ -710,6 +759,14 @@ end new Instance pointer to the new cell instance.

+

+ A floating-point integer class exists too (). 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. +

+

Cells, libraries and PCells

If a cell is a cell imported from a library, will return true and it is possible to derive @@ -804,6 +861,11 @@ end a modified copy (out-of-place). Various variants of the and methods exist taking different forms of transformations (simple, complex).

+ +

+ The floating-point variant () behaves the same way, except that by convention the + unit of coordinates is micrometers. +

The Instance class

@@ -864,8 +926,8 @@ end

A Shapes container is usually obtained from a cell with a given layer index and is filled with geometrical primitives using one of the 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"): 

# cell = a Cell object
@@ -873,6 +935,15 @@ end
shapes = cell.shapes(layer_index) shapes.insert(RBA::Box::new(0, 0, 1000, 2000)) +

+ With floating-point objects: +

+ +
# 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))
+

A Shapes object can also be created without a cell:

@@ -1040,7 +1111,13 @@ end

- The layer index a shape is on can be derived with . + Floating-point objects are supported too. For example, is equivalent to , + but delivers the object in micrometer units. receives a micrometer-unit object. + is equivalent to , but gets the first point of the box in micrometer units. +

+ +

+ The layer index a shape is on can be obtained with . A shape can be moved to a different layer by assigning a different layer index with . In that context, layers can also be addressed by layer/datatype or name using a object. The respective methods to address a shape's layer then are and @@ -1060,6 +1137,10 @@ end and get or modify individual aspects of the box.

+ +

+ For the floating-point equivalents in micrometer units see the . +

Methods applying for polygon and simple polygon shapes

@@ -1086,6 +1167,10 @@ end given new one.

+

+ For the floating-point equivalents in micrometer units see the . +

+

Methods applying for path shapes

A Shape object represents a path if it returns true on . @@ -1107,6 +1192,10 @@ end used to obtain the path's contour.

+

+ For the floating-point equivalents in micrometer units see the . +

+

Methods applying for text shapes

A Shape object represents a text object if it returns true on . @@ -1129,6 +1218,10 @@ end shape with the given Text object.

+

+ For the floating-point equivalents in micrometer units see the . +

+

Methods applying for edge shapes

@@ -1142,6 +1235,10 @@ end getter and setter.

+

+ For the floating-point equivalents in micrometer units see the . +

+ diff --git a/src/lay/doc/programming/geometry_api.xml b/src/lay/doc/programming/geometry_api.xml index 5bbe8cfea..7b75c79fc 100644 --- a/src/lay/doc/programming/geometry_api.xml +++ b/src/lay/doc/programming/geometry_api.xml @@ -35,6 +35,35 @@ methods. The * operator used with a factor as the second operand will scale both the x and y coordinates.

+

Points and vectors

+ + +

+ Next to points there is a corresponding vector class (). + 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: +

+ +
    +
  • Subtracting a point from a point renders a vector
    • +
  • Adding a vector to a point renders a point
    • +
+ +

+ As points, vectors have an x and a y component which can be accessed with and . + Vectors offer two functions to compute the vector product () and the scalar product + (). For some applications it's sufficient to know the sign of the product. You can + get that with and respectively. +

+ +

+ 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: +

+ + 
(p1 - p2).transformed(t) == p1.transformed(t) - p2.transformed(t)
+

The Box class

@@ -105,11 +134,11 @@ 
# 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)
@@ -119,9 +148,16 @@ transformed_box_as_polygon = RBA::Polygon::new(box).transformed_cplx(RBA::ICplxT -

The class method 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. +

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:

+ + 
dbox = RBA::DBox::new(2.1, 3.1, 10.7, 11.8)
+box = RBA::Box::new(dbox)
+# -> (2,3;11,12)
+ +

An integer box can be turned into a floating-point unit box using

The SimplePolygon class

@@ -389,22 +425,28 @@ a == b # -> 0.0999999999999999916733

- 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. +

+ +

+ Some operations which are implemented on integer coordinates (like the removal of holes in polygons) are not available for the floating-point type objects.

- All floating-point type objects have class methods like "from_i.." (i.e. ) 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. ). 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. ) 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. + . 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.

- For the point object there is also a floating-point equivalent (DPoint, see ). Is behaves like - the integer-coordinate point. + For the point and vector object there is also a floating-point equivalent ( and ). + Both behaves like their integer-coordinate equivalent.

Transformations

@@ -414,20 +456,23 @@ a == b + +

- 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:

    -
  • Mirroring around the x axis
    • +
  • Mirroring around the x axis (optional)
  • Rotation
  • Scaling
  • Displacement

- 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. The 8 possible rotation/mirror variants can be coded in a single rotation/mirror code which is used frequently throughout KLayout (see ). @@ -435,30 +480,62 @@ a == b

For transforming floating-point coordinates, the 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).

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.

  • : 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).
  • : 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.
  • : 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.
    • +
  • : 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. +
+

+ Multiplication of a transformation with an object renders the transformed object: +

+ + 
t = ... # a transformation
+p = ... # some point
+
+# compute the transformed point:
+q = t * p
+ +

+ Multiplication of two transformations corresponds to concatenation of two transformations: +

+ + 
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)
+ +

+ 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. +

+

The Region class