Skip to main content
Version: main

surface

surface(
league: str,
team: Any = None,
*,
season: Any = None,
ax: Any = None,
center_logo: bool | float = False,
**sportypy_kwargs: Any,
) -> Any

Draw the league's playing surface with sportypy, in a team's colors.

Arguments​

NameTypeDescription
leaguestrThe SDV surface key: a team league ("nfl", "nba", "nhl", "pwhl", "cfb", "mlb", "ncaa_softball", "cfl", the national teams' "fiba" and "iihf", "soccer" (a 105 x 68 m pitch, the frame pitch_coords() returns), ...) or a surface without team identities ("fifa", "epl", "little_league", the lacrosse "nll", "pll", "ncaa_mlacrosse", the tennis "atp", "wta", "ncaa_tennis", the volleyball "fivb", "ncaa_volleyball", the curling "wcf", "curling_canada", ...). Every sportyR surface has a key; an unknown one lists them.
teamAnyA team to color the surface by (end zones, lane and apron, center line and boards; baseball, softball and soccer stay in their regulation colors, so the team shows through center_logo); None for the plain surface. Only for a key that is an SDV team league.
seasonAnyThe season, for teams whose colors changed.
axAnyThe matplotlib Axes to draw on; None makes a new figure.
center_logobool | floatTrue to draw the team's logo at center ice / court / field (0.25 of the Axes height), or a height fraction. A baseball or softball field's origin is home plate, so there the logo goes in shallow center field, as in sdvplotR: at x = 0, midway between second base (baseline_distance * sqrt(2)) and the center-field fence, 0.15 x center_field_distance across (True; a fraction still sets the height), from the league's field parameters and field_updates. On grass (football, soccer, baseball, softball) the logo is the team's dark-background variant, as in sdvplotR.
**sportypy_kwargsAnyPassed to sportypy: display_range, xlim, ylim and rotation go to draw(); the rest (field_updates, color_updates, units, ...) to the surface class. sportypy's x_trans / y_trans only shift the data plotted through sportypy's own surface methods onto the drawn surface; they do not move the surface or its center logo (unlike sportyR and sdvplotR, where they move the surface), so data drawn on the returned Axes must be in the surface's own frame.

Returns​

matplotlib.axes.Axes — The Axes sportypy drew on.

Raises​

  • InputError: (a ValueError) If sportypy has no surface for league, or team is given for a key without team identities; and, when team is given, if season is not a year or is outside the seasons sdvplot knows for the league, or center_logo is a height outside (0, 1]. Without team, season and center_logo are not used.
  • OptionalDependencyError: If the surfaces extra (sportypy 1.2 or newer) is not installed, or team and center_logo are set and the team's logo is an SVG without the svg extra.
  • OfflineError: If team and center_logo are set and the logo manifest or the team's logo is neither cached nor downloadable (a DownloadError, also an OSError, when the CDN answers with an error status; an IntegrityError when it sends a file that does not match the manifest's sha256, or one PIL cannot decode).
  • UnsafeDownloadError: (an OSError) If team and center_logo are set and a download is refused: larger than the byte cap, past the deadline, or redirected away from https.
  • UnsafeCachePathError: (a ValueError) If team and center_logo are set and the manifest's sha256 or extension for the logo would put the file outside the cache directory.

Example​

import sdvplot

ax = sdvplot.surface("nfl", "KC", center_logo=True)

See also​

Surface keys​

The 59 keys league takes, in sdvplot._surface.SURFACES' order: the sport, the sportypy class drawn, and whether the key is an SDV team league, which takes a team (its colors on a basketball court, football field or hockey rink, and its logo through center_logo); a key that is not refuses one. sdvplotR's surface_map and sdvplot-js's surfaces.ts use the same keys.

