added method to find convexity of arc in arcline

Author: radevgit

CONVEX_HULL_ALGORITHM.md

@@ -0,0 +1,173 @@
+# Arcline Convex Hull Algorithm
+
+## Core Concept
+Pure gift-wrapping (Jarvis march) adapted for circular arcs: instead of drawing straight lines between points, draw tangent lines to circles.
+
+## Algorithm
+
+### 1. Find Starting Point
+- If the first arc is **concave** (backward-traversed): use its start point
+- If the first arc is **convex** (forward-traversed): use tangent to two circles (previous arc's circle and this arc's circle)
+- This gives the initial "point" to start from
+
+### 2. Gift-Wrapping Loop
+From the current point/arc end, for each candidate arc/point:
+- **If candidate is a point**: Direction is point - current_position
+- **If candidate is an arc**: Compute external tangent from current_position to the circle
+  - The tangent touches the circle at a tangent point
+  - Use that tangent point as the next position
+
+Find the arc/point that creates the **rightmost tangent** (maximum right turn in CCW, or minimum left turn).
+
+### 3. Move to Next
+- The other end of the tangent line is the new current position
+- This position is either:
+  - A point (end of a line segment)
+  - A tangent point on an arc's circle (end point of the arc for convex, or start point for concave)
+
+### 4. Repeat Until Closure
+Continue until returning to the starting point/arc.
+
+## Why This Works
+- Gift-wrapping naturally selects the outer boundary
+- Tangent lines to circles ensure the hull stays convex
+- Works for both line segments (zero-radius circles) and arcs (non-zero radius)
+- Handles mixed arclines (arcs + line segments)
+
+## Algorithm Steps
+
+### 1. Mark Convexity of Each Arc
+For each arc in the input arcline, determine if it's **convex** (forward-traversed) or **concave** (backward-traversed).
+
+**Logic**: `is_arc_convex(arcs, i)`
+- Get previous arc at index `i-1`
+- Get current arc at index `i`
+- **Convex**: Current arc starts where previous arc ends (`prev.b == arc.a`)
+  - Arcs are connected in forward direction, following the curve naturally
+- **Concave**: Current arc starts where previous arc starts (`prev.b == arc.b`)
+  - Arc is traversed backward, creating a concave turn
+  
+**Why this works**: Since the input is a closed polyline, adjacent arcs either connect forward (convex) or require reversal (concave). Only forward-connected sequences form the actual convex hull boundary.
+
+### 2. Find Starting Point
+Identify the first convex arc in the sequence to begin hull construction.
+
+**Logic**: `find_start_point(arcs, start_idx)`
+- Iterate through arcs from `start_idx`
+- Return the index of the first arc marked as convex
+- If no convex arc exists, the polyline is entirely concave (degenerate case)
+
+**Why this works**: Starting from a convex arc ensures we begin on the actual boundary.
+
+### 3. Sequential Processing with Smart Candidate Selection & Tangent Cutting
+Build the hull by iterating through arcs sequentially, but when connecting each convex arc to the next one, **evaluate ALL arcs as candidates using cross product**, and **cut arcs at tangent points where they would overlap**.
+
+**Main loop structure**:
+```
+i = start_idx
+loop:
+    if is_convex[i]:
+        current_arc = arcs[i]
+        
+        // STEP A: Find best next arc by evaluating ALL candidates
+        best_next_idx = select best arc from all convex arcs
+                        using cross product comparison
+        next_arc = arcs[best_next_idx]
+        
+        // STEP B: Tangent point cutting (THE SPECIAL ARC-SPECIFIC PART)
+        // If current and next arcs are adjacent and both curved:
+        //   - Compute external tangent line between their circles
+        //   - Cut current arc at the tangent point on its end
+        //   - Cut next arc at the tangent point on its start
+        // This avoids redundant curvature in the hull
+        
+        arc_start, arc_end = split_at_tangent_points(current_arc, next_arc)
+        
+        // STEP C: Add to hull
+        if arc is significant (not degenerate):
+            add arc or line segment to hull
+        
+    i = (i + 1) % n
+    
+    // Stop when we've cycled back to start after processing at least one
+    if i == start_idx && processed_something:
+        break
+```
+
+**Three-step process per arc**:
+1. **Find best candidate** (like gift-wrapping points)
+2. **Cut at tangents** (unique to arcs - optimize representation)
+3. **Add to hull** (connect and store)
+
+### 4. Candidate Arc Selection (THE CRITICAL PART)
+**Old (broken) approach**: Sequential search
+- Starting from arc `i+1`, find the FIRST convex arc
+- Break immediately when found
+- **Problem**: Only checks adjacent arcs, misses optimal candidates far away
+- **Result**: For spiral, follows nearby inner arcs → hull cuts through interior
+
+**New (fixed) approach**: Gift-wrapping with cross product
+- Evaluate ALL convex arcs as candidates
+- For each candidate arc `j`:
+  - Get direction from previous arc to current arc: `prev_dir = current.b - prev.b`
+  - Get direction from current to candidate: `to_candidate = candidate.a - current.b`
+  - Compute cross product: `cross = prev_dir.x * to_candidate.y - prev_dir.y * to_candidate.x`
+  - Positive = left turn (counterclockwise), larger = more left turn
+- **Select**: Arc with **maximum cross product** (most extreme left turn)
+- **Why this works**: Most left turn naturally wraps around convex boundary
+  - For spiral: outer arcs have larger left turns than inner arcs
+  - For simple shapes: maintains proper convex sequence
+
+### 5. Arc Splitting at Tangent Points (Optional)
+If two consecutive convex arcs are adjacent (indices differ by 1) and both are curved:
+- Compute external tangent line between their circles
+- Split current arc at tangent point to avoid redundant curvature
+- This optimizes the hull representation but isn't essential for correctness
+
+### 6. Close the Loop
+After processing all arcs:
+- Add final connecting segment from last hull arc end to first hull arc start
+- This completes the closed hull boundary
+
+## Complexity Analysis
+- **Time**: O(n²) where n = number of arcs
+  - Outer loop: O(n) arcs processed
+  - Inner loop: O(n) candidates evaluated per arc
+  - Cross product: O(1)
+- **Space**: O(n) for marking convexity and building hull
+
+## Why the Fix Works
+
+**Problem Scenario** (Spiral with 200 arcs):
+- Input: 200 arcs forming an inward spiral
+- Old algorithm: For arc i, sequential search found FIRST convex arc after i
+  - Arc 100 → Arc 101 (first convex found, sequential order)
+  - Arc 101 → Arc 102
+  - Follows spiral sequentially, connecting nearby arcs
+  - Result: Hull cuts through interior (not convex!)
+  
+- New algorithm: For arc i, evaluate ALL convex arcs with cross product
+  - Arc 100 → Evaluate all 200 arcs
+  - Calculate cross products to find which makes most left turn
+  - Outer arcs (e.g., 50, 150) have larger left turns than nearby inner arcs
+  - Select the arc with max cross product (most extreme turn)
+  - Result: Hull wraps around exterior (actually convex!)
+
+**Metrics**:
+- Original broken: 222 hull paths (cutting through spiral)
+- Fixed: ~30-50 hull paths (wrapping around exterior)
+- Test passes: All 18 tests, including test_arcline_200
+
+**Why sequential iteration still works**:
+- We iterate through all convex arcs in sequence (prerequisite for closure)
+- But at each arc, we choose the BEST next candidate globally, not locally
+- This ensures the hull boundary follows the convex envelope, not the input sequence
+- The cross product naturally selects outer arcs for a spiral
+
+## Edge Cases Handled
+1. **Empty arcline**: Return empty hull
+2. **Single arc**: Return that arc
+3. **All concave arcs**: Return empty hull (degenerate)
+4. **Line segments in arcline**: Treated as zero-radius arcs, handled by general logic
+5. **Circular shapes**: All arcs convex, hull correctly wraps circumference
+6. **Mixed arcs and segments**: Both contribute to hull boundary