test-kivy-app/kivy_venv/lib/python3.11/site-packages/kivy/tools/image-testsuite/README.md

Generating the image test suite

On Linux/unix systems, you can use the imagemagick-testsuite.sh script to create an image test suite using the convert command line utility. You must have ImageMagick installed ("apt install imagemagick" on debian derivatives). There is also a rule in the Makefile, make image-testsuite.

A more comprehensive test suite can be generated using Gimp (tested on version 2.8.18). To install the plugin, copy gimp28-testsuite.py to your gimp plugins directory, on linux/unix systems usually ~/.gimp-2.8/plug-ins. You can find the plugin location via the Gimp menu Edit - Preferences - Folders - Plug-Ins. Once installed, the plugin should appear in "Tools" menu, named "Kivy image testsuite".

Test images must be saved in the kivy/tests/image-testsuite directory, after this you can run the test. It is (currently) preferable to run it directly as a script, instead of via make test, since the latter won't give you useful debug output.

cd kivy/tests
python test_imageloader.py | less

or to get only the summary report:

python test_imageloader.py | grep REPORT | less

Kivy ImageLoader testsuite

These tools generate a wide range of images for testing Kivy's ImageLoaders. The pixel data is encoded in the file name, and reproduced "from the sideline" in order to verify the pixel data loaded from file. This is used to expose issues in the Kivy core and underlying provider libraries.

The filenames consist of sections separated by an underscore _:

v0_ <W> x <H> _ <pat> _ <alpha> _ <fmt> _ <testname> _ <encoder> . <ext>

Variables are enclosed in pointy brackets. The leading v0_ indicates that it conforms to version 0 of the test protocol (described in this document) and must be present.

v0_5x1_rgb_FF_PNG24_OPAQUE_magick.png

This is a 5x1 image, pattern is "rgb", alpha is "FF". PNG24 is the internal file format name (ImageMagick-specific), and OPAQUE is the test we are performing (drawing opaque pixels only), see test names below.

• indicates the pixel colors (in order), as they are drawn in the image file.

• is the global alpha from 00-FF (2 bytes, ascii) which is applied to all pixels except 't' (transparent) which have fixed alpha at 00

• (aka fmtinfo) is an encoder-specific string with information about the format or process that generated the file. For example, if the same image is saved with and without interlacing, it will contain "I1" and "I0" to distinguish the files.

  • ImageMagick test suite generator uses magick format name, such as PNG24
  • The Gimp generator plugin adds information about the layer that was exported to form the image:
    • BPP1G = 1 byte per pixel, gray
    • BPP2GA = 2 bytes per pixel, gray + alpha
    • BPP3 = 3 bytes per pixel, rgb
    • BPP4 = 4 bytes per pixel, rgba
    • IX = indexed, IXA = indexed+alpha
    • Note: Indexed images are drawn in RGB or GRAY images (with alpha if needed), and converted to indexed before export. These values represent the layer type at time of export, it affects the parameters used for encoding the output data.

• is a special string that indicates what type of data is expected in the file. Options are OPAQUE, BINARY, ALPHA and repeated for grayscale, GRAY-OPAQUE, GRAY-BINARY, GRAY-ALPHA. We expect BINARY and ALPHA tests to result in an alpha channel (details below)

• identifies the software that created the file, "magick", "gimp" ..

• is the extension, must be lowercase and match the extensions supported by Kivy image loaders (or they will be ignored)

Test names

• OPAQUE tests opaque pixels (normal RGB) (lossless formats)
• BINARY tests opaque + fully transparent pixels (GIF etc)
• ALPHA tests semi-transparent pixels (normal RGBA) (PNG32 etc)
• GRAY-OPAQUE tests opaque grayscale only (various PNG, tga, )
• GRAY-BINARY tests opaque grayscale + fully transparent pixels (PNGs)
• GRAY-ALPHA tests semi-transparent grayscale pixels (TGA, XCF)

Patterns must conform to the specific test. For example, the pattern "rgb" has undefined behavior for a grayscale test, since r/g/b can't be represented in grayscale. So all grayscale formats must use 0-9A-F only, and optionally 't' for transparent pixels in GRAY-BINARY/GRAY-ALPHA.

Test name	Valid pattern characters
OPAQUE	wxrgbcyp, and full grayscale**
GRAY-OPAQUE	0123456789ABCDEF (full grayscale)
BINARY	t REQUIRED + wrgbcyp, limited grayscale (no 0/x!!!)
GRAY-BINARY	t REQUIRED + limited grayscale (no 0/x!!!)
ALPHA	t, wxrbgcyp and full grayscale**
GRAY-ALPHA	t, 0123456789ABCDEF (full grayscale)

• **: While grayscale is supported here, it is generally better to use colors, since all the bytes in a grayscale pixel represented as rgb are identical. For example, 'A' or \xAA\xAA\xAA will pass despite a byte order problem.

• !!!: In some cases, black color is used for binary transparency. So if you use "0" (or "x"), test_imageloader will expect #000000FF in RGBA, but the pixel becomes transparent (a=00) and test fails. All BINARY tests MUST include at least one "t" pixel to ensure that the image is saved with an alpha channel.

Pixel values

Each character in the pattern represents the color of a single pixel. It is important that you include only the correct type of pixel values for the different test types (see table above). Individual pixel values get their alpha from global setting ( in filename), but 't' pixels always have alpha = 0x00 regardless of the test's alpha setting.

OPAQUE, BINARY, ALPHA (lowercase)
-----------------------------------------
"w" White (#fff)     "x" Black  (#000)!!!
"r" Red   (#f00)     "g" Green  (#0f0)
"b" Blue  (#00f)     "y" Yellow (#ff0)
"c" Cyan  (#0ff)     "p" Purple (#f0f)


GRAY-OPAQUE, GRAY-BINARY, GRAY-ALPHA (uppercase)
------------------------------------------------
"0" #000!!!  "1" #111     "2" #222     "3" #333
"4" #444     "5" #555     "6" #666     "7" #777
"8" #888     "9" #999     "A" #AAA     "B" #BBB
"C" #CCC     "D" #DDD     "E" #EEE     "F" #FFF

!!! See warnings above regarding BINARY tests