Provides a new artist for matplotlib to display a scale bar, aka micron bar.
It is particularly useful when displaying calibrated images plotted using
plt.imshow(...).
The artist supports customization either directly from the ScaleBar object or from the matplotlibrc.
Easiest way to install using pip:
pip install matplotlib-scalebar
For development installation from the git repository:
git clone git@github.com:ppinard/matplotlib-scalebar.git
pip install -e matplotlib-scalebar
There are many ways to customize the scale bar. Examples and explanations of the arguments of the ScaleBar class are given below, but here is a quick start guide.
The constructor arguments dx and units specify the pixel dimension.
For example ScaleBar(0.2, 'um') indicates that each pixel is equal to 0.2 micrometer.
By default, the scale bar uses SI units of length (e.g. m, cm, um, km, etc.).
See examples below for other system of units.
In this example, we load a sample image from the matplotlib library, create a subplot, plot image, create scale bar and add scale bar as an "artist" of the subplot.
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.cbook as cbook
from matplotlib_scalebar.scalebar import ScaleBar
# Load image
with cbook.get_sample_data("s1045.ima.gz") as dfile:
im = np.frombuffer(dfile.read(), np.uint16).reshape((256, 256))
# Create subplot
fig, ax = plt.subplots()
ax.axis("off")
# Plot image
ax.imshow(im, cmap="gray")
# Create scale bar
scalebar = ScaleBar(0.08, "cm", length_fraction=0.25)
ax.add_artist(scalebar)
# Show
plt.show()
Here are arguments of the ScaleBar class constructor and examples how to use them.
scalebar = ScaleBar(
dx,
units="m",
dimension="si-length",
label=None,
length_fraction=None,
height_fraction=None,
width_fraction=None,
location=None,
pad=None,
border_pad=None,
sep=None,
frameon=None,
color=None,
box_color=None,
box_alpha=None,
scale_loc=None,
label_loc=None,
font_properties=None,
label_formatter=None,
scale_formatter=None,
fixed_value=None,
fixed_units=None,
animated=False,
rotation=None,
)
Each argument can also be changed afterwards using their respective property.
scalebar.dx = 2.0
The following schematic illustrates the nomenclature used in the definition of the arguments.
Size of one pixel in units specified by the next argument.
Set dx to 1.0 if the axes image has already been calibrated by setting its extent.
fig, ax = plt.subplots()
ax.axis("off")
ax.imshow(im, cmap="gray", extent=[0, 20.48, 0, 20.48])
scalebar = ScaleBar(1, "cm", length_fraction=0.25)
ax.add_artist(scalebar)
Special notes for geospatial plots: If you are plotting geospatial coordinates (such as scatterplots of the location of structures, geopandas geodataframe plots, etc.), dx needs to be set differently depending on the coordinate system:
dx = 1.dx = great_circle_distance((X, Y), (X + 1, Y))Units of dx.
The units needs to be valid for the specified dimension.
Default: m.
Dimension of dx and units. It can either be equal:
si-length (default): scale bar showing km, m, cm, etc.imperial-length: scale bar showing in, ft, yd, mi, etc.si-length-reciprocal: scale bar showing 1/m, 1/cm, etc.pixel-length: scale bar showing px, kpx, Mpx, etc.angle: scale bar showing °, ʹ (minute of arc) or ʹʹ (second of arc)matplotlib_scalebar.dimension._Dimension objectfig, ax = plt.subplots()
ax.axis("off")
ax.imshow(im, cmap="gray")
scalebar = ScaleBar(0.0315, "in", dimension="imperial-length", length_fraction=0.25)
ax.add_artist(scalebar)
Optional label associated with the scale bar.
Default: None, no label is shown.
The position of the label with respect to the scale bar can be adjusted using label_loc argument.
Desired length of the scale bar as a fraction of the subplot's width.
Default: None, value from matplotlibrc or 0.2.
The actual length of the scale bar is automatically determined based on the specified pixel size (dx and units) and the contraint that the scale value can only take the following numbers: 1, 2, 5, 10, 15, 20, 25, 50, 75, 100, 125, 150, 200, 500 or 750.
If you want a specific value, see fixed_value and fixed_units.
In the example below, the scale bar for a length_fraction of 0.25 and 0.5 is the same because the scale cannot have a value between 2 and 5 mm.
Deprecated, use width_fraction.
Width of the scale bar as a fraction of the subplot's height.
Default: None, value from matplotlibrc or 0.01.
A location code, same as matplotlib's legend, either: upper right, upper left, lower left, lower right, right, center left, center right, lower center, upper center or center.
Default: None, value from matplotlibrc or upper right.
Alias for location.
Padding inside the box, as a fraction of the font size.
Default: None, value from matplotlibrc or 0.2.
Padding outside the box, fraction of the font size.
Default: None, value from matplotlibrc or 0.1.
Separation in points between the scale bar and scale, and between the scale bar and label.
Default: None, value from matplotlibrc or 5.
Whether to draw a box behind the scale bar, scale and label.
Default: None, value from matplotlibrc or True.
Color for the scale bar, scale and label.
Default: None, value from matplotlibrc or k (black).
Background color of the box.
Default: None, value from matplotlibrc or w (white).
Transparency of box.
Default: None, value from matplotlibrc or 1.0 (opaque).
Location of the scale with respect to the scale bar.
Either bottom, top, left, right, none.
Default: None, value from matplotlibrc or bottom.
If "none", no scale is shown.
Location of the label with respect to the scale bar.
Either bottom, top, left, right, none.
Default: None, value from matplotlibrc or top.
If "none", no label is shown.
Font properties of the scale and label text, specified either as dict or str.
See FontProperties for the arguments.
Default: None, default font properties of matplotlib.
Deprecated, use scale_formatter.
Custom function called to format the scale.
Needs to take 2 arguments - the scale value and the unit.
Default: None which results in
scale_formatter = lambda value, unit: f"{value} {unit}"
Value for the scale.
The length of the scale bar is calculated based on the specified pixel size dx.
Default: None, the value is automatically determined based on length_fraction.
Units of the fixed_value.
Default: None, if fixed value is not None, the units of dx are used.
Animation state.
Default: False
Whether to create a scale bar based on the x-axis (default) or y-axis.
rotation can either be horizontal or vertical.
Note you might have to adjust scale_loc and label_loc to achieve desired layout.
Default: None, value from matplotlibrc or horizontal.
fig, ax = plt.subplots()
ax.axis("off")
ax.imshow(im, cmap="gray")
scalebar = ScaleBar(
0.08,
"cm",
length_fraction=0.25,
rotation="vertical",
scale_loc="right",
border_pad=1,
pad=0.5,
)
ax.add_artist(scalebar)
_all_deprecated in future matplotlib (> 3.5) (#44)minimumdescent (#36)validate_legend_loc (#33)@maweigert, @crosbyla, @joschkazj, @AKuederle, @habi, @huangziwei, @SirJohnFranklin, @alexandrejaguar, @parishcm, @wiai, @cosmicshear, @ericore, @seangrogan, @PhilipeRLeal, @din14970, @SarthakJariwala, @k1moradi, @anntzer, @bugalo, @musicinmybrain
License under the BSD License, compatible with matplotlib.
Copyright (c) 2015-2022 Philippe Pinard
FAQs
Artist for matplotlib to display a scale bar
We found that matplotlib-scalebar demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.