API Reference

This page contains the API reference for the Session PY library.

Point Module

class session_py.point.Point(x=0.0, y=0.0, z=0.0)

Bases: object

A 3D point with visual properties.

Parameters:

• x (float, optional) – X coordinate. Defaults to 0.0.

• y (float, optional) – Y coordinate. Defaults to 0.0.

• z (float, optional) – Z coordinate. Defaults to 0.0.

name

The name of the point.

Type:

str

guid

The unique identifier of the point.

Type:

str

x

The X coordinate of the point.

Type:

float

y

The Y coordinate of the point.

Type:

float

z

The Z coordinate of the point.

Type:

float

pointcolor

The color of the point.

Type:

Color

width

The width of the point for display.

Type:

float

__init__(x=0.0, y=0.0, z=0.0)

property x

Get the X coordinate.

property y

Get the Y coordinate.

property z

Get the Z coordinate.

static ccw(a, b, c)

Check if the points are in counter-clockwise order.

Parameters:

• a (Point) – First point.

• b (Point) – Second point.

• c (Point) – Third point.

Returns:

True if the points are in counter-clockwise order, False otherwise.

Return type:

bool

mid_point(p)

Calculate the mid point between this point and another point.

Parameters:

p (Point) – The other point.

Returns:

The mid point between this point and the other point.

Return type:

Point

distance(p, double_min=1e-12)

Calculate the distance between this point and another point.

Parameters:

• p (Point) – The other point.

• double_min (float, optional) – The minimum value for the distance. Defaults to 1e-12.

Returns:

The distance between this point and the other point.

Return type:

float

static area(points)

Calculate the area of a polygon.

Parameters:

points (list of Point) – The points of the polygon.

Returns:

The area of the polygon.

Return type:

float

static centroid_quad(vertices)

Calculate the centroid of a quadrilateral.

Parameters:

vertices (list of Point) – The vertices of the quadrilateral.

Returns:

The centroid of the quadrilateral.

Return type:

Point

Vector Module

class session_py.vector.Vector(x=0.0, y=0.0, z=0.0)

Bases: object

A 3D vector with visual properties.

Parameters:

• x (float, optional) – X coordinate. Defaults to 0.0.

• y (float, optional) – Y coordinate. Defaults to 0.0.

• z (float, optional) – Z coordinate. Defaults to 0.0.

guid

The unique identifier of the vector.

Type:

str

name

The name of the vector.

Type:

str

x

The X coordinate of the vector.

Type:

float

y

The Y coordinate of the vector.

Type:

float

z

The Z coordinate of the vector.

Type:

float

__init__(x=0.0, y=0.0, z=0.0)

property x

Get the X coordinate.

property y

Get the Y coordinate.

property z

Get the Z coordinate.

static x_axis()

Get unit vector along the x-axis.

Returns:

Unit vector (1, 0, 0).

Return type:

Vector

static y_axis()

Get unit vector along the y-axis.

Returns:

Unit vector (0, 1, 0).

Return type:

Vector

static z_axis()

Get unit vector along the z-axis.

Returns:

Unit vector (0, 0, 1).

Return type:

Vector

static from_start_and_end(start, end)

Vector from start to end (end - start).

Parameters:

• start (Vector) – Start vector.

• end (Vector) – End vector.

Returns:

The vector from start to end.

Return type:

Vector

reverse()

Reverse the vector (negate all components).

Returns:

Self.

Return type:

Vector

compute_length()

Compute the length of the vector using optimized algorithm.

Returns:

The length of the vector.

Return type:

float

magnitude()

Get the cached magnitude of the vector, computing it if necessary.

Returns:

The magnitude (length) of the vector.

Return type:

float

length_squared()

Get the squared length of the vector (avoids sqrt for performance).

Returns:

The squared length of the vector.

Return type:

float

normalize_self()

Normalize the vector in place (make it unit length).

Returns:

True if successful, False if vector has zero length.

Return type:

bool

normalize()

Return a normalized copy of the vector.

Returns:

A new vector that is the unit vector of this vector.

Return type:

Vector

dot(other)

Calculate dot product with another vector.

Parameters:

other (Vector) – Other vector.

Returns:

Dot product value.

Return type:

float

cross(other)

Calculate cross product with another vector.

Parameters:

other (Vector) – Other vector.

Returns:

Cross product vector (orthogonal to inputs).

Return type:

Vector

is_parallel_to(v)

Check if this vector is parallel/antiparallel to another.

Parameters:

v (Vector) – Other vector.

Returns:

1 if parallel, -1 if antiparallel, 0 otherwise.

Return type:

int

angle(other, sign_by_cross_product=False, degrees=True, tolerance=1e-12)

Angle between this vector and another.

Parameters:

• other (Vector) – The other vector.

