1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530
|
# (C) British Crown Copyright 2014 - 2020, Met Office
#
# This file is part of cartopy.
#
# cartopy is free software: you can redistribute it and/or modify it under
# the terms of the GNU Lesser General Public License as published by the
# Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# cartopy is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with cartopy. If not, see <https://www.gnu.org/licenses/>.
"""This module contains tools for handling tick marks in cartopy."""
from __future__ import (absolute_import, division, print_function)
import numpy as np
from matplotlib.ticker import Formatter, MaxNLocator
import cartopy.crs as ccrs
from cartopy.mpl.geoaxes import GeoAxes
class _PlateCarreeFormatter(Formatter):
"""
Base class for formatting ticks on geographical axes using a
rectangular projection (e.g. Plate Carree, Mercator).
"""
_target_projection = ccrs.PlateCarree()
def __init__(self, degree_symbol=u'\u00B0', number_format='g',
transform_precision=1e-8, dms=False,
minute_symbol=u"'", second_symbol=u"''",
seconds_number_format='g',
auto_hide=True):
"""
Base class for simpler implementation of specialised formatters
for latitude and longitude axes.
"""
self._degree_symbol = degree_symbol
self._degrees_number_format = number_format
self._transform_precision = transform_precision
self._dms = dms
self._minute_symbol = minute_symbol
self._second_symbol = second_symbol
self._seconds_num_format = seconds_number_format
self._auto_hide = auto_hide
self._auto_hide_degrees = False
self._auto_hide_minutes = False
self._precision = 5 # locator precision
def __call__(self, value, pos=None):
if self.axis is not None and isinstance(self.axis.axes, GeoAxes):
# We want to produce labels for values in the familiar Plate Carree
# projection, so convert the tick values from their own projection
# before formatting them.
source = self.axis.axes.projection
if not isinstance(source, (ccrs._RectangularProjection,
ccrs.Mercator)):
raise TypeError("This formatter cannot be used with "
"non-rectangular projections.")
projected_value = self._apply_transform(value,
self._target_projection,
source)
# Round the transformed value using a given precision for display
# purposes. Transforms can introduce minor rounding errors that
# make the tick values look bad, these need to be accounted for.
f = 1. / self._transform_precision
projected_value = round(f * projected_value) / f
else:
# There is no projection so we assume it is already PlateCarree
projected_value = value
# Return the formatted values, the formatter has both the re-projected
# tick value and the original axis value available to it.
return self._format_value(projected_value, value)
def _format_value(self, value, original_value):
hemisphere = self._hemisphere(value, original_value)
if not self._dms:
return (self._format_degrees(abs(value)) +
hemisphere)
value, deg, mn, sec = self._get_dms(abs(value))
# Format
label = u''
if sec:
label = self._format_seconds(sec)
if mn or (not self._auto_hide_minutes and label):
label = self._format_minutes(mn) + label
if not self._auto_hide_degrees or not label:
label = self._format_degrees(deg) + hemisphere + label
return label
def _get_dms(self, x):
"""Convert to degrees, minutes, seconds
Parameters
----------
x: float or array of floats
Degrees
Return
------
x: degrees rounded to the requested precision
degs: degrees
mins: minutes
secs: seconds
"""
self._precision = 6
x = np.asarray(x, 'd')
degs = np.round(x, self._precision).astype('i')
y = (x - degs) * 60
mins = np.round(y, self._precision).astype('i')
secs = np.round((y - mins)*60, self._precision - 3)
return x, degs, mins, secs
def set_locs(self, locs):
Formatter.set_locs(self, locs)
if not self._auto_hide:
return
self.locs, degs, mins, secs = self._get_dms(self.locs)
secs = np.round(secs, self._precision-3).astype('i')
secs0 = secs == 0
mins0 = mins == 0
def auto_hide(valid, values):
"""Should I switch on auto_hide?"""
if not valid.any():
return False
if valid.sum() == 1:
return True
return np.diff(values.compress(valid)).max() == 1
# Potentially hide minutes labels when pure minutes are all displayed
self._auto_hide_minutes = auto_hide(secs0, mins)
# Potentially hide degrees labels when pure degrees are all displayed
self._auto_hide_degrees = auto_hide(secs0 & mins0, degs)
def _format_degrees(self, deg):
"""Format degrees as an integer"""
if self._dms:
deg = int(deg)
number_format = 'd'
else:
number_format = self._degrees_number_format
return u'{value:{number_format}}{symbol}'.format(
value=abs(deg),
number_format=number_format,
symbol=self._degree_symbol)
def _format_minutes(self, mn):
"""Format minutes as an integer"""
return u'{value:d}{symbol}'.format(
value=int(mn),
symbol=self._minute_symbol)
def _format_seconds(self, sec):
"""Format seconds as an float"""
return u'{value:{fmt}}{symbol}'.format(
value=sec,
fmt=self._seconds_num_format,
symbol=self._second_symbol)
def _apply_transform(self, value, target_proj, source_crs):
"""
Given a single value, a target projection and a source CRS,
transform the value from the source CRS to the target
projection, returning a single value.
"""
raise NotImplementedError("A subclass must implement this method.")
def _hemisphere(self, value, value_source_crs):
"""
Given both a tick value in the Plate Carree projection and the
same value in the source CRS, return a string indicating the
hemisphere that the value is in.
Must be over-ridden by the derived class.
"""
raise NotImplementedError("A subclass must implement this method.")
class LatitudeFormatter(_PlateCarreeFormatter):
"""Tick formatter for latitude axes."""
def __init__(self, degree_symbol=u'\u00B0', number_format='g',
transform_precision=1e-8, dms=False,
minute_symbol=u"'", second_symbol=u"''",
seconds_number_format='g', auto_hide=True,
):
"""
Tick formatter for latitudes.
When bound to an axis, the axis must be part of an axes defined
on a rectangular projection (e.g. Plate Carree, Mercator).
Parameters
----------
degree_symbol: optional
The character(s) used to represent the degree symbol in the
tick labels. Defaults to u'\u00B0' which is the unicode
degree symbol. Can be an empty string if no degree symbol is
desired.
number_format: optional
Format string to represent the longitude values when `dms`
is set to False. Defaults to 'g'.
transform_precision: optional
Sets the precision (in degrees) to which transformed tick
values are rounded. The default is 1e-7, and should be
suitable for most use cases. To control the appearance of
tick labels use the *number_format* keyword.
dms: bool, optional
Wether or not formatting as degrees-minutes-seconds and not
as decimal degrees.
minute_symbol: str, optional
The character(s) used to represent the minute symbol.
second_symbol: str, optional
The character(s) used to represent the second symbol.
seconds_number_format: optional
Format string to represent the "seconds" component of the longitude
values. Defaults to 'g'.
auto_hide: bool, optional
Auto-hide degrees or minutes when redundant.
Note
----
A formatter can only be used for one axis. A new formatter
must be created for every axis that needs formatted labels.
Examples
--------
Label latitudes from -90 to 90 on a Plate Carree projection::
ax = plt.axes(projection=PlateCarree())
ax.set_global()
ax.set_yticks([-90, -60, -30, 0, 30, 60, 90],
crs=ccrs.PlateCarree())
lat_formatter = LatitudeFormatter()
ax.yaxis.set_major_formatter(lat_formatter)
Label latitudes from -80 to 80 on a Mercator projection, this
time omitting the degree symbol::
ax = plt.axes(projection=Mercator())
ax.set_global()
ax.set_yticks([-90, -60, -30, 0, 30, 60, 90],
crs=ccrs.PlateCarree())
lat_formatter = LatitudeFormatter(degree_symbol='')
ax.yaxis.set_major_formatter(lat_formatter)
When not bound to an axis::
lat_formatter = LatitudeFormatter()
ticks = [-90, -60, -30, 0, 30, 60, 90]
lat_formatter.set_locs(ticks)
labels = [lat_formatter(value) for value in ticks]
"""
super(LatitudeFormatter, self).__init__(
degree_symbol=degree_symbol,
number_format=number_format,
transform_precision=transform_precision,
dms=dms,
minute_symbol=minute_symbol,
second_symbol=second_symbol,
seconds_number_format=seconds_number_format,
auto_hide=auto_hide,
)
def _apply_transform(self, value, target_proj, source_crs):
return target_proj.transform_point(0, value, source_crs)[1]
def _hemisphere(self, value, value_source_crs):
if value > 0:
hemisphere = 'N'
elif value < 0:
hemisphere = 'S'
else:
hemisphere = ''
return hemisphere
class LongitudeFormatter(_PlateCarreeFormatter):
"""Tick formatter for a longitude axis."""
def __init__(self,
zero_direction_label=False,
dateline_direction_label=False,
degree_symbol=u'\u00B0',
number_format='g',
transform_precision=1e-8,
dms=False,
minute_symbol=u"'",
second_symbol=u"''",
seconds_number_format='g',
auto_hide=True,
):
"""
Create a formatter for longitudes.
When bound to an axis, the axis must be part of an axes defined
on a rectangular projection (e.g. Plate Carree, Mercator).
Parameters
----------
zero_direction_label: optional
If *True* a direction label (E or W) will be drawn next to
longitude labels with the value 0. If *False* then these
labels will not be drawn. Defaults to *False* (no direction
labels).
dateline_direction_label: optional
If *True* a direction label (E or W) will be drawn next to
longitude labels with the value 180. If *False* then these
labels will not be drawn. Defaults to *False* (no direction
labels).
degree_symbol: optional
The symbol used to represent degrees. Defaults to u'\u00B0'
which is the unicode degree symbol.
number_format: optional
Format string to represent the latitude values when `dms`
is set to False. Defaults to 'g'.
transform_precision: optional
Sets the precision (in degrees) to which transformed tick
values are rounded. The default is 1e-7, and should be
suitable for most use cases. To control the appearance of
tick labels use the *number_format* keyword.
dms: bool, optional
Wether or not formatting as degrees-minutes-seconds and not
as decimal degrees.
minute_symbol: str, optional
The character(s) used to represent the minute symbol.
second_symbol: str, optional
The character(s) used to represent the second symbol.
seconds_number_format: optional
Format string to represent the "seconds" component of the latitude
values. Defaults to 'g'.
auto_hide: bool, optional
Auto-hide degrees or minutes when redundant.
Note
----
A formatter can only be used for one axis. A new formatter
must be created for every axis that needs formatted labels.
Examples
--------
Label longitudes from -180 to 180 on a Plate Carree projection
with a central longitude of 0::
ax = plt.axes(projection=PlateCarree())
ax.set_global()
ax.set_xticks([-180, -120, -60, 0, 60, 120, 180],
crs=ccrs.PlateCarree())
lon_formatter = LongitudeFormatter()
ax.xaxis.set_major_formatter(lon_formatter)
Label longitudes from 0 to 360 on a Plate Carree projection
with a central longitude of 180::
ax = plt.axes(projection=PlateCarree(central_longitude=180))
ax.set_global()
ax.set_xticks([0, 60, 120, 180, 240, 300, 360],
crs=ccrs.PlateCarree())
lon_formatter = LongitudeFormatter()
ax.xaxis.set_major_formatter(lon_formatter)
When not bound to an axis::
lon_formatter = LongitudeFormatter()
ticks = [0, 60, 120, 180, 240, 300, 360]
lon_formatter.set_locs(ticks)
labels = [lon_formatter(value) for value in ticks]
"""
super(LongitudeFormatter, self).__init__(
degree_symbol=degree_symbol,
number_format=number_format,
transform_precision=transform_precision,
dms=dms,
minute_symbol=minute_symbol,
second_symbol=second_symbol,
seconds_number_format=seconds_number_format,
auto_hide=auto_hide,
)
self._zero_direction_labels = zero_direction_label
self._dateline_direction_labels = dateline_direction_label
def _apply_transform(self, value, target_proj, source_crs):
return target_proj.transform_point(value, 0, source_crs)[0]
@classmethod
def _fix_lons(cls, lons):
if isinstance(lons, list):
return [cls._fix_lons(lon) for lon in lons]
p180 = lons == 180
m180 = lons == -180
# Wrap
lons = ((lons + 180) % 360) - 180
# Keep -180 and 180 when requested
for mp180, value in [(m180, -180), (p180, 180)]:
if np.any(mp180):
if isinstance(lons, np.ndarray):
lons = np.where(mp180, value, lons)
else:
lons = value
return lons
def set_locs(self, locs):
_PlateCarreeFormatter.set_locs(self, self._fix_lons(locs))
def _format_degrees(self, deg):
return _PlateCarreeFormatter._format_degrees(self, self._fix_lons(deg))
def _hemisphere(self, value, value_source_crs):
value = self._fix_lons(value)
# Perform basic hemisphere detection.
if value < 0:
hemisphere = 'W'
elif value > 0:
hemisphere = 'E'
else:
hemisphere = ''
# Correct for user preferences:
if value == 0 and self._zero_direction_labels:
# Use the original tick value to determine the hemisphere.
if value_source_crs < 0:
hemisphere = 'E'
else:
hemisphere = 'W'
if value in (-180, 180) and not self._dateline_direction_labels:
hemisphere = ''
return hemisphere
class LongitudeLocator(MaxNLocator):
"""
A locator for longitudes that works even at very small scale.
Parameters
----------
dms: bool
Allow the locator to stop on minutes and seconds (False by default)
"""
default_params = MaxNLocator.default_params.copy()
default_params.update(nbins=8, dms=False)
def set_params(self, **kwargs):
"""Set parameters within this locator."""
if 'dms' in kwargs:
self._dms = kwargs.pop('dms')
MaxNLocator.set_params(self, **kwargs)
def _guess_steps(self, vmin, vmax):
dv = abs(vmax - vmin)
if dv > 180:
dv -= 180
if dv > 50.:
steps = np.array([1, 2, 3, 6, 10])
elif not self._dms or dv > 3.:
steps = np.array([1, 1.5, 2, 2.5, 3, 5, 10])
else:
steps = np.array([1, 10/6., 15/6., 20/6., 30/6., 10])
self.set_params(steps=np.array(steps))
def _raw_ticks(self, vmin, vmax):
self._guess_steps(vmin, vmax)
return MaxNLocator._raw_ticks(self, vmin, vmax)
def bin_boundaries(self, vmin, vmax):
self._guess_steps(vmin, vmax)
return MaxNLocator.bin_boundaries(self, vmin, vmax)
class LatitudeLocator(LongitudeLocator):
"""
A locator for latitudes that works even at very small scale.
Parameters
----------
dms: bool
Allow the locator to stop on minutes and seconds (False by default)
"""
def tick_values(self, vmin, vmax):
vmin = max(vmin, -90.)
vmax = min(vmax, 90.)
return LongitudeLocator.tick_values(self, vmin, vmax)
def _guess_steps(self, vmin, vmax):
vmin = max(vmin, -90.)
vmax = min(vmax, 90.)
LongitudeLocator._guess_steps(self, vmin, vmax)
def _raw_ticks(self, vmin, vmax):
ticks = LongitudeLocator._raw_ticks(self, vmin, vmax)
return [t for t in ticks if -90 <= t <= 90]
def bin_boundaries(self, vmin, vmax):
ticks = LongitudeLocator.bin_boundaries(self, vmin, vmax)
return [t for t in ticks if -90 <= t <= 90]
|