next up previous contents index
Next: Operations Up: Computational Geometry and Layer Previous: Computational Geometry and Layer   Contents   Index


Trapezoid Lists and Layer Expressions

For the functions described below, a ``zoidlist'' argument can actually have the following data types:

zoidlist Obviously
integer zero Implies an empty zoidlist
integer nonzero Implies the reference zoidlist
string The string is parsed as a layer expression, which is evaluated, and the result used
layer_expr evaluate layer expression, use result

(int) SetZref(arg)
This function sets the reference zoidlist. The reference zoidlist represents the current ``background'' needed by some functions and operators which manipulate zoidlists. For example, when a zoidlist is polarity inverted, the reference zoidlist specifies the boundary of the inversion, i.e., the inverse of an empty zoidlist would be the reference zoidlist.

The reference zoidlist can be set from various types of object passed as the arg. This can be a zoidlist, or an object handle, or an array of size 4 or larger, which contains rectangle coordinates in microns in order left, bottom, right, top. The argument can also be the constant 0, in which case the reference zoid list will be the boundary of the physical current cell, or a large ``infinity'' box if there is no current cell. This is the default if no reference zoid list is given.

This function will return 1 and fails only if the argument is not an appropriate type.

(zoidlist) GetZref()
This function returns the current reference zoidlist, which will be empty if no reference area has been set with SetZref or otherwise.

(int) GetZrefBB(array)
This will return the bounding box of the reference zoidlist, as returned from GetZref. If the reference zoidlist is empty, the bounding box of the current cell is returned. The coordinates are in microns, in order left, bottom, right, top. On success, the function returns 1. If there is no reference zoidlist or current cell, 0 is returned.

(int) AdvanceZref(clear, array)
This function allows iteration over a given area by establishing a grid over the area and incrementally setting the reference area (see SetZref) to elements of the grid. The grid is aligned from the lower-left corner of the given area and iteration advances right and up. The reference area is set to the intersection of the grid element area and the given area. The size of the square grid elements is given by the PartitionSize variable, or defaults to 100 microns if this variable is not set.

The second argument is an array of size 4 or larger, or 0. If 0, the given area is taken to be the bounding box of the current cell. Otherwise, the array elements define the given rectangular area, in microns, in order left, bottom, right, top.

With the boolean first argument set to zero, the function will set the reference area to the first (lower left) or next grid element intersection area and return 1. The function will return zero when it advances past the last grid element that overlaps the given area, at which time the reference area is returned to the default value. Thus, this function can be used in a loop to limit the computation area for each iteration, for large cells that would be inefficient to process in one step.

If the first argument is nonzero, the internal state is cleared. This should be called if the iteration is not complete and one wishes to start a new loop.

(zoidlist) Zhead(zoidlist)
This function will remove the first trapezoid from the passed trapezoid list, and return it as a new list. If the passed list is empty, the returned list will be empty. If the passed list contains a single trapezoid, it will become empty.

(int) Zvalues(zoidlist, array)
This function will return the coordinates of the first trapezoid in the list in the array, which must have size 6 or larger. The order of the values is

0 x lower-left
1 x lower-right
2 y lower
3 x upper-left
4 x upper-right
5 y upper

On success, 1 is returned. If the passed trapezoid list is empty, the return value is 0 and the array is untouched.

(int) Zlength(zoidlist)
This function returns the number of trapezoids contained in the list passed as an argument.

(int) Zarea(zoidlist)
This function returns the total area of the trapezoids contained in the list passed as an argument, in square microns. This does not account for overlapping trapezoids, call GeomOr first if overlapping trapezoids are present (lists returned from the script functions have already been clipped/merged unless otherwise noted).

(zoidlist) GetZlist(layersrc, depth)
This function returns a zoidlist from the layer source given in the first argument, which is a string in the form
lname[.stname][.cellname]
Any of lname, stname, cname can be double-quoted, which must be true if the token contains the separation char `.'. The stname is the name of a symbol table, the cname is tha name of a cell found in the symbol table. If there are only two fields, the second field is cname, and the current symbol table is understood. If no cname is given, the current cell is understood.

The returned list is clipped to the current reference area (see SetZref). The second argument is the hierarchy depth to search, which can be a non-negative integer or a string starting with `a' to indicate ``all''. If not called in physical mode, an empty list is returned.

The layer specification can also be given in the form

lname.@dbname
where dbname is the name of a saved database. Operation will be similar to the GetZlistDb script function.

(zoidlist) GetSqZlist(layername)
This function returns a trapezoid list derived from objects in the selection queue on the layer whose name is passed as the argument. Labels are ignored, as are subcells unless the layer name is the special name ``$$'', in which case the subcell bounding boxes are returned.

