0
# Linear Algebra
1

2
Core mathematical data structures and operations for numerical computing, including dense matrices, vectors, points, and linear algebra functions.
3

4
## Capabilities
5

6
### Matrix Operations
7

8
Dense 2D matrix class for floating point numerical computations with support for various initialization methods and basic operations.
9

10
```python { .api }
11
class matrix:
12
    """Dense 2D matrix of floating point numbers."""
13
    
14
    def __init__(self, rows: int, cols: int): 
15
        """Create matrix with specified dimensions."""
16
    
17
    def __init__(self, data: list):
18
        """Create matrix from list of lists."""
19
    
20
    def set_size(self, rows: int, cols: int):
21
        """Resize matrix to new dimensions."""
22
    
23
    def nr(self) -> int:
24
        """Get number of rows."""
25
    
26
    def nc(self) -> int:
27
        """Get number of columns."""
28
    
29
    def serialize(self, filename: str):
30
        """Save matrix to file."""
31
    
32
    def deserialize(self, filename: str):
33
        """Load matrix from file."""
34
    
35
    @property
36
    def shape(self) -> tuple:
37
        """Matrix dimensions as (rows, cols)."""
38
```
39

40
**Usage Example:**
41
```python
42
import dlib
43

44
# Create a 3x3 matrix
45
m = dlib.matrix(3, 3)
46

47
# Create from data
48
data = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
49
m2 = dlib.matrix(data)
50

51
print(f"Matrix shape: {m2.shape}")  # (3, 3)
52
print(f"Rows: {m2.nr()}, Cols: {m2.nc()}")  # Rows: 3, Cols: 3
53
```
54

55
### Vector Operations
56

57
Column vector class for mathematical operations with support for dynamic sizing and various initialization methods.
58

59
```python { .api }
60
class vector:
61
    """Column vector for mathematical operations."""
62
    
63
    def __init__(self, size: int = 0):
64
        """Create vector with specified size."""
65
    
66
    def __init__(self, data: list):
67
        """Create vector from list."""
68
    
69
    def set_size(self, size: int):
70
        """Resize vector to new size."""
71
    
72
    def resize(self, size: int):
73
        """Resize vector (alias for set_size)."""
74
    
75
    @property
76
    def shape(self) -> tuple:
77
        """Vector dimensions."""
78
```
79

80
### Array Operations
81

82
1D array class for floating point numbers, essentially a wrapper around std::vector<double>.
83

84
```python { .api }
85
class array:
86
    """1D array of floating point numbers."""
87
    
88
    def __init__(self, size: int = 0):
89
        """Create array with specified size."""
90
    
91
    def __init__(self, data: list):
92
        """Create array from list."""
93
    
94
    def clear(self):
95
        """Remove all elements."""
96
    
97
    def resize(self, size: int):
98
        """Resize array to new size."""
99
    
100
    def extend(self, data: list):
101
        """Append elements from list."""
102
```
103

104
### Point Types
105

106
2D point classes for integer and floating point coordinates with basic geometric operations.
107

108
```python { .api }
109
class point:
110
    """2D point with integer coordinates."""
111
    
112
    def __init__(self, x: int, y: int):
113
        """Create point with integer coordinates."""
114
    
115
    def __init__(self, dpoint_obj: dpoint):
116
        """Create from dpoint."""
117
    
118
    x: int  # X coordinate
119
    y: int  # Y coordinate
120
    
121
    def normalize(self) -> point:
122
        """Return unit normalized copy."""
123

124
class dpoint:
125
    """2D point with floating point coordinates."""
126
    
127
    def __init__(self, x: float, y: float):
128
        """Create point with floating coordinates."""
129
    
130
    def __init__(self, point_obj: point):
131
        """Create from integer point."""
132
    
133
    x: float  # X coordinate  
134
    y: float  # Y coordinate
135
    
136
    def normalize(self) -> dpoint:
137
        """Return unit normalized copy."""
138
```
139

140
**Usage Example:**
141
```python
142
import dlib
143

144
# Integer points
145
p1 = dlib.point(10, 20)
146
p2 = dlib.point(30, 40)
147

148
# Floating point
149
dp1 = dlib.dpoint(10.5, 20.7)
150
dp2 = dlib.dpoint(p1)  # Convert from integer point
151

152
# Operations
153
p3 = p1 + p2  # Addition
154
distance = dlib.length(p1)  # Distance from origin
155
dot_product = dlib.dot(p1, p2)  # Dot product
156
```
157

158
### Point Containers
159

160
Container classes for managing collections of points.
161

162
```python { .api }
163
class points:
164
    """Array of point objects."""
165
    
166
    def clear(self):
167
        """Remove all points."""
168
    
169
    def resize(self, size: int):
170
        """Resize container."""
171
    
172
    def extend(self, point_list: list):
173
        """Add points from list."""
174

175
class dpoints:
176
    """Array of dpoint objects."""
177
    
178
    def clear(self):
179
        """Remove all points."""
180
    
181
    def resize(self, size: int):
182
        """Resize container."""
183
    
184
    def extend(self, dpoint_list: list):
185
        """Add points from list."""
186
```
187

188
### Linear Algebra Functions
189

190
Core mathematical functions for vector and point operations.
191

