Repository navigation
Define additional/custom hatches #20690
Description
Problem
The current set of hatching options within matplotlib is somewhat limited, being only the following, with the ability to make more dense ones.
In geoscience (and possibly other fields, but that is my background) there are a number of other hatching patterns that have long historical use and are still common, cf the USGS templates, available as a pdf here. Some of these are complex enough to be difficult to generate programmatically (eg 706: contorted schist), while others are much simpler (eg 328-K, which is a grid of offset +).
Is there a means to safely define hatches such the latter? A workaround, adding custom hatches to _hatch_types can be done but raises a deprecation warning (MatplotlibDeprecationWarning: hatch must consist of a string of "*+-./OX\ox|" or None, but found the following invalid values "p". Passing invalid values is deprecated since 3.4 and will become an error two minor releases later.) since PR #17926, and is therefore not a stable long-term solution.
Proposed Solution
It would be good to have a means to define custom hatches in a safe way. In many cases I think it likely to be package maintainers adding the functionality (as striplog does) rather than users.
A less comprehensive solution that would still cover many common use-cases would be to allow for repetitive hatching of a single (user-chosen) symbol. (That is, being able to place a regular grid of + or L in the way that the current hatches API handles cases like . and o.)
Activity
jklymak commented on Jul 20, 2021
I don't think there would be a problem adding a public interface to add a patch pattern. I think the largest issue would be documenting it. But if it was clear it was an advanced feature I don't imagine there would be a problem if you wanted to open a PR.
mtb-za commented on Jul 21, 2021
Thanks for the encouragement. I will have a think about how the API might look, and see if I can make something sensible for a PR.
story645 commented on Jul 22, 2021
@mtb-za you can always start w/ a really rough PR and ask us to mark it as a draft if you wanna publicly hash it out.
dopplershift commented on Jul 22, 2021
You can also create a draft PR yourself by clicking the arrow to the right of the green "Create Pull Request" button (when submitting the PR) and selecting "Create draft pull request":
tacaswell commented on Jul 23, 2021
This is something we proposed in the most recent CZI proposal so it is reassuring to get further confirmation of user need :)
In the discussion around that @QuLogic said that any tiling path should be able to be used as a hatch (including contorted schist).
QuLogic commented on Jul 27, 2021
Yes, theoretically it should be possible, but might need to do a bit of low-level surgery to expose it.
MosGeo commented on Jul 27, 2021
In addition to striplog, I believe projects like Cartopy will benefit greatly from this once geologic standards (e.g., https://github.com/cecgeology/USGS-FGDC) are implemented as matplotlib custom hatches.
jorge243 commented on Nov 9, 2021
Hey! Any updates on this potentially very useful feature?
timhoffm commented on Nov 9, 2021
Obviously, no, you'd see the progress in this thread. If there is a pull request that'd be linked here. Resources are limited and nobody has stepped up to take this on.
jklymak commented on Nov 9, 2021
I think this is on the roadmap for the coming year as part of the CZI grant, but not sure the status or who will do this work. It is relatively major, though maybe just so far as it requires careful API decisions.
dopplershift commented on Nov 9, 2021
Here's a proposal: We don't perform the removal of the deprecation (#17926) until we have this API in place.
dopplershift commented on Nov 9, 2021
Actually, I'll go a step further and say don't do the removal until the release after the new API ships.
timhoffm commented on Nov 10, 2021
What's the advantage of continuing to accept invalid hatch patterns?
3 remaining items
SBGit-2019 commented on Aug 3, 2022
I agree: Please keep the "unofficial" way working and maybe even remove the decrepation warning until there is an official API to support that feature.
story645 commented on Jul 25, 2023
xref #19077 as an attempt at a hatch class
story645 commented on Feb 18, 2025
@leejjoon has two nice 3rd party hatch libraries
So wondering if a starting place is what sorta things would it be helpful to have in mpl to support building those libraries and are there ideas in those libraries we'd wanna adopt?
leejjoon commented on Feb 19, 2025
These two packages use rectangular tiles containing a set of paths (clipped to a rectangle) to fill an area. Currently, this is implemented as a path effect, but it should be easy to adapt to the hatch API as far as it allows a callable object that takes the extent of the area to be filled as an argument. I think this is a simple but not very efficient solution as hatching is done by the artist not by the backend. On the other hand, if we would like to utilize hatching capability from the backend side, things will get much more complicated.
For the former simpler approach, I can give it a try if there is an interest.
timhoffm commented on Feb 19, 2025
AFAIK we currently do hatching in the backend. I'm inclined to say that we should not add a different approach to the core library as that increases complexity. Is extended hatch configuration specialized enough so that using a third party library good enough? Can we do something to make hooking into the hatch easier for third parties without growing much complexity on our side?
dopplershift commented on Feb 19, 2025
Right now, while you can achieve the same effect as hatching using a tiling path effect, it's an entirely different parameter than passing in a value for the hatch parameter. IMO, until we have an API that allows users to extend the options for hatch, or we make path_effects the one well-documented way to accomplish hatching, this issue remains.
timhoffm commented on Feb 20, 2025
It seems all hatching is running through Path.hatch().
matplotlib/lib/matplotlib/path.py
Lines 1029 to 1037 in 7ede092
which calls
matplotlib/lib/matplotlib/hatch.py
Lines 199 to 204 in 7ede092
So the backends effectively obtain a Path and individually decide how to render it.
If somebody is interested in looking into this: It should be possible to support other Paths. The main question is proably API and how we want to define the patterns. The string-based approach won't suffice here.
leejjoon commented on Feb 21, 2025
Here is a one approach.
This require very minimal change from the matplotlib side.
main...leejjoon:matplotlib:custom-hatch#diff-9fa22d18bda986f54317196aa0414a09252e8421779c006ed9ac51bf229ed1e9
A user can simply set the hatch with a custom hatch instance. For example,
However, the current hatch implementation in Matplotlib is limited in the sense that the hatch pattern need to be designed in "a unit square". It would be better to support pasterns of different size, different width and height. The change for this need to be made every supported backends although I envision that the required change is not significant.
Mat-Beut commented on Sep 2, 2025
Since it hasn't been fetched yet to the main repo.
If we want to use it in our scripts, and store those scripts on github.
Do we have to clone the fork to import localy from here or can we download the USGpatterns and custom_hatch file, include it in our repo while crediting the main repo, fork repo and contributor that participated in the creation of those files ?
story645 commented on Sep 2, 2025
@Mat-Beut I think you can just use the standalone library version if it fits your needs: https://mpl-pe-pattern-usgs.readthedocs.io/en/latest/