hLXdZddlZddlmZmZmZmZmZmZm Z m Z m Z m Z ddl mZmZmZmZddlmZmZmZmZdededed eeeeeffd Zdeded eeeeeffd Zd ed eeeeeffd Zdeeefdeeefdeeefd eeeefeeefeeefeeefffdZdeeefdeeefd efdZ d%dededededededededed eeeeeeeffdZ d&ded ededed!ed"ed eeeeeeeeeeffd#Z dededededededededed eeeeeeeeeeffd$Z!y)'a Utility functions for SVG processing and path manipulation. This module provides low-level utility functions used throughout the svglib package for processing SVG content. It includes functions for parsing SVG path data, converting between different curve representations, and handling geometric transformations. The module includes: - SVG path parsing and normalization - Bezier curve conversion utilities - Elliptical arc processing functions - Vector mathematics helpers - String parsing utilities for SVG attributes N) acosceilcopysigncosdegreesfabshypotradianssinsqrt)ListTupleUnioncast)mmultrotatetransformPoint translateopmin_numvaluereturnc 8tjd|Dcgc]}|r t|}}g}tdt ||D]K}|dkDr |dvr |dk(rdnd}|j |t ttt||||zgM|Scc}w)aParse SVG coordinate string into alternating operators and coordinate lists. Splits a string of numeric values into groups and pairs each group with the appropriate SVG path operation. Automatically converts 'M' to 'L' for subsequent coordinate pairs to handle move-to followed by line-to sequences. Args: op: SVG path operation character (e.g., 'M', 'L', 'm', 'l'). min_num: Minimum number of coordinates expected per operation. value: String containing comma/whitespace-separated numeric values. Returns: List alternating between operation strings and coordinate lists. Example: ['M', [10.0, 20.0], 'L', [30.0, 40.0]] Examples: >>> split_floats('M', 2, '10,20 30,40') ['M', [10.0, 20.0], 'L', [30.0, 40.0]] >>> split_floats('L', 2, '100 200') ['L', [100.0, 200.0]] Note: Supports scientific notation (e.g., '1.23e-4') and handles various whitespace and comma separators automatically. (-?\d*\.?\d*(?:[eE][+-]?\d+)?)r>MmrlL) refindallfloatrangelenextendrr list)rrrseqfloatsresis >> split_arc_values('A', '50,50 0 1,0 100,100') ['A', [50.0, 50.0, 0.0, 1.0, 0.0, 100.0, 100.0]] >>> split_arc_values('a', '25 25 30 0 1 50 75') ['a', [25.0, 25.0, 30.0, 0.0, 1.0, 50.0, 75.0]] Note: The large-arc-flag and sweep-flag are converted to float but should be treated as boolean values (0 or 1). rz([1|0])z[\s,]*c32K|]}t|yw)N)r!).0nums r* z#split_arc_values..fs.RcuSz.Rs) joinrfinditerstripr$rr r!r%groups)rrfloat_reflag_rea_seq_rer(r&s r*split_arc_valuesr8?s81HG  x7GXx P    *,C{{8U[[]3V BT%[$.RSZZ\.R*RSTUV Jattrc~iddddddddddd dd dd dd dd ddddddddddddddddddd}|j}g}tjd|jtj}d}|D]}|jdk(r||vr9|d k(r|d k(rd }n|dk(r|dk(rd}n|}||dk(s@|j |ggT|j dk(r|j t||n|j t||||tt|d}|S)aNormalize SVG path data into structured format. Parses raw SVG path string and converts it into a standardized list format where each path command is paired with its coordinate parameters. Automatically handles command sequences and converts implicit line commands after move commands. Args: attr: Raw SVG path string (e.g., "M 10 20 L 30 40 Z"). Returns: Normalized list alternating between command strings and coordinate lists. Close path commands ('Z', 'z') are paired with empty lists for consistency. Examples: >>> normalise_svg_path("M 10 20 L 30 40 Z") ['M', [10.0, 20.0], 'L', [30.0, 40.0], 'Z', []] >>> normalise_svg_path("M 0 0 L 10 0 10 10 Z") ['M', [0.0, 0.0], 'L', [10.0, 0.0], 'L', [10.0, 10.0], 'Z', []] >>> normalise_svg_path("m 100,200 300,400") ['m', [100.0, 200.0], 'l', [300.0, 400.0]] Note: - Converts sequences of M/m commands to M/m followed by L/l commands - Handles all SVG path commands: M, L, H, V, C, c, S, s, Q, q, T, t, A, a, Z, z - Supports various whitespace and comma separators - All coordinates are converted to float values AaQqTtSsrrrrHVhvCr)cZzz([achlmqstvz]))flags) keysrsplitr3Ir$lowerr8r+rstr)r:opsop_keysresultr4ritems r*normalise_svg_pathr]js@  Q  Q  Q  Q   Q   Q   Q  Q  Q  Q  Q  Q  Q  Q  Q  Q! " Q# $  ) C,hhjG-/F XX& BDD AF B' ::<2   7?s{rSys2w!| r2h'xxzS  .r489 l2s2w=>c6":&B''* Mr9q0q1q2c|}|dd|d|dz zz|dd|d|dz zzf}|dd|d|dz zz|dd|d|dz zzf}|}||||fS)azConvert quadratic Bezier curve to cubic Bezier curve. Converts a quadratic Bezier curve defined by control points q0, q1, q2 into an equivalent cubic Bezier curve. This is useful for SVG processing since cubic curves are more commonly supported than quadratic curves. Args: q0: Starting point as (x, y) tuple. q1: Control point as (x, y) tuple. q2: End point as (x, y) tuple. Returns: Tuple of four (x, y) points defining the equivalent cubic Bezier curve: (start_point, control_point1, control_point2, end_point). Examples: >>> convert_quadratic_to_cubic_path((0, 0), (5, 10), (10, 0)) ((0, 0), (3.3333333333, 6.6666666666), (6.6666666666, 6.6666666666), (10, 0)) >>> # Simple case: straight line becomes straight line >>> convert_quadratic_to_cubic_path((0, 0), (5, 5), (10, 10)) ((0, 0), (3.3333333333, 3.3333333333), (6.6666666666, 6.6666666666), (10, 10)) Note: The conversion uses the standard formula where the cubic control points are calculated as: c1 = q0 + (2/3)*(q1 - q0), c2 = c1 + (1/3)*(q2 - q0). rgUUUUUU?rHgUUUUUU?)r^r_r`c0c1c2c3s r*convert_quadratic_to_cubic_pathrgs@ B Q%%2a52a5=) )2a55BqEBqEM3J+J KB Q%%2a52a5=) )2a55BqEBqEM3J+J KB B r2r>r9urKct|t|z}|dk(ry|d|dz|d|dzz|z }|dkrd}n|dkDrd}|d|dz|d|dzz }ttt||S)aCalculate the signed angle between two 2D vectors. Computes the angle between vectors u and v using the atan2 method to determine the correct quadrant and sign. Returns angle in degrees. Args: u: First vector as (x, y) tuple. v: Second vector as (x, y) tuple. Returns: Signed angle in degrees between the vectors, ranging from -180 to 180. Examples: >>> vector_angle((1, 0), (0, 1)) # 90 degrees counterclockwise 90.0 >>> vector_angle((1, 0), (0, -1)) # 90 degrees clockwise -90.0 >>> vector_angle((1, 0), (1, 0)) # Same direction 0.0 >>> vector_angle((1, 0), (-1, 0)) # Opposite direction 180.0 Note: - Handles zero-length vectors by returning 0 - Uses numerical stability checks to avoid domain errors in acos - Result is always in the range [-180, 180] degrees rrH)r rrr)rhrKdrNrFs r* vector_anglerls> q E1IAAv 1!qtad{ "a'A2v  Q  !qt adQqTk!A 8DGQ' ((r9x1y1x2y2fAfSrxryphic tt|}t|}|rHt|} t| } t| } d||z z} d||z z} | | z| | zz }| | z| | zz}nd||z z}d||z z}||z||zz ||z||zz z}|dkDr5t |}||z}||z}||z||zz ||z||zz z}d|z dz }n |dk7rd|z dz }d|cxkrdkrnnd}t |}||k(r| }||z|z|z }||z|z |z }|r) |z |zz d||zzz}| |z| |zzd||zzz}n|d||zzz}|d||zzz}t d||z |z ||z |z f}t ||z |z ||z |z f| |z |z | |z |z fdz}|dk(r |dkDr|dz}n|dk(r |dkr|dz }||||| | fS)aJConvert SVG arc endpoint parameters to center-based representation. Implements the algorithm from W3C SVG specification for converting elliptical arc parameters from endpoint format to center format. This is needed for proper arc rendering in ReportLab. Args: x1: X-coordinate of arc start point. y1: Y-coordinate of arc start point. x2: X-coordinate of arc end point. y2: Y-coordinate of arc end point. fA: Large arc flag (0 or 1). fS: Sweep flag (0 or 1). rx: Arc radius in X direction. ry: Arc radius in Y direction. phi: Rotation angle of the arc in degrees (default 0). Returns: Tuple of (cx, cy, rx, ry, start_angle, sweep_angle): - cx, cy: Center point coordinates - rx, ry: Adjusted radii (may be scaled up if too small) - start_angle: Starting angle in degrees - sweep_angle: Sweep angle in degrees Raises: This function handles all edge cases internally and doesn't raise exceptions. Examples: >>> end_point_to_center_parameters(0, 0, 10, 0, 0, 1, 5, 5) (5.0, 0.0, 5.0, 5.0, 180.0, 180.0) >>> # Degenerate case - identical points >>> end_point_to_center_parameters(5, 5, 5, 5, 0, 0, 10, 10) (5.0, 5.0, 10.0, 10.0, 0.0, 0.0) See Also: W3C SVG 1.1 Implementation Notes, Section F.6.5: http://www.w3.org/TR/SVG/implnote.html#ArcImplementationNotes Note: The rotation angle phi is reduced to zero by coordinate transformation outside this function for simplicity. ?rHrg|۽)rHrih)rr r rr rl)rmrnrorprqrrrsrtruphi_radsin_phicos_phitxtyx1dy1drrrcxdcydcxcytheta1dthetas r*end_point_to_center_parametersrsl bB bB #,g,g, BG_ BG_lWr\)lWr\)R"WoR"Wo, c R"Wc R"W 55A1u !W b b #Ib !C#Ib$9 9 EAI a EAI ~A~  QA Rx B r6C<2 C FSL/B C s]Ws] *SBG_ < s]Ws] *SBG_ < 3"r'? " 3"r'? "&C#I#3cCi25E"F GFCi2 c R/ 0SD3J"3DtczUWFW2X     Qw6A:#  qVaZ#  r2rF7VG ++r9rr start_angextentc dt|dkrd}|}ntt|dz }||z }|dk(rgSt|}|dz} tddt| z zt | z } |dkr| } g} t|} | |z} t| }t | }t |D]}|}|}| ||zz} t| }t | }| j |||zz|||zz |||| |zz zz|||| |zzzz |||| |zzzz|||| |zz zz |||zz|||zz f| S)uOConvert elliptical arc to cubic Bezier curve segments. Approximates an elliptical arc with cubic Bezier curves using the kappa constant method. The arc is divided into segments of at most 90 degrees each for accurate approximation. Args: cx: X-coordinate of ellipse center. cy: Y-coordinate of ellipse center. rx: Radius in X direction. ry: Radius in Y direction. start_ang: Starting angle in degrees (default 0). extent: Angular extent in degrees (default 90). Returns: List of Bezier curve segments, each as an 8-tuple: (x1, y1, x2, y2, x3, y3, x4, y4) where: - (x1, y1): Start point - (x2, y2): First control point - (x3, y3): Second control point - (x4, y4): End point Examples: >>> # Quarter circle (90 degrees) >>> curves = bezier_arc_from_centre(0, 0, 10, 10, 0, 90) >>> len(curves) # One segment for 90 degrees 1 >>> # Half circle (180 degrees) - split into two 90-degree segments >>> curves = bezier_arc_from_centre(0, 0, 10, 10, 0, 180) >>> len(curves) 2 >>> # Full circle (360 degrees) - split into four 90-degree segments >>> curves = bezier_arc_from_centre(0, 0, 10, 10, 0, 360) >>> len(curves) 4 Note: - Arcs are automatically subdivided into segments ≤ 90° for accuracy - Uses the standard kappa = 4/3 * (1 - cos(θ/2)) / sin(θ/2) formula - Handles both clockwise and counterclockwise arcs - Returns empty list for zero-extent arcs ZrHrrwgUUUUUU?)absrr rr r"append)rrrsrtrrnfrag frag_anglefrag_radhalf_radkappa point_listr start_radrds1r)rcs0s r*bezier_arc_from_centrers^ 6{b S[2%&e^ Q z"H#~H S]*+c(m; >> # Simple 180-degree arc >>> curves = bezier_arc_from_end_points(0, 0, 10, 10, 0, 0, 1, 20, 0) >>> len(curves) # Split into segments 2 >>> # Degenerate case - identical points (returns empty list) >>> curves = bezier_arc_from_end_points(10, 10, 5, 5, 0, 0, 0, 10, 10) >>> len(curves) 0 >>> # Rotated ellipse arc >>> curves = bezier_arc_from_end_points(0, 0, 10, 5, 45, 1, 0, 7, 7) >>> len(curves) # Will be split into multiple segments 2 Note: - Returns empty list if start and end points are identical - Automatically handles coordinate transformations for rotation - Splits arcs into ≤90° segments for accurate Bezier approximation - Follows W3C SVG 1.1 specification for arc parameter interpretation r)rrrrrrr)rmrnrsrtrurqrrrorpmxtx2ty2rrrrbpr(x3y3x4y4s r*bezier_arc_from_end_pointsrsdt RxB"H  63$<B3!4 5!"r2h/S,J q#sBB- )BB 6$BBIv F 9R$fSk 2.0  *BBBB JJrB8, b"X./ b"X./!b"X./   ,J BBB- )BB 6&b"b"iHHr9)r)rr)"__doc__rmathrrrrrrr r r r typingr rrrreportlab.graphics.shapesrrrrrXintr!r+r8r]rgrlrrrrbr9r*rs  TTT++NN%S%3%s%tE#tE{BR