<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">

<!-- generated by /home/matthias/klayout/dvb/scripts/extract_doc.rb  -->
<!-- DO NOT EDIT! -->

<doc>
<title>DRC Reference: Source Object</title>
<keyword name="Source"/>
<p>
The layer object represents a collection of polygons, edges or edge pairs.
A source specifies where to take layout from. That includes the actual layout,
the top cell and options such as clip/query boxes, cell filters etc.
</p>
<h2-index/>
<h2>"cell" - Specifies input from a specific cell</h2>
<keyword name="cell"/>
<a name="cell"/><p>Usage:</p>
<ul>
<li><tt>source.cell(name)</tt></li>
</ul>
<p>
This method will create a new source that delivers shapes from the 
specified cell. 
</p>
<h2>"cell_name" - Returns the name of the currently selected cell</h2>
<keyword name="cell_name"/>
<a name="cell_name"/><p>Usage:</p>
<ul>
<li><tt>cell_name</tt></li>
</ul>
<h2>"cell_obj" - Returns the <class_doc href="Cell">Cell</class_doc> object of the currently selected cell</h2>
<keyword name="cell_obj"/>
<a name="cell_obj"/><p>Usage:</p>
<ul>
<li><tt>cell_obj</tt></li>
</ul>
<h2>"clip" - Specifies clipped input</h2>
<keyword name="clip"/>
<a name="clip"/><p>Usage:</p>
<ul>
<li><tt>source.clip(box)</tt></li>
<li><tt>source.clip(p1, p2)</tt></li>
<li><tt>source.clip(l, b, r, t)</tt></li>
</ul>
<p>
Creates a source which represents a rectangular part of the 
original input. Three ways are provided to specify the rectangular
region: a single <class_doc href="DBox">DBox</class_doc> object (micron units), two <class_doc href="DPoint">DPoint</class_doc>
objects (lower/left and upper/right coordinate in micron units)
or four coordinates: left, bottom, right and top coordinate.
</p><p>
This method will create a new source which delivers the shapes
from that region clipped to the rectangle. A method doing the 
same but without clipping is <a href="#touching">touching</a> or <a href="#overlapping">overlapping</a>.
</p>
<h2>"extent" - Returns a layer with the bounding box of the selected layout</h2>
<keyword name="extent"/>
<a name="extent"/><p>Usage:</p>
<ul>
<li><tt>source.extent</tt></li>
</ul>
<p>
The extent function is useful to invert a layer:
</p><p>
<pre>
inverse_1 = extent.sized(100.0) - input(1, 0)
</pre>
</p>
<h2>"input" - Specifies input from a source</h2>
<keyword name="input"/>
<a name="input"/><p>Usage:</p>
<ul>
<li><tt>source.input(layer)</tt></li>
<li><tt>source.input(layer, datatype)</tt></li>
<li><tt>source.input(layer_into)</tt></li>
<li><tt>source.input(filter, ...)</tt></li>
</ul>
<p>
Creates a layer with the shapes from the given layer of the source.
The layer can be specified by layer and optionally datatype, by a <class_doc href="LayerInfo">LayerInfo</class_doc>
object or by a sequence of filters. 
Filters are expressions describing ranges
of layers and/or datatype numbers or layer names. Multiple filters
can be given and all layers matching at least one of these filter
expressions are joined to render the input layer for the DRC engine.
</p><p>
Some filter expressions are:
</p><p>
<ul>
<li><tt>1/0-255 </tt>: Datatypes 0 to 255 for layer 1 </li>
<li><tt>1-10 </tt>: Layers 1 to 10, datatype 0 </li>
<li><tt>METAL </tt>: A layer named "METAL" </li>
<li><tt>METAL (17/0) </tt>: A layer named "METAL" or layer 17, datatype 0 (for GDS, which does
not have names)</li>
</ul>
</p><p>
Layers created with "input" contain both texts and polygons. There is a subtle
difference between flat and deep mode: in flat mode, texts are not visible in polygon
operations. In deep mode, texts appear as small 2x2 DBU rectangles. In flat mode, 
some operations such as clipping are not fully supported for texts. Also, texts will
vanish in most polygon operations such as booleans etc.
</p><p>
Texts can later be selected on the layer returned by "input" with the <a href="/about/drc_ref_layer.xml#texts">Layer#texts</a> method.
</p><p>
If you don't want to see texts, use <a href="#polygons">polygons</a> to create an input layer with polygon data
only. If you only want to see texts, use <a href="#labels">labels</a> to create an input layer with texts only.
</p><p>
Use the global version of "input" without a source object to address the default source.
</p>
<h2>"labels" - Gets the labels (texts) from an input layer</h2>
<keyword name="labels"/>
<a name="labels"/><p>Usage:</p>
<ul>
<li><tt>source.labels(layer)</tt></li>
<li><tt>source.labels(layer, datatype)</tt></li>
<li><tt>source.labels(layer_into)</tt></li>
<li><tt>source.labels(filter, ...)</tt></li>
</ul>
<p>
Creates a layer with the labels from the given layer of the source.
</p><p>
This method is identical to <a href="#input">input</a>, but takes only texts from the given input
layer.
</p><p>
Use the global version of "labels" without a source object to address the default source.
</p>
<h2>"layers" - Gets the layers the source contains</h2>
<keyword name="layers"/>
<a name="layers"/><p>Usage:</p>
<ul>
<li><tt>source.layers</tt></li>
</ul>
<p>
Delivers a list of <class_doc href="LayerInfo">LayerInfo</class_doc> objects representing the layers
inside the source.
</p><p>
One application is to read all layers from a source. In the following
example, the "and" operation is used to perform a clip with the given
rectangle. Note that this solution is not efficient - it's provided
as an example only:
</p><p>
<pre>
output_cell("Clipped")