192
```python { .api }
193
def dot(a, b):
194
    """
195
    Compute dot product of vectors or points.
196
    
197
    Args:
198
        a: First vector/point
199
        b: Second vector/point
200
    
201
    Returns:
202
        Dot product value
203
    """
204

205
def length(point_obj) -> float:
206
    """
207
    Compute distance from origin (L2 norm).
208
    
209
    Args:
210
        point_obj: Point object
211
    
212
    Returns:
213
        Distance as float
214
    """
215

216
def polygon_area(points_list) -> float:
217
    """
218
    Calculate area of polygon using shoelace formula.
219
    
220
    Args:
221
        points_list: List of point objects forming polygon
222
    
223
    Returns:
224
        Polygon area
225
    """
226
```
227

228
### Projective Transformations
229

230
2D projective transformation class for geometric transformations.
231

232
```python { .api }
233
class point_transform_projective:
234
    """Projective transformation for 2D points."""
235
    
236
    def __init__(self):
237
        """Create identity transformation."""
238
    
239
    def __init__(self, matrix_3x3):
240
        """Create from 3x3 transformation matrix."""
241
    
242
    @property
243
    def m(self):
244
        """3x3 transformation matrix."""
245
    
246
    def __call__(self, point_obj) -> point:
247
        """Apply transformation to point."""
248

249
def inv(transform: point_transform_projective) -> point_transform_projective:
250
    """
251
    Compute inverse of projective transformation.
252
    
253
    Args:
254
        transform: Projective transformation
255
    
256
    Returns:
257
        Inverse transformation
258
    """
259

260
def find_projective_transform(from_points, to_points) -> point_transform_projective:
261
    """
262
    Find projective transform mapping one set of points to another.
263
    
264
    Args:
265
        from_points: Source points
266
        to_points: Target points
267
    
268
    Returns:
269
        Projective transformation
270
    """
271
```
272

273
**Usage Example:**
274
```python
275
import dlib
276

277
# Create transformation from point correspondences
278
src_points = [dlib.point(0, 0), dlib.point(100, 0), dlib.point(100, 100), dlib.point(0, 100)]
279
dst_points = [dlib.point(10, 10), dlib.point(90, 20), dlib.point(80, 80), dlib.point(20, 90)]
280

281
transform = dlib.find_projective_transform(src_points, dst_points)
282

283
# Apply transformation
284
transformed_point = transform(dlib.point(50, 50))
285

286
# Compute inverse
287
inv_transform = dlib.inv(transform)
288
```
289

290
### Container Types for Advanced Data Structures
291

292
Additional container types for complex data organization.
293

294
```python { .api }
295
class vectors:
296
    """Array of vector objects."""
297
    
298
    def clear(self): ...
299
    def resize(self, size: int): ...
300
    def extend(self, vector_list: list): ...
301

302
class vectorss:
303
    """Array of arrays of vector objects."""
304
    
305
    def clear(self): ...
306
    def resize(self, size: int): ...
307
    def extend(self, vectors_list: list): ...
308

309
class range:
310
    """Represents a range of elements."""
311
    
312
    def __init__(self, begin: int, end: int):
313
        """Create range [begin, end)."""
314
    
315
    def __init__(self, end: int):
316
        """Create range [0, end)."""
317
    
318
    begin: int  # Start index
319
    end: int    # End index (exclusive)
320

321
class ranges:
322
    """Array of range objects."""
323
    
324
    def clear(self): ...
325
    def resize(self, size: int): ...
326
    def extend(self, range_list: list): ...
327

328
class rangess:
329
    """Array of arrays of range objects."""
330
    
331
    def clear(self): ...
332
    def resize(self, size: int): ...
333
    def extend(self, ranges_list: list): ...
334
```
335

336
### Sparse Vector Support
337

338
Sparse vector representation using index/value pairs for memory-efficient storage of sparse data.
339

340
```python { .api }
341
class pair:
342
    """Index/value pair for sparse vectors."""
343
    
344
    def __init__(self, index: int, value: float):
345
        """Create index/value pair."""
346
    
347
    first: int    # Index
348
    second: float # Value
349

350
class sparse_vector:
351
    """Sparse column vector using index/value pairs."""
352
    
353
    def clear(self):
354
        """Remove all elements."""
355
    
356
    def resize(self, size: int):
357
        """Resize container."""
358
    
359
    def extend(self, pair_list: list):
360
        """Add pairs from list."""
361

362
class sparse_vectors:
363
    """Array of sparse_vector objects."""
364
    
365
    def clear(self): ...
366
    def resize(self, size: int): ...
367
    def extend(self, sparse_vector_list: list): ...
368

369
class sparse_vectorss:
370
    """Array of arrays of sparse_vector objects."""
371
    
372
    def clear(self): ...
373
    def resize(self, size: int): ...
374
    def extend(self, sparse_vectors_list: list): ...
375

376
def make_sparse_vector(sparse_vec: sparse_vector) -> sparse_vector:
377
    """
378
    Sort and deduplicate sparse vector.
379
    
380
    Args:
381
        sparse_vec: Input sparse vector
382
    
383
    Returns:
384
        Sorted and deduplicated sparse vector
385
    """
386
```
387

388
**Usage Example:**
389
```python
390
import dlib
391

392
# Create sparse vector
393
sparse_vec = dlib.sparse_vector()
394
sparse_vec.extend([
395
    dlib.pair(0, 1.5),
396
    dlib.pair(5, 2.3), 
397
    dlib.pair(10, -0.8)
398
])
399

400
# Clean up sparse vector
401
clean_vec = dlib.make_sparse_vector(sparse_vec)
402
```