• sign_by_cross_product (bool, optional) – If True, sign the angle using the z-component of the cross product.

• degrees (bool, optional) – If True (default), return angle in degrees; otherwise radians.

• tolerance (float, optional) – Denominator tolerance to treat near-zero lengths as zero.

Returns:

The angle value (degrees if degrees else radians).

Return type:

float

projection(projection_vector, tolerance=1e-12)

Project this vector onto another vector.

Parameters:

• projection_vector (Vector) – Vector to project onto.

• tolerance (float, optional) – Treat projection_vector length below this as zero.

Returns:

(projection_vector, projected_length, perpendicular_vector, perpendicular_length), where projection_vector is Vector, projected_length is float, perpendicular_vector is Vector, and perpendicular_length is float.

Return type:

tuple

get_leveled_vector(vertical_height)

Get a copy scaled by a vertical height along the Z-axis.

Parameters:

vertical_height (float) – Target vertical height.

Returns:

Scaled copy matching the C++ implementation.

Return type:

Vector

static cosine_law(triangle_edge_length_a, triangle_edge_length_b, angle_in_between_edges, degrees=True)

Calculate third side of triangle using the cosine law.

Parameters:

• triangle_edge_length_a (float) – Length of side a.

• triangle_edge_length_b (float) – Length of side b.

• angle_in_between_edges (float) – Angle between a and b.

• degrees (bool, optional) – If True, the angle is provided in degrees.

Returns:

Length of the third side.

Return type:

float

static sine_law_angle(triangle_edge_length_a, angle_in_front_of_a, triangle_edge_length_b, degrees=True)

Calculate angle using the sine law.

Parameters:

• triangle_edge_length_a (float) – Length of side a.

• angle_in_front_of_a (float) – Angle opposite to side a.

• triangle_edge_length_b (float) – Length of side b.

• degrees (bool, optional) – If True, return angle in degrees.

Returns:

Angle opposite to side b (degrees if degrees).

Return type:

float

static sine_law_length(triangle_edge_length_a, angle_in_front_of_a, angle_in_front_of_b, degrees=True)

Calculate side length using the sine law.

Parameters:

• triangle_edge_length_a (float) – Length of side a.

• angle_in_front_of_a (float) – Angle opposite to side a.

• angle_in_front_of_b (float) – Angle opposite to side b.

• degrees (bool, optional) – If True, angles are provided in degrees.

Returns:

Length of side b.

Return type:

float

static angle_between_vector_xy_components(vector, degrees=True)

Angle between the vector’s XY components.

Parameters:

• vector (Vector) – Input vector.

• degrees (bool, optional) – If True, return degrees; otherwise radians.

Returns:

Angle in the XY plane.

Return type:

float

static sum_of_vectors(vectors)

Sum a list of vectors (component-wise).

Parameters:

vectors (list[Vector]) – Vectors to sum.

Returns:

The component-wise sum.

Return type:

Vector

coordinate_direction_3angles(degrees=True)

Compute coordinate direction angles (alpha, beta, gamma).

Parameters:

degrees (bool, optional) – Return angles in degrees if True, radians if False.

Returns:

(alpha, beta, gamma)

Return type:

tuple

coordinate_direction_2angles(degrees=True)

Compute coordinate direction angles (phi, theta).

Parameters:

degrees (bool, optional) – Return angles in degrees if True, radians if False.

Returns:

(phi, theta)

Return type:

tuple

perpendicular_to(v)

Set this vector to be perpendicular to v.

Parameters:

v (Vector) – Reference vector.

Returns:

True on success, False otherwise.

Return type:

bool

Plane Module

class session_py.plane.Plane(origin=None, x_axis=None, y_axis=None, name='my_plane')

Bases: object

A 3D plane defined by origin and coordinate axes.

Parameters:

• origin (Point, optional) – Origin point of the plane. Defaults to Point(0, 0, 0).

• x_axis (Vector, optional) – X-axis direction. Defaults to Vector(1, 0, 0).

• y_axis (Vector, optional) – Y-axis direction. Defaults to Vector(0, 1, 0).

• name (str, optional) – Name of the plane. Defaults to “my_plane”.

guid

The unique identifier of the plane.

Type:

str

name

The name of the plane.

Type:

str

origin

The origin point of the plane.

Type:

Point

x_axis

The X-axis direction vector.

Type:

Vector

y_axis

The Y-axis direction vector.

Type:

Vector

z_axis

The Z-axis direction vector (normal).

Type:

Vector

a

Plane equation coefficient (normal x-component).

Type:

float

b

Plane equation coefficient (normal y-component).

Type:

float

c

Plane equation coefficient (normal z-component).

Type:

float

d

Plane equation coefficient (distance from origin).

Type:

