feat: add Graham Scan convex hull algorithm

[AliAlimohammadi]

Description

This PR adds an implementation of the Graham Scan algorithm for computing the convex hull of a set of 2D points to the geometry module.

What is the Graham Scan?

The Graham scan is a classic computational geometry algorithm that finds the convex hull of a finite set of points in the plane. The convex hull is the smallest convex polygon that contains all the points - you can visualize it as stretching a rubber band around the outermost points.

Algorithm Overview:

1. Find the bottom-most point (or left-most in case of a tie) as the anchor
2. Sort all other points by polar angle relative to the anchor
3. Process points in order, maintaining a stack of hull candidates
4. Remove points that would create a clockwise turn (non-convex angle)

Time Complexity: $O(n.log n)$ - dominated by the sorting step
Space Complexity: $O(n)$ - for storing the output hull

Files Added

• geometry/graham_scan.py - Main implementation with Point class and graham_scan() function
• geometry/tests/test_graham_scan.py - Comprehensive test suite

Type of Change

• New algorithm implementation
• Tests added
• Documentation/docstrings included

Checklist

• My code follows the style guidelines of this project (passes ruff linting)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (comprehensive docstrings)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have checked my code and corrected any misspellings

Testing

All tests pass successfully:

# Run the tests
python -m pytest geometry/tests/test_graham_scan.py -v

# Run doctests
python -m doctest geometry/graham_scan.py -v

Test Coverage:

• Edge cases: empty list, single point, two points, duplicate points
• Collinear points (returns empty hull as expected)
• Basic shapes: triangles, rectangles
• Complex shapes: star patterns with interior points
• Points on hull edges (collinear with vertices)
• Different input orderings produce consistent results
• Large point sets (20+ points)

Code Quality

• ✅ Passes ruff linting with zero errors
• ✅ Type hints on all functions and methods
• ✅ Comprehensive docstrings with examples
• ✅ Follows PEP 8 style guide
• ✅ Maximum line length: 88 characters
• ✅ No trailing whitespace

Example Usage

from geometry.graham_scan import Point, graham_scan

# Create a set of points
points = [
    Point(0, 0),
    Point(4, 0),
    Point(4, 3),
    Point(0, 3),
    Point(2, 1.5),  # Interior point
]

# Compute convex hull
hull = graham_scan(points)

# Print hull vertices
for point in hull:
    print(f"({point.x}, {point.y})")

# Output:
# (0.0, 0.0)
# (4.0, 0.0)
# (4.0, 3.0)
# (0.0, 3.0)

References

• Wikipedia: Graham Scan
• Graham, R.L. (1972). "An Efficient Algorithm for Determining the Convex Hull of a Finite Planar Set"
• Computational Geometry: Algorithms and Applications

[algorithms-keeper]

Click here to look at the relevant links ⬇️

🔗 Relevant Links

Repository:

• Contributing guidelines
• Project Euler solution guidelines

Python:

• Formatted string literals (f-strings)
• Type hints
• doctest
• unittest
• pytest

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

---

algorithms-keeper commands and options

algorithms-keeper actions can be triggered by commenting on this PR:

• @algorithms-keeper review to trigger the checks for only added pull request files
• @algorithms-keeper review-all to trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.

NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.

[algorithms-keeper]

Click here to look at the relevant links ⬇️

🔗 Relevant Links

Repository:

• Contributing guidelines
• Project Euler solution guidelines

Python:

• Formatted string literals (f-strings)
• Type hints
• doctest
• unittest
• pytest

Automated review generated by algorithms-keeper. If there's any problem regarding this review, please open an issue about it.

---

algorithms-keeper commands and options

algorithms-keeper actions can be triggered by commenting on this PR:

• @algorithms-keeper review to trigger the checks for only added pull request files
• @algorithms-keeper review-all to trigger the checks for all the pull request files, including the modified files. As we cannot post review comments on lines not part of the diff, this command will post all the messages in one comment.

NOTE: Commands are in beta and so this feature is restricted only to a member or owner of the organization.

[AliAlimohammadi]

@poyea, this is ready to be merged.