feat: add Jarvis March (Gift Wrapping) convex hull algorithm

[AliAlimohammadi]

Description

This PR adds an implementation of the Jarvis March algorithm (also known as the Gift Wrapping algorithm) for computing the convex hull of a set of 2D points.

The convex hull is the smallest convex polygon that contains all given points. The Jarvis March algorithm is an output-sensitive algorithm with time complexity $O(n·h)$, where $n$ is the number of input points and $h$ is the number of points on the convex hull.

What's Included

• jarvis_march.py: Complete implementation in the geometry directory
• Point class: Represents 2D coordinates
• Helper functions: Cross product calculation and point-on-segment detection
• Comprehensive doctests: 33 tests covering various scenarios including:
  • Simple shapes (triangles, rectangles)
  • Complex shapes (star patterns)
  • Edge cases (collinear points, duplicate points, too few points)
  • Interior points exclusion

Algorithm Details

• Time Complexity: $O(n·h)$ where $n$ is the number of points and $h$ is the hull size
• Space Complexity: $O(h)$ for storing hull points
• Approach:
  1. Find the leftmost point as the starting point
  2. Iteratively select the most counter-clockwise point from the current point
  3. Handle collinear points to avoid adding unnecessary vertices
  4. Return empty list for degenerate cases (< 3 non-collinear points)

Testing

All doctests pass successfully:

$ python jarvis_march.py -v
33 tests in 9 items.
33 passed and 0 failed.
Test passed.

References

• Wikipedia: Gift wrapping algorithm
• GeeksforGeeks: Jarvis Algorithm

Checklist

• Code follows the repository's style guidelines
• Comprehensive docstrings with examples
• All doctests pass
• Type hints included
• Algorithm has proper documentation with complexity analysis
• No duplicate of existing algorithms in the repository

[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.