KLayout Documentation (Qt 4): Main Index » Class Index » API reference - Class Box

API reference - Class Box

Description: A box class with integer coordinates

Public constructors
Public methods
Public static methods and constants
Deprecated methods (protected, public, static, non-static and constructors)
Detailed description

This object represents a box (a rectangular shape).

The definition of the attributes is: p1 is the lower left point, p2 the upper right one. If a box is constructed from two points (or four coordinates), the coordinates are sorted accordingly.

A box can be empty. An empty box represents no area (not even a point). Empty boxes behave neutral with respect to most operations. Empty boxes return true on empty?.

A box can be a point or a single line. In this case, the area is zero but the box still can overlap other boxes for example and it is not empty.

See The Database API for more details about the database objects.

Public constructors

new Box ptr	new	(const DBox dbox)	Creates an integer coordinate box from a floating-point coordinate box
new Box ptr	new		Creates an empty (invalid) box
new Box ptr	new	(int left, int bottom, int right, int top)	Creates a box with four coordinates
new Box ptr	new	(const Point lower_left, const Point upper_right)	Creates a box from two points

Public methods

[const]	bool	!=	(const Box box)	Returns true if this box is not equal to the other box
[const]	Box	&	(const Box box)	Returns the intersection of this box with another box
[const]	Box	*	(const Box box)	Returns the convolution product from this box with another box
[const]	Box	*	(double scale_factor)	Returns the scaled box
[const]	Box	+	(const Point point)	Joins box with a point
[const]	Box	+	(const Box box)	Joins two boxes
[const]	bool	<	(const Box box)	Returns true if this box is 'less' than another box
[const]	bool	==	(const Box box)	Returns true if this box is equal to the other box
	void	_create		Ensures the C++ object is created
	void	_destroy		Explicitly destroys the object
[const]	bool	_destroyed?		Returns a value indicating whether the object was already destroyed
[const]	bool	_is_const_object?		Returns a value indicating whether the reference is a const reference
	void	_manage		Marks the object as managed by the script side.
	void	_unmanage		Marks the object as no longer owned by the script side.
[const]	double	area		Computes the box area
	void	assign	(const Box other)	Assigns another object to self
[const]	int	bottom		Gets the bottom coordinate of the box
	void	bottom=	(int c)	Sets the bottom coordinate of the box
[const]	Point	center		Gets the center of the box
[const]	bool	contains?	(int x, int y)	Returns true if the box contains the given point
[const]	bool	contains?	(const Point point)	Returns true if the box contains the given point
[const]	new Box ptr	dup		Creates a copy of self
[const]	bool	empty?		Returns a value indicating whether the box is empty
	Box	enlarge	(int dx, int dy)	Enlarges the box by a certain amount.
	Box	enlarge	(const Vector enlargement)	Enlarges the box by a certain amount.
[const]	Box	enlarged	(int dx, int dy)	Enlarges the box by a certain amount.
[const]	Box	enlarged	(const Vector enlargement)	Returns the enlarged box.
[const]	unsigned long	hash		Computes a hash value
[const]	unsigned int	height		Gets the height of the box
[const]	bool	inside?	(const Box box)	Tests if this box is inside the argument box
[const]	bool	is_point?		Returns true, if the box is a single point
[const]	int	left		Gets the left coordinate of the box
	void	left=	(int c)	Sets the left coordinate of the box
	Box	move	(int dx, int dy)	Moves the box by a certain distance
	Box	move	(const Vector distance)	Moves the box by a certain distance
[const]	Box	moved	(int dx, int dy)	Moves the box by a certain distance
[const]	Box	moved	(const Vector distance)	Returns the box moved by a certain distance
[const]	bool	overlaps?	(const Box box)	Tests if this box overlaps the argument box
[const]	Point	p1		Gets the lower left point of the box
	void	p1=	(const Point p)	Sets the lower left point of the box
[const]	Point	p2		Gets the upper right point of the box
	void	p2=	(const Point p)	Sets the upper right point of the box
