0
# SVG Path Processing
1

2
Utility functions for parsing, normalizing, and converting SVG path data and mathematical operations for arc and bezier curve processing. These functions handle the complex mathematics required for accurate SVG path rendering.
3

4
## Capabilities
5

6
### Path Data Parsing
7

8
Parse and normalize SVG path data strings into structured format for processing.
9

10
```python { .api }
11
def normalise_svg_path(attr):
12
    """
13
    Normalize SVG path data by adding operation codes.
14
    
15
    Converts SVG path strings into structured list format with explicit
16
    operation codes for multi-argument parameters and fixes consecutive
17
    M/m operators to M/m + L/l sequences.
18
    
19
    Parameters:
20
    - attr: str - SVG path data string (e.g., "M 10 20, M 20 20, L 30 40, Z")
21
    
22
    Returns:
23
    list: Normalized path operations and coordinates
24
        Example: ['M', [10, 20], 'L', [20, 20], 'L', [30, 40], 'Z', []]
25
    """
26
```
27

28
**Usage Example:**
29

30
```python
31
from svglib.utils import normalise_svg_path
32

33
# Normalize complex path data
34
path_data = "M 10 20, M 20 20, L 30 40, 40 40, Z"
35
normalized = normalise_svg_path(path_data)
36
# Returns: ['M', [10, 20], 'L', [20, 20], 'L', [30, 40], 'L', [40, 40], 'Z', []]
37

38
# Handle path with curves
39
curve_path = "M 0 0 C 10 10, 20 10, 30 0"
40
normalized_curve = normalise_svg_path(curve_path)
41
```
42

43
### Float Value Parsing
44

45
Split string values into float arrays with appropriate SVG path operations.
46

47
```python { .api }
48
def split_floats(op, min_num, value):
49
    """
50
    Split string of numbers into float list with SVG path operations.
51
    
52
    Converts coordinate strings to float arrays and inserts appropriate
53
    operation codes for multi-coordinate sequences.
54
    
55
    Parameters:
56
    - op: str - SVG path operation ('m', 'M', 'l', 'L', etc.)
57
    - min_num: int - Minimum number of coordinates per operation
58
    - value: str - String containing coordinate values
59
    
60
    Returns:
61
    list: Operation codes and coordinate arrays
62
        Example: ['m', [10.0, 20.0], 'l', [30.0, 40.0]]
63
    """
64
```
65

66
### Arc Value Parsing
67

68
Parse SVG arc command values with proper flag and coordinate handling.
69

70
```python { .api }
71
def split_arc_values(op, value):
72
    """
73
    Parse SVG arc command values.
74
    
75
    Handles the complex arc parameter format with rx, ry, rotation,
76
    large-arc-flag, sweep-flag, and endpoint coordinates.
77
    
78
    Parameters:
79
    - op: str - Arc operation ('A' or 'a')
80
    - value: str - Arc parameter string
81
    
82
    Returns:
83
    list: Arc operations with parsed parameters
84
    """
85
```
86

87
### Bezier Curve Conversion
88

89
Convert quadratic Bezier curves to cubic Bezier format for ReportLab compatibility.
90

91
```python { .api }
92
def convert_quadratic_to_cubic_path(q0, q1, q2):
93
    """
94
    Convert quadratic Bezier curve to cubic Bezier curve.
95
    
96
    ReportLab only supports cubic Bezier curves, so this function converts
97
    SVG quadratic curves (Q commands) to cubic format (C commands).
98
    
99
    Parameters:
100
    - q0: tuple - Start point (x, y)
101
    - q1: tuple - Control point (x, y)
102
    - q2: tuple - End point (x, y)
103
    
104
    Returns:
105
    tuple: Four control points for cubic curve (c0, c1, c2, c3)
106
    """
107
```
108

109
**Usage Example:**
110

111
```python
112
from svglib.utils import convert_quadratic_to_cubic_path
113

114
# Convert quadratic to cubic
115
start = (0, 0)
116
control = (50, 100)
117
end = (100, 0)
118

119
cubic_points = convert_quadratic_to_cubic_path(start, control, end)
120
c0, c1, c2, c3 = cubic_points
121
# c0 = (0, 0), c1 ≈ (33.33, 66.67), c2 ≈ (66.67, 66.67), c3 = (100, 0)
122
```
123