This function can be called successfully only in physical mode.

(zoidlist) TransformZ(zoidlist, refx, refy, newx, newy)
Return a transformed copy of the passed trapezoid list. The transform should have been set previously with SetTransform or equivalent. The original list is not touched and can be closed if no longer needed. The function internally converts each input trapezoid to a polygon, applies the transformation to the polygon coordinates, then decomposes the polygons into a new trapezoid list, which is returned.

The remaining arguments are ``reference'' and ``new'' coordinates, which provide for translations. The reference point is the point about which rotations and mirroring are performed, and is translated to the new location, if different.

(zoidlist) BloatZ(dimen, zoidlist, mode)
This function returns a new zoidlist which is a bloated version of the zoidlist passed as an argument (similar to the !bloat command). Edges will be pushed outward or pulled inward by dimen (positive values push outward). The dimen is given in microns.

The third argument is an integer that specifies the algorithm to use for bloating. Giving zero specifies the default algorithm. See the description of the !bloat command (19.13.12) for documentation of the algorithms available.

(zoidlist) ExtentZ(zoidlist)
This will return a zoidlist with at most one component: a rectangle giving the bounding box of the list given as an argument. If the passed list is null, the return is a null list.

(zoidlist) EdgesZ(dimen, zoidlist, mode)
This returns a list of zoids that in some way describe edges in the zoid list passed. The dimen is given in microns.

The mode is an integer which specifies the algorithm to use to define the edges. The values 0-3 are equivalent to the BloatZ function returning edges only, with the four corner fill-in modes.

mode 0
Provides an edge template as from the BloatZ function with corner fill-in mode 0 (rounded corners).

mode 1
Provides an edge template as from the BloatZ function with corner fill-in mode 1 (flat corners).

mode 2
Provides an edge template as from the BloatZ function with corner fill-in mode 2 (projected corners).

mode 3
Provides an edge template as from the BloatZ function with corner fill-in mode 3 (no corner fill).

mode 4
The zoid list is logically merged into distinct polygons, and a ``halo'' extending outside of the polygon by width dimen (positive value taken) is constructed. The trapezoids describing the halo are returned.

mode 5
The zoid list is logically merged into distinct polygons, and a wire object is constructed using each polygon vertex list. The wire width is twice the dimen value passed. The trapezoid list representing the wire area is returned. This may fail and give strange shapes if the dimensions of a polygon are smaller than half the wire width.

mode 6
For each zoid in the zoidlist argument, a new zoid is constructed from each edge that covers the area within +/- dimen normal to the edge. The list of new zoids is returned.

(zoidlist) ManhattanizeZ(dimen, zoidlist, mode)
This function returns a new zoidlist which is a Manhattan approximation of the zoidlist passed as an argument (similar to the !manh command). The first argument is the minimum rectangle width or height in microns used to approximate non-Manhattan pieces. The third argument is a boolean which specifies which of the two algorithms to employ. These algorithms are described with the !manh command, though in this function there is no reassembly into polygons.

All of the returned trapezoids are rectangles. The function will fail if the argument is smaller than 0.01.

(zoidlist) RepartitionZ(zoidlist)
This is a rather obscure function that conditions a list of trapezoids so that the area covered will be constructed with trapezoids that are as long (horizontally) as possible. Logically, this is what would happen if the initial trapezoid list was converted to distinct polygons, then split back into trapezoids.

(zoidlist) BoxZ(l, b, r, t)
This function returns a zoidlist containing a single trapezoid which represents the box given in the arguments. The given coordinates are in microns. This function never fails.

(zoidlist) ZoidZ(xll, xlr, yl, xul, xur, yu)
This function returns a zoidlist containing a single horizontal trapezoid which represents the horizontal trapezoid given in the arguments. The six numbers must represent a non-degenerate figure or the function will fail. The given coordinates are in microns.

(zoidlist) ObjectZ(object_handle all)
This function returns a zoidlist which is generated by fracturing the outlines of the objects in the object_handle. If all is 0, only the first object in the list is used. If all is nonzero, all objects in the list are used. This function will fail if the first argument is not a handle to an object list.

(layer_expr) ParseLayerExpr(string)
This function returns a variable which contains a parse tree for a layer expression contained in the string passed as an argument. The resulting variable is used to rapidly evaluate the layer expression. The return value can not be assigned or otherwise manipulated, and can only be passed to functions that expect this variable type. The function will fail on a parse error in the layer expression.

