0
# Geometric Computations
1

2
Geometric computation functions including ellipse fitting, line segment intersections, primitive shape generation, hull sectioning, and vertex calculations for color space visualization and analysis.
3

4
## Capabilities
5

6
### Ellipse Fitting and Analysis
7

8
Functions for fitting ellipses to data points and working with elliptical representations.
9

10
```python { .api }
11
def ellipse_fitting(coefficients: ArrayLike, method: str = "Halir 1998") -> NDArray:
12
    """
13
    Fit an ellipse to given coefficients using specified method.
14
    
15
    Parameters:
16
    - coefficients: ellipse coefficients or data points
17
    - method: fitting method
18
        - "Halir 1998" (default): Halir and Flusser (1998) algebraic ellipse fitting
19
    
20
    Returns:
21
    Fitted ellipse parameters
22
    """
23

24
def ellipse_coefficients_general_form(coefficients: ArrayLike) -> NDArray:
25
    """
26
    Convert ellipse coefficients to general form Ax² + Bxy + Cy² + Dx + Ey + F = 0.
27
    
28
    Parameters:
29
    - coefficients: ellipse coefficients in canonical form
30
    
31
    Returns:
32
    General form coefficients [A, B, C, D, E, F]
33
    """
34

35
def ellipse_coefficients_canonical_form(coefficients: ArrayLike) -> NDArray:
36
    """
37
    Convert ellipse coefficients to canonical form parameters.
38
    
39
    Parameters:
40
    - coefficients: ellipse coefficients in general form
41
    
42
    Returns:
43
    Canonical form parameters [center_x, center_y, semi_major, semi_minor, angle]
44
    """
45

46
def point_at_angle_on_ellipse(coefficients: ArrayLike, angle: float) -> NDArray:
47
    """
48
    Calculate point coordinates at given angle on ellipse.
49
    
50
    Parameters:
51
    - coefficients: ellipse coefficients in canonical form
52
    - angle: angle in radians
53
    
54
    Returns:
55
    Point coordinates [x, y] on ellipse
56
    """
57

58
# Method collection for ellipse fitting
59
ELLIPSE_FITTING_METHODS: Dict[str, Callable]
60
```
61

62
### Line Segment Operations
63

64
Functions for working with line segments including intersection calculations and extensions.
65

66
```python { .api }
67
def intersect_line_segments(l_1: ArrayLike, l_2: ArrayLike) -> LineSegmentsIntersections_Specification:
68
    """
69
    Calculate intersection points between two line segments.
70
    
71
    Parameters:
72
    - l_1: first line segment endpoints as array [[x1, y1], [x2, y2]]
73
    - l_2: second line segment endpoints as array [[x1, y1], [x2, y2]]
74
    
75
    Returns:
76
    LineSegmentsIntersections_Specification with intersection data
77
    """
78

79
def extend_line_segment(segment: ArrayLike, distance: float) -> NDArray:
80
    """
81
    Extend line segment by specified distance.
82
    
83
    Parameters:
84
    - segment: line segment endpoints [[x1, y1], [x2, y2]]
85
    - distance: extension distance
86
    
87
    Returns:
88
    Extended line segment endpoints
89
    """
90

91
class LineSegmentsIntersections_Specification:
92
    """
93
    Specification class for line segment intersection results.
94
    
95
    Attributes:
96
    - xy: intersection point coordinates
97
    - intersect: whether segments intersect
98
    - parallel: whether segments are parallel
99
    - collinear: whether segments are collinear
100
    """
101
    xy: NDArray
102
    intersect: bool
103
    parallel: bool
104
    collinear: bool
105
```
106

107
### Primitive Shape Generation
108

109
Functions for generating geometric primitives used in color space visualizations.
110

