Query: advanced search, command line: function calls available

Functions listed below can be called from a query expression.

List manipulation

llen(lst)

Determine length of a list.

Arguments:

• lst is the list (should be written as list(lst) to make sure no iteration is done)

Return value: integer length of the list.

mklist(args...)

Create a list of the objects passed.

Arguments:

Variable number of objects.

Return value: the list.

layerlist()

Returns a list of all layers.

Math & abstract geometry

distance(x1, y1, x2, y2)

Calculate the distance of two points.

Arguments:

• x1: first point, X coordinate
• y1: first point, Y coordinate
• x2: second point, X coordinate
• y2: second point, Y coordinate

Return value: floating point distance value in nanometers.

abs(number)

Returns the absolute value of a number

int(arg)

Returns the argument converted to an integer (truncating floating point numbers)

double(arg)

Returns the argument converted to a double precision number.

Object geometry

overlap(obj1, obj2, [bloat])

Returns 1 if obj1 and obj2 overlap (even if they are on different layers)

Arguments:

• obj1 and obj2 are objects;
• an optional bloat value, in coords: bloat up (or shrink, if negative) one of the objects by this value before the test.

Return value: 1 for overlap, 0 for no overlap.

intersect(obj1, obj2, [bloat])

Returns 1 if obj1 and obj2 intersect (must share a layer)

Arguments:

• obj1 and obj2 are objects;
• an optional bloat value, in coords: bloat up (or shrink, if negative) one of the objects by this value before the test.

Return value: 1 for intersection, 0 for no overlap.

pstkring(pstk, minimum_ring_thickness)

Return the number of layers on which the ring of a padstack is too thin.

Arguments:

• pstk is the padstack object
• minimum_ring_thickness is a coordinate value of the minimum ring thickness

Return value: negative on wrong arguments, 0 if the padstack does not violate the minimum_ring_thickness requirement, positive integer (number of violations) otherwise.

Networks

netlist()

Return the netlist.

Arguments: None.

Return value: an unordered list of all networks specified on the edited netlist (which is the netlist the board is currently using). Each item of the list is a net.

netterms(net)

Return terminals of a network.

Arguments:

• net is a network of the netlist of the current board.

Return value: an unordered list of objects (each terminal of the network as described by the edited netlist).

netobjs(net)

Return terminals and all copper objects galvanically connected to a network.

Arguments:

• net is a network of the netlist of the current board.

Return value: an unordered list of copper objects connected to the network.

netsegs(net)

Return a list of objects, one terminal object per disconnecte segment of the network.

Arguments:

• net is a network of the netlist of the current board.

Return value: an unordered list of terminal objects, one picked randomly from each disconnected segment of the net.

netbreak(obj, minimum_overlap)

Start a search on a galvanically connected network segment starting from an object (typically returned by netsegs()) and generate a DRC violation if there are copper objects with overlap smaller than the minimum_overlap.

Arguments:

• obj is the starting object of the search
• minimum_overlap is the coordinate value that represents the minimum required ovlerap between copper objects (e.g. 0.5mm)

Return value: a list that represents a DRC violation (or empty list).

netshort(obj, minimum_distance)

Start a search on a galvanically connected network segment starting from an object (typically returned by netsegs()) and generate a DRC violation if there are disconnected copper objects with distance smaller than the minimum_distance from the network.

Arguments:

• obj is the starting object of the search
• minimum_distance is the coordinate value that represents the minimum required distance from any non-connected copper objects (e.g. 0.5mm)

Return value: a list that represents a DRC violation (or empty list).

netlen(net)

Return the length of a 2-terminal network.

Arguments: net object or net name.

Return value: network length.

Object accessors

subcobjs(subc)

Return a list of objects that are within the subc.

Arguments:

• subc is an object of type subcircuit

Return value: an unordered list of objects.

poly_num_islands(poly)

Return the number of visible polygon islands.

Arguments:

• poly is the polygon object

Return value: 0 if the polygon has been cleared out of existnece, 1 for normal polygons and a positive integer higher than 1 if the polygon has the FULLPOLY flag and is sliced into multiple parts not naturally connected by the polygon itself.

thermal_on(tobj, lobj)

Return a string description of thermals of tobj on layer corrseponding to lobj.

Arguments:

• tobj is the object whose thermals are being queried
• lobj is either a layer or an object-on-a-layer, and it addresses the layer to query the thermals on

Return value: a string that consists of:

• empty if there's no thermal; or
• a single 'n' for no-shape; or
• a single '@' for solid connection; or
• 'o' for round, 'x' for sharp thermal
• in case of round or sharp thermal, a 'd' suffix if it is diagonal

obj_by_idpath(idpath)

Returns the object addressed by idpath.

Arguments:

• idpath is a string addressing an object on the board