float

__init__(origin=None, x_axis=None, y_axis=None, name='my_plane')

property origin

Get the origin point.

property x_axis

Get the X-axis vector.

property y_axis

Get the Y-axis vector.

property z_axis

Get the Z-axis vector (normal).

property a

Get plane equation coefficient a.

property b

Get plane equation coefficient b.

property c

Get plane equation coefficient c.

property d

Get plane equation coefficient d.

static from_point_normal(point, normal)

Create a plane from a point and normal vector.

Parameters:

• point (Point) – Point on the plane.

• normal (Vector) – Normal vector of the plane.

Returns:

The constructed plane.

Return type:

Plane

static from_points(points)

Create a plane from three or more points.

Parameters:

points (list of Point) – List of at least 3 points.

Returns:

The constructed plane.

Return type:

Plane

static from_two_points(point1, point2)

Create a plane from two points.

Parameters:

• point1 (Point) – First point.

• point2 (Point) – Second point.

Returns:

The constructed plane.

Return type:

Plane

static xy_plane()

Create the XY plane.

Returns:

XY plane at origin.

Return type:

Plane

static yz_plane()

Create the YZ plane.

Returns:

YZ plane at origin.

Return type:

Plane

static xz_plane()

Create the XZ plane.

Returns:

XZ plane at origin.

Return type:

Plane

reverse()

Reverse the plane’s normal direction.

rotate(angles_in_radians)

Rotate the plane around its normal.

Parameters:

angles_in_radians (float) – Rotation angle in radians.

is_right_hand()

Check if the plane follows the right-hand rule.

Returns:

True if x_axis × y_axis = z_axis (right-handed).

Return type:

bool

static is_same_direction(plane0, plane1, can_be_flipped=True)

Check if two planes have the same or flipped normal.

Parameters:

• plane0 (Plane) – First plane.

• plane1 (Plane) – Second plane.

• can_be_flipped (bool, optional) – Allow flipped normals. Defaults to True.

Returns:

True if normals are parallel or antiparallel.

Return type:

bool

static is_same_position(plane0, plane1)

Check if two planes are in the same position.

Parameters:

• plane0 (Plane) – First plane.

• plane1 (Plane) – Second plane.

Returns:

True if origins are very close.

Return type:

bool

static is_coplanar(plane0, plane1, can_be_flipped=True)

Check if two planes are coplanar.

Parameters:

• plane0 (Plane) – First plane.

• plane1 (Plane) – Second plane.

• can_be_flipped (bool, optional) – Allow flipped normals. Defaults to True.

Returns:

True if planes are coplanar.

Return type:

bool

translate_by_normal(distance)

Translate (move) a plane along its normal direction by a specified distance.

Parameters:

distance (float) – Distance to move the plane along its normal (positive = normal direction, negative = opposite).

Returns:

New plane translated by the specified distance.

Return type:

Plane

Xform Module

class session_py.xform.Xform(m=None)

Bases: object

__init__(m=None)

static identity()

static from_matrix(m)

static translation(x, y, z)

static scaling(x, y, z)

static rotation_x(angle_radians)

static rotation_y(angle_radians)

static rotation_z(angle_radians)

static rotation(axis, angle_radians)

static change_basis(origin, x_axis, y_axis, z_axis)

static change_basis_alt(origin_1, x_axis_1, y_axis_1, z_axis_1, origin_0, x_axis_0, y_axis_0, z_axis_0)

static plane_to_plane(origin_0, x_axis_0, y_axis_0, z_axis_0, origin_1, x_axis_1, y_axis_1, z_axis_1)

static plane_to_xy(origin, x_axis, y_axis, z_axis)

static xy_to_plane(origin, x_axis, y_axis, z_axis)

static scale_xyz(scale_x, scale_y, scale_z)

static scale_uniform(origin, scale_value)

static scale_non_uniform(origin, scale_x, scale_y, scale_z)

static axis_rotation(angle, axis)

static look_at_rh(eye, target, up)

inverse() → Xform | None

is_identity()

transformed_point(point)

transformed_vector(vector)

transform_point(point)

transform_vector(vector)

Quaternion Module

class session_py.quaternion.Quaternion(s=1.0, v=None)

Bases: object

__init__(s=1.0, v=None)

static identity()

static from_sv(s, x, y, z)

static from_axis_angle(axis, angle)

rotate_vector(v)

magnitude()

normalize()

conjugate()

Line Module

class session_py.line.Line(x0=0.0, y0=0.0, z0=0.0, x1=0.0, y1=0.0, z1=1.0)

Bases: object

A 3D line segment with visual properties.

Parameters:

• x0 (float, optional) – X coordinate of start point. Defaults to 0.0.

• y0 (float, optional) – Y coordinate of start point. Defaults to 0.0.

