Skip to content

Commit bff08ff

Browse files
committed
docs: explain slow first plots and persistent font caches
Signed-off-by: 李永祺 <doribelove@gmail.com>
1 parent f6a572c commit bff08ff

2 files changed

Lines changed: 72 additions & 0 deletions

File tree

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,5 @@ unit quaternions :math:`\q \in \mathrm{S}^3`, and twists :math:`S \in \se{2},
2121
intro
2222
spatialmath
2323
functions
24+
troubleshooting
2425
indices

‎docs/source/troubleshooting.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
Troubleshooting
2+
===============
3+
4+
.. _slow-first-plot:
5+
6+
Slow first plot
7+
---------------
8+
9+
The first plot in a fresh environment can take several seconds while Matplotlib
10+
scans installed fonts and builds its font cache. You may see the message
11+
``Matplotlib is building the font cache; this may take a moment``. The time
12+
depends on the system and the installed fonts.
13+
14+
SpatialMath imports Matplotlib's plotting interface lazily, so this cost is
15+
usually deferred until plotting is first requested. A fast ``import spatialmath``
16+
does not mean that the font cache is already populated. If the delay recurs in
17+
each new process, check whether the cache directory is writable and persists
18+
between runs, especially in containers, CI runners and sandboxes.
19+
20+
Find the cache directory
21+
^^^^^^^^^^^^^^^^^^^^^^^^
22+
23+
Use the same Python environment as your application:
24+
25+
.. code-block:: shell
26+
27+
python -c "import matplotlib; print(matplotlib.get_cachedir())"
28+
29+
``MPLCONFIGDIR`` overrides the directory used for Matplotlib's configuration and
30+
cache. Set it **before importing Matplotlib**. If the usual directories are not
31+
writable, Matplotlib can fall back to a temporary directory, which may prevent
32+
reuse between runs. See Matplotlib's
33+
`environment variable documentation <https://matplotlib.org/stable/install/environment_variables_faq.html#envvar-MPLCONFIGDIR>`_
34+
for platform-specific defaults.
35+
36+
Keep and prepopulate the cache
37+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38+
39+
For a Linux or macOS shell, choose a persistent, writable directory and run a
40+
one-time warm-up:
41+
42+
.. code-block:: shell
43+
44+
export MPLCONFIGDIR="$HOME/.cache/spatialmath-matplotlib"
45+
mkdir -p "$MPLCONFIGDIR"
46+
MPLBACKEND=Agg python -c "import matplotlib.pyplot"
47+
48+
Use the same ``MPLCONFIGDIR`` when running the application. The warm-up still
49+
pays the initial scan cost; retaining the cache lets later processes reuse it.
50+
``Agg`` allows this command to run without a display and is selected only for
51+
the warm-up command, so it does not change the application's plotting backend.
52+
53+
* **Docker:** after installing Matplotlib and the image's fonts, prepopulate the
54+
cache during the image build:
55+
56+
.. code-block:: dockerfile
57+
58+
RUN MPLBACKEND=Agg python -c "import matplotlib.pyplot"
59+
60+
The build step and application must use the same cache directory, with
61+
appropriate permissions for the runtime user. A cache built in root's home
62+
will not help an application using another user's default cache directory.
63+
A volume mounted over the populated directory also hides the built-in cache.
64+
65+
* **CI:** restore the cache directory before the first plot or warm-up command,
66+
and save it afterwards using the CI system's cache facility. Include the
67+
operating system and Matplotlib version in the cache key, and refresh it when
68+
the installed fonts change.
69+
70+
* **Sandboxes:** configure ``MPLCONFIGDIR`` to point to a writable directory that
71+
survives between runs, rather than a temporary directory recreated each time.

0 commit comments

Comments
 (0)