Figure.image: Add alias "bitcolor" for "G"

[yvonnefroehlich]

Description of proposed changes

This PR aims to add the alias bitcolor for G of the method pygmt.Figure.image.
Following the Code Style, no underscore is used (please see https://www.pygmt.org/dev/contributing.html#contributing-code). However, the GMTjl documentation uses an underscore, i.e., bit_color (please see https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/image/index.html#imag).

Upstream GMT documentation: https://docs.generic-mapping-tools.org/dev/image.html#g

Preview: https://pygmt-dev--2615.org.readthedocs.build/en/2615/api/generated/pygmt.Figure.image.html

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• If adding new functionality, add an example to docstrings or tutorials.
• Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[weiji14]

Is a list allowed?

[yvonnefroehlich]

A list can be used to set both foreground and background colors of 1-bit images:

import pygmt

fig = pygmt.Figure()

for i_G in [
        None,
        "blue+b",
        ["blue+b", "red+f"],
]:
    fig.image(imagefile="@vader1.png", G=i_G)  
    fig.shift_origin(xshift="1c")

fig.show()
# fig.savefig(fname="image_Q_list.png")

Output figure:

[weiji14]

Ah I see, thanks for the example! So the list would translate to -Gblue+b -Gred+f. Makes sense.

[yvonnefroehlich]

Exactly! Maybe moving the sentence "Can be repeated with different settings." upwards makes this a bit clearer (please see commit 951a110)?

[yvonnefroehlich]

@GenericMappingTools/pygmt-maintainers I just realized that for pygmt.Figure.grdimage the parameter bit_color has an underscore. In this PR for the similar parameter of pygmt.Figure.image, I used no underscore because of the Code Style. However, I feel it is confusing to have different versions across different functions or methods. Does it make sense, that I change bitcolor to bit_color for pygmt.Figure.image (even we break the Code Style)? This would cause no issue with backwards compatibility, as this new alias goes into v0.10.0, but changing it the other way around for pygmt.Figure.grdimage would.

[seisman]

Does it make sense, that I change bitcolor to bit_color for pygmt.Figure.image (even we break the Code Style)? This would cause no issue with backwards compatibility, as this new alias goes into v0.10.0, but changing it the other way around for pygmt.Figure.grdimage would.

I think it makes more sense to change bit_color to bitcolor, but we need to keep backward compatibility for at least two more minor versions.

[yvonnefroehlich]

Does it make sense, that I change bitcolor to bit_color for pygmt.Figure.image (even we break the Code Style)? This would cause no issue with backwards compatibility, as this new alias goes into v0.10.0, but changing it the other way around for pygmt.Figure.grdimage would.

I think it makes more sense to change bit_color to bitcolor, but we need to keep backward compatibility for at least two more minor versions.

Yes, I also prefer changing it for Figure.grdimage and to follow the Code Style.
Please see PR #2635 for this change.