(zoidlist) EvalLayerExpr(layer_expr, zoidlist, depth, isclear)
This function evaluates the layer expression passed as the first argument. The first argument can be a string containing the layer expression, or a return from ParseLayerExpr. If the second argument is nonzero, it is taken as a reference zoidlist. If 0, the current reference zoidlist (as set with SetZref) will be used. The third argument is the depth into the cell hierarchy to process. This can be an integer, with 0 representing the current cell only, or a string starting with `a' to indicate use of all levels of the hierarchy. If isclear is 0, the returned zoidlist will represent all areas within the reference where the layer expression is ``true''. if isclear is nonzero, the complement regions will be returned. The function will fail on a parse or evaluation error.

(int) TestCoverageFull(layer_expr, zoidlist, minsize)
This function will return an integer value indicating the coverage of the layer expression given in the first argument over the regions described in the second argument. The first argument can be a string containing a layer expression, or a return from ParseLayerExpression. If the second argument is 0, the current reference zoidlist as set with SetZref is assumed. This defaults to tha area of the current cell.

The third argument is an integer which gives the minimum dimension in internal units of trapezoids which will be considered in the result. Sub-dimensional trapezoids are ignored. This minimizes false-positive tests due to ``slivers'' caused by clipping errors in non-Manhattan geometry. If the geomentry is known to be Manhattan, 0 can be used. If 45's only, 2 is recommended, otherwise 4. Negative values are taken as zero.

The function tests each dark-area trapezoid from the layer expression against the reference zoid list. It will return immediately on the first such zoid that is not fully covered by the reference zoid list.

The return value is 0 if there was only one trapezoid from the layer expression, and it did not overlap the reference zoid list. Otherwise, if all layer expression trapezoids were covered by the reference zoid list, 2 is returned, or 1 if not. Note that 1 will be returned if there is no intersection and more than one layer expression trapezoid. Use TestCoveragePartial to fully distinguish the not-full case. The present function is most efficient for determining when the layer expression dark area is or is not fully covered.

(int) TestCoveragePartial(layer_expr, zoidlist, minsize)
This function will return an integer value indicating the coverage of the layer expression given in the first argument over the regions described in the second argument. The first argument can be a string containing a layer expression, or a return from ParseLayerExpression. If the second argument is 0, the current reference zoidlist as set with SetZref is assumed. This defaults to tha area of the current cell.

The third argument is an integer which gives the minimum dimension in internal units of trapezoids which will be considered in the result. Sub-dimensional trapezoids are ignored. This minimizes false-positive tests due to ``slivers'' caused by clipping errors in non-Manhattan geometry. If the geomentry is known to be Manhattan, 0 can be used. If 45's only, 2 is recommended, otherwise 4. Negative values are taken as zero.

The function tests each dark-area trapezoid from the layer expression against the reference zoid list. It will return immediately on the first such zoid that is partially covered by the reference zoid list, of after finding both a fully covered zoid and a fully uncovered zoid.

The return value is 0 if there is no dark area from the layer expression that intersects the reference zoid list, 2 if the layer expression dark area falls entirely in the reference zoid list, and 1 if coverage is partial. This test is a bit expensive but provides definitive results,

(int) TestCoverageNone(layer_expr, zoidlist, minsize)
This function will return an integer value indicating the coverage of the layer expression given in the first argument over the regions described in the second argument. The first argument can be a string containing a layer expression, or a return from ParseLayerExpression. If the second argument is 0, the current reference zoidlist as set with SetZref is assumed. This defaults to tha area of the current cell.

The third argument is an integer which gives the minimum dimension in internal units of trapezoids which will be considered in the result. Sub-dimensional trapezoids are ignored. This minimizes false-positive tests due to ``slivers'' caused by clipping errors in non-Manhattan geometry. If the geomentry is known to be Manhattan, 0 can be used. If 45's only, 2 is recommended, otherwise 4. Negative values are taken as zero.

The function tests each dark-area trapezoid from the layer expression against the reference zoid list. It will return immediately on the first such zoid that is not completely uncovered by the reference zoid list.

The return value is 0 if there is no dark area from the layer expression that intersects the reference zoid list, 1 otherwise. This test is most efficient when determining whether or not the layer expression dark area intersects the reference list.

(int) TestCoverage(layer_expr, zoidlist, testfull)
This function is deprecated and should not be used in new scripts. The TestCoverageFull, TestCoveragePartial, and TestCoverageNone functions are replacements.

When the boolean testfull is true, this function is identical to TestCoveragePartial with a minsize value of 4. When testfull is false, this function is equivalent to TestCoverageNone again with a minsize of 4.

(object_handle) ZtoObjects(zoidlist, lname, join, to_dbase)
This function will create a list of objects from a zoidlist. The objects will be created on the layer whose name is given in the second argument, which will be created if it does not already exist. If this argument is 0, the current layer will be used. If the join argument is nonzero, the objects created will comprise a minimal set of polygons that enclose all of the trapezoids. If the join argument is 0, the objects will be have the same geometry as the individual trapezoids. If the to_dbase argument is nonzero, the new objects will be added to the database. Otherwise, the new objects will be ``copies'' that can be manipulated with other functions that accept object copies, but they will not appear in the database. The function will fail if not called in physical mode, or the layer could not be created.

(int) ZtoTempLayer(longname, zoidlist, join)
This function creates a temporary layer using longname, and adds the content of the zoidlist to the new layer, in the current cell. If the temporary layer for longname exists, it will be used, with existing geometry untouched. If join is nonzero, the zoidlist will be added as a minimal set of polygons, otherwise each zoid will be added as a box or polygon. The function returns 1 on success, 0 otherwise. This works in physical mode only.

(int) ClearTempLayer(longname)
This function will clear all of the objects in the current cell from the given layer, without saving them in the undo list. If successful, 1 is returned, otherwise 0 is returned. This works in physical mode only.

(int) ZtoFile(filename, zoidlist, ascii)
Save the zoidlist in a file, whose name is given in the first argument. The zoidlist can be recovered with ZfromFile.

There are two file formats available. If the boolean argument ascii is nonzero, a human-readable ASCII text file is produced. Each line contains the six numbers that describe a trapezoid, using the following C-style format string:

"yl=%d yu=%d ll=%d ul=%d lr=%d ur=%d"
The numbers are integer values in internal units (usually 1000 units per micron).

If the ascii argument is zero, the file is in OASIS format, using a single dummy cell (named ``zoidlist'') and layer (``0100''), and uses only TRAPEZOID and CTRAPEZOID geometry records. The OASIS representation is more compact and is the appropriate choice for very large trapezoid collections.

The function returns 1 if successful, 0 otherwise.

(zoidlist) ZfromFile(filename)
Read the file, which was produced by ZtoFile, and return the list of trapezoids it contains. If an error occurs in reading or an interrupt is received, this function will fail (halting the script). Otherwise a zoidlist will always be returned, but the list may be empty.

(int) ReadZfile(filename)
This will read a trapezoid list file whose name is specified as the required string argument. This is an ASCII file consisting of two types of lines:

  1. Trapezoid lines, in the ASCII format used by ZfromFile and produced by ZtoFile, i.e., in the format:
    yl=%d yu=%d ll=%d ul=%d lr=%d ur=%d

  2. Layer designation lines in the form:
    L layer_name
    The layer_name should be an Xic-style name for a layer, the layer will be created if it does not exist.

When a layer designation line is encountered, the trapezoids that have been read since the file start or last layer designator are written into the current cell on the specified layer. Thus, each block of trapezoid lines must be followed by a layer designation line for the trapezoids to be recognized.

However, if the file contains no layer designation lines, all trapezoids will be added to the current cell on the current layer.

Lines that are not recognized as one of these two forms are ignored.

This function always returns 1. The function will fail if the file can not be opened.

(zoidlist) ChdGetZlist(chd_name, cellname, scale, array, clip, all)
This function will create and return a trapezoid list created from objects read through the Cell Hierarchy Digest (CHD) whose access name is given in the first argument.

See the table in 14.1 for the features that apply during a call to this function. An overall transformation can be set with ChdSetFlatReadTransform, in which case the area given applies in the ``root'' coordinates.

The cellname, if nonzero, must be the cell name after any aliasing that was in force when the CHD was created. If cellname is passed 0, the default cell for the CHD is understood. This is a cell name configured into the CHD, or the first top-level cell found in the archive file.

The scale factor will be applied to all coordinates. The accepted range is 0.001 - 1000.0.

If the array argument is passed 0, no windowing will be used. Otherwise the array should have four components which specify a rectangle, in microns, in the coordinates of cellname. The values are

array[0] X left
array[1] Y bottom
array[2] X right
array[3] Y top

If an array is given, only the objects and subcells needed to render the window will be processed.

If the boolean value clip is nonzero and an array is given, trapezoids will be clipped to the window. Otherwise no clipping is done.

If the boolean variable all is nonzero, the objects in the hierarchy under cellname will be transformed and added to the trapezoid list, i.e., the list will be a flat representation of the entire hierarchy. Otherwise, only objects in cellname are processed.


next up previous contents index
Next: Operations Up: Computational Geometry and Layer Previous: Computational Geometry and Layer   Contents   Index
Stephen R. Whiteley 2022-05-28