`tactics2d.geometry`

Geometry module.

`CardinalDirection`

Bases: Enum

Enum representing cardinal (global) compass directions.

Attributes:

NORTH –

Represents north direction ("N").
SOUTH –

Represents south direction ("S").
EAST –

Represents east direction ("E").
WEST –

Represents west direction ("W").

`from_string(direction)` `classmethod`

Convert a string to a CardinalDirection enum member.

Parameters:

direction (str) –

The string representation of the direction.

Returns:

CardinalDirection ( CardinalDirection ) –

The corresponding enum member.

Raises:

ValueError –

If the input string does not match any enum member.

`Circle`

This class implement some common operations on circle.

`get_arc(center_point, radius, delta_angle, start_angle, clockwise=True, step_size=0.1)` `staticmethod`

This function gets the points on an arc curve line.

Parameters:

center_point (ndarray) –

The center of the arc. The shape is (2,).
radius (float) –

The radius of the arc.
delta_angle (float) –

The angle of the arc. This values is expected to be positive. The unit is radian.
start_angle (float) –

The start angle of the arc. The unit is radian.
clockwise (bool, default: True ) –

The direction of the arc. True represents clockwise. False represents counterclockwise.
step_size (float, default: 0.1 ) –

The step size of the arc. The unit is radian.

Returns:

arc_points ( ndarray ) –

The points on the arc. The shape is (int(radius * delta / step_size), 2).

`get_circle(**kwargs)` `staticmethod`

Create a circle from various input parameter combinations.

Supported usages:

1. From two points. The first point is the center, and the second point is a point on the circumference.
    get_circle(point1, point2)

2. From three points on the circumference.
    get_circle(point1, point2, point3)

3. From a tangent vector and radius.
    get_circle(tangent_point, tangent_heading, radius, side)

Parameters:

point1 (ArrayLike) –

The first point, either the center of the circle or a point on the circumference. The shape should be (2,).
point2 (ArrayLike) –

The second point, a point on the circumference. The shape should be (2,).
point3 (ArrayLike) –

The third point on the circumference. The shape should be (2,).
tangent_point (ArrayLike) –

A point on the circumference where the tangent is applied. The shape should be (2,).
tangent_heading (float) –

The heading of the tangent line at the tangent point, in radians.
radius (float) –

The radius of the circle.
side (Union[str, RelativeDirection]) –

The side of the tangent line to consider. Can be "L"/"R" or a RelativeDirection enum value (LEFT/RIGHT).

Returns:

Tuple[ndarray, float] –

Tuple[np.ndarray, float]: A tuple containing the center of the circle as a numpy array and the radius as a float. The center is an array of shape (2,)

Examples:

>>> Circle.get_circle(point1=np.array([0, 0]), point2=np.array([1, 0]))
(array([0.5, 0. ]), 0.5)

>>> Circle.get_circle(point1=np.array([0, 0]), point2=np.array([1, 0]), point3=np.array([0, 1]))
(array([0.5, 0.5]), 0.7071067811865476)

>>> Circle.get_circle(tangent_point=np.array([1, 0]), tangent_heading=np.pi/2, radius=1, side="L")
(array([1., 1.]), 1.0)

`FrenetPoint` `dataclass`

A point represented in reference-path Frenet coordinates.

`ReferencePath`

A route reference path with Cartesian/Frenet conversion helpers.

`cartesian_to_frenet(x, y)`

Project a Cartesian point to Frenet coordinates on this reference path.

`frenet_to_cartesian(s, d)`

Convert Frenet coordinates to Cartesian pose on this reference path.

`heading_at(s)`

Return the local tangent heading along this reference path.

`RelativeDirection`

Bases: Enum

Enum representing relative directions from a reference point.

Attributes:

LEFT –

Represents the left direction ("L").
RIGHT –

Represents the right direction ("R").
FRONT –

Represents the forward direction ("F").
BACK –

Represents the backward direction ("B").

`from_string(direction)` `classmethod`

Convert a string to a RelativeDirection enum member.

Parameters:

direction (str) –

The string representation of the direction.

Returns:

RelativeDirection ( RelativeDirection ) –

The corresponding enum member.

Raises:

ValueError –

If the input string does not match any enum member.

`as_point(point, name='point')`

Convert input to a validated 2D point array.

Parameters:

point –

Array-like with exactly 2 elements.
name (str, default: 'point' ) –

Field name used in the error message.

Returns:

ndarray –

A copy of the input as a (2,) float64 array.

Raises:

ValueError –

If the resulting array does not have shape (2,).

`cumulative_s(pts)`

Return cumulative arc-length coordinates of a polyline.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2). Empty and single-point arrays are handled gracefully.

Returns:

ndarray –

Cumulative arc-length array with shape (N,), starting at 0.0.
ndarray –

