line

geometry.line

Line module.

Classes:

• Line –

  Represents a line in a 3D modelling space.

geometry.line.Line

Line(start_point: Point, end_point: Point)

Represents a line in a 3D modelling space.

Parameters:

• start_point (Point) –

  Starting point

• end_point (Point) –

  End point

Initialize the line.

Source code in blueprints/geometry/line.py

def __init__(self, start_point: Point, end_point: Point) -> None:
    """Initialize the line."""
    self._start_point = start_point
    self._end_point = end_point
    self._validate_points()
    Line.id += 1

geometry.line.Line.delta_x property

delta_x: float

Difference in X-coordinate between starting and end point (X end - X start).

geometry.line.Line.delta_y property

delta_y: float

Difference in Y-coordinate between starting and end point (Y end - Y start).

geometry.line.Line.delta_z property

delta_z: float

Difference in Z-coordinate between starting and end point (Z end - Z start).

geometry.line.Line.end_point property writable

end_point: Point

Return the end point.

geometry.line.Line.length property

length: float

Return the total length of the line.

geometry.line.Line.midpoint property

midpoint: Point

Midpoint of the line.

geometry.line.Line.start_point property writable

start_point: Point

Return the start point.

geometry.line.Line.unit_vector property

unit_vector: ndarray

Return the unit vector of the line.

geometry.line.Line.adjust_length

adjust_length(
    distance: float, direction: Literal["start", "end"] = "end"
) -> Self

Extends or shortens the line in a given direction. The end of the line is the default direction.

Parameters:

• distance (float) –

  Distance to extend or shorten the line. Positive number extends the line, negative number shortens the line.

• direction (Literal['start', 'end'], default: 'end' ) –

  Given direction where the line needs to be extended. Default towards the end of the line.

Returns:

• Line –

  The new line with the adjusted length.

Source code in blueprints/geometry/line.py

def adjust_length(self, distance: float, direction: Literal["start", "end"] = "end") -> Self:
    """Extends or shortens the line in a given direction. The end of the line is the default direction.

    Parameters
    ----------
    distance : float
        Distance to extend or shorten the line. Positive number extends the line, negative number shortens the line.
    direction: Literal["start", "end"]
        Given direction where the line needs to be extended. Default towards the end of the line.

    Returns
    -------
    Line
        The new line with the adjusted length.
    """
    if distance < 0 and abs(distance) >= self.length:
        raise ValueError("When shortening the line, the absolute value of the extra length must be less than the total length of the line.")

    match direction.lower():
        case "end":
            new_point = self._end + distance * self.unit_vector
            self.end_point = Point(new_point)
        case "start":
            new_point = self._start - distance * self.unit_vector
            self.start_point = Point(new_point)
        case _:
            msg = "Invalid input for 'direction', use 'start' or 'end'."
            raise ValueError(msg)
    return self

geometry.line.Line.angle

angle(coordinate_system: CoordinateSystemOptions = XY) -> DEG

Calculates rotation of the end point in relation to the start point in a given plane/coordinate system [deg].

• The rotation is calculated in the given plane in relation to the start point.
• The rotation is calculated in the range [0, 2*pi].
• The rotation is calculated in the counter-clockwise direction.

Parameters:

• coordinate_system (CoordinateSystemOptions, default: XY ) –

  Desired plane that will be used as reference to calculate the rotation. Standard is XY-plane.

Returns:

• DEG –

  rotation of end point relative to the start point in degrees in the given plane [deg].

Source code in blueprints/geometry/line.py

def angle(self, coordinate_system: CoordinateSystemOptions = CoordinateSystemOptions.XY) -> DEG:
    """
    Calculates rotation of the end point in relation to the start point in a given plane/coordinate system [deg].

    - The rotation is calculated in the given plane in relation to the start point.
    - The rotation is calculated in the range [0, 2*pi].
    - The rotation is calculated in the counter-clockwise direction.

    Parameters
    ----------
    coordinate_system: CoordinateSystemOptions
        Desired plane that will be used as reference to calculate the rotation. Standard is XY-plane.

    Returns
    -------
    DEG
        rotation of end point relative to the start point in degrees in the given plane [deg].
    """
    return (
        calculate_rotation_angle(
            start_point=self.start_point,
            end_point=self.end_point,
            coordinate_system=coordinate_system,
        )
        * RAD_TO_DEG
    )