• z0 (float, optional) – Z coordinate of start point. Defaults to 0.0.

• x1 (float, optional) – X coordinate of end point. Defaults to 0.0.

• y1 (float, optional) – Y coordinate of end point. Defaults to 0.0.

• z1 (float, optional) – Z coordinate of end point. Defaults to 1.0.

guid

Unique identifier of the line.

Type:

str

name

Name of the line.

Type:

str

linecolor

Color of the line.

Type:

Color

width

Width of the line for display.

Type:

float

__init__(x0=0.0, y0=0.0, z0=0.0, x1=0.0, y1=0.0, z1=1.0)

property x0

Get the X coordinate of start point.

property y0

Get the Y coordinate of start point.

property z0

Get the Z coordinate of start point.

property x1

Get the X coordinate of end point.

property y1

Get the Y coordinate of end point.

property z1

Get the Z coordinate of end point.

classmethod from_points(p1, p2)

Create a line from two points.

Parameters:

• p1 (Point) – Start point.

• p2 (Point) – End point.

Returns:

New line from p1 to p2.

Return type:

Line

classmethod with_name(name, x0, y0, z0, x1, y1, z1)

Create a line with a specific name.

Parameters:

• name (str) – Name for the line.

• x0 (float) – Start point coordinates.

• y0 (float) – Start point coordinates.

• z0 (float) – Start point coordinates.

• x1 (float) – End point coordinates.

• y1 (float) – End point coordinates.

• z1 (float) – End point coordinates.

Returns:

New named line.

Return type:

Line

length()

Calculate the length of the line.

Returns:

Length of the line.

Return type:

float

squared_length()

Calculate the squared length of the line.

Returns:

Squared length of the line.

Return type:

float

to_vector()

Convert line to vector from start to end.

Returns:

Direction vector of the line.

Return type:

Vector

point_at(t)

Get point at parameter t along the line.

Parameters:

t (float) – Parameter value (0.0 = start, 1.0 = end).

Returns:

Point at parameter t.

Return type:

Point

start()

Get start point.

Returns:

Start point of the line.

Return type:

Point

end()

Get end point.

Returns:

End point of the line.

Return type:

Point

Tolerance Module

class session_py.tolerance.Tolerance(*args, **kwargs)

Bases: object

Tolerance settings for geometric operations.

Parameters:

• unit ({"M", "MM"}, optional) – The unit of the tolerance settings.

• name (str, optional) – The name of the tolerance settings.

SUPPORTED_UNITS = ['M', 'MM']

ABSOLUTE = 1e-09

RELATIVE = 1e-06

ANGULAR = 1e-06

APPROXIMATION = 0.001

PRECISION = 3

LINEARDEFLECTION = 0.001

ANGULARDEFLECTION = 0.1

ANGLE_TOLERANCE_DEGREES = 0.11

ZERO_TOLERANCE = 1e-12

__init__(unit='M', absolute=None, relative=None, angular=None, approximation=None, precision=None, lineardeflection=None, angulardeflection=None, name=None)

reset()

Reset all precision settings to their default values.

property unit

property units

property absolute

property relative

property angular

property approximation

property precision

property lineardeflection

property angulardeflection

tolerance(truevalue, rtol, atol)

Compute the tolerance for a comparison.

compare(a, b, rtol, atol)

Compare two values.

is_zero(a, tol=None)

Check if a value is close enough to zero to be considered zero.

is_positive(a, tol=None)

Check if a value can be considered a strictly positive number.

is_negative(a, tol=None)

Check if a value can be considered a strictly negative number.

is_between(value, minval, maxval, atol=None)

Check if a value is between two other values.

is_close(a, b, rtol=None, atol=None)

Check if two values are close enough to be considered equal.

is_allclose(A, B, rtol=None, atol=None)

Check if two lists of values are element-wise close enough to be considered equal.

is_angle_zero(a, tol=None)

Check if an angle is close enough to zero to be considered zero.

is_angles_close(a, b, tol=None)

Check if two angles are close enough to be considered equal.

geometric_key(xyz, precision=None, sanitize=True)

Compute the geometric key of a point.

geometric_key_xy(xy, precision=None, sanitize=True)

Compute the geometric key of a point in the XY plane.

format_number(number, precision=None)

Format a number as a string.

precision_from_tolerance(tol=None)

Compute the precision from a given tolerance.

session_py.tolerance.is_finite(x)

Test if a number is finite (equivalent to C++ IS_FINITE function).

Polyline Module

class session_py.polyline.Polyline(points: List[Point] | None = None)

Bases: object

A polyline defined by a collection of points with an associated plane.

__init__(points: List[Point] | None = None)

Creates a new Polyline with default guid and name.

Parameters:

points – The collection of points.