Returns an empty array for empty input.

`curvature_stats(pts)`

Estimate maximum absolute curvature and curvature-rate of a polyline.

Uses finite-difference heading changes between consecutive segments. Returns zero statistics for polylines with fewer than 4 points or fewer than 3 non-degenerate segments.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2).

Returns:

dict[str, float] –

Dictionary with keys:
dict[str, float] –
- "max_abs_curvature": maximum absolute curvature in radians/metre.
dict[str, float] –
- "max_abs_curvature_rate": maximum absolute rate of change of curvature in radians/metre².

`cut_polyline(line, pt, keep)`

Cut a Shapely LineString at a point and return one side as a numpy array.

Parameters:

line (LineString) –

Source Shapely :class:~shapely.geometry.LineString.
pt (Point) –

Cutting point as a Shapely :class:~shapely.geometry.Point. The nearest projection of pt onto line is used as the cut location.
keep (str) –

Which side of the cut to return. "before" returns the segment from the start up to the cut; "after" returns the segment from the cut to the end.

Returns:

ndarray –

Cut polyline points as an (M, 2) numpy array. Returns an empty
ndarray –

(0, 2) array if line has no coordinates.

Raises:

ValueError –

If keep is not "before" or "after".

`euclidean_distance(a, b)`

Compute the Euclidean distance between two 2D points.

Parameters:

a –

First point as an array-like with at least 2 elements.
b –

Second point as an array-like with at least 2 elements.

Returns:

float –

Euclidean distance between the first two coordinates of a and b.

`find_intersection_point(line1, line2, *, pick='first_on_line1')`

Find a representative intersection point between two LineStrings.

Parameters:

line1 (LineString) –

First Shapely LineString.
line2 (LineString) –

Second Shapely LineString.
pick (str, default: 'first_on_line1' ) –
Selection rule controlling which intersection point is returned. One of:
- "first_on_line1": closest to the start of line1.
- "last_on_line1": closest to the end of line1.
- "first_on_line2": closest to the start of line2.
- "last_on_line2": closest to the end of line2.
Any other value returns the first intersection found.

Returns:

Point | None –

A Shapely :class:~shapely.geometry.Point representing the chosen
Point | None –

intersection, or None if the lines do not intersect.

`has_self_intersection(pts)`

Return whether a polyline self-intersects.

Polylines with fewer than 4 points cannot self-intersect and always return False.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2).

Returns:

bool –

True if any two non-adjacent segments cross each other.

`heading_unit(heading)`

Return the unit direction vector of a heading angle.

Parameters:

heading (float) –

Heading angle in radians, measured counter-clockwise from the positive x-axis.

Returns:

ndarray –

Unit vector [cos(heading), sin(heading)] with shape (2,).

`nearest_s(polyline, point)`

Project a point onto a polyline and return the arc-length coordinate.

Parameters:

polyline (ndarray) –

Input polyline points with shape (N, 2), N >= 2.
point (ndarray) –

Query point with shape (2,).

Returns:

float –

Arc-length coordinate (s) of the closest point on the polyline,
float –

in the same unit as the coordinate values.

Raises:

ValueError –

If polyline does not have shape (N, 2) or contains fewer than 2 points, or if point shape is not (2,).

`normalize_angle(angle)`

Normalize an angle to the range [-pi, pi].

Parameters:

angle (float) –

Input angle in radians.

Returns:

float –

Equivalent angle in [-pi, pi].

`offset_polyline(pts, offset)`

Offset a polyline laterally by a signed distance.

Positive offset is to the left of the polyline direction; negative offset is to the right.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2), N >= 2.
offset (float) –

Signed lateral offset distance in metres.

Returns:

ndarray –

Offset polyline points with shape (N, 2).

Raises:

ValueError –

If pts does not have shape (N, 2) or contains fewer than 2 points.

`oriented_box(x, y, heading, length, width)`

Build an oriented rectangular polygon from a centre pose and dimensions.

Parameters:

x (float) –

Centre x-coordinate in metres.
y (float) –

Centre y-coordinate in metres.
heading (float) –

Orientation in radians, measured counter-clockwise from the positive x-axis.
length (float) –

Box length along the heading direction in metres. Values below 0.1 are clamped to 0.1.
width (float) –

Box width perpendicular to the heading direction in metres. Values below 0.1 are clamped to 0.1.

Returns:

Shapely ( Polygon ) –

class:~shapely.geometry.Polygon representing the oriented box.

`point_at_s(points, s)`

Sample one point from a polyline by arc-length coordinate.

Parameters:

points (ndarray) –

Polyline points with shape (N, 2), N >= 2.
s (float) –

Arc-length coordinate. Clamped to [0, total_length].

Returns:

ndarray –

Interpolated point at arc-length s with shape (2,).

Raises:

ValueError –