111
```python { .api }
112
def primitive(method: str = "cube", **kwargs) -> NDArray:
113
    """
114
    Generate geometric primitive vertices using specified method.
115
    
116
    Parameters:
117
    - method: primitive type
118
        - "cube" (default): unit cube vertices
119
        - "grid": rectangular grid
120
    - **kwargs: method-specific parameters
121
    
122
    Returns:
123
    Primitive vertex coordinates
124
    """
125

126
def primitive_grid(width: int = 16, height: int = 16, depth: int = 16) -> NDArray:
127
    """
128
    Generate rectangular grid primitive.
129
    
130
    Parameters:
131
    - width: grid width resolution
132
    - height: grid height resolution  
133
    - depth: grid depth resolution
134
    
135
    Returns:
136
    Grid vertex coordinates as ndarray shape (width*height*depth, 3)
137
    """
138

139
def primitive_cube() -> NDArray:
140
    """
141
    Generate unit cube primitive vertices.
142
    
143
    Returns:
144
    Cube vertex coordinates as ndarray shape (8, 3)
145
    """
146

147
# Method collection for primitive generation
148
PRIMITIVE_METHODS: Dict[str, Callable]
149

150
# Axis mapping for plane-to-axis conversions
151
MAPPING_PLANE_TO_AXIS: Dict[str, int]
152
```
153

154
### Primitive Vertices Generation
155

156
Functions for generating vertices for various primitive shapes with different backends.
157

158
```python { .api }
159
def primitive_vertices(method: str = "cube", **kwargs) -> NDArray:
160
    """
161
    Generate primitive vertices using specified method.
162
    
163
    Parameters:
164
    - method: vertex generation method
165
        - "cube": cube vertices
166
        - "grid": grid vertices
167
        - "quad_mpl": matplotlib quad vertices
168
        - "sphere": sphere vertices
169
    - **kwargs: method-specific parameters
170
    
171
    Returns:
172
    Vertex coordinates
173
    """
174

175
def primitive_vertices_cube_mpl(**kwargs) -> NDArray:
176
    """
177
    Generate cube vertices for matplotlib visualization.
178
    
179
    Parameters:
180
    - **kwargs: additional parameters for cube generation
181
    
182
    Returns:
183
    Cube vertices formatted for matplotlib
184
    """
185

186
def primitive_vertices_grid_mpl(width: int = 16, height: int = 16, **kwargs) -> NDArray:
187
    """
188
    Generate grid vertices for matplotlib visualization.
189
    
190
    Parameters:
191
    - width: grid width resolution
192
    - height: grid height resolution
193
    - **kwargs: additional parameters
194
    
195
    Returns:
196
    Grid vertices formatted for matplotlib
197
    """
198

199
def primitive_vertices_quad_mpl(**kwargs) -> NDArray:
200
    """
201
    Generate quadrilateral vertices for matplotlib visualization.
202
    
203
    Parameters:
204
    - **kwargs: additional parameters for quad generation
205
    
206
    Returns:
207
    Quad vertices formatted for matplotlib
208
    """
209

210
def primitive_vertices_sphere(segments: int = 16, **kwargs) -> NDArray:
211
    """
212
    Generate sphere vertices.
213
    
214
    Parameters:
215
    - segments: number of spherical segments
216
    - **kwargs: additional parameters
217
    
218
    Returns:
219
    Sphere vertex coordinates
220
    """
221

222
# Method collection for primitive vertices
223
PRIMITIVE_VERTICES_METHODS: Dict[str, Callable]
224
```
225

226
### Hull Section Analysis
227

228
Functions for analyzing hull sections in geometric data.
229

230
```python { .api }
231
def hull_section(points: ArrayLike, axis: str = "z", origin: float = 0, 
232
                normalise: bool = True) -> NDArray:
233
    """
234
    Calculate hull section of points along specified axis.
235
    
236
    Parameters:
237
    - points: point coordinates as ndarray
238
    - axis: sectioning axis ("x", "y", or "z")
239
    - origin: section plane position along axis
240
    - normalise: whether to normalise coordinates
241
    
242
    Returns:
243
    Hull section boundary points
244
    """
245
```
246

247
## Usage Examples
248

249
### Ellipse Fitting
250

251
```python
252
import colour
253
import numpy as np
254

255
# Generate sample ellipse data points
256
angles = np.linspace(0, 2*np.pi, 20)
257
a, b = 5, 3  # semi-major and semi-minor axes
258
x = a * np.cos(angles) + np.random.normal(0, 0.1, 20)
259
y = b * np.sin(angles) + np.random.normal(0, 0.1, 20)
260
points = np.column_stack([x, y])
261

262
# Fit ellipse to points
263
ellipse_params = colour.ellipse_fitting(points, method="Halir 1998")
264
print(f"Ellipse parameters: {ellipse_params}")
265

266
# Get points on fitted ellipse
267
test_angles = np.array([0, np.pi/4, np.pi/2])
268
ellipse_points = [colour.point_at_angle_on_ellipse(ellipse_params, angle) 
269
                  for angle in test_angles]
270
print(f"Points on ellipse: {ellipse_points}")
271
```
272

