Make graphics subcommands for quality, silhouettes, framerate...

[goddard@…]

The following bug report has been submitted:
Platform:        Darwin-18.7.0-x86_64-i386-64bit
ChimeraX Version: 0.91 (2019-08-30)
Description
Make a graphics subcommands to set parameters for quality, silhouettes, selection, frame rate....  Deprecate most of the set command parameters in favor of the graphics command versions.

Log:
UCSF ChimeraX version: 0.91 (2019-08-30)  
© 2016-2019 Regents of the University of California. All rights reserved.  
How to cite UCSF ChimeraX  




OpenGL version: 4.1 ATI-2.11.20
OpenGL renderer: AMD Radeon Pro Vega 20 OpenGL Engine
OpenGL vendor: ATI Technologies Inc.

[Tom Goddard]

The purpose is to group the many graphics settings so a user can more easily find the ones of interest.

[Tom Goddard]

Done.

I made new graphics subcommands quality, rate, selection and silhouette and hid or removed most of the parameters from the set command that are now handled by these graphics commands. Below are usage lines in the new organization. The set command still will accept the following options although that are hidden in usage output and should instead be set with the graphics command.

hidden = ['silhouettes', 'silhouette_width',

'silhouette_color', 'silhouette_depth_jump',
'selection_color', 'selection_width',
'max_frame_rate'],

Usage summaries

usage set

set [bgColor a color] [subdivision a number]

— set miscellaneous parameters

usage gra

graphics [backgroundColor a color]

— set graphics parameters

Subcommands are:
graphics driver
graphics quality
graphics rate
graphics restart
graphics selection
graphics silhouettes
graphics triangles

usage gra qual

graphics quality [subdivision a number] [atomTriangles an integer] [bondTriangles an integer] [totalAtomTriangles an integer] [totalBondTriangles an integer] [ribbonDivisions an integer] [ribbonSides an integer]

— Set graphics quality parameters

usage gra rate

graphics rate [reportFrameRate] [maxFrameRate a number] [waitForVsync true or false]

— Set graphics rendering rate parameters

reportFrameRate: true or false

usage gra sel

graphics selection [width a number] [color a color]

— set selewction outline parameters

usage gra silh

graphics silhouettes [enable] [width a number] [color a color] [depthJump a number]

— set silhouette parameters

enable: true or false

[Elaine Meng]

I’m a little sad these aren't “set” subcommands instead of “graphics” subcommands because “set” is already familiar and much easier to type. However, “set subdivision” is the same kind of stuff as in “graphics quality” and could just be included in the quality settings. Vetoable, but I’d vote for this division of subcommands

graphics: quality (+subdivision), driver, restart, triangles
set: bgcolor, silhouette, selection 

...or maybe even just making “set” and "graphics” interchangeable (one aliased to the other) but I don’t know if that’s simple when there are subcommands.

[goddard@…]

The subdivision option is currently part of the "graphics quality” subcommand (and also the set command).  The reason I put lots of obscure stuff (silhouette color, jump depth, selection color, …) under graphics subcommands is because set was becoming a massive grab bag of obscure graphics options — in fact every set option we support so far was a graphics setting.  I considered moving all the obscure graphics quality settings like atomTriangles to the set command so the set vs graphics partitioning would at least be consistent but decided it would be better to go the other direction and move all graphics settings to the graphics command.  I also was trying to group the graphics options (quality, silhouettes, framerate, …) so a user would have a better chance finding what they need.  I can look into changing this after I return from Montana, mid-September.

[Elaine Meng]

Could “backgroundColor” be “bgColor” instead?  We just finished making it the same (bgColor, easier to type) amongst set, label, and 2dlabels commands so that it would be easier to remember.

Also there was a “~set bgColor” to go back to the saved Background preference (or black if never saved). Does the graphics command have something to do that?

[Elaine Meng]

Saw one small typo in "graphics quality" usage:  "set selewction outline parameters”

Maybe “graphics triangles” could somehow be folded into graphics quality (which has all the actual triangle-related settings).  I understand if it’s too awkward to combine, however.

There used to be a “graphics colorDepth” setting.  Did that go away?

I’ve reorganized and updated the “graphics” manpage, think I got it all.  Haven’t addressed crossrefs with other pages yet.  Currently is it true that all the old “set” commands also still work?  I could add a sentence saying something like “most graphics options have a corresponding set command and vice versa” if that sounds right to you.  Thanks!   Page in progress: http://www.cgl.ucsf.edu/home/meng/chimerax/docs/user/commands/graphics.html

[Tom Goddard]

Ok, I renamed the backgroundColor option to bgColor in the graphics command. The backgroundColor option still exists for backwards compatibility but is hidden.

I did not add the equivalent of "~set bgColor". It could be implemented as "graphics bgColor default" but I don't think it is worth the effort since 99% of the time "graphics bgColor black" does the same job.

[Tom Goddard]

Ok, fixed selewction typo.

Command graphics triangles takes an optional models argument making a bit awkward to merge into graphics quality. The main use case for it is not related to quality. It is more about whether exported models will be tractable in other software due to the large number of triangles, e.g. for making animations or 3d printing. Putting it under "graphics quality" won't make it easier to find for that use. So I'm going to leave it as is.

The colorDepth option is part of the graphics quality command (allowed values 8 and 16). It wasn't listed due to a code mistake, fixed now.

It is not true that most graphics commands have a current set command equivalent. Here is the full list of set command options taken from std_commands/set.py: bg_color, silhouettes, silhouette_width, silhouette_color, silhouette_depth_jump, selection_color, selection_width, subdivision, max_frame_rate.

[Elaine Meng]

Doh, only the “vice versa” is true (set commands all have a corresponding graphics option).  I guess I can say that, as well as “many graphics options have a corresponding set command” unless you plan to take set commands away.  Let me know if that happens.

Thanks for the explanations and fixes!

[Tom Goddard]

Only the set command bgColor and subdivision options are visible in usage. It doesn't make sense to say there are hidden set options unless they get unhidden.

[Elaine Meng]

OK, then I should remove a bunch of the set documentation and make sure all the crossrefs go to graphics docs instead.

[Elaine Meng]

Are you planning to keep “set” with two and only two options visible (subdivision and bgColor), and are you planning to remove any of the backward compatibility of the other “set” options? 

Currently ChimeraX uses “set” for
(1) background-color icons (Graphics tab)
(2) Presets…Overall Look… [both choices]

I still dislike typing “graphics” instead of “set” although I’m happy with the reorganization into subcommands. Possibilities are to
(A) keep current status with redundancy between the two options of “set” and “graphics"
(B) eradicate visibility of “set" entirely (use “graphics" instead for 1-2 above and remove docs for “set")
(C) eradicate current “set” and its docs but alias it to “graphics” …. this would remove most of the backward compatibility, however

I CC'd Eric since this governs whether we need to change the commands that "Presets…Overall Look” uses and reports in the Log.

[Tom Goddard]

I kept the set command bgColor and subdivision because I thought they were likely used in scripts.

My rough thinking has been that the graphics command should have options to make all graphics setting changes. The set command also has the bgColor and subdivision settings for backwards compatibility. The set command would also allow future additions of options that are not graphics settings. For example in Chimera the set command has options echo (whether to echo script commands) that would be part of "set" in ChimeraX. The Chimera set command also has a few center of rotation options that I don't think I would put under graphics settings since those are really about mouse interaction. Maybe we will come up with more non-graphics settings in the future and those will be controlled by the set command.