grep -r XPM3 * in /usr/share/emacs shows etc/PROBLEMS:** macOS doesn't come with libxpm, so only XPM3 is supported. This subservience  to Apple contradicts the general principle of open source. However, we can adapt to it. sudo install xpmutils installs sxpm, which can convert XPM 1 and 2 to 3. sxpm --help is inscrutable. sxpm file.xpm - o file.xpm changes file.xpm to XPM3. When this is applied to the icon files, emacs 27.1 in Linux correctly uses them in the toolbar even when they are located in ~/icons.

Many thanks to Benjamin Riefenstahl and Eli Zaretskii for helping me to resolve this problem.

Date: Thu, 23 May 2024 21:08:24 -0700
From: David McCracken <davidm@ixont.com>

I have developed a library that includes a toolbar with custom icons. It
works in all versions of Emacs in Windows and in Emacs version 26.3
under Ubuntu-Mate 20.54 but the toolbar doesn't work in Emacs 27.1 under
Ubuntu-Mate 22.04. In my preferred configuration I put my icons under
the user home directory so that this doesn't change if Emacs is
updated. My library accesses this with e.g.
(tool-bar-add-item "~/icons/lxa-next"
to use my lxa-next.xpm icon. In Emacs 26.3 it also works to put my icon
in /usr/share/emacs/26.3/etc/images and refer to it as simply
"lxa-next". Emacs 27.1 shows nothing either way. My lxa-next.xpm appears
similar to the native lock-broken.xpm (4.7kB vs. 4.6kB) so I
experimented referring to that instead of mine and it worked. I also
tested left-arrow but instead of left-arrow.xpm or pbm, it showed a very
plain < image that doesn't exist in the images directory. It should be
noted that there is a lock-broken.pbm but the xpm version was
automatically selected. The icon selection mechanism of Emacs 26.3 is
usable but could be improved by accepting an explicit icon file
extension. That of 27.1 is unusable and, unless we can fix it, I will
have to advise users of my library to install an older version of Emacs.

I tried to visit the XPM file you attached, and it displays okay with
both Emacs 27.1 and the current development version, at least on
MS-Windows.  So I don't see a reason why this would not work on a tool
bar.  I suggest that you post some minimal Lisp code that displays
these icons on the Emacs tool bar, starting from "emacs -Q", and then
we could try the code and see if the problem can be reproduced and
debugged.

Btw, to clarify: you are saying that your XPM icons don't work in
Emacs 27.1 both on MS-Windows and on Ubuntu?  Or only on Ubuntu?

Thanks.