geometry.line.Line.divide_into_n_lines

divide_into_n_lines(n: int = 2) -> list[Line]

Return a list of evenly divided lines.

Parameters:

• n (int, default: 2 ) –

  Total number of lines desired. A minimum of 2 lines are required.

Source code in blueprints/geometry/line.py

def divide_into_n_lines(self, n: int = 2) -> list["Line"]:
    """Return a list of evenly divided lines.

    Parameters
    ----------
    n : int
        Total number of lines desired. A minimum of 2 lines are required.
    """
    if not isinstance(n, int):
        msg = "n must be an integer"
        raise TypeError(msg)
    if n < 2:
        msg = "n must be equal or greater than 2"
        raise ValueError(msg)

    evenly_spaced_points = self.get_evenly_spaced_points(n + 1)
    return [Line(start_point=point_1, end_point=point_2) for point_1, point_2 in pairwise(evenly_spaced_points)]

geometry.line.Line.get_evenly_spaced_points

get_evenly_spaced_points(n: int = 2) -> list[Point]

Return a list of evenly spaced internal points of the line from start to end point with an n number of desired points.

Parameters:

• n (int, default: 2 ) –

  Total number of internal points desired. A minimum of 2 points are required.

Source code in blueprints/geometry/line.py

def get_evenly_spaced_points(self, n: int = 2) -> list[Point]:
    """Return a list of evenly spaced internal points of the line from start to end point with an n number of desired points.

    Parameters
    ----------
    n : int
        Total number of internal points desired. A minimum of 2 points are required.
    """
    if not isinstance(n, int):
        msg = "n must be an integer"
        raise TypeError(msg)
    if n < 2:
        msg = "n must be equal or greater than 2"
        raise ValueError(msg)

    # Create a list of evenly spaced points
    evenly_spaced_points = np.linspace(start=0, stop=self.length, num=n, endpoint=True)

    return [Point(self._start + distance * self.unit_vector) for distance in evenly_spaced_points]

geometry.line.Line.get_internal_point

get_internal_point(
    distance: float, reference: Literal["start", "end"] = "start"
) -> Point

Return an internal point within the line in a given distance from the reference point.

Parameters:

• distance (float) –

  Distance from the given reference point following the axis of the line

• reference (Literal['start', 'end'], default: 'start' ) –

  Reference point in the line where given distance is declared. Default -> "start"

Returns:

• Point –

  Internal point within the line in a given distance from the reference point.

Raises:

• ValueError –

  If the distance is greater than the total length of the line. If the distance is a negative number.

Source code in blueprints/geometry/line.py

def get_internal_point(self, distance: float, reference: Literal["start", "end"] = "start") -> Point:
    """Return an internal point within the line in a given distance from the reference point.

    Parameters
    ----------
    distance : float
        Distance from the given reference point following the axis of the line
    reference: Literal["start", "end"]
        Reference point in the line where given distance is declared. Default -> "start"

    Returns
    -------
    Point
        Internal point within the line in a given distance from the reference point.

    Raises
    ------
    ValueError
        If the distance is greater than the total length of the line.
        If the distance is a negative number.
    """
    if distance > self.length:
        msg = f"Distance must be equal or less than total length of the line. Length={self.length} | Distance={distance}"
        raise ValueError(msg)
    if distance < 0:
        msg = "Given Distance must be a positive number."
        raise ValueError(msg)

    match reference.lower():
        case "start":
            internal_point = self._start + distance * self.unit_vector
        case "end":
            internal_point = self._end - distance * self.unit_vector
        case _:
            msg = f"'{reference}' is an invalid input for 'reference_point', use 'start' or 'end'."
            raise ValueError(msg)
    return Point(internal_point)