# Geometry

### Geometry Module

Provides utility functions for performing geometric and spatial calculations in 2D and 3D environments.

***

## Accessing the Module

```lua
local GEOMETRY <const> = exports.boii_utils:get("modules.geometry")
```

***

## Shared

### distance\_2d(p1, p2)

Calculates the distance between two 2D points.

#### Parameters

| Name | Type    | Description           |
| ---- | ------- | --------------------- |
| p1   | `table` | First point `{x, y}`  |
| p2   | `table` | Second point `{x, y}` |

#### Example

```lua
local d = GEOMETRY.distance_2d({x = 0, y = 0}, {x = 3, y = 4})
-- d = 5
```

***

### distance\_3d(p1, p2)

Calculates the distance between two 3D points.

#### Parameters

| Name | Type    | Description              |
| ---- | ------- | ------------------------ |
| p1   | `table` | First point `{x, y, z}`  |
| p2   | `table` | Second point `{x, y, z}` |

#### Example

```lua
local d = GEOMETRY.distance_3d({x = 0, y = 0, z = 0}, {x = 0, y = 0, z = 10})
-- d = 10
```

***

### midpoint(p1, p2)

Returns the midpoint between two 3D points.

#### Parameters

| Name | Type    | Description              |
| ---- | ------- | ------------------------ |
| p1   | `table` | First point `{x, y, z}`  |
| p2   | `table` | Second point `{x, y, z}` |

#### Example

```lua
local mid = GEOMETRY.midpoint({x = 0, y = 0, z = 0}, {x = 4, y = 4, z = 4})
-- mid = {x = 2, y = 2, z = 2}
```

***

### is\_point\_in\_rect(point, rect)

Checks if a point is within a 2D rectangle.

#### Parameters

| Name  | Type    | Description                           |
| ----- | ------- | ------------------------------------- |
| point | `table` | The point `{x, y}`                    |
| rect  | `table` | The rectangle `{x, y, width, height}` |

#### Example

```lua
local inside = GEOMETRY.is_point_in_rect({x = 5, y = 5}, {x = 0, y = 0, width = 10, height = 10})
-- inside = true
```

***

### is\_point\_in\_box(point, box)

Checks if a 3D point is within a box.

#### Parameters

| Name  | Type    | Description                               |
| ----- | ------- | ----------------------------------------- |
| point | `table` | The point `{x, y, z}`                     |
| box   | `table` | The box `{x, y, z, width, height, depth}` |

#### Example

```lua
local inside = GEOMETRY.is_point_in_box({x = 2, y = 2, z = 2}, {x = 0, y = 0, z = 0, width = 5, height = 5, depth = 5})
```

***

### is\_point\_on\_line\_segment(point, line\_start, line\_end)

Checks if a 2D point lies on a line segment.

#### Parameters

| Name        | Type    | Description                 |
| ----------- | ------- | --------------------------- |
| point       | `table` | The point `{x, y}`          |
| line\_start | `table` | Line segment start `{x, y}` |
| line\_end   | `table` | Line segment end `{x, y}`   |

#### Example

```lua
local result = GEOMETRY.is_point_on_line_segment({x = 2, y = 2}, {x = 0, y = 0}, {x = 4, y = 4})
```

***

### project\_point\_on\_line(p, p1, p2)

Projects a point onto a 2D line segment.

#### Parameters

| Name | Type    | Description         |
| ---- | ------- | ------------------- |
| p    | `table` | Point `{x, y}`      |
| p1   | `table` | Line start `{x, y}` |
| p2   | `table` | Line end `{x, y}`   |

#### Example

```lua
local projected = GEOMETRY.project_point_on_line({x = 3, y = 4}, {x = 0, y = 0}, {x = 5, y = 0}) -- projected = {x = 3, y = 0}
```

***

### calculate\_slope(p1, p2)

Calculates the slope of a line between two 2D points.

#### Parameters

| Name | Type    | Description          |
| ---- | ------- | -------------------- |
| p1   | `table` | First point `{x,y}`  |
| p2   | `table` | Second point `{x,y}` |

#### Example

```lua
local slope = GEOMETRY.calculate_slope({x = 1, y = 2}, {x = 4, y = 6}) -- slope = 1.333
```

### angle\_between\_points(p1, p2)

Returns the angle between two 2D points in degrees.

#### Parameters

| Name | Type    | Description               |
| ---- | ------- | ------------------------- |
| p1   | `table` | The first point `{x, y}`  |
| p2   | `table` | The second point `{x, y}` |

#### Example

```lua
local angle = GEOMETRY.angle_between_points({ x = 0, y = 0 }, { x = 1, y = 1 })
```

***

### angle\_between\_3\_points(p1, p2, p3)

Calculates the angle between three 3D points (with `p2` as the vertex).