is_empty() → bool

Returns true if the polyline has no points.

segment_count() → int

Returns the number of segments (n-1 for n points).

length() → float

Calculates the total length of the polyline.

get_point(index: int) → Point | None

Returns the point at the given index, or None if out of bounds.

add_point(point: Point) → None

Adds a point to the end of the polyline.

insert_point(index: int, point: Point) → None

Inserts a point at the specified index.

remove_point(index: int) → Point | None

Removes and returns the point at the specified index.

reverse() → None

Reverses the order of points in the polyline.

reversed() → Polyline

Returns a new polyline with reversed point order.

shift(times: int) → None

Shift polyline points by specified number of positions.

length_squared() → float

Calculate squared length of polyline (faster, no sqrt).

static point_at_parameter(start: Point, end: Point, t: float) → Point

Get point at parameter t along a line segment (t=0 is start, t=1 is end).

static closest_point_to_line(point: Point, line_start: Point, line_end: Point) → float

Find closest point on line segment to given point, returns parameter t.

static line_line_overlap(line0_start: Point, line0_end: Point, line1_start: Point, line1_end: Point) → Tuple[Point, Point] | None

Check if two line segments overlap and return the overlapping segment.

static line_line_average(line0_start: Point, line0_end: Point, line1_start: Point, line1_end: Point) → Tuple[Point, Point]

Calculate average of two line segments.

static line_line_overlap_average(line0_start: Point, line0_end: Point, line1_start: Point, line1_end: Point) → Tuple[Point, Point]

Calculate overlap average of two line segments.

static line_from_projected_points(line_start: Point, line_end: Point, points: List[Point]) → Tuple[Point, Point] | None

Create line from projected points onto a base line.

closest_distance_and_point(point: Point) → Tuple[float, int, Point]

Find closest distance and point from a point to this polyline.

is_closed() → bool

Check if polyline is closed (first and last points are the same).

center() → Point

Calculate center point of polyline.

center_vec() → Vector

Calculate center as vector.

get_average_plane() → Tuple[Point, Vector, Vector, Vector]

Get average plane from polyline points.

get_fast_plane() → Tuple[Point, Plane]

Get fast plane calculation from polyline.

static get_middle_line(line0_start: Point, line0_end: Point, line1_start: Point, line1_end: Point) → Tuple[Point, Point]

Calculate middle line between two line segments.

static extend_line(line_start: Point, line_end: Point, distance0: float, distance1: float) → None

Extend line segment by specified distances at both ends.

static scale_line(line_start: Point, line_end: Point, distance: float) → None

Scale line segment inward by specified distance.

extend_segment(segment_id: int, dist0: float, dist1: float, proportion0: float = 0.0, proportion1: float = 0.0) → None

Extend polyline segment.

static extend_segment_equally_static(segment_start: Point, segment_end: Point, dist: float, proportion: float = 0.0) → None

Extend segment equally on both ends (static utility).

extend_segment_equally(segment_id: int, dist: float, proportion: float = 0.0) → None

Extend polyline segment equally.

move_by(direction: Vector) → None

Move polyline by direction vector.

is_clockwise(plane: Plane) → bool

Check if polyline is clockwise oriented.

flip() → None

Flip polyline direction (reverse point order).

get_convex_corners() → List[bool]

Get convex/concave corners of polyline.

static tween_two_polylines(polyline0: Polyline, polyline1: Polyline, weight: float) → Polyline

Interpolate between two polylines.

PointCloud Module

class session_py.pointcloud.PointCloud(points=None, normals=None, colors=None)

Bases: object

A point cloud with points, normals, colors, and transformation.

Parameters:

• points (List[Point], optional) – Collection of points.

• normals (List[Vector], optional) – Collection of normals.

• colors (List[Color], optional) – Collection of colors.

guid

Unique identifier.

Type:

str

name

Name of the point cloud.

Type:

str

points

Collection of points.

Type:

List[Point]

normals

Collection of normals.

Type:

List[Vector]

colors

Collection of colors.

Type:

List[Color]

xform

Transformation matrix.

Type:

Xform

__init__(points=None, normals=None, colors=None)

size() → int

Get number of points.

is_empty() → bool

Check if point cloud is empty.

Color Module

class session_py.color.Color(r: int, g: int, b: int, a: int, name: str = 'my_color')

Bases: object

A color with RGBA values for cross-language compatibility.

Parameters:

• r (int, optional) – Red component (0-255). Defaults to 255.

• g (int, optional) – Green component (0-255). Defaults to 255.

• b (int, optional) – Blue component (0-255). Defaults to 255.

• a (int, optional) – Alpha component (0-255). Defaults to 255.

• name (str, optional) – Name of the color. Defaults to “white”.

name

The name of the color.