[const]	unsigned long	perimeter		Returns the perimeter of the box
[const]	int	right		Gets the right coordinate of the box
	void	right=	(int c)	Sets the right coordinate of the box
[const]	DBox	to_dtype	(double dbu = 1)	Converts the box to a floating-point coordinate box
[const]	string	to_s		Returns a string representing this box
[const]	int	top		Gets the top coordinate of the box
	void	top=	(int c)	Sets the top coordinate of the box
[const]	bool	touches?	(const Box box)	Tests if this box touches the argument box
[const]	Box	transformed	(const ICplxTrans t)	Transforms the box with the given complex transformation
[const]	Box	transformed	(const Trans t)	Returns the box transformed with the given simple transformation
[const]	DBox	transformed	(const CplxTrans t)	Returns the box transformed with the given complex transformation
[const]	unsigned int	width		Gets the width of the box

Public static methods and constants

new Box ptr

from_s

(string s)

Creates a box object from a string

Deprecated methods (protected, public, static, non-static and constructors)

	void	create		Use of this method is deprecated. Use _create instead
	void	destroy		Use of this method is deprecated. Use _destroy instead
[const]	bool	destroyed?		Use of this method is deprecated. Use _destroyed? instead
[static]	new Box ptr	from_dbox	(const DBox dbox)	Use of this method is deprecated. Use new instead
[const]	bool	is_const_object?		Use of this method is deprecated. Use _is_const_object? instead

Detailed description

!=

Signature: [const] bool != (const Box box)

Description: Returns true if this box is not equal to the other box

Returns true, if this box and the given box are not equal

&

Signature: [const] Box & (const Box box)

Description: Returns the intersection of this box with another box

box:

The box to take the intersection with

Returns:

The intersection box

The intersection of two boxes is the largest box common to both boxes. The intersection may be empty if both boxes to not touch. If the boxes do not overlap but touch the result may be a single line or point with an area of zero. Overwrites this box with the result.

*

Signature: [const] Box * (const Box box)

Description: Returns the convolution product from this box with another box

box:

The box to convolve with this box.

Returns:

The convolved box

The * operator convolves the firstbox with the one given as the second argument. The box resulting from "convolution" is the outer boundary of the union set formed by placing the second box at every point of the first. In other words, the returned box of (p1,p2)*(q1,q2) is (p1+q1,p2+q2).

Signature: [const] Box * (double scale_factor)

Description: Returns the scaled box

scale_factor:

The scaling factor

Returns:

The scaled box

The * operator scales the box with the given factor and returns the result.

This method has been introduced in version 0.22.

+

Signature: [const] Box + (const Point point)

Description: Joins box with a point

point:

The point to join with this box.

Returns:

The box joined with the point

The + operator joins a point with the box. The resulting box will enclose both the original box and the point.

Signature: [const] Box + (const Box box)

Description: Joins two boxes

box:

The box to join with this box.

Returns:

The joined box

The + operator joins the first box with the one given as the second argument. Joining constructs a box that encloses both boxes given. Empty boxes are neutral: they do not change another box when joining. Overwrites this box with the result.

<

Signature: [const] bool < (const Box box)

Description: Returns true if this box is 'less' than another box

Returns true, if this box is 'less' with respect to first and second point (in this order)

==

Signature: [const] bool == (const Box box)

Description: Returns true if this box is equal to the other box

Returns true, if this box and the given box are equal

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

area

Signature: [const] double area

Description: Computes the box area

Returns the box area or 0 if the box is empty

assign

Signature: void assign (const Box other)

Description: Assigns another object to self

bottom

Signature: [const] int bottom

Description: Gets the bottom coordinate of the box

Python specific notes:
The object exposes a readable attribute 'bottom'. This is the getter.

bottom=

Signature: void bottom= (int c)

Description: Sets the bottom coordinate of the box

Python specific notes:
The object exposes a writable attribute 'bottom'. This is the setter.

center

Signature: [const] Point center