124
### Vector Mathematics
125

126
Calculate angles and relationships between vectors for arc processing.
127

128
```python { .api }
129
def vector_angle(u, v):
130
    """
131
    Calculate angle between two vectors.
132
    
133
    Used in arc processing to determine sweep angles and orientations.
134
    
135
    Parameters:
136
    - u: tuple - First vector (x, y)
137
    - v: tuple - Second vector (x, y)
138
    
139
    Returns:
140
    float: Angle between vectors in degrees
141
    """
142
```
143

144
### Arc Parameter Conversion
145

146
Convert between different arc parameter representations used in SVG.
147

148
```python { .api }
149
def end_point_to_center_parameters(x1, y1, x2, y2, fA, fS, rx, ry, phi=0):
150
    """
151
    Convert SVG arc endpoint parameters to center parameters.
152
    
153
    SVG uses endpoint parameterization for arcs, but mathematical processing
154
    often requires center parameterization. This function performs the conversion.
155
    
156
    Parameters:
157
    - x1, y1: float - Start point coordinates
158
    - x2, y2: float - End point coordinates
159
    - fA: int - Large arc flag (0 or 1)
160
    - fS: int - Sweep flag (0 or 1)
161
    - rx, ry: float - Ellipse radii
162
    - phi: float - Rotation angle in degrees
163
    
164
    Returns:
165
    tuple: (cx, cy, start_angle, sweep_angle) - Center and angle parameters
166
    """
167
```
168

169
### Bezier Arc Generation
170

171
Generate Bezier curve approximations for elliptical arcs.
172

173
```python { .api }
174
def bezier_arc_from_centre(cx, cy, rx, ry, start_ang=0, extent=90):
175
    """
176
    Generate Bezier curves approximating an elliptical arc from center parameters.
177
    
178
    Converts arc specifications to series of cubic Bezier curves that
179
    ReportLab can render accurately.
180
    
181
    Parameters:
182
    - cx, cy: float - Arc center coordinates
183
    - rx, ry: float - Ellipse radii
184
    - start_ang: float - Start angle in degrees
185
    - extent: float - Arc extent in degrees
186
    
187
    Returns:
188
    list: List of cubic Bezier curve control points
189
    """
190

191
def bezier_arc_from_end_points(x1, y1, rx, ry, phi, fA, fS, x2, y2):
192
    """
193
    Generate Bezier curves for SVG arc from endpoint parameters.
194
    
195
    High-level function that combines endpoint-to-center conversion with
196
    Bezier arc generation for direct SVG arc processing.
197
    
198
    Parameters:
199
    - x1, y1: float - Start point coordinates
200
    - rx, ry: float - Ellipse radii
201
    - phi: float - Rotation angle in degrees
202
    - fA: int - Large arc flag (0 or 1)
203
    - fS: int - Sweep flag (0 or 1)
204
    - x2, y2: float - End point coordinates
205
    
206
    Returns:
207
    list: List of cubic Bezier curve control points
208
    """
209
```
210

211
**Usage Example:**
212

213
```python
214
from svglib.utils import bezier_arc_from_centre, bezier_arc_from_end_points
215

216
# Generate arc from center parameters
217
curves = bezier_arc_from_centre(
218
    cx=50, cy=50,  # Center
219
    rx=30, ry=20,  # Radii
220
    start_ang=0, extent=90  # Quarter circle
221
)
222

223
# Generate arc from SVG endpoint format
224
curves = bezier_arc_from_end_points(
225
    x1=0, y1=50,     # Start point
226
    rx=30, ry=20,    # Radii
227
    phi=0,           # No rotation
228
    fA=0, fS=1,      # Small arc, positive sweep
229
    x2=50, y2=0      # End point
230
)
231
```
232

233
## Mathematical Constants and Utilities
234

235
The module uses various mathematical operations from Python's `math` module:
236

237
- `acos`, `cos`, `sin` - Trigonometric functions for arc calculations
238
- `degrees`, `radians` - Angle unit conversions
239
- `sqrt`, `hypot` - Distance and magnitude calculations
240
- `copysign`, `fabs` - Sign and absolute value operations
241
- `ceil` - Rounding operations
242

243
These are used internally by the arc and curve processing functions to perform accurate geometric calculations required for SVG path rendering.