Type:

str

guid

The unique identifier of the color.

Type:

str

r

The red component of the color (0-255).

Type:

int

g

The green component of the color (0-255).

Type:

int

b

The blue component of the color (0-255).

Type:

int

a

The alpha component of the color (0-255).

Type:

int

__init__(r: int, g: int, b: int, a: int, name: str = 'my_color')

to_float_array() → list[float]

Convert to normalized float array [0-1] (matches Rust implementation).

classmethod from_float(r, g, b, a) → Color

Create color from normalized float values [0-1].

classmethod white() → Color

Create a white color.

classmethod black() → Color

Create a black color.

classmethod grey() → Color

Create a grey color.

classmethod red() → Color

Create a red color.

classmethod orange() → Color

Create an orange color.

classmethod yellow() → Color

Create a yellow color.

classmethod lime() → Color

Create a lime color.

classmethod green() → Color

Create a green color.

classmethod mint() → Color

Create a mint color.

classmethod cyan() → Color

Create a cyan color.

classmethod azure() → Color

Create an azure color.

classmethod blue() → Color

Create a blue color.

classmethod violet() → Color

Create a violet color.

classmethod magenta() → Color

Create a magenta color.

classmethod pink() → Color

Create a pink color.

classmethod maroon() → Color

Create a maroon color.

classmethod brown() → Color

Create a brown color.

classmethod olive() → Color

Create an olive color.

classmethod teal() → Color

Create a teal color.

classmethod navy() → Color

Create a navy color.

classmethod purple() → Color

Create a purple color.

classmethod silver() → Color

Create a silver color.

Graph Module

class session_py.graph.Graph(name='my_graph')

Bases: object

A graph data structure with string-only vertices and attributes.

Parameters:

• name (str, optional) – Name of the graph.

• default_node_attributes (dict, optional) – Default attributes for new vertices.

• default_edge_attributes (dict, optional) – Default attributes for new edges.

__init__(name='my_graph')

Initialize a new Graph.

has_node(key)

Check if a node exists in the graph.

Parameters:

key (str) – The node to check for.

Returns:

True if the node exists.

Return type:

bool

Examples

>>> graph = Graph()
>>> graph.add_node("node1")
'node1'
>>> graph.has_node("node1")
True
>>> graph.has_node("node2")
False

has_edge(edge)

Check if an edge exists in the graph.

Parameters:

edge (tuple or str) – Either a tuple (u, v) or two separate arguments u, v.

Returns:

True if the edge exists, False otherwise.

Return type:

bool

Examples

>>> graph = Graph()
>>> graph.add_edge("A", "B", "edge_attr")
('A', 'B')
>>> graph.has_edge(("A", "B"))
True
>>> graph.has_edge(("C", "D"))
False

add_node(key, attribute='')

Add a node to the graph.

Parameters:

• key (str) – The node identifier.

• attribute (str, optional) – Node attribute data.

Returns:

The node key that was added.

Return type:

str

Examples

>>> graph = Graph()
>>> graph.add_node("node1", "attribute_data")
'node1'
>>> graph.has_node("node1")
True

add_edge(u, v, attribute='')

Add an edge between u and v.

Parameters:

• u (str) – First node (must be string).

• v (str) – Second node (must be string).

• attribute (str, optional) – Single string attribute for the edge.

Returns:

The edge tuple (u, v).

Return type:

tuple

Raises:

TypeError – If u or v are not strings.

Examples

>>> graph = Graph()
>>> graph.add_edge("node1", "node2", "edge_data")
('node1', 'node2')
>>> graph.has_edge(("node1", "node2"))
True

remove_node(key)

Remove a node and all its edges from the graph.

Parameters:

key (str) – The node to remove.

Raises:

KeyError – If the node is not in the graph.

Examples

>>> graph = Graph()
>>> graph.add_node("node1")
'node1'
>>> graph.remove_node("node1")
>>> graph.has_node("node1")
False

remove_edge(edge)

Remove an edge from the graph.

Parameters:

edge (tuple) – A tuple (u, v) representing the edge to remove.

Examples

>>> graph = Graph()
>>> graph.add_edge("A", "B", "edge_attr")
('A', 'B')
>>> graph.remove_edge(("A", "B"))
>>> graph.has_edge(("A", "B"))
False

get_vertices()

Return a list of all vertices in the graph.

Returns:

A list of all vertex objects in the graph.

Return type:

list of Vertex

get_edges()

Iterate over all edges in the graph.

Yields:

tuple – Edge identifier (u, v)

Examples

>>> graph = Graph()
>>> graph.add_edge("node1", "node2", "edge_data")
('node1', 'node2')
>>> edges = list(graph.edges())
>>> assert ("node1", "node2") in edges
>>> assert len(edges) == 1