Description: Gets the center of the box

contains?

Signature: [const] bool contains? (int x,int y)

Description: Returns true if the box contains the given point

Returns:

true if the point is inside the box.

Tests whether a point (x, y) is inside the box. It also returns true if the point is exactly on the box contour.

Signature: [const] bool contains? (const Point point)

Description: Returns true if the box contains the given point

The point to test against.

Returns:

true if the point is inside the box.

Tests whether a point is inside the box. It also returns true if the point is exactly on the box contour.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

dup

Signature: [const] new Box ptr dup

Description: Creates a copy of self

empty?

Signature: [const] bool empty?

Description: Returns a value indicating whether the box is empty

An empty box may be created with the default constructor for example. Such a box is neutral when combining it with other boxes and renders empty boxes if used in box intersections and false in geometrical relationship tests.

enlarge

Signature: Box enlarge (int dx,int dy)

Description: Enlarges the box by a certain amount.

Returns:

A reference to this box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Signature: Box enlarge (const Vector enlargement)

Description: Enlarges the box by a certain amount.

enlargement:

The grow or shrink amount in x and y direction

Returns:

A reference to this box.

Enlarges the box by x and y value specified in the vector passed. Positive values with grow the box, negative ones will shrink the box. The result may be an empty box if the box disappears. The amount specifies the grow or shrink per edge. The width and height will change by twice the amount. Does not check for coordinate overflows.

enlarged

Signature: [const] Box enlarged (int dx,int dy)

Description: Enlarges the box by a certain amount.

Returns:

The enlarged box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Signature: [const] Box enlarged (const Vector enlargement)

Description: Returns the enlarged box.

enlargement:

The grow or shrink amount in x and y direction

Returns:

The enlarged box.

from_dbox

Signature: [static] new Box ptr from_dbox (const DBox dbox)

Description: Creates an integer coordinate box from a floating-point coordinate box

Use of this method is deprecated. Use new instead

Python specific notes:
This method is the default initializer of the object

from_s

Signature: [static] new Box ptr from_s (string s)

Description: Creates a box object from a string

Creates the object from a string representation (as returned by to_s)

This method has been added in version 0.23.

hash

Signature: [const] unsigned long hash

Description: Computes a hash value

Returns a hash value for the given box. This method enables boxes as hash keys.

This method has been introduced in version 0.25.

Python specific notes:
This method is also available as 'hash(object)'

height

Signature: [const] unsigned int height

Description: Gets the height of the box

inside?

Signature: [const] bool inside? (const Box box)

Description: Tests if this box is inside the argument box

Returns true, if this box is inside the given box, i.e. the box intersection renders this box

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

is_point?

Signature: [const] bool is_point?

Description: Returns true, if the box is a single point

left

Signature: [const] int left

Description: Gets the left coordinate of the box

Python specific notes:
The object exposes a readable attribute 'left'. This is the getter.

left=

Signature: void left= (int c)

Description: Sets the left coordinate of the box

Python specific notes:
The object exposes a writable attribute 'left'. This is the setter.

move

Signature: Box move (int dx,int dy)

Description: Moves the box by a certain distance

Returns:

A reference to this box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Signature: Box move (const Vector distance)

Description: Moves the box by a certain distance

distance:

The offset to move the box.

Returns:

A reference to this box.

Moves the box by a given offset and returns the moved box. Does not check for coordinate overflows.

moved

Signature: [const] Box moved (int dx,int dy)

Description: Moves the box by a certain distance

Returns:

The enlarged box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Signature: [const] Box moved (const Vector distance)

Description: Returns the box moved by a certain distance

distance:

The offset to move the box.

Returns:

The moved box.

Moves the box by a given offset and returns the moved box. Does not modify this box. Does not check for coordinate overflows.

new

Signature: [static] new Box ptr new (const DBox dbox)

Description: Creates an integer coordinate box from a floating-point coordinate box

This constructor has been introduced in version 0.25 and replaces the previous static method 'from_dbox'.

