The Geometry API
The Geometry API
The central class of the layout database is the Layout class, which provides a concept for layers, shape containers, cells and hierarchy. Separate from that, a set of classes exist, which represent basic shapes and geometrical objects. While shapes embedded in a Layout object are not independent and care has to be taken when manipulating them inside the database API, the free objects are easy to manage, manipulate and in general to work with as they are normal objects in the script interpreter's context.
In addition, the gometry API provides basic objects such as points, edges and transformations for general use throughout the API. Higher objects such as regions and edge collections provide implementations for geometrical algorithms like boolean operations and DRC checks.
The Point class
The Point object represents an integer coordinate in the 2-dimensional layout space, expressed in database units. That object provides the x and y coordinates through the Point#x and Point#y attributes. Points can be added, subtracted, the euclidian distance and it's square can be computed using the Point#distance and Point#sq_distance methods. The * operator used with a factor as the second operand will scale both the x and y coordinates.
The Box class
The Box object represents a rectangle whose sides are parallel to the axes. The coordinates are integer values and express the rectangle's dimensions in database units. The basic specification consists of two points, giving the lower left and upper right corner. The constructor takes either two points (which are ordered internally) or four coordinates representing the left, bottom, right and top coordinates.
A box has a couple of attributes which are shown in the figure above. The Box#area method delivers the area of the rectangle. A box can be "empty" (non-existing). Such a rectangle can be created by the default constructor without parameters. An empty box basically behaves as a region without a point, i.e. testing the intersection with an empty box always returns false. An empty box returns true on Box#empty?. A box whose lower left point is identical to the upper right one contains just a single point. Such a box returns true on Box#is_point?.
A box supports a couple of operations:
The class method 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.
The SimplePolygon class
A SimplePolygon object is a polygon that does not have holes. It consists of a single, closed contour. Such polygons are compatible with the GDS2 format for example. A SimplePolygon object can be created from a Box object or from an array of Point objects. Internally, the points will be ordered into a clockwise orientation.
The class method SimplePolygon#from_dpoly creates a integer-coordinate type SimplePolygon object from a floating-point coordinate type DSimplePolygon object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.
The SimplePolygon#bbox method returns the bounding box of the polyon. SimplePolygon#area will return the area of the polygon. SimplePolygon#num_points returns the number of points, while SimplePolygon#point returns the point for a given index. SimplePolygon#points= replaces the polygon by a new polygon with the given array of points.
The SimplePolygon#each_point iterator will deliver each point in clockwise orienation, starting form the bottom/leftmost one. SimplePolygon#each_edge will deliver all edges of the polygon (connecting every point with the next one).
SimplePolygon#compress will remove points that connect two collinear edges. It has a parameter that controls whether to remove reflecting edges (spikes) as well. SimplePolygon#inside? returns true, if a given point is inside the polygon. SimplePolygon#minkowsky_sum computes the Minkowsky sum between a polygon and another object in various flavors. SimplePolygon#move will displace the polygon by the distance given by the Point argument. SimplePolygon#moved will return the moved polygon without modifying the polygon it is called on (out-of-place operation). SimplePolygon#transformed and SimplePolygon#transformed_cplx will return the transformed polygon, either with a simple or a complex transformation (see the description of the Box object and the section about transformations below for a discussion of transformations). Finally, SimplePolygon#round_corners will apply a corner rounding to a copy of the polygon and return that copy without modifying the polygon.
Please note that using the Point-array constructors it is possible to create polygons with self-intersecting or twisted contours. Such polygons may not behave as expected.
The Polygon class
The Polygon object is basically an extension of the SimplePolygon object and in contrast to that object, supports holes. Polygon objects are not compatible with the GDS2 or OASIS format and will be converted to SimplePolygon objects by introducing cutlines when writing them.
A polygon consists of an outer contour (the hull) and zero to many hole contours. The outer contour like for the SimplePolygon is oriented clockwise while the hole contours are oriented counterclockwise. This orientation is established internally. For the API, contours are represented by arrays of Point objects.
A Polygon differs from a SimplyPolygon by providing methods to modify holes and the hull. Holes can be inserted by using the Polygon#insert_hole method. A hole is identified by an index. The Polygon#holes method returns the number of holes. The hole index runs from 0 to the number of holes minus one.
The class method Polygon#from_dpoly creates a integer-coordinate type Polygon object from a floating-point coordinate type DPolygon object (see below). The floating-point coordinates are rounded to the nearest integer coordinates. A constructor is provided that creates a Polygon object from a SimplePolygon object.
Polygon#each_edge will deliver all edges. The orientation of the edges determines whether they belong to a hole or the hull contour. Polygon#each_point_hull will iterated over all points of the hull and Polygon#each_point_hole over the points of the hole with the given index. Polygon#num_points_hull will return the number of points for the hull and Polygon#num_points_hole the number of points for the given hole. Polygon#point_hull will return a specific point from the hull and Polygon#point_hole a specific point for the given hole. Polygon#num_points returns the total number of points.
Polygon#resolve_holes will remove all holes and connect them with the hull by introducing cutlines that connect the hole with the hull. This operation introduces new vertexes and hence may apply some distortion due to grid snapping. Polygon#resolved_holes returns the polygon with the holes removed without modifying the object it is called on (out-of-place operation). Polygon#to_simple_polygon basically does the same but returns a SimplePolygon object.
Using Polygon#assign_hull (or Polygon#hull=) and Polygon#assign_hole the hull contour or a hole contour can be replaced with the given array of Point objects. Please note that it is possible to create invalid polygons where the holes are not completely contained in the hull. Such polygons may not behave as expected. The same is true for polygons with self-intersecting or twisted contours.
The Path class
A Path object represents a line with a certain width. The figure above depicts the basic properties of a path. The basic geometry of a path is defined by it's spine - a sequence of points that the path follows. By default, a path has rectangular end caps with variable length. The end caps can be round, in which case the extension should be half the path width to avoid paths which are not compatible with the GDS2 format. Round-ended paths return true on Path#is_round?. An example for such a path is depicted in the following figure:
A path with is given in database units. The hull contour of paths with an odd width cannot be represented on-grid and should be avoided. Such path objects are allowed in the GDS2 format, but not in OASIS.
The spine points of a path can be iterated with Path#each_point. Path#num_points returns the number of points. Path#point returns a specific point and Path#points= allows replacing of the spine with the given array of Point objects. Path#round= sets the "round ended" flag. Path#bbox and Path#area deliver the bounding box and the area, where the area is only approximate and is computed from the spine's length including the extensions times the width for efficiency. For certain acute-angle configurations that value may not be the exact area.
Path#polygon returns the polygon representing the path's hull. Path#simple_polygon returns a SimplePolygon object that represents the hull. Path#move, Path#moved, Path#transformed and Path#transformed_cplx basically work like for the other objects.
The class method Path#from_dpath creates a integer-coordinate type Path object from a floating-point coordinate type DPath object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.
The Text class
A Text object is basically a point with a label attached. The extension of a text object only includes the point, not the text itself. For display purposes, a text orientation, font and alignment options can be specified.
The location and the orientation of the text are combined in a Trans object. That transformation can be read and written with the Text#trans attribute. The text orientation is not always shown in the drawing. Whether the text is shown in the orientation specified depends on the application settings.
Font number and alignment flags can be read and written using the Text#font, Text#halign and Text#valign attributes. If one of these attributes is not set, the application-provided default is used. The font is currently just a number and is provided to support the respective property of the GDS2 format. For the documentation of the alignment flags see the class documentation for the Text class.
The text string is accessible with the Text#string attribute. Not all characters are supported. Depending on the format, only a subset of the ASCII character set are supported. Sometimes, line-feed control characters are found in text strings. Following the strict OASIS specification for example, such characters are not allowed. The lower and upper case letters and most of the special printing characters of the ASCII character set are usually safe for use in text strings.
Text#move, Text#moved, Text#transformed and Text#transformed_cplx basically work like for the other objects. The class method Text#from_dtext creates a integer-coordinate type Text object from a floating-point coordinate type DText object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.
The Edge class
Edge objects are basically connections between two points. Edge objects are provided to support special applications and are mapped to zero-width, two-point paths in the GDS2 format. Edge objects are not supported as editable objects in KLayout currently. Edge objects may be created by script and are useful sometimes to represent the output of a design rule check tool for example.
Edge objects however a frequently used as raw objects in various applications, i.e. as one output option of a boolean operation. Therefore, the Edge class provides a couple of operations on edges, mainly tests for the geometrical relationship of two edges and points in relation to edges. An edge also may represent a straight line through the two endpoints of the edge, i.e. for the Edge#crossed_by? check.
An edge is defined by two points: the start and end point. Edge#p1 is the attribute for the start point, Edge#p2 the attribute for the end point. Various properties deliver extensions of the edge (Edge#dx and Edge#dy for the horizontal and vertical extension, Edge#length and Edge#sq_length for the length and the square of the length, Edge#ortho_length for the Manhattan distance between the points). Edge#swap_points swaps p1 and p2 and effectively inverts the orientation of the edge. Edge#bbox is the bounding box of the edge.
Various methods test the relationship between two edges or an edge and a point. See the following figure for a summary of these methods:
Edge#move, Edge#moved, Edge#transformed and Edge#transformed_cplx basically work like for the other objects. The class method Edge#from_dedge creates a integer-coordinate type Edge object from a floating-point coordinate type DEdge object (see below). The floating-point coordinates are rounded to the nearest integer coordinates.
The floating-point geometrical primitives
Beside the integer-coordinate primitives like Box, Edge, Polygon etc., KLayout provides floating-point coordinate variants as well. These objects require more memory and are subject to floating-point rounding issues and are therefore not employed inside the database. They are provided however, to allow a temporary representation of micron-unit objects or for use int the Marker class for example.
The class names for the floating-point variants is the same the integer-coordinate type prefixed with a "D" (for example, DBox is the floating-point variant of Box). Since floating-point variants support fractional coordinates, scaling with an arbitrary value is not connected with a loss of accuracy due to rounding. That is why floating-point coordinates are the target type of general transformations including an arbitrary scaling. For example:
RBA::Box.new(1,1,2,2)*2.5 # -> (3,3;5,5) # but: RBA::DBox.new(1,1,2,2)*2.5 # -> (2.5,2.5;5,5)
However, the higher precision of floating-point coordinates comes with subtle issues originating from the finite-precision representation. For example, the value of 0.1 cannot be precisely represented by a floating-point value. The value of 0.1 is approximated and therefore depending on the way it is approximated, 0.1 is not necessarily equal to 0.1. For example (try this in the Ruby console):
a = 0.1 b = 1e-6*1e5 a # -> 0.1 b # -> 0.1 # but: a == b # -> false! # the reason is: "%.21g"%a # -> 0.100000000000000005551 "%.21g"%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) are not available for the floating-point type objects.
All floating-point type objects have class methods like "from_i.." (i.e. 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. Box#from_dbox). 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 DPoint). Is behaves like the integer-coordinate point.
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:
For memory performance, unless necessary a restricted version of that transformation is used. 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 Trans class. The 8 possible rotation/mirror variants can be coded in a single rotation/mirror code which is used frequently throughout KLayout (see Transformations in KLayout).
For transforming floating-point coordinates, the DTrans object is provided. The basic difference is that the displacement uses floating-point coordinates (by employing a DPoint 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:
The Region class
Regions are basically collections of polygons. Regions provide higher functions such as boolean operations and sizing which cannot be implemented on pure polygons because their output may be a number of polygons. A Region is a general representation of a set of points in a two-dimensional area while a polygon is a coherence set of points.
Regions can be created by starting with an empty region and filling the latter with polygons. Regions can also be created from a RecursiveShapeIterator which allows feeding layout data into the region in a very flexible way. In the latter case, boxes and paths will be converted to polygons when feeding them into the region.
Regions feature some important concepts:
The region object is very mighty and easy to use. Here is an example which computes the difference of two boxes (rendering a ring) and sizes the latter:
r1 = RBA::Region::new r1.insert(RBA::Box::new(-2000, -3000, 2000, 3000)) r2 = RBA::Region::new r2.insert(RBA::Box::new(-1500, -2000, 1500, 2000)) r = (r1 - r2).sized(100) puts r
Using a Region object with input from a cell is almost as simple as this. The following example will take the input from layer 11 and 21 from the top cell and the hierarchy below (as is flat) and compute the intersection in layer 100:
ly = RBA::CellView::active.layout l11 = ly.layer(11, 0) l21 = ly.layer(21, 0) r11 = RBA::Region::new(ly.top_cell.begin_shapes_rec(l11)) r21 = RBA::Region::new(ly.top_cell.begin_shapes_rec(l21)) ly.top_cell.shapes(ly.layer(100, 0)).insert(r11 & r21)
A variety of operations is implemented on regions:
Region#&, Region#|, Region#- and Region#^ implement boolean operations (AND, OR, NOT and XOR). The operations can be combined with assignment (in-place) using Region#&= etc. Region#+ adds the polygons from another region to self which is basically the same then a boolean OR.
Region#each will deliver all original polygons (unless the region was already merged).
Region#each_merged will deliver the merged polygons.
Region#edges will translate the polygons to edges covering their boundaries. If merged semantics is specified, the edges will only cover the outer edges, not inner ones.
Region#enclosing_check, Region#inside_check, Region#isolated_check, Region#notch_check, Region#separation_check, Region#space_check and Region#width_check implement DRC functions. DRC functions deliver EdgePairs edge pair collections, not regions. Each edge pair marks a violation of the given check.
Region#extents replaces each polygon with it's bounding box.
Region#grid_check performs an on-grid check returning edge pairs for off-grid markers.
Region#holes identifies holes and delivers a new region with the holes as filled polygons.
Region#hulls identifies holes and delivers a new region without the holes.
Region#insert adds polygons in various flavors.
Region#members_of selects polygons which are contained in the same way in another region.
Region#minkowsky_sum computes the Minkowsky sum of the region with other objects (edges, single polygons and other regions).
Region#smooth smoothes out coarse steps of the polygons.
Region#with_angle marks polygon vertices which satisfy a certain angle criterion.
The Edges class
A variety of operations is implemented on regions:
Edges#&, Edges#|, Edges#- and Edges#^ implement boolean operations (AND, OR, NOT and XOR). The operations can be combined with assignment (in-place) using Region#&= etc. Edges#+ adds the polygons from another edge set to self which is basically the same then a boolean OR. Boolean AND and NOT are available between edges and regions as well and will deliver the edge parts inside the given region or not inside the given region.
Edges#each will deliver the edges in the collection.
Edges#centers will deliver the center parts of the edges.
Edges#enclosing_check, Edges#inside_check, Edges#separation_check, Edges#space_check and Edges#width_check implement DRC functions. DRC functions deliver EdgePairs edge pair collections, not edge sets. Each edge pair marks a violation of the given check.
Edges#extents returns a region with the bounding boxes of the edges.
Edges#inside_part and Edges#outside_part return the parts of the edge set which are inside or outside a given region. The effect is comparable to the boolean operations but differs at the exact boundary of the polygons of the region.
Edges#members_of selects edges which are contained in the same way in another edge set.
The EdgePair class
Edge pairs are handy objects to describe the output of a DRC violation. A space violation marker for example will consist of two edges which mark the opposite parts of the space violation. Such markers are represented by objects of EdgePair.
Edge pairs are simple objects consisting of two edges ("first" and "second"). Polygons can generated from edge pairs covering the marked edges and their connecting files using EdgePair#polygon. Edge pairs can be transformed using EdgePair#transformed.
Edge pairs can be "normalized" using EdgePair#normalize. Normalization will bring the edge pairs in a form such that when connecting their start and end points a closed loop without intersections is formed. Normalized edge pairs will produce nicer polygons later on.
A floating-point version of the EdgePair class exists as well: DEdgePair.
The EdgePairs class
EdgePairs provides a collection of edge pairs and is the preferred output of DRC functions which deliver one DRC marker for each violation.
EdgePair collections can be conveniently split into individual edges using EdgePairs#edges or converted into polygons covering the markers with EdgePairs#polygons. The first and second edges can be extracted as a Edges edge collection with EdgePairs#first_edges and EdgePairs#second_edges. EdgePairs#extents will deliver a region containing the bounding boxes of the edge pairs.