neighbors(node)

Get all neighbors of a node.

Parameters:

node (str) – The node to get neighbors for.

Returns:

Iterator over neighbor vertices.

Return type:

iterator

Examples

>>> graph = Graph()
>>> graph.add_edge("A", "B", "edge1")
('A', 'B')
>>> graph.add_edge("A", "C", "edge2")
('A', 'C')
>>> sorted(list(graph.neighbors("A")))
['B', 'C']

number_of_vertices()

Get the number of vertices in the graph.

Returns:

Number of vertices.

Return type:

int

Examples

>>> graph = Graph()
>>> graph.add_node("node1")
'node1'
>>> graph.number_of_vertices()
1

number_of_edges()

Get the number of edges in the graph.

Returns:

Number of edges.

Return type:

int

Examples

>>> graph = Graph()
>>> graph.add_edge("node1", "node2")
('node1', 'node2')
>>> graph.number_of_edges()
1

clear()

Remove all vertices and edges from the graph.

Examples

>>> graph = Graph()
>>> graph.add_node("node1")
'node1'
>>> graph.clear()
>>> graph.number_of_vertices()
0

node_attribute(node, value=None)

Get or set node attribute.

Parameters:

• node (str) – The node identifier.

• value (str, optional) – If provided, set the attribute to this value.

Returns:

The attribute value as string.

Return type:

str

Raises:

KeyError – If the node does not exist.

Examples

>>> graph = Graph()
>>> graph.add_node("node1", "initial_data")
'node1'
>>> assert graph.node_attribute("node1") == "initial_data"
>>> graph.node_attribute("node1", "new_data")
>>> assert graph.node_attribute("node1") == "new_data"

edge_attribute(u, v, value=None)

Get or set edge attribute.

Parameters:

• u (hashable) – First vertex of the edge.

• v (hashable) – Second vertex of the edge.

• value (str, optional) – If provided, set the attribute to this value.

Returns:

The attribute value as string.

Return type:

str

Raises:

KeyError – If the edge does not exist.

Examples

>>> graph = Graph()
>>> graph.add_edge("node1", "node2", "edge_data")
('node1', 'node2')
>>> graph.edge_attribute("node1", "node2")
'edge_data'
>>> graph.edge_attribute("node1", "node2", "new_data")
'new_data'
>>> graph.edge_attribute("node1", "node2")
'new_data'

Objects Module

class session_py.objects.Objects

Bases: object

A collection of all geometry objects.

name

The name of the collection.

Type:

str

guid

The unique identifier of the collection.

Type:

UUID

points

The list of points.

Type:

list[Point]

lines

The list of lines.

Type:

list[Line]

planes

The list of planes.

Type:

list[Plane]

bboxes

The list of bounding boxes.

Type:

list[BoundingBox]

polylines

The list of polylines.

Type:

list[Polyline]

pointclouds

The list of point clouds.

Type:

list[PointCloud]

meshes

The list of meshes.

Type:

list[Mesh]

cylinders

The list of cylinders.

Type:

list[Cylinder]

arrows

The list of arrows.

Type:

list[Arrow]

__init__()

Session Module

class session_py.session.Session(name='my_session')

Bases: object

A Session containing geometry objects with hierarchical and graph structures.

The Session class manages collections of geometry objects and provides: - Fast GUID-based lookup - Hierarchical tree structure for organization - Graph structure for object relationships - JSON serialization/deserialization

Parameters:

name (str, optional) – Name of the Session. Defaults to “Session”.

objects

Collection of geometry objects in the Session.

Type:

Objects

lookup

Fast lookup dictionary mapping GUIDs to geometry objects.

Type:

dict[UUID, Point]

tree

Hierarchical tree structure for organizing geometry objects.

Type:

Tree

graph

Graph structure for storing relationships between geometry objects.

Type:

Graph

name

Name of the Session.

Type:

str

__init__(name='my_session')

add_point(point: Point) → TreeNode

Add a point to the Session.

Automatically creates corresponding nodes in both graph and tree structures.

Parameters:

point (Point) – The point to add to the session.

Returns:

The TreeNode created for this point.

Return type:

TreeNode

add_line(line) → TreeNode

Add a line to the Session.

Returns:

The TreeNode created for this line.

Return type:

TreeNode

add_plane(plane) → TreeNode

Add a plane to the Session.

Returns:

The TreeNode created for this plane.

Return type:

TreeNode

add_bbox(bbox) → TreeNode

Add a bounding box to the Session.

Returns:

The TreeNode created for this bounding box.

Return type:

TreeNode

add_polyline(polyline) → TreeNode

Add a polyline to the Session.

Returns:

The TreeNode created for this polyline.

Return type:

TreeNode

add_pointcloud(pointcloud) → TreeNode

