Basketball

Basketball is currently supported for the following leagues (in alphabetical order):

• FIBA — Fédération Internationale de Basketball
• NBA — National Basketball Association
• NBA G League
• NCAA — National Collegiate Athletic Association
• NFHS — National Federation of State High Schools
• WNBA — Women's National Basketball Association

Extension of the BaseSurfacePlot class to create a basketball court.

This is a second-level child class of the BaseSurface class, and as such will have access to its attributes and methods. sportypy will ship with pre-defined leagues that will have their own subclass, but a user can manually specify their own court parameters to create a totally-customized court. The court’s features are parameterized by the basic dimensions of the court, which comprise the attributes of the class.

@author: Ross Drucker

class sportypy.surfaces.basketball.BasketballCourt(league_code='', court_updates={}, color_updates={}, rotation=0.0, x_trans=0.0, y_trans=0.0, units='default', **added_features)

A subclass of BaseSurfacePlot to make a generic basketball court.

This allows for the creation of the basketball court in a way that is entirely parameterized by the court’s baseline characteristics.

All attributes should default to 0.0 (if of a numeric type) or an empty string (if of a string type). Customized parameters may be specified via a child class (see below) or by directly specifying all necessary attributes of a valid basketball court. The attributes needed to instantiate a particular league’s surface must be specified in the court_params dictionary. For many leagues, these will be provided in the surface_dimensions.json file in the data/ subdirectory of sportypy.

See the BaseSurfacePlot and BaseSurface class definitions for full details.

league_code

The league for which the plot should be drawn. This is case-insensitive but should be the shortened name of the league (e.g. “National Basketball Association” should be either “NBA” or “nba”). The default is an empty string

Type:

str

rotation_amt

The angle (in degrees) through which to rotate the final plot. The default is 0.0

Type:

float

x_trans

The amount that the x coordinates are to be shifted. By convention, the +``x`` axis extends from the center of the surface towards the right-hand basket when viewing the court in TV view. The default is 0.0

Type:

float

y_trans

The amount that the y coordinates are to be shifted. By convention, the +``y`` axis extends from the center of the surface towards the top of the court when viewing the court in TV view. The default is 0.0

Type:

float

feature_colors

A dictionary of coloring parameters to pass to the plot

Type:

dict

court_params

A dictionary containing the following parameters of the court:

• court_lengthfloat

  The length of the court

• court_widthfloat

  The width of the court

• line_thicknessfloat

  The thickness of the lines of the court in the court’s specified units

• bench_sidestr

  The side, in TV view where the team benches are located

• court_apron_endlinefloat

  The thickness of the court’s apron beyond the endline

• court_apron_sidelinefloat

  The thickness of the court’s apron beyond the sideline

• court_apron_to_boundaryfloat

  The distance from the inner edge of the court apron to the outer edge of the court’s boundary line (sideline and endline will be spaced the same)

• center_circle_radiuslist or float

  The radius (radii) of the court’s center circle(s) in the court’s specified units. These should be measured from the center of the court to the outer edge of the circle. When providing a list (e.g. for the NBA), these values should go in decreasing order

• division_line_extensionfloat

  The distance that the division line extends beyond the sidelines. This may be omitted if the value is 0

• basket_center_to_baselinefloat

  The distance from the center of the basket ring to the inner edge of the baseline

• basket_center_to_three_point_arcfloat

  The distance from the cetner of the basket ring to the outer edge of the arc of the three point line

• basket_center_to_corner_threefloat

  The distance from the center of the basket ring to the outer edge of the three-point line in the corner

• backboard_face_to_baselinefloat

  The distance from the face of the backboard to the inner edge of the baseline

• lane_lengthfloat

  The distance from the inner edge of the baseline to the center-court side of the free-throw lane in the court’s specified units in TV view

• lane_widthfloat

  The distance from the outer edges of the free-throw lane when viewing the court in TV view

• paint_marginfloat

  The distance from the painted area of the lane to the lane boundary lines

• free_throw_circle_radiusfloat

  The radius of the free-throw circle, measured from the center of the free-throw line, given

• free_throw_line_to_backboardfloat

  The distance from the free-throw line to the face of the backboard

• free_throw_circle_overhangfloat

  The arc length of any part of the free-throw circle that extends beyond the free-throw line

• n_free_throw_circle_dashesfloat

  The number of dashes that comprise the free-throw circle

• free_throw_dash_lengthfloat

  The arc length of each dash of the free-throw circle

• free_throw_dash_spacingfloat

  The arc length of the gap between each dash of the free-throw circle

• lane_space_mark_lengthsfloat or list of either lists or floats

  The length (measurement in the baseline-to-free-throw-line direction) of lane space marks (blocks) of the free-throw lane