KeySportsportypy classTakes a team
nflfootballsportypy.surfaces.football.NFLFieldyes
aaffootballsportypy.surfaces.football.NFLFieldyes
uflfootballsportypy.surfaces.football.NFLFieldyes
usflfootballsportypy.surfaces.football.NFLFieldyes
xflfootballsportypy.surfaces.football.NFLFieldyes
cfbfootballsportypy.surfaces.football.NCAAFieldyes
cflfootballsportypy.surfaces.football.CFLFieldyes
nfhs_footballfootballsportypy.surfaces.football.NFHSFieldno
nbabasketballsportypy.surfaces.basketball.NBACourtyes
nbaglbasketballsportypy.surfaces.basketball.NBAGLeagueCourtyes
wnbabasketballsportypy.surfaces.basketball.WNBACourtyes
mbbbasketballsportypy.surfaces.basketball.NCAACourtyes
wbbbasketballsportypy.surfaces.basketball.NCAACourtyes
fibabasketballsportypy.surfaces.basketball.FIBACourtyes
nfhs_basketballbasketballsportypy.surfaces.basketball.NFHSCourtno
mlbbaseballsportypy.surfaces.baseball.MLBFieldyes
milbbaseballsportypy.surfaces.baseball.MiLBFieldyes
ncaa_baseballbaseballsportypy.surfaces.baseball.NCAAFieldyes
little_leaguebaseballsportypy.surfaces.baseball.LittleLeagueFieldno
ponybaseballsportypy.surfaces.baseball.PonyFieldno
nfhs_baseballbaseballsportypy.surfaces.baseball.NFHSFieldno
ncaa_softballsoftballsportypy.surfaces.softball.NCAASoftballFieldyes
nhlhockeysportypy.surfaces.hockey.NHLRinkyes
whlhockeysportypy.surfaces.hockey.NHLRinkyes
pwhlhockeysportypy.surfaces.hockey.PWHLRinkyes
ahlhockeysportypy.surfaces.hockey.AHLRinkyes
echlhockeysportypy.surfaces.hockey.ECHLRinkyes
ohlhockeysportypy.surfaces.hockey.OHLRinkyes
qmjhlhockeysportypy.surfaces.hockey.QMJHLRinkyes
ushlhockeysportypy.surfaces.hockey.USHLRinkyes
phfhockeysportypy.surfaces.hockey.PHFRinkyes
iihfhockeysportypy.surfaces.hockey.IIHFRinkyes
nwhlhockeysportypy.surfaces.hockey.NWHLRinkno
ncaa_mhockeyhockeysportypy.surfaces.hockey.NCAARinkyes
ncaa_whockeyhockeysportypy.surfaces.hockey.NCAARinkyes
soccersoccersportypy.surfaces.soccer.FIFAPitchyes
fifasoccersportypy.surfaces.soccer.FIFAPitchno
eplsoccersportypy.surfaces.soccer.EPLPitchno
mlssoccersportypy.surfaces.soccer.MLSPitchno
nwslsoccersportypy.surfaces.soccer.NWSLPitchno
ncaa_soccersoccersportypy.surfaces.soccer.NCAAPitchno
nlllacrossesportypy.surfaces.lacrosse.NLLFieldno
plllacrossesportypy.surfaces.lacrosse.PLLFieldno
world_lacrosselacrossesportypy.surfaces.lacrosse.WorldLacrosseFieldno
ncaa_mlacrosselacrossesportypy.surfaces.lacrosse.NCAAMLacrosseFieldno
ncaa_wlacrosselacrossesportypy.surfaces.lacrosse.NCAAWLacrosseFieldno
usa_mlacrosselacrossesportypy.surfaces.lacrosse.USAMLacrosseFieldno
usa_wlacrosselacrossesportypy.surfaces.lacrosse.USAWLacrosseFieldno
atptennissportypy.surfaces.tennis.ATPCourtno
wtatennissportypy.surfaces.tennis.WTACourtno
itftennissportypy.surfaces.tennis.ITFCourtno
itatennissportypy.surfaces.tennis.ITACourtno
ustatennissportypy.surfaces.tennis.USTACourtno
ncaa_tennistennissportypy.surfaces.tennis.NCAACourtno
fivbvolleyballsportypy.surfaces.volleyball.FIVBCourtno
usa_volleyballvolleyballsportypy.surfaces.volleyball.USAVolleyballCourtno
ncaa_volleyballvolleyballsportypy.surfaces.volleyball.NCAACourtno
wcfcurlingsportypy.surfaces.curling.WCFSheetno
curling_canadacurlingsportypy.surfaces.curling.CurlingCanadaSheetno