Return value: the addressed object or void.

poly_is_valid(obj)

Returns true if obj is a polygon and has a valid contour. Returns false if obj is a polygon with an invalid contour (e.g. self-intersecting).

Arguments:

• obj is an object (preferrably a polygon)

Return value: 0 or 1 indicating the validity of the polygon.

text_invalid_chars(obj)

Returns the number of invalid characters of a text object. An invalid character is not rendering with the current font of the text (it is out of range or the font does not have a symbol for the character).

Arguments:

• obj is a text object

Return value: a positive integer; 0 means all characters would render properly

Advanced layer access

layer_setup(obj, directive [, res])

Takes an object and executes a directive on the layer setup of the object. If the directive matches, retruns either a measure (if result is specified) or returns true.

Directive is a comma separated list of requirements; the directive matches only if all requirements matched. A requirement is specified in the form of key:value.

Key is a dash separated list of:

• above - match a layer group that is above the object's layer (location modifier)
• below - match a layer group that is below the object's layer (location modifier)
• on - match the layer group of the object (location modifier)
• type - match a layer group type; value is a layer group type
• net - objects belonging to a specific net on an adjacent copper layer group that covers the current object; value is the name of a net
• netmargin - supplement for the net key: require the cover to extend the specified; value is a size (coord)

Examples requirements:

• above-type:copper - there is an adjacent copper layer group above the object's layer
• below-type:!copper - there is no adjacent copper layer group below the object's layer
• above-net:vcc - there are copper objects connected to the net called "vcc" on the adjacent copper layer group above the current object
• above-net:vcc,above-netmargin:1.3mm - there are copper objects connected to the net called "vcc" on the adjacent copper layer group above the current object; coverage calculated +1.3mm around the object; defaults to 0 if not specified

"Above" and "below" are not in the board's coordinate system, but are relative to the object. In other words, the function first assumes above is upward and below is downward, then runs all requirements on the object. If there is no match, above/below directions are reversed and the test is ran again.

Example directive:

above-type:!copper,below-net:gnd,below-netmargin:125mil

This directive requires:

• there's no copper layer group above the object (so that the object is on the top or bottom copper layer group)
• the object is fully covered on the adjacent copper layer group "below" by copper objects belonging to the network named "gnd"
• plus this coverage extends beyond the object to 125mil in every direction

Normally the return value is integer 0 (no match) or 1 (match).

If the optional res parameter is specified, it must be a requirement where key is result. Alternatively the result requirement can be specified in the directive parameter. When a result is specified, the return value of layer_setup() will not be a 0/1 boolean but a readout specified by the result requirement (or the invalid value is returned on no match). The value of a result requirement is one of:

• above - use a layer group that is above the object's layer (location modifier)
• below - use a layer group that is below the object's layer (location modifier)
• on - use the layer group of the object (location modifier)
• substrate - return the substrate layer group (using the location)
• uncovered - return the area (in square nanometers) that are not covered by the "net" directive; note: the total area is the area of the original object bloated by netmargin

Complex query script example:

layer_setup(OBJ, "above-type:!copper,below-net:gnd", "result:below-substrate").a."thickness"

OBJ will match if it is on the top or bottom copper layer and is fully covered by gnd copper on the adjacent copper layer group on the next internal copper layer group. When matched, the return value of layer_setup is the substrate layer group between the object's layer and that adjacent internal layer group. The .a."thickness" part retrieves the value of the thickness attribute of this substrate layer. On mismatch, the whole expression evaluates to the invalid value.

Misc

action(args...)

Execute a pcb-rnd action.

Arguments: variable nunmber of objects and constants.

Return value: invalid on error, or the return value of the action.

coord(str)

Converts str to coordinates. Useful when using attribute values.

Arguments:

• str is a string (number with units) or a numeric value (taken as nanometers)

Return value: integer length of the list.

isvoid(value)

Checks whether value is void (invalid).

Arguments:

• value is any value, typically a function call

Return value: 1 if value is void (invalid), 0 otherwise.

getconf(path)

Fetch the value of a config node

Arguments:

• path is a conf node path, e.g. editor/grid

Return value: invalid if the config node doesn't exist, else the value of the config node (converted to the most appropriate data type).

violation(i1, v1, ..., iN, vN)

Build a DRC violation report (a list object).

Arguments (a variable number of pairs of instruction and value):

• i is an instruction, see below.
• v is a value (a constant or an object)

Instruction is one of the following constants:

• DRCGRP1 - the following v is an object, part of group 1 of offending objects
• DRCGRP2 - the following v is an object, part of group 2 of offending objects
• DRCEXPECT - the following v is a numeric value that represent the expected value
• DRCMEASURE - the following v is a numeric value that represent the measured value that mismatches the expected value

Return value: a list suitable for the drc_query to process.