Add a point cloud to the Session.

Returns:

The TreeNode created for this point cloud.

Return type:

TreeNode

add_mesh(mesh) → TreeNode

Add a mesh to the Session.

Returns:

The TreeNode created for this mesh.

Return type:

TreeNode

add_cylinder(cylinder) → TreeNode

Add a cylinder to the Session.

Returns:

The TreeNode created for this cylinder.

Return type:

TreeNode

add_arrow(arrow) → TreeNode

Add an arrow to the Session.

Returns:

The TreeNode created for this arrow.

Return type:

TreeNode

add(node: TreeNode, parent: TreeNode = None) → None

Add a TreeNode to the tree hierarchy.

Parameters:

• node (TreeNode) – The TreeNode to add.

• parent (TreeNode, optional) – Parent TreeNode (defaults to root if not provided).

add_edge(guid1: str, guid2: str, attribute: str = '') → None

Add an edge between two geometry objects in the graph.

Parameters:

• guid1 (str) – GUID of the first geometry object.

• guid2 (str) – GUID of the second geometry object.

• attribute (str, optional) – Edge attribute description.

get_object(guid: str) → Point | None

Get a geometry object by its GUID.

Parameters:

guid (str) – The string GUID of the geometry object to retrieve.

Returns:

The geometry object if found, None otherwise.

Return type:

Point | None

remove_object(guid: str) → bool

Remove a geometry object by its GUID.

Parameters:

guid – The UUID of the geometry object to remove.

Returns:

True if the object was removed, False if not found.

add_hierarchy(parent_guid: str, child_guid: str) → bool

Add a parent-child relationship in the tree structure.

Parameters:

• parent_guid (UUID) – The GUID of the parent geometry object.

• child_guid (UUID) – The GUID of the child geometry object.

Returns:

True if the relationship was added successfully.

Return type:

bool

get_children(guid: str) → list[str]

Get all children GUIDs of a geometry object in the tree.

Parameters:

guid (str) – The string GUID to search for.

Returns:

List of children GUIDs.

Return type:

list[UUID]

add_relationship(from_guid: str, to_guid: str, relationship_type: str = 'default') → None

Add a relationship edge in the graph structure.

Parameters:

• from_guid (UUID) – The GUID of the source geometry object.

• to_guid (UUID) – The GUID of the target geometry object.

• relationship_type (str, optional) – The type of relationship. Defaults to “default”.

get_neighbours(guid: str) → list[str]

Get all GUIDs connected to the given GUID in the graph.

Parameters:

guid (UUID) – The GUID of the geometry object to find connections for.

Returns:

List of connected geometry GUIDs as strings.

Return type:

list[str]

Tree Module

class session_py.tree.Tree(name='my_tree')

Bases: object

A hierarchical data structure with parent-child relationships.

Parameters:

name (str, optional) – The name of the tree. Defaults to “Tree”.

guid

The unique identifier of the tree.

Type:

UUID

name

The name of the tree.

Type:

str

root

The root node of the tree.

Type:

TreeNode

__init__(name='my_tree')

property root

add(node, parent=None)

Add a node to the tree.

Parameters:

• node (TreeNode) – The node to add.

• parent (TreeNode, optional) – The parent node. If None, adds as root.

property nodes

remove(node)

Remove a node from the tree.

Parameters:

node (TreeNode) – The node to remove.

property leaves

traverse(strategy='depthfirst', order='preorder')

Traverse the tree from the root node.

Parameters:

• strategy ({"depthfirst", "breadthfirst"}, optional) – The traversal strategy.

• order ({"preorder", "postorder"}, optional) – The traversal order. This parameter is only used for depth-first traversal.

Yields:

TreeNode – The next node in the traversal.

Raises:

ValueError – If the strategy is not "depthfirst" or "breadthfirst". If the order is not "preorder" or "postorder".

get_node_by_name(name)

Get a node by its name.

Parameters:

name (str) – The name of the node.

get_nodes_by_name(name)

Get all nodes by their name.

Parameters:

name (str) – The name of the node.

Returns:

The nodes.

Return type:

list[TreeNode]

add_child_by_guid(parent_guid: UUID, child_guid: UUID) → bool

Add a parent-child relationship using GUIDs.

Parameters:

• parent_guid (UUID) – The GUID of the parent node.

• child_guid (UUID) – The GUID of the child node.

Returns:

True if the relationship was added, False if nodes not found.

Return type:

bool

get_children_guids(guid: UUID) → list[UUID]

Get all children GUIDs of a node by its GUID.

Parameters:

guid (UUID) – The GUID of the parent node.

Returns:

List of children GUIDs.

Return type:

list[UUID]

print_hierarchy()

Print the spatial hierarchy of the tree.