Deprecate the opacity argument for plot3d and use alpha

[mathzeta]

Most 3d plot functions use the "opacity" keyword argument to set the transparency of the plot. On the other hand, most 2d plot functions use the "alpha" keyword argument.

It seems that the "opacity" keyword argument is also not well-documented. It sometimes appears only in the Examples sections, and not in the Input section. This is the case, at least in the following:

• plot3d()
• line()
• circle()
• parametric_plot3d()
• revolution_plot3d()

Harmonizing the 2d plot and 3d plot functions would be a better UI. For example, changing a single letter of obj.plot2d(some_args, alpha=0.5) to obj.plot3d(some_args, alpha=0.5) (or vice versa) should "just work", without ignoring arguments.

Depends on #25095

CC: @yuan-zhou @mkoeppe @slel @jcamp0x2a @paulmasson

Component: graphics

Keywords: days79

Issue created by migration from https://trac.sagemath.org/ticket/21984

[yuan-zhou]

comment:1

See #25095. In the plot3d functions, the argument "alpha" is equivalent to "opacity" now.

[yuan-zhou]

Dependencies: #25095

[paulmasson]

comment:4

If alpha and opacity are equivalent after #25095 then why deprecate anything? The term "opacity" is by far more common in the HTML world. I vote we deprecate this ticket...

[mkoeppe]

comment:6

I haven't checked but it sounds to me that there is a discrepancy between 2d and 3d, and also possibly a documentation issue.

[mathzeta]

comment:7

I do not remember the original code that caused me to report this problem, but here is an example that works as expected:

sage: C = circle((0,0), 1, fill=True, alpha=0.5)
sage: C.plot()
Launched png viewer for Graphics object consisting of 1 graphics primitive
sage: C.plot3d()
Launched html viewer for Graphics3d Object

and one that does not (at least in version 9.1):

sage: C = circle((0,0), 1, fill=True, opacity=0.5)
sage: C.plot() # opacity is 1 here
verbose 0 (163: primitive.py, options) WARNING: Ignoring option 'opacity'=0.500000000000000
[...]
Launched png viewer for Graphics object consisting of 1 graphics primitive
sage: C.plot3d()
verbose 0 (163: primitive.py, options) WARNING: Ignoring option 'opacity'=0.500000000000000
[...]
NotImplementedError: Unknown plot3d equivalent for opacity

Between the terms "alpha" and "opacity" I have no strong preference (both are common, e.g. opacity in CSS and alpha in RGBA). If "opacity" is now more common in Sage, then deprecating "alpha" sounds fine. The doc for that circle function still uses alpha.

I just prefer consistency across the graphics function of Sage, and in particular that it will be easy to change obj.plot() to obj.plot3d(). It is not artificial to plot something complicated in 2d, with keywords computed from different places, and then trying to plot it again in 3d.

More generally, it is a problem of not having proper tests for graphics.

[slel]

comment:8

Repurpose the ticket to "Make 'opacity' and 'alpha'
synonyms in all 2D and 3D plotting functions"?

[mathzeta]

comment:9

Replying to @slel:

Repurpose the ticket to "Make 'opacity' and 'alpha'
synonyms in all 2D and 3D plotting functions"?

Sure, sounds sensible, but I still prefer to (also) emphasize a consistent API. For example, in the EXAMPLES section across all plotting functions mainly use just one of them, say 'opacity'.

What will happen if both 'opacity' and 'alpha' are given? Raising an error or ignoring one argument are the go-to options. Other options?