• lane_space_mark_widthsfloat or list of either lists or floats

  The widths (measurement in the sideline-to-sideline direction) of the lane space marks (blocks) of the free-throw lane in the court’s specified units

• lane_space_mark_separationsfloat or list of either lists or floats

  The separations between each lane space mark in the court’s specified dimensions. The first “spacing” measurement corresponds to the distance between the face of the backboard and the baseline-side edge of the first/”low” block

• painted_area_visibilitybool or list of bools

  Whether or not to show the painted area. This is particularly useful if more than one free-throw lane is specified (e.g. an NBA court with an NCAA lane drawn in addition to the NBA-sized lane)

• lane_boundary_visibilitybool or list of bools

  Whether or not to show the lane boundary. This is particularly useful if more than one free-throw lane is specified (e.g. an NBA court with an NCAA lane drawn in addition to the NBA-sized lane)

Type:

dict

• lane_space_mark_visibilitybool or list of bools

  Whether or not to draw the lane space marks. This is particularly useful if more than one free-throw lane is specified (e.g. an NBA court with an NCAA lane drawn in addition to the NBA-sized lane)

• lane_lower_defensive_box_marks_visibilitybool or list of bools

  Whether or not to draw the lower defensive box markings that appear in the free-throw lane/painted area

• baseline_lower_defensive_box_marks_int_sepfloat

  The interior separation between the lower defensive box markings on the baseline

• baseline_to_lane_lower_defensive_box_marksfloat

  The interior distance from the inner edge of the baseline to the baseline-side edge of the lower defensive box markings located in the free-throw lane/painted area

• lane_lower_defensive_box_marks_int_sepfloat

  The interior separation between the lower defensive box markings in the free-throw lane/painted area

• lower_defensive_box_mark_extensionfloat

  The distance that the lower defensive box markings extend from their anchor points

• inbounding_line_to_baselinefloat

  The interior distance from the inner edge of the baseline to the baseline-side edge of the inbounding line in the court’s specified units

• inbounding_line_anchor_sidefloat

  The side where the primary inbounding lines are located. This should be either 1.0 or -1.0, corresponding to the top or bottom of the court in TV view, respectively

• inbounding_line_in_play_extfloat

  The distance into the court (measured from the inner edge of the sideline) that the inbounding lines protrude into the court

• inbounding_line_out_of_bounds_extfloat

  The distance away from the court (measured from the outer edge of the sideline) that the inbounding lines protrude away the court

• symmetric_inbounding_linebool

  Whether or not the inbounding lines are symmetric about the court

• substitution_line_ext_sepfloat

  The external separation of the lines marking the substitution area

• substitution_line_widthfloat

  The distance away from the court (measured from the outer edge of the sideline) that the substitution lines protrude away from the court

• team_bench_line_extfloat

  The distance that the team bench line extends from its anchor point

• restricted_arc_radiusfloat

  The inner radius of the restricted arc in the court’s specified units

• backboard_widthfloat

  The distance the backboard spans across the lane in the court’s specified units. This is the left-to-right dimension of the backboard a free-throw shooter would see when shooting their free-throws

• backboard_thicknessfloat

  The thickness of the backboard. This is the observed thickness when viewing the court from a bird’s eye view

• basket_ring_inner_radiusfloat

  The inner radius of the basket ring

• basket_ring_connector_widthfloat

  The dimension of the piece of the basket ring that connects the backboard to the basket ring. When viewing the court in TV view from above, this is the dimension in the y direction

• basket_ring_connector_extensionfloat

  The distance the basket ring’s connector extends from the backboard into the free-throw lane

• basket_ring_thicknessfloat

  The thickness of the basket ring

cani_change_dimensions()

Determine what features of the court can be re-parameterized.

This function is a helper function for the user to aid in customizing a court’s parameters. The printed result of this method will be the names of the features that are able to be reparameterized. This method is also useful when defining new features and using an existing league’s court dimensions as a starting point

Return type:

Nothing, but a message will be printed out

cani_color_features()

Determine what features of the court can be colored.

This function is a helper function for the user to aid in plot styling and customization. The printed result of this method will be the names of the features that are able to be colored

Return type:

Nothing, but a message will be printed out

cani_plot_leagues(league_code=None)

Show if a league can be plotted, or what leagues are pre-defined.

A user may wish to know if a specific basketball league can be plotted. This method allows a user to check if that specific league code comes shipped with sportypy for easier plotting (if they provide the league code), or can also show what leagues are available to be plotted

Parameters:

league_code (str or None) – A league code that may or may not be shipped with the package. If the league code is None, this will display all leagues that do come shipped with sportypy. The default is None

Return type:

Nothing, but a message will be printed out

