Opened 4 years ago

Last modified 2 weeks ago

#21984 needs_info enhancement

Deprecate the opacity argument for plot3d and use alpha

Reported by: mathzeta2 Owned by:
Priority: minor Milestone: sage-duplicate/invalid/wontfix
Component: graphics Keywords: days79
Cc: yzh, mkoeppe, slelievre, gh-jcamp0x2a, paulmasson Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #25095 Stopgaps:

Description

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.

Change History (7)

comment:1 Changed 2 years ago by yzh

  • Cc yzh added
  • Dependencies set to #25095

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

comment:2 Changed 2 years ago by yzh

  • Cc mkoeppe slelievre added

comment:3 Changed 2 weeks ago by mkoeppe

  • Cc gh-jcamp0x2a paulmasson added
  • Milestone changed from sage-7.5 to sage-9.2

comment:4 Changed 2 weeks ago by paulmasson

  • Milestone changed from sage-9.2 to sage-duplicate/invalid/wontfix

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...

comment:5 Changed 2 weeks ago by paulmasson

  • Status changed from new to needs_review

comment:6 Changed 2 weeks ago by mkoeppe

  • Status changed from needs_review to needs_info

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

comment:7 Changed 2 weeks ago by mathzeta2

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.

Note: See TracTickets for help on using tickets.