Incorrect documentation for pixmap.tint_with

[arun-mani-j]

Describe the bug (mandatory)

The documentation of pixmap.tint_with at https://pymupdf.readthedocs.io/en/latest/pixmap.html#Pixmap.tint_with has different parameters. Calling it with the three values, like pixmap.tint_with(100, 100, 100) causes this error:

TypeError: Pixmap.tint_with() takes 3 positional arguments but 4 were given

Using help(pixmap.tint_with) gives a different docstring.

Signature: px.tint_with(black, white)
Docstring: Tint colors with modifiers for black and white.
File:      ~/Projects/web/lib/python3.10/site-packages/fitz/fitz.py
Type:      method

To Reproduce (mandatory)

1. Obtain a Pixmap for a page.
2. Call pixmap.tint_with with three integers.
3. Error occurs.

Expected behavior (optional)

Expected no error to occur.

Your configuration (mandatory)

3.10.9 (main, Dec  7 2022, 13:47:07) [GCC 12.2.0] linux 
PyMuPDF 1.21.1: Python bindings for the MuPDF 1.21.1 library.
Version date: 2022-12-13 00:00:01.
Built for Python 3.10 on linux (64-bit).

Installed via pip install PyMuPDF.

Additional context (optional)

The corresponding documentation file is https://github.com/pymupdf/PyMuPDF/blob/master/docs/pixmap.rst.
I can create a PR for the fix, but I don't know what tint_with does 😅 I found that method while searching for a way to colorize a PDF page like turning background to slight orange for better readability at night time.

[JorjMcKie]

Thanks for spotting this documentation issue!

[arun-mani-j]

You are welcome! If possible, please add an example for this method, so that people like me can know what it does 😅 . Please let me know if I can be of any help :)

[JorjMcKie]

Here is a first impression of what happens. The meaning as per MuPDF documentation is:

black: Map black to this hexadecimal RGB color.
white: Map white to this hexadecimal RGB color.

So best is to specify the two values as integer in hexa notation 0xrrggbb for each, black or white in pix.tint_with(black, white).
So doing pix.tint_with(0x000000, 0xffffff) is a no-op.

• pix.tint_with(0x00ff00, 0xffffff) changes black to green, white unchanged
• pix.tint_with(0xff0000, 0x0000ff) changes black to red, white to blue

Here is an impression of a number of effects on an original:

[arun-mani-j]

Thanks for the elaborate explanation! This is exactly the method I have been looking for ^^