#### Parameters

| Name | Type    | Description                     |
| ---- | ------- | ------------------------------- |
| p1   | `table` | First point `{x, y, z}`         |
| p2   | `table` | Center/vertex point `{x, y, z}` |
| p3   | `table` | Third point `{x, y, z}`         |

#### Example

```lua
local angle = GEOMETRY.angle_between_3_points(p1, p2, p3)
```

***

### do\_circles\_intersect(c1\_center, c1\_radius, c2\_center, c2\_radius)

Checks if two 2D circles intersect.

#### Parameters

| Name       | Type     | Description                      |
| ---------- | -------- | -------------------------------- |
| c1\_center | `table`  | Center of first circle `{x, y}`  |
| c1\_radius | `number` | Radius of first circle           |
| c2\_center | `table`  | Center of second circle `{x, y}` |
| c2\_radius | `number` | Radius of second circle          |

#### Example

```lua
local result = GEOMETRY.do_circles_intersect({ x = 0, y = 0 }, 5, { x = 3, y = 0 }, 5)
```

***

### is\_point\_in\_circle(point, circle\_center, circle\_radius)

Checks if a 2D point is inside a circle.

#### Parameters

| Name           | Type     | Description                 |
| -------------- | -------- | --------------------------- |
| point          | `table`  | The point to check `{x, y}` |
| circle\_center | `table`  | Circle center `{x, y}`      |
| circle\_radius | `number` | Radius of the circle        |

#### Example

```lua
local inside = GEOMETRY.is_point_in_circle({ x = 2, y = 2 }, { x = 0, y = 0 }, 5)
```

***

### do\_lines\_intersect(l1\_start, l1\_end, l2\_start, l2\_end)

Determines whether two 2D line segments intersect.

#### Parameters

| Name      | Type    | Description              |
| --------- | ------- | ------------------------ |
| l1\_start | `table` | Start of line 1 `{x, y}` |
| l1\_end   | `table` | End of line 1 `{x, y}`   |
| l2\_start | `table` | Start of line 2 `{x, y}` |
| l2\_end   | `table` | End of line 2 `{x, y}`   |

#### Example

```lua
local intersects = GEOMETRY.do_lines_intersect(p1, p2, p3, p4)
```

***

### line\_intersects\_circle(line\_start, line\_end, circle\_center, circle\_radius)

Checks if a line segment intersects with a circle.

#### Parameters

| Name           | Type     | Description            |
| -------------- | -------- | ---------------------- |
| line\_start    | `table`  | Line start `{x, y}`    |
| line\_end      | `table`  | Line end `{x, y}`      |
| circle\_center | `table`  | Circle center `{x, y}` |
| circle\_radius | `number` | Radius of circle       |

#### Example

```lua
local hit = GEOMETRY.line_intersects_circle(p1, p2, { x = 0, y = 0 }, 10)
```

***

### does\_rect\_intersect\_line(rect, line\_start, line\_end)

Checks if a 2D rectangle intersects with a line segment.

#### Parameters

| Name        | Type    | Description                       |
| ----------- | ------- | --------------------------------- |
| rect        | `table` | Rectangle `{x, y, width, height}` |
| line\_start | `table` | Line start `{x, y}`               |
| line\_end   | `table` | Line end `{x, y}`                 |

#### Example

```lua
local crosses = GEOMETRY.does_rect_intersect_line(rect, p1, p2)
```

***

### closest\_point\_on\_line\_segment(point, line\_start, line\_end)

Returns the closest point on a line segment to a given point.

#### Parameters

| Name        | Type    | Description                 |
| ----------- | ------- | --------------------------- |
| point       | `table` | The point to check `{x, y}` |
| line\_start | `table` | Line start `{x, y}`         |
| line\_end   | `table` | Line end `{x, y}`           |

#### Example

```lua
local closest = GEOMETRY.closest_point_on_line_segment({ x = 2, y = 2 }, p1, p2)
```

***

### triangle\_area\_3d(p1, p2, p3)

Returns the area of a 3D triangle given three vertices.

#### Parameters

| Name | Type    | Description          |
| ---- | ------- | -------------------- |
| p1   | `table` | Vertex 1 `{x, y, z}` |
| p2   | `table` | Vertex 2 `{x, y, z}` |
| p3   | `table` | Vertex 3 `{x, y, z}` |

#### Example

```lua
local area = GEOMETRY.triangle_area_3d(p1, p2, p3)
```

***

### is\_point\_in\_sphere(point, sphere\_center, sphere\_radius)

Checks if a 3D point lies inside a sphere.

#### Parameters

| Name           | Type     | Description               |
| -------------- | -------- | ------------------------- |
| point          | `table`  | `{x, y, z}`               |
| sphere\_center | `table`  | Sphere center `{x, y, z}` |
| sphere\_radius | `number` | Radius of the sphere      |

