Geometry

class kipy.geometry.Angle(proto: Angle | None = None)

property degrees: float

classmethod from_degrees(degrees: float)

Initialize Angle with a value in degrees

normalize() → Angle

Normalizes the angle to fall within the range [0, 360)

Added in version 0.4.0.

normalize180() → Angle

Normalizes the angle to fall within the range [-180, 180)

Added in version 0.4.0.

to_radians() → float

class kipy.geometry.ArcStartMidEnd(proto: ArcStartMidEnd | None = None, proto_ref: ArcStartMidEnd | None = None)

bounding_box() → Box2

Returns the bounding box of the arc – not calculated by KiCad; may differ from KiCad’s

center() → Vector2 | None

Calculates the center of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The center of the arc, or None if the arc is degenerate

property end: Vector2

end_angle() → float | None

property mid: Vector2

radius() → float

Calculates the radius of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The radius of the arc, or 0 if the arc is degenerate

property start: Vector2

start_angle() → float | None

class kipy.geometry.Box2(pos_proto: Vector2 | None = None, size_proto: Vector2 | None = None)

center() → Vector2

classmethod from_pos_size(pos: Vector2, size: Vector2)

classmethod from_proto(other: Box2)

classmethod from_xywh(x_nm: int, y_nm: int, w_nm: int, h_nm: int)

inflate(amount: int)

merge(other: Vector2 | Box2)

move(delta: Vector2)

property pos: Vector2

property size: Vector2

class kipy.geometry.PolyLine(proto: PolyLine | None = None, proto_ref: PolyLine | None = None)

append(node: PolyLineNode)

clear()

property closed: bool

insert(index: int, node: PolyLineNode)

property nodes: list[PolyLineNode]

remove(node: PolyLineNode)

rotate(delta: Angle, center: Vector2)

class kipy.geometry.PolyLineNode(proto: PolyLineNode | None = None, proto_ref: PolyLineNode | None = None)

property arc: ArcStartMidEnd

static from_point(point: Vector2)

static from_xy(x: int, y: int)

property has_arc: bool

property has_point: bool

property point: Vector2

class kipy.geometry.PolygonWithHoles(proto: PolygonWithHoles | None = None, proto_ref: PolygonWithHoles | None = None)

add_hole(hole: PolyLine)

bounding_box() → Box2

property holes: list[PolyLine]

move(delta: Vector2)

property outline: PolyLine

remove_hole(hole: PolyLine)

rotate(delta: Angle, center: Vector2 | None = None)

class kipy.geometry.Vector2(proto: Vector2 | None = None)

Wraps a kiapi.common.types.Vector2, aka VECTOR2I

angle() → float

Returns the angle (direction) of the vector in radians

angle_degrees() → float

Returns the angle (direction) of the vector in degrees

Added in version 0.3.0.

classmethod from_xy(x_nm: int, y_nm: int)

Initialize Vector2 with x and y values in nanometers

classmethod from_xy_mm(x_mm: int, y_mm: int)

Initialize Vector2 with x and y values in mm

Added in version 0.3.0.

length() → float

rotate(angle: Angle, center: Vector2) → Vector2

Rotates the vector in-place by an angle in degrees around a center point

Parameters:

• angle – The angle to rotate by

• center – The center point to rotate around

Returns:

The rotated vector

Added in version 0.4.0.

property x: int

property y: int

class kipy.geometry.Vector3D(proto: Vector3D | None = None)

Wraps a kiapi.common.types.Vector3D

classmethod from_xyz(x_nm: float, y_nm: float, z_nm: float)

Initialize Vector3D with x, y, and z values in nanometers

length() → float

property x: float

property y: float

property z: float

kipy.geometry.arc_center(start: Vector2, mid: Vector2, end: Vector2) → Vector2 | None

Calculates the center of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The center of the arc, or None if the arc is degenerate

kipy.geometry.arc_end_angle(start: Vector2, mid: Vector2, end: Vector2) → float | None

Calculates the arc’s ending angle in radians, normalized to [0, 2*pi)

Returns:

The ending angle of the arc, or None if the arc is degenerate

kipy.geometry.arc_end_angle_degrees(start: Vector2, mid: Vector2, end: Vector2) → float | None

Calculates the arc’s ending angle in degrees, normalized to [0, 360)

Added in version 0.3.0.

kipy.geometry.arc_radius(start: Vector2, mid: Vector2, end: Vector2) → float

Calculates the radius of the arc. Uses a different algorithm than KiCad so may have slightly different results. The KiCad API preserves the start, middle, and end points of the arc, so any other properties such as the center point and angles must be calculated

Returns:

The radius of the arc, or 0 if the arc is degenerate

kipy.geometry.arc_start_angle(start: Vector2, mid: Vector2, end: Vector2) → float | None

Calculates the arc’s starting angle in radians, normalized to [0, 2*pi)

Returns:

The starting angle of the arc, or None if the arc is degenerate

kipy.geometry.arc_start_angle_degrees(start: Vector2, mid: Vector2, end: Vector2) → float | None

Calculates the arc’s starting angle in degrees, normalized to [0, 360)

Added in version 0.3.0.

kipy.geometry.normalize_angle_degrees(angle: float) → float

Normalizes an angle to fall within the range [0, 360)

Added in version 0.3.0.

kipy.geometry.normalize_angle_radians(angle: float) → float

Normalizes an angle to fall within the range [0, 2*pi)

Added in version 0.3.0.

Errors

exception kipy.errors.ApiError(message: str, raw_message: str = '', code: int = 3)

Raised when KiCad returns an error from an API call. This indicates that the communcation was successful, but the API call failed for some reason.

property code: int

property raw_message: str

exception kipy.errors.ConnectionError

Raised when a connection to KiCad cannot be established

exception kipy.errors.FutureVersionError

Raised when a version check shows that kicad-python is talking to a version of KiCad newer than the one it was built against

Utilities

kipy.util.units.from_mm(value_mm: float) → int

KiCad uses several internal unit systems, but for the IPC API, all distance units are defined as 64-bit nanometers :param value_mm: a quantity in millimeters :return: the quantity in KiCad API units

kipy.util.units.to_mm(value_nm: int) → float

Converts a KiCad API length/distance value (in nanometers) to millimeters

kipy.util.board_layer.canonical_name(layer: int) → str

Returns the canonical name of the given layer identifier. This is the name that is used in the KiCad user interface if the user has not set a custom layer name, and in the KiCad file formats in various places.

kipy.util.board_layer.is_copper_layer(layer: int) → bool

Checks if the given layer is a copper layer

kipy.util.board_layer.iter_copper_layers()

Yields all copper layers.

kipy.util.board_layer.layer_from_canonical_name(name: str) → int

Returns the layer identifier for the given canonical layer name, or BL_UNKNOWN if the name is not recognized.