Sage: Ticket #21984: Deprecate the opacity argument for plot3d and use alpha
https://trac.sagemath.org/ticket/21984
<p>
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.
</p>
<p>
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:
</p>
<ul><li><code>plot3d()</code>
</li><li><code>line()</code>
</li><li><code>circle()</code>
</li><li><code>parametric_plot3d()</code>
</li><li><code>revolution_plot3d()</code>
</li></ul><p>
Harmonizing the 2d plot and 3d plot functions would be a better UI. For example, changing a single letter of <code>obj.plot2d(some_args, alpha=0.5)</code> to <code>obj.plot3d(some_args, alpha=0.5)</code> (or vice versa) should "just work", without ignoring arguments.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/21984
Trac 1.1.6yzhWed, 04 Apr 2018 22:36:41 GMTcc, dependencies set
https://trac.sagemath.org/ticket/21984#comment:1
https://trac.sagemath.org/ticket/21984#comment:1
<ul>
<li><strong>cc</strong>
<em>yzh</em> added
</li>
<li><strong>dependencies</strong>
set to <em>#25095</em>
</li>
</ul>
<p>
See <a class="closed ticket" href="https://trac.sagemath.org/ticket/25095" title="defect: polygon3d ignores the "alpha" (and equivalent "opacity") argument (closed: fixed)">#25095</a>. In the plot3d functions, the argument "alpha" is equivalent to "opacity" now.
</p>
TicketyzhWed, 04 Apr 2018 22:40:13 GMTcc changed
https://trac.sagemath.org/ticket/21984#comment:2
https://trac.sagemath.org/ticket/21984#comment:2
<ul>
<li><strong>cc</strong>
<em>mkoeppe</em> <em>slelievre</em> added
</li>
</ul>
TicketmkoeppeWed, 22 Jul 2020 17:47:12 GMTcc, milestone changed
https://trac.sagemath.org/ticket/21984#comment:3
https://trac.sagemath.org/ticket/21984#comment:3
<ul>
<li><strong>cc</strong>
<em>gh-jcamp0x2a</em> <em>paulmasson</em> added
</li>
<li><strong>milestone</strong>
changed from <em>sage-7.5</em> to <em>sage-9.2</em>
</li>
</ul>
TicketpaulmassonWed, 22 Jul 2020 23:19:56 GMTmilestone changed
https://trac.sagemath.org/ticket/21984#comment:4
https://trac.sagemath.org/ticket/21984#comment:4
<ul>
<li><strong>milestone</strong>
changed from <em>sage-9.2</em> to <em>sage-duplicate/invalid/wontfix</em>
</li>
</ul>
<p>
If <code>alpha</code> and <code>opacity</code> are equivalent after <a class="closed ticket" href="https://trac.sagemath.org/ticket/25095" title="defect: polygon3d ignores the "alpha" (and equivalent "opacity") argument (closed: fixed)">#25095</a> then why deprecate anything? The term "opacity" is by far more common in the HTML world. I vote we deprecate this ticket...
</p>
TicketpaulmassonWed, 22 Jul 2020 23:20:11 GMTstatus changed
https://trac.sagemath.org/ticket/21984#comment:5
https://trac.sagemath.org/ticket/21984#comment:5
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
</ul>
TicketmkoeppeWed, 22 Jul 2020 23:36:38 GMTstatus changed
https://trac.sagemath.org/ticket/21984#comment:6
https://trac.sagemath.org/ticket/21984#comment:6
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>needs_info</em>
</li>
</ul>
<p>
I haven't checked but it sounds to me that there is a discrepancy between 2d and 3d, and also possibly a documentation issue.
</p>
Ticketmathzeta2Thu, 23 Jul 2020 11:25:28 GMT
https://trac.sagemath.org/ticket/21984#comment:7
https://trac.sagemath.org/ticket/21984#comment:7
<p>
I do not remember the original code that caused me to report this problem, but here is an example that works as expected:
</p>
<pre class="wiki">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
</pre><p>
and one that does not (at least in version 9.1):
</p>
<pre class="wiki">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
</pre><p>
Between the terms "alpha" and "opacity" I have no strong preference (both are common, e.g. opacity in CSS and alpha in RGB<strong>A</strong>). If "opacity" is now more common in Sage, then deprecating "alpha" sounds fine. The <a class="ext-link" href="https://doc.sagemath.org/html/en/reference/plotting/sage/plot/circle.html#sage.plot.circle.circle"><span class="icon"></span>doc for that circle</a> function still uses <code>alpha</code>.
</p>
<p>
I just prefer consistency across the graphics function of Sage, and in particular that it will be easy to change <code>obj.plot()</code> to <code>obj.plot3d()</code>. 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.
</p>
<p>
More generally, it is a problem of not having proper tests for graphics.
</p>
TicketslelievreFri, 11 Sep 2020 01:59:15 GMT
https://trac.sagemath.org/ticket/21984#comment:8
https://trac.sagemath.org/ticket/21984#comment:8
<p>
Repurpose the ticket to "Make 'opacity' and 'alpha'
synonyms in all 2D and 3D plotting functions"?
</p>
Ticketmathzeta2Fri, 11 Sep 2020 17:02:02 GMT
https://trac.sagemath.org/ticket/21984#comment:9
https://trac.sagemath.org/ticket/21984#comment:9
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/21984#comment:8" title="Comment 8">slelievre</a>:
</p>
<blockquote class="citation">
<p>
Repurpose the ticket to "Make 'opacity' and 'alpha'
synonyms in all 2D and 3D plotting functions"?
</p>
</blockquote>
<p>
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'.
</p>
<p>
What will happen if both 'opacity' and 'alpha' are given? Raising an error or ignoring one argument are the go-to options. Other options?
</p>
Ticket