If points does not have shape (N, 2) or contains fewer than 2 points.

`point_heading_at_s(points, s)`

Sample one point and tangent heading from a polyline by arc-length coordinate.

Parameters:

points (ndarray) –

Polyline points with shape (N, 2), N >= 2.
s (float) –

Arc-length coordinate. Clamped to [0, total_length].

Returns:

ndarray –

A tuple (point, heading) where point has shape (2,) and
float –

heading is the tangent angle in radians at s.

Raises:

ValueError –

If points does not have shape (N, 2) or contains fewer than 2 points.

`polyline_end_pose(pts)`

Return the end point and tangent heading of a polyline.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2), N >= 2.

Returns:

ndarray –

A tuple (end_point, end_heading) where end_point has shape
float –

(2,) and end_heading is the tangent angle in radians.

Raises:

ValueError –

If pts does not have shape (N, 2) or contains fewer than 2 points.

`polyline_length(pts)`

Return the arc length of a polyline.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2). Arrays with fewer than 2 points return 0.0 without raising.

Returns:

float –

Total arc length in the same unit as the coordinate values. Returns
float –

0.0 for empty or single-point inputs.

`resample_polyline(points, n)`

Resample a polyline to exactly n uniformly spaced points by arc length.

Parameters:

points (ndarray) –

Polyline points with shape (N, 2).
n (int) –

Number of output points. Values <= 1 return the first point only.

Returns:

ndarray –

Resampled polyline points with shape (n, 2). Returns an empty
ndarray –

array for empty input.

`sample_by_s(pts, s_start, s_end, n_samples)`

Sample positions, headings, and right normals uniformly by arc length.

s_start and s_end are clamped to [0, total_length]. n_samples is clamped to at least 2.

Parameters:

pts (ndarray) –

Input polyline points with shape (N, 2), N >= 2.
s_start (float) –

Start arc-length coordinate.
s_end (float) –

End arc-length coordinate. Must be >= s_start after clamping; equal values produce a degenerate single-point segment.
n_samples (int) –

Number of output points. Values below 2 are raised to 2.

Returns:

ndarray –

A tuple (positions, headings, right_normals):
ndarray –
- positions: sampled points with shape (n_samples, 2).
ndarray –
- headings: tangent heading angles in radians with shape (n_samples,).
tuple[ndarray, ndarray, ndarray] –
- right_normals: unit right-normal vectors with shape (n_samples, 2).

Raises:

ValueError –

If pts does not have shape (N, 2) or contains fewer than 2 points.

tactics2d.geometry

CardinalDirection

from_string(direction) classmethod

Circle

get_arc(center_point, radius, delta_angle, start_angle, clockwise=True, step_size=0.1) staticmethod

get_circle(**kwargs) staticmethod

FrenetPoint dataclass

ReferencePath

cartesian_to_frenet(x, y)

frenet_to_cartesian(s, d)

heading_at(s)

RelativeDirection

from_string(direction) classmethod

as_point(point, name='point')

cumulative_s(pts)

curvature_stats(pts)

cut_polyline(line, pt, keep)

euclidean_distance(a, b)

find_intersection_point(line1, line2, *, pick='first_on_line1')

has_self_intersection(pts)

heading_unit(heading)

nearest_s(polyline, point)

normalize_angle(angle)

offset_polyline(pts, offset)

oriented_box(x, y, heading, length, width)

point_at_s(points, s)

point_heading_at_s(points, s)

polyline_end_pose(pts)

polyline_length(pts)

resample_polyline(points, n)

sample_by_s(pts, s_start, s_end, n_samples)

`tactics2d.geometry`

`CardinalDirection`

`from_string(direction)` `classmethod`

`Circle`

`get_arc(center_point, radius, delta_angle, start_angle, clockwise=True, step_size=0.1)` `staticmethod`

`get_circle(**kwargs)` `staticmethod`

`FrenetPoint` `dataclass`

`ReferencePath`

`cartesian_to_frenet(x, y)`

`frenet_to_cartesian(s, d)`

`heading_at(s)`

`RelativeDirection`

`from_string(direction)` `classmethod`

`as_point(point, name='point')`

`cumulative_s(pts)`

`curvature_stats(pts)`

`cut_polyline(line, pt, keep)`

`euclidean_distance(a, b)`

`find_intersection_point(line1, line2, *, pick='first_on_line1')`

`has_self_intersection(pts)`

`heading_unit(heading)`

`nearest_s(polyline, point)`

`normalize_angle(angle)`

`offset_polyline(pts, offset)`

`oriented_box(x, y, heading, length, width)`

`point_at_s(points, s)`

`point_heading_at_s(points, s)`

`polyline_end_pose(pts)`

`polyline_length(pts)`

`resample_polyline(points, n)`

`sample_by_s(pts, s_start, s_end, n_samples)`