clip_box = polygon_layer
clip_box.insert(box(0.um, -4.um, 4.um, 0.um))

layers.each { |l| (input(l) &amp; clip_box).output(l) }
</pre>
</p>
<h2>"layout" - Returns the <class_doc href="Layout">Layout</class_doc> object associated with this source</h2>
<keyword name="layout"/>
<a name="layout"/><p>Usage:</p>
<ul>
<li><tt>layout</tt></li>
</ul>
<h2>"make_layer" - Creates an empty polygon layer based on the hierarchy of the layout</h2>
<keyword name="make_layer"/>
<a name="make_layer"/><p>Usage:</p>
<ul>
<li><tt>make_layer</tt></li>
</ul>
<p>
This method delivers a new empty original layer.
</p>
<h2>"overlapping" - Specifies input selected from a region in overlapping mode</h2>
<keyword name="overlapping"/>
<a name="overlapping"/><p>Usage:</p>
<ul>
<li><tt>source.overlapping(...)</tt></li>
</ul>
<p>
Like <a href="#clip">clip</a>, this method will create a new source delivering shapes
from a specified rectangular region. In contrast to clip, all shapes
overlapping the region with their bounding boxes are delivered as a whole
and are not clipped. Hence shapes may extent beyond the limits of
the specified rectangle.
</p><p>
<a href="#touching">touching</a> is a similar method which delivers shapes touching
the search region with their bounding box (without the requirement to overlap)
</p>
<h2>"path" - Gets the path of the corresponding layout file or nil if there is no path</h2>
<keyword name="path"/>
<a name="path"/><p>Usage:</p>
<ul>
<li><tt>path</tt></li>
</ul>
<h2>"polygons" - Gets the polygon shapes (or shapes that can be converted polygons) from an input layer</h2>
<keyword name="polygons"/>
<a name="polygons"/><p>Usage:</p>
<ul>
<li><tt>source.polygons(layer)</tt></li>
<li><tt>source.polygons(layer, datatype)</tt></li>
<li><tt>source.polygons(layer_into)</tt></li>
<li><tt>source.polygons(filter, ...)</tt></li>
</ul>
<p>
Creates a layer with the polygon shapes from the given layer of the source.
With "polygon shapes" we mean all kind of shapes that can be converted to polygons.
Those are boxes, paths and real polygons.
</p><p>
This method is identical to <a href="#input">input</a> with respect to the options supported.
</p><p>
Use the global version of "polygons" without a source object to address the default source.
</p>
<h2>"select" - Adds cell name expressions to the cell filters</h2>
<keyword name="select"/>
<a name="select"/><p>Usage:</p>
<ul>
<li><tt>source.select(filter1, filter2, ...)</tt></li>
</ul>
<p>
This method will construct a new source object with the given cell filters 
applied.
Cell filters will enable or disable cells plus their subtree.
Cells can be switched on and off, which makes the hierarchy traversal
stop or begin delivering shapes at the given cell. The arguments of 
the select method form a sequence of enabling or disabling instructions
using cell name pattern in the glob notation ("*" as the wildcard, like shell).
Disabling instructions start with a "-", enabling instructions with a "+" or
no specification.
</p><p>
The following options are available:
</p><p>
<ul>
<li><tt>+</tt><i>name_filter </i>: Cells matching the name filter will be enabled </li>
<li><i>name_filter </i>: Same as "+name_filter" </li>
<li><tt>-</tt><i>name_filter </i>: Cells matching the name filter will be disabled </li>
</ul>
</p><p>
To disable the TOP cell but enabled a hypothetical cell B below the top cell, use that
code:
</p><p>
<pre>
layout_with_selection = layout.select("-TOP", "+B")
l1 = layout_with_selection.input(1, 0)
...
</pre>
</p><p>
Please note that the sample above will deliver the children of "B" because there is 
nothing said about how to proceed with cells other than "TOP" or "B".
The following code will just select "B" without it's children, because in the 
first "-*" selection, all cells including the children of "B" are disabled:
</p><p>
<pre>
layout_with_selection = layout.select("-*", "+B")
l1 = layout_with_selection.input(1, 0)
...
</pre>
</p>
<h2>"touching" - Specifies input selected from a region in touching mode</h2>
<keyword name="touching"/>
<a name="touching"/><p>Usage:</p>
<ul>
<li><tt>source.touching(box)</tt></li>
<li><tt>source.touching(p1, p2)</tt></li>
<li><tt>source.touching(l, b, r, t)</tt></li>
</ul>
<p>
Like <a href="#clip">clip</a>, this method will create a new source delivering shapes
from a specified rectangular region. In contrast to clip, all shapes
touching the region with their bounding boxes are delivered as a whole
and are not clipped. Hence shapes may extent beyond the limits of
the specified rectangle.
</p><p>
<a href="#overlapping">overlapping</a> is a similar method which delivers shapes overlapping
the search region with their bounding box (and not just touching)
</p>
</doc>