draw(ax=None, display_range='full', xlim=None, ylim=None, rotation=None)

Draw the court.

Parameters:

• ax (matplotlib.Axes) – An Axes object onto which the plot can be drawn. If None is supplied, then the currently-active Axes object will be used

• display_range (str, optional) –

  The portion of the surface to display. The entire surface will always be drawn under the hood, however this parameter limits what is shown in the final plot. The following explain what each display range corresponds to:

  • "full": The entire court

  • "in bounds only": The full in-bound area of the court

  • "in_bounds_only": The full in-bound area of the court

  • "offense": The attacking/offensive half court

  • "offence": The attacking/offensive half court

  • "offensivehalfcourt": The attacking/offensive half court

  • "offensive_half_court": The attacking/offensive half

    court

  • "offensive half court": The attacking/offensive half

    court

  • "defense": The defensive half court

  • "defence": The defensive half court

  • "defensivehalfcourt": The defensive half court

  • "defensive_half_court": The defensive half court

  • "defensive half court": The defensive half court

  • "offensivekey": The attacking/offensive key

  • "offensive_key": The attacking/offensive key

  • "offensive key": The attacking/offensive key

  • "attackingkey": The attacking/offensive key

  • "attacking_key": The attacking/offensive key

  • "attacking key": The attacking/offensive key

  • "defensivekey": The defensive key

  • "defensive_key": The defensive key

  • "defensive key": The defensive key

  • "defendingkey": The defensive key

  • "defending_key": The defensive key

  • "offensivepaint": The attacking/offensive painted area

  • "offensive_paint": The attacking/offensive painted area

  • "attackingpaint": The attacking/offensive painted area

  • "attacking_paint": The attacking/offensive painted area

  • "offensivelane": The attacking/offensive painted area

  • "offensive_lane": The attacking/offensive painted area

  • "offensive lane": The attacking/offensive painted area

  • "attackinglane": The attacking/offensive painted area

  • "attacking_lane": The attacking/offensive painted area

  • "attacking lane": The attacking/offensive painted area

  • "defensivepaint": The defensive painted area

  • "defensive_paint": The defensive painted area

  • "defendingpaint": The defensive painted area

  • "defending_paint": The defensive painted area

  • "defensivelane": The defensive painted area

  • "defendinglane": The defensive painted area

  • "defending_lane": The defensive painted area

  • "defending lane": The defensive painted area

  The default is "full"

• xlim (float or tuple of floats or None) – The display range in the x direction to be used. If a single float is provided, this will be used as the lower bound of the x coordinates to display and the upper bound will be the +``x`` end of the court. If a tuple, the two values will be used to determine the bounds. If None, then the display_range will be used instead to set the bounds. The default is None

• ylim (float or tuple of floats or None) – The display range in the y direction to be used. If a single float is provided, this will be used as the lower bound of the y coordinates to display and the upper bound will be the +``y`` side of the court. If a tuple, the two values will be used to determine the bounds. If None, then the display_range will be used instead to set the bounds. The default is None

• rotation (float or None) – Angle (in degrees) through which to rotate the court when drawing. If used, this will set the class attribute of _rotation. A value of 0.0 will correspond to a TV view of the court, where +``x`` is to the right and +``y`` is on top. The rotation occurs counterclockwise. The default is None

reset_colors()

Reset the features of the court to their default color set.

The colors can be passed at the initial instantiation of the class via the color_updates parameter, and through the update_colors() method, these can be changed. This method allows the colors to be reset to their default values after experiencing such a change

reset_court_params()

Reset the features of the court to their default parameterizations.

The court parameters can be passed at the initial instantiation of the class via the court_updates parameter, and through the update_court_params() method, these can be changed. This method allows the feature parameterization to be reset to their default values after experiencing such a change

update_colors(color_updates={}, *args, **kwargs)

Update the colors currently used in the plot.

The colors can be passed at the initial instantiation of the class via the color_updates parameter, but this method allows the colors to be updated after the initial instantiation and will re-instantiate the class with the new colors

Parameters:

color_updates (dict) – A dictionary where the keys correspond to the name of the feature that’s color is to be updated (see cani_color_features() method for a list of these names). The default is an empty dictionary

Return type:

Nothing, but the class is re-instantiated with the updated colors

update_court_params(court_param_updates={}, *args, **kwargs)

Update the court’s defining parameters.

This method should primarily be used in cases when plotting a league not currently supported by sportypy

Parameters:

court_updates (dict) – A dictionary where the keys correspond to the name of the parameter of the court that is to be updated (see cani_change_dimensions() method for a list of these parameters). The default is an empty dictionary

Return type:

Nothing, but the class is re-instantiated with the updated parameters