273
### Line Segment Intersections
274

275
```python
276
import colour
277
import numpy as np
278

279
# Define two line segments
280
line1 = np.array([[0, 0], [4, 4]])  # Diagonal line
281
line2 = np.array([[0, 4], [4, 0]])  # Opposite diagonal
282

283
# Find intersection
284
intersection = colour.intersect_line_segments(line1, line2)
285
print(f"Intersection point: {intersection.xy}")
286
print(f"Do they intersect? {intersection.intersect}")
287
print(f"Are they parallel? {intersection.parallel}")
288

289
# Extend a line segment
290
extended_line = colour.extend_line_segment(line1, 2.0)
291
print(f"Extended line: {extended_line}")
292
```
293

294
### Primitive Generation
295

296
```python
297
import colour
298
import numpy as np
299

300
# Generate cube vertices
301
cube_vertices = colour.primitive("cube")
302
print(f"Cube vertices shape: {cube_vertices.shape}")
303
print(f"Cube vertices:\n{cube_vertices}")
304

305
# Generate grid primitive
306
grid_vertices = colour.primitive_grid(width=4, height=4, depth=4)
307
print(f"Grid vertices shape: {grid_vertices.shape}")
308

309
# Generate sphere vertices
310
sphere_vertices = colour.primitive_vertices("sphere", segments=8)
311
print(f"Sphere vertices shape: {sphere_vertices.shape}")
312
```
313

314
### Visualization Primitives
315

316
```python
317
import colour
318
import numpy as np
319

320
# Generate matplotlib-compatible primitives
321
quad_vertices = colour.primitive_vertices_quad_mpl()
322
cube_vertices_mpl = colour.primitive_vertices_cube_mpl()
323
grid_vertices_mpl = colour.primitive_vertices_grid_mpl(width=8, height=8)
324

325
print(f"Quad vertices for matplotlib: {quad_vertices.shape}")
326
print(f"Cube vertices for matplotlib: {cube_vertices_mpl.shape}")
327
print(f"Grid vertices for matplotlib: {grid_vertices_mpl.shape}")
328
```
329

330
### Hull Section Analysis
331

332
```python
333
import colour
334
import numpy as np
335

336
# Generate random 3D points
337
points = np.random.random((100, 3)) * 10
338

339
# Calculate hull sections along different axes
340
hull_z = colour.hull_section(points, axis="z", origin=5.0)
341
hull_x = colour.hull_section(points, axis="x", origin=7.5, normalise=False)
342

343
print(f"Z-axis hull section shape: {hull_z.shape}")
344
print(f"X-axis hull section shape: {hull_x.shape}")
345
```
346

347
## Types
348

349
```python { .api }
350
from colour.hints import ArrayLike, NDArray, Dict, Callable
351
from typing import NamedTuple
352

353
# Specification classes  
354
class LineSegmentsIntersections_Specification(NamedTuple):
355
    xy: NDArray
356
    intersect: bool
357
    parallel: bool
358
    collinear: bool
359

360
# Method collections type
361
GeometryMethodCollection = Dict[str, Callable]
362

363
# Axis mapping type
364
AxisMapping = Dict[str, int]
365
```
366

367
## Imports
368

369
```python
370
# Ellipse operations
371
from colour.geometry import (
372
    ellipse_fitting, ellipse_coefficients_general_form,
373
    ellipse_coefficients_canonical_form, point_at_angle_on_ellipse,
374
    ELLIPSE_FITTING_METHODS
375
)
376

377
# Line operations  
378
from colour.geometry import (
379
    intersect_line_segments, extend_line_segment,
380
    LineSegmentsIntersections_Specification
381
)
382

383
# Primitive generation
384
from colour.geometry import (
385
    primitive, primitive_grid, primitive_cube,
386
    primitive_vertices, PRIMITIVE_METHODS, PRIMITIVE_VERTICES_METHODS
387
)
388

389
# Hull analysis
390
from colour.geometry import hull_section
391

392
# Alternative imports from main package
393
from colour import (
394
    ellipse_fitting, intersect_line_segments, primitive,
395
    primitive_vertices, hull_section
396
)
397
```