Document kerb generation logic with ABCDE points system in algorithm description

[Copilot]

The main algorithm documentation was missing a crucial section describing the kerb generation logic, which is an important part of the crossing generation process. This PR adds comprehensive documentation for the sophisticated ABCDE points system used to create accurate kerb positions at street crossings.

What was added

The documentation now includes a detailed section on Kerb Generation Logic (ABCDE Points System) that covers:

Point Definition System

• Point A: Intersection of crossing line with sidewalk geometry (side I)
• Point B: Kerb position at side I (interpolated along segment A-C)
• Point C: Intersection of crossing line with street geometry (crossing center)
• Point D: Kerb position at side II (interpolated along segment E-C)
• Point E: Intersection of crossing line with sidewalk geometry (side II)

Iterative Algorithm Details

The documentation explains how the two_intersections_byvector_with_sidewalks method works:

1. Vector Projection: Starting from point C, vectors are projected in both directions to find sidewalk intersections
2. Iterative Scaling: Vector lengths are doubled when intersections aren't found initially
3. Distance Validation: Crossing lengths are validated against expected street width plus tolerance
4. Adaptive Center Repositioning: Center point C is moved incrementally inward when crossings are too long
5. Quality Control: Maximum iterations and absolute length limits prevent infinite loops and unrealistic crossings

Implementation Parameters

All relevant parameters are documented with their default values:

• increment_inward = 0.5m: Distance increment for center point adjustment
• max_crossings_iterations = 20: Maximum attempts to find valid crossing geometry
• abs_max_crossing_len = 100m: Absolute crossing length limit
• perc_draw_kerbs = 30%: Percentage along A-C and E-C segments for kerb placement
• perc_tol_crossings = 25%: Tolerance for crossing length validation

Why this matters

This documentation fills a significant gap in the algorithm description, providing developers and users with a complete understanding of how kerbs are generated. The ABCDE points system is a sophisticated part of the codebase that handles complex geometric calculations for creating realistic street crossings with proper kerb placement.

The implementation referenced is found in osm_sidewalkreator.py around line 1552, where the detailed comment already outlined the ABCDE points concept, but this knowledge was not accessible in the main documentation.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.