#### Example

```lua
local inside = GEOMETRY.is_point_in_sphere(pos, center, 10)
```

***

### do\_spheres\_intersect(s1\_center, s1\_radius, s2\_center, s2\_radius)

Checks if two spheres intersect.

#### Parameters

| Name       | Type     | Description               |
| ---------- | -------- | ------------------------- |
| s1\_center | `table`  | Sphere 1 center `{x,y,z}` |
| s1\_radius | `number` | Sphere 1 radius           |
| s2\_center | `table`  | Sphere 2 center `{x,y,z}` |
| s2\_radius | `number` | Sphere 2 radius           |

#### Example

```lua
local hit = GEOMETRY.do_spheres_intersect(c1, 5, c2, 6)
```

***

### is\_point\_in\_convex\_polygon(point, polygon)

Checks if a 2D point lies inside a convex polygon.

#### Parameters

| Name    | Type    | Description                            |
| ------- | ------- | -------------------------------------- |
| point   | `table` | `{x, y}`                               |
| polygon | `table` | List of points `{ {x,y}, {x,y}, ... }` |

#### Example

```lua
local inside = GEOMETRY.is_point_in_convex_polygon({ x = 2, y = 3 }, polygon)
```

***

### rotate\_point\_around\_point\_2d(point, pivot, angle\_degrees)

Rotates a point around another point by degrees.

#### Parameters

| Name           | Type     | Description              |
| -------------- | -------- | ------------------------ |
| point          | `table`  | `{x, y}`                 |
| pivot          | `table`  | Rotation center `{x, y}` |
| angle\_degrees | `number` | Degrees to rotate        |

#### Example

```lua
local result = GEOMETRY.rotate_point_around_point_2d({x = 3, y = 3}, {x = 0, y = 0}, 90)
```

***

### distance\_point\_to\_plane(point, plane\_point, plane\_normal)

Calculates the shortest distance from a point to a plane.

#### Parameters

| Name          | Type    | Description         |
| ------------- | ------- | ------------------- |
| point         | `table` | `{x, y, z}`         |
| plane\_point  | `table` | Point on the plane  |
| plane\_normal | `table` | Normal of the plane |

#### Example

```lua
local dist = GEOMETRY.distance_point_to_plane(p, plane_p, normal)
```

***

### rotation\_to\_direction(rotation)

Converts Euler angles into a directional vector.

#### Parameters

| Name     | Type    | Description                     |
| -------- | ------- | ------------------------------- |
| rotation | `table` | Euler rotation `{x, y, z}` in ° |

#### Example

```lua
local dir = GEOMETRY.rotation_to_direction({x = 0, y = 0, z = 90})
```

***

### rotate\_box(center, width, length, heading)

Returns the 4 rotated corners of a box in 3D.

#### Parameters

| Name    | Type     | Description               |
| ------- | -------- | ------------------------- |
| center  | `table`  | Center of box `{x, y, z}` |
| width   | `number` | Box width                 |
| length  | `number` | Box length                |
| heading | `number` | Heading in degrees        |

#### Example

```lua
local corners = GEOMETRY.rotate_box({x=0,y=0,z=0}, 4, 2, 45)
```

***

### calculate\_rotation\_matrix(heading, pitch, roll)

Returns a basic Z rotation matrix.

#### Parameters

| Name    | Type     | Description        |
| ------- | -------- | ------------------ |
| heading | `number` | Heading in degrees |
| pitch   | `number` | Pitch in degrees   |
| roll    | `number` | Roll in degrees    |

#### Example

```lua
local matrix = GEOMETRY.calculate_rotation_matrix(90, 0, 0)
```

***

### translate\_point\_to\_local\_space(point, box\_origin, rot\_matrix)

Converts world point into local box space.

#### Parameters

| Name        | Type    | Description         |
| ----------- | ------- | ------------------- |
| point       | `table` | Point `{x, y, z}`   |
| box\_origin | `table` | Origin `{x, y, z}`  |
| rot\_matrix | `table` | 3x3 rotation matrix |

#### Example

```lua
local local_point = GEOMETRY.translate_point_to_local_space(p, origin, matrix)
```

***

### is\_point\_in\_oriented\_box(point, box)

Checks if a point is inside a rotated 3D box.

#### Parameters

| Name  | Type    | Description                                                                           |
| ----- | ------- | ------------------------------------------------------------------------------------- |
| point | `table` | The point `{x, y, z}`                                                                 |
| box   | `table` | Box config with keys `coords`, `width`, `height`, `depth`, `heading`, `pitch`, `roll` |

#### Example

```lua
local inside = GEOMETRY.is_point_in_oriented_box(pos, box)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.boii.dev/old-docs/boii_utils/api/geometry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.