Python specific notes:
This method is the default initializer of the object

Signature: [static] new Box ptr new

Description: Creates an empty (invalid) box

Empty boxes don't modify a box when joined with it. The intersection between an empty and any other box is also an empty box. The width, height, p1 and p2 attributes of an empty box are undefined. Use empty? to get a value indicating whether the box is empty.

Python specific notes:
This method is the default initializer of the object

Signature: [static] new Box ptr new (int left,int bottom,int right,int top)

Description: Creates a box with four coordinates

Four coordinates are given to create a new box. If the coordinates are not provided in the correct order (i.e. right < left), these are swapped.

Python specific notes:
This method is the default initializer of the object

Signature: [static] new Box ptr new (const Point lower_left,const Point upper_right)

Description: Creates a box from two points

Two points are given to create a new box. If the coordinates are not provided in the correct order (i.e. right < left), these are swapped.

Python specific notes:
This method is the default initializer of the object

overlaps?

Signature: [const] bool overlaps? (const Box box)

Description: Tests if this box overlaps the argument box

Returns true, if the intersection box of this box with the argument box exists and has a non-vanishing area

p1

Signature: [const] Point p1

Description: Gets the lower left point of the box

Python specific notes:
The object exposes a readable attribute 'p1'. This is the getter.

p1=

Signature: void p1= (const Point p)

Description: Sets the lower left point of the box

Python specific notes:
The object exposes a writable attribute 'p1'. This is the setter.

p2

Signature: [const] Point p2

Description: Gets the upper right point of the box

Python specific notes:
The object exposes a readable attribute 'p2'. This is the getter.

p2=

Signature: void p2= (const Point p)

Description: Sets the upper right point of the box

Python specific notes:
The object exposes a writable attribute 'p2'. This is the setter.

perimeter

Signature: [const] unsigned long perimeter

Description: Returns the perimeter of the box

This method is equivalent to 2*(width+height). For empty boxes, this method returns 0.

This method has been introduced in version 0.23.

right

Signature: [const] int right

Description: Gets the right coordinate of the box

Python specific notes:
The object exposes a readable attribute 'right'. This is the getter.

right=

Signature: void right= (int c)

Description: Sets the right coordinate of the box

Python specific notes:
The object exposes a writable attribute 'right'. This is the setter.

to_dtype

Signature: [const] DBox to_dtype (double dbu = 1)

Description: Converts the box to a floating-point coordinate box

The database unit can be specified to translate the integer-coordinate box into a floating-point coordinate box in micron units. The database unit is basically a scaling factor.

This method has been introduced in version 0.25.

to_s

Signature: [const] string to_s

Description: Returns a string representing this box

This string can be turned into a box again by using from_s

Python specific notes:
This method is also available as 'str(object)' and 'repr(object)'

top

Signature: [const] int top

Description: Gets the top coordinate of the box

Python specific notes:
The object exposes a readable attribute 'top'. This is the getter.

top=

Signature: void top= (int c)

Description: Sets the top coordinate of the box

Python specific notes:
The object exposes a writable attribute 'top'. This is the setter.

touches?

Signature: [const] bool touches? (const Box box)

Description: Tests if this box touches the argument box

Two boxes touch if they overlap or their boundaries share at least one common point. Touching is equivalent to a non-empty intersection ('!(b1 & b2).empty?').

transformed

Signature: [const] Box transformed (const ICplxTrans t)

Description: Transforms the box with the given complex transformation

The magnifying transformation to apply

Returns:

The transformed box (in this case an integer coordinate box)

This method has been introduced in version 0.18.

Signature: [const] Box transformed (const Trans t)

Description: Returns the box transformed with the given simple transformation

The transformation to apply

Returns:

The transformed box

Signature: [const] DBox transformed (const CplxTrans t)

Description: Returns the box transformed with the given complex transformation

The magnifying transformation to apply

Returns:

The transformed box (a DBox now)

width

Signature: [const] unsigned int width

Description: Gets the width of the box