#19 - Add basketball pass lines

[apradillap]

Summary

Released in v1.1.0 — Adds a new Lines function to mplbasketball for drawing lines (#19) on basketball courts, adapted from mplsoccer’s LineCollection but tailored for basketball visualizations.

Features Added

• Lines function: Draw lines on basketball courts with various visual effects
• Special effects: Comet lines (increasing width), transparent lines (increasing opacity), colormap lines
• Coordinate transformation: Support for all court orientations and coordinate systems
• Basketball-specific applications: Pass visualization, player movement tracking
• Comprehensive testing: 12 test cases covering all functionality
• Documentation: Complete usage guide integrated in README.md

Key Features

• Multiple line types: Basic lines, comet lines, transparent lines, colormap lines
• Coordinate system support: Works with all court types (NBA, WNBA, NCAA, FIBA)
• Orientation support: Full court, half-court, vertical orientations
• Visual effects:
  • Comet effect (lines that increase in width)
  • Transparency gradients (lines that increase in opacity)
  • Colormap integration
  • Combined effects (comet + transparent)
• Error handling: Comprehensive validation and error messages
• Performance optimized: Uses matplotlib's LineCollection for efficient rendering

Files Added/Modified

• mplbasketball/lines.py - New Lines functionality
• mplbasketball/__init__.py - Updated to include Lines
• examples/plot_lines.py - Example demonstrating Lines usage
• tests/test_lines.py - Comprehensive test suite
• README.md - Updated with Lines documentation

Example Usage

from mplbasketball import Court, Lines

court = Court(court_type="nba", origin="center")
fig, ax = court.draw(orientation="h")

# Basic line
Lines(0, 0, 20, 20, color="red", linewidth=3, ax=ax)

# Comet line (increasing width)
Lines(-40, 25, 40, -25, comet=True, color="blue", linewidth=8, ax=ax)

# Transparent line (increasing opacity)
Lines(-35, -20, 35, 20, transparent=True, color="green", 
      alpha_start=0.1, alpha_end=1.0, linewidth=6, ax=ax)

Testing

• All 12 tests pass successfully
• Covers basic functionality, special effects, coordinate transformation, error handling
• Validates parameter types, array sizes, and incompatible combinations

Breaking Changes

None - this is a new feature addition that doesn't affect existing functionality.

Dependencies

• No new dependencies added
• Uses existing matplotlib and numpy functionality
• Compatible with current mplbasketball architecture

Documentation

• Complete documentation added to README.md
• Examples for all major use cases
• Parameter reference and basketball-specific applications
• Positioned logically after matplotlib integration examples

[apradillap]

Hi @sreekar-voleti @ojadeyemi! When you have a moment, could you review my PR? Thanks a lot!

[ojadeyemi]

I tested the logic, and it looks like it works just fine.

[apradillap]

Fingers crossed this PR gets approved soon by @sreekar-voleti!! I'd reaaly like to take it further and maybe write a paper for a sports conference., it would be great to give this work some extra visibility. Thanks Sreekar!!