= Needed Command Functionality =
Chimera2 command functionality needed for early release(s) based on [[EarlyReleaseRequirements]].

This is somewhat high-level; more detailed guidelines and examples are in [http://www.cgl.ucsf.edu/home/meng/chi2/command-structure.html Chimera2 Command-Structure Thoughts].  See also 
[http://preview.cgl.ucsf.edu/chimera2/docs/user/ Chimera2 User Guide], manpage mockups: 
- [http://www.cgl.ucsf.edu/home/meng/chi2/frameatom_spec2.html atomspec]
- [http://www.cgl.ucsf.edu/home/meng/chi2/surface.html surface]
- [http://www.cgl.ucsf.edu/home/meng/chi2/color.html color]
- [http://www.cgl.ucsf.edu/home/meng/chi2/transparency.html transparency]
- [http://www.cgl.ucsf.edu/home/meng/chimera2/user/commands/namespec.html namespec]

Potential renaming of Chimera1 commands (up for discussion):
- ~~Chimera1 '''freeze''' → Chimera2 '''stop'''~~ (done)
 - Nov 5 2015 Greg will add Log message to remind users of '''stop''' function if no ongoing motion
-  ~~'''~select/select''' (model activation/deactivation) → '''freeze/~freeze'''~~
 - Nov 5 2015 decided activation concept not needed in Chimera2
- ~~'''window, focus''' → '''view ''spec'' '''~~ (done)
- ~~'''windowsize''' → '''window'''~~
 - Nov 5 2015 deemed unnecessary now that it can be truncated (since the '''window''' command is not present)
- ~~'''scale''' → '''zoom'''~~ (done)
- '''display/modeldisplay''' → '''show/hide'''
 - Nov 2 2015 agreed to proceed with this, with '''~show''' as an undocumented alias to '''hide'''
- '''alias''' (target-defining function) → '''namespec''' (previously agreed upon)
 - Nov 5 2015 for the other (command-defining) function of '''alias''', agreed to change syntax for listing and deleting aliases, and to use analogous approach for other commands that also allow the user to assign names to definitions ('''namespec''', '''colordef''', ''etc.''...'''view''' is already that way)
    - '''alias''' → '''alias list'''
    - '''~alias ''name''''' → '''alias delete (''name''|all)'''
- ~~'''2dlabels''' → '''title'''~~ (done)
- ~~'''ribbon''' → '''cartoon'''~~ (done but we still have '''ribbon''' as a synonym)

== Late summer release ==

Initial versions (not necessarily full implementations) of:
* '''open''' (both local files and web-fetch)
  - for this release: PDB, PDB/mmCIF, density maps, sessions
  - as of Nov 2 2015 done for the above except sessions
  - prefixes (''e.g.'' '''pdb:''' should allow opening file with non-standard suffix as that format; currently only treats the string as an ID code)
  - Nov 5 2015 intend to add keywords '''from''' to specify database for web fetch and '''format''' which could be useful for both fetch and local files, and possibly other keywords; retain colon syntax as alternative
* ~~'''close'''~~ (done for models; might want to add '''session''' and/or '''all''' keywords later)
* ~~'''exit, quit''' or equivalent~~ (done)
* ~~something like Chimera1 '''focus''' and/or '''window''' (rename as '''view''')~~ (done)
* '''display''', '''modeldisplay''' (plan to replace with '''show/hide''')
  - as of Nov 2 2015 implemented as '''display''' and its options 
  - Nov 5 2015 some discussion as to whether a show-only option (like Chimera1 '''show''') is possible; there is an undocumented '''only''' option but EM and TG think it may be too confusing in combination with the other options of the command
* '''cartoon''' including spline, path-smoothing, and any other whole-chain parameters as options
  - see [http://www.cgl.ucsf.edu/home/meng/chi2/ribbons.html ribbons writeup]
  - for this release, just ribbons (not pipes/cylinders or worm-by-attr)
  - as of Nov 2 2015 the above is done but no controls for width, thickness, cross-sectional shape (would this be in '''cartoon''' or '''style'''?)
  - Nov 5 2015 tether options have not been separated out (still '''tetherShape''' etc. options of '''cartoon''' instead of '''shape''' etc. options of '''cartoon tether''')
* ~~'''surface''' solvent-excluded molecular surface~~ (done)
  - see [[SurfaceCategories]] discussion of categories and command design
  - see [http://www.cgl.ucsf.edu/home/meng/chi2/surface.html surface command mockup] based on subsequent discussion
  - Nov 5 2015 plan to add '''~surface''' as undocumented alias to '''surface hide''', if possible
* ~~'''color''' (just the first usage with single colorname in the [http://www.cgl.ucsf.edu/home/meng/chi2/color.html color command mockup]~~ (done)
  - leaving color-by-attr as in '''rangecolor''', color-by-scalar-field as in '''scolor''', and '''rainbow''' for later
* '''volume''' control over isosurface display (redundancy with show/hide/color etc. OK with me, but should review structure and keywords ''vs.'' the negotiable [http://www.cgl.ucsf.edu/home/meng/chi2/command-structure.html command guidelines])
  - Nov 5 2015 '''volume''' has been ported over from Chimera1 but Tom G will check over it to see which parts are functional (we know at least a few things related to commas are problematic in Chimera2)
* some way to adjust subdivision/smoothness
  - Nov 5 2015 done for atoms/bonds ('''set subdivision''') but not cartoons
  - done for molecular surfaces; '''surface''' has grid-spacing, resolution options

Extremely useful catchalls that I suggest retaining as permanent commands even though there will be some redundancy:
* '''set''' global settings
  - for this release: ~~silhouettes, background color, depth-cuing amount and color, interactive shadows, lighting (ambient occlusion, ambient-only, N-point)~~ (done, some via '''set''', some via other commands such as '''lighting''')
  - if many sub-options, e.g. '''lighting''', could make a separate top-level command; also keeping a redundant but longer '''set''' command is OK with me
* '''setattr''' attribute values
  - need some way for the user to look up the names and possible values of attributes

For this release, GUI-only or commands? (eventually they should be commands)
* '''select''' (including up/down) see [http://www.rbvi.ucsf.edu/chimera/docs/UsersGuide/selection.html#expandselect Chimera1 selection cascades]
  - as of Nov 2 2015 a good '''select''' command but hierarchy is very limited compared to Chimera1 (presumably will be expanded later) and command doesn't include up/down options
* '''save session''' with restore covered by '''open''', or '''session (save|restore)'''
* ~~'''save image''' with supersampling option~~ (done)

Command accoutrements:
* decide whether we will have '''~commands''' (consensus seems to be yes)
* decide on keyword conventions (see [http://www.cgl.ucsf.edu/home/meng/chi2/command-structure.html command guidelines])
* decide on what kinds of colorspecs are allowed, ''e.g.'' can color names include spaces?
  - as of Nov 2 2015 basically done but we could consider adding some easier-to-type alternatives later
* ~~set of built-in color names~~ (done)
* ~~built-in specs '''solvent, ions, ligand, main, helix, strand, coil'''~~ (these specific ones are done)
* built-in specs for ~~element~~ (done), atom type
* basic hierarchical atomspecs (see [http://www.cgl.ucsf.edu/home/meng/chi2/frameatom_spec2.html Chimera2 atomspec writeup])
  - as of Nov 2 2015 mostly done, lacking a few things like wild cards
* some way to look up attribute names/values for '''setattr'''

== December release ==

The following functionality is listed for the December release, but not necessarily as commands:
* ~~'''transparency''' (similar to '''color'''; takes care of individual settings, whereas '''set''' or another command would be used for related global parameters)~~ (done)
 - see [http://www.cgl.ucsf.edu/home/meng/chi2/transparency.html transparency command mockup]
 - single-layer transparency ('''set''' or other command control)
   - Nov 5 2015 single-layer done but there is no multi-layer option, thus no control to switch between them
* ~~'''cofr''' or '''focus'''-like command ('''view'''+'''cofr''') for setting fixed center of rotation~~ (done)
* '''clip''', '''section''', '''thickness''' (suggest combining into single command to control global clipping, say '''clip''' or '''gclip''')
* '''mclip''' per-model clipping, plane or slab
* capping of clipped objects, including surfaces, cartoons, atoms/bonds ('''set''' if global, '''setattr''' if per-object; could also be an option in '''clip''' and/or '''mclip''')
  - Nov 5 2015 surfaces first, the other things may come later
* pseudobonds that could be intermodel (implying need for '''distance''')
  - Nov 5 2015 TomG says there is support for these but no feature that creates them
* ~~'''help''' to bring up command documentation~~ (done)
  - however, the '''usage''' results for almost all commands need improvement
    -  prevent both the keyword and non-keyword specifications for some parameter being shown, e.g. '''usage select''' 
      - Nov 5 2015 unresolved, TomG would like to retain the flexibility of supplying the parameter with or without keyword, yet not show both of those ways in the usage info
    - get rid of seemingly incorrect nesting, e.g. '''usage cofr'''
    - do we want to show several options that aren't yet implemented, e.g. '''usage color''' or '''usage cartoon'''
* ~~'''delete'''~~ (done)

Expanded functionality of existing commands:
* '''open''' (including fetch) cellPACK, which would elicit interface for exploring hierarchy
* '''save''' reply log, command history
  - as of Nov 2 2015 the log can be saved via the '''log''' command and the command history can be saved via its GUI; '''save''' itself needs work (session-saving not yet done)
* '''select''' all, ~~clear~~ (done), invert
* '''set''' and '''setattr''' as mentioned in the previous section

Command accoutrements:
* command documentation (in progress, done for several)
* full atomspecs (see [http://www.cgl.ucsf.edu/home/meng/chi2/frameatom_spec2.html Chimera2 atomspec writeup])
* translation of menu actions into commands (if needed for full logging and replay... maybe it's not?)
  - Nov 5 2015 done for the display and graphics icons; menu doesn't have any actions yet anyway!

== Highly desirable ==

Again listed but not necessarily as commands:
* '''repr''', '''ribrepr''', '''ribscale''', '''surfrepr''' (maybe consolidate into '''style''' command, generalizing ribbon to cartoon as per [http://www.cgl.ucsf.edu/home/meng/chi2/ribbons.html ribbons writeup], and including pseudobonds; I'm not sure consolidation is better, however, since consolidation makes longer commands, and these will be used frequently):
  - ~~atom/bond '''stick, bs, sphere'''~~ (implemented via '''style'''; do we need a '''line''' or '''wire'''?)
  - pseudobond '''dashedStick''' (since TomG already added it; could be named something else)
  - '''stick''' and '''line''' (if we even have the latter) would apply to both atoms/bonds and pseudobonds
  - surface (volume isosurface and molecular surface) '''solid, mesh'''
  - a default style or a few possibilities for ribbons/cartoons (say '''smooth''' and '''edged''', maybe '''flat''', with default scaling; '''tube''' should be easier to implement than those, even though it's down in the '''Would be nice''' section)
  - each style could have sub-options (''e.g.'' stick radius), or if it's too complicated to include them in the '''style''' command, they could be adjusted with '''setattr'''
  - see [http://www.cgl.ucsf.edu/home/meng/chi2/command-structure.html#examples command examples] for more detailed thoughts
  - Nov 5 2015 decided to leave on the table, revisit when we figure out what comprises a cartoon style and have more of them to play with
* smart molecule display
  - IMO, this implies the need for '''preset''' with at least two interactive options: one with all atoms shown and one similar to the smart display; I'd vote for a third one with molecular surface(s) colored to match the corresponding chain's ribbon, possibly transparent
* color-by-attr as in '''rangecolor''', color-by-scalar-field as in '''scolor''', and color sequentially as in '''rainbow'''
   - merge into main'''color''' command, see [http://www.cgl.ucsf.edu/home/meng/chi2/color.html color command mockup]
   - need to add more palettes, including color-blind-friendly
  - '''defattr''' would be useful for reading in custom attributes
* '''findhbond'''
  - consider option to find salt bridges only
* '''define''' geometric objects based on atomic coordinates: axes, planes, centroids, ellipsoids
* '''shape''' or other way of defining geometric objects arbitrarily
  - I suggest BILD-like position specification; Chimera1 '''shape''' position specification is much too difficult
* '''scene''' save, restore, list
* '''label''' (possibly merge with '''rlabel'''; takes care of individual settings, whereas '''set''' or another command would set related global parameters)
  - command control of font/fontsize would be nice
* '''2dlabels''' (has been renamed '''title''')
  - could merge create/change operations into a single operation, possibly without keyword (something like "title t1 text Hello xpos .1 ypos .1”)
  - EM: I ''think'' it's been ported over from Chimera1 but I haven't tested or documented it
* '''colorkey'''

Expanded functionality of existing commands:
* '''style''' options for pseudobonds: dotted and dashed sticks, dotted and dashed lines (but do we really need the latter any more?)
* fancy-shaped selection and clipping (Chimera1 has octant stuff in '''vop''' subcommands)
  - potentially options of '''select, clip, mclip''', ''e.g.'' to use some previously defined 3D geometric object (an enclosed shape, I assume)
  - projections of 2D shapes or outlines as mentioned in the '''Would be nice''' section could also be used
  - EM: I ''think'' '''vop''' has been completely ported over from Chimera1
* '''volume''' 
  - isosurface smoothing
  - EM: I '' think'' '''volume''' has been completely ported over from Chimera1, including the surface smoothing options
  - '''sop hideDust''' equivalent (could be separate command, but is this used for anything other than isosurfaces?)
* '''save''' PDB, volume data format(s), graphics format(s), ''etc.''
* '''set''' (or other command, ''e.g.'' '''background''') global settings: background color gradient, multiple-layer transparency (correctly rendered even for multiple models)
* '''setattr''' (or other command, ''e.g.'' '''material''') individual attributes: material properties
  - EM: there is a '''material''' command but I haven't explored it

Command accoutrements:
* more built-in specs like '''protein, nucleic acid,''' functional groups, amino acid categories, atom types, ''etc.''

== Would be nice ==

Again listed but not necessarily as commands:
* '''nucleotides''' base-slab, sugar-tube, and ladder options
  - need better defaults than in Chimera1, at least for smart display
* '''findclash''' (also needed for coloring surface interaction patches)
  - consider facilitating the use of contact defaults (in Chimera1, the overall defaults are the clash defaults, so to use the GUI's contact defaults you have to look up the two values in the documentation and specify them individually in the command)

Expanded functionality of existing commands:
* '''open''' Chimera1 sessions (session conversion)
* '''preset''' publication options 
* '''cartoon''' options for pipes and planks
 - that's what the [[EarlyReleaseRequirements]] says, but I don't think box-shaped planks are needed (or even desirable) if there is an option for well-smoothed strands similar to our B spline strands in Chimera1; beta-sheet curvature is the rule rather than the exception
 - cylinders (pipes) could be a distinct option for helices and should integrate with helix axes, ''i.e.'' the pipes=axes could be used in measurements
 - see [http://www.cgl.ucsf.edu/home/meng/chi2/ribbons.html ribbons writeup]
* cartoon '''style''' option '''tube''' (or something like that, similar to our current rounded licorice)
* '''surface''' 
 - provisions for multiple surfaces on same atoms, including SAS and/or SES
  - as of Nov 2 2015 done-ish, can have multiple surfaces on same atoms, but there is no SAS capability
 - patch boundary-smoothing, see '''smoothBorders''' in the [http://www.cgl.ucsf.edu/home/meng/chi2/surface.html surface command mockup]
  - as of Nov 2 2015 done-ish, '''sharpBoundaries''' option fulfills similar role
* surface '''style''' option '''mesh'''
* atoms/bonds ring fill, aromaticity, and bond multiplicity display (sub-options of '''style stick''' and/or settable with '''setattr'''; could also apply to '''style line''', but do we still need that style?)
* smart clipping, leaving individual objects such as multiscale surfaces whole
 - potentially options of '''clip, mclip'''
 - in Chimera1, certain things are already only wholly selectable (surface pieces, ''etc.''), but if we become able to select subparts/triangles within surfaces, it could also be an option of '''select'''
* '''set''' (or other command, ''e.g.'' '''background, lighting, camera''') global settings: background images, lighting contrast, camera modes (orthographic, stereo)
  - as of Nov 2 2015 some of these are done, '''camera''' command
* '''setattr''' per-model silhouettes (remove silhouettes from global settings?)

GUI-only, or do we need commands?
* interactively adjustable light positions
* for surface patch boundary smoothing, individual triangle-hiding or hand-drawn boundaries
* hand-drawn or 2D-shape custom silhouettes (2D outlines? perhaps could be an option of '''2dlabels''')... also ties in with the fancy-shaped selection in the '''Highly desirable''' section

== Eventually ==
* '''morph'''
  - atoms/bonds
  - maps
* '''coordset'''-like trajectory playback but also the ability to show more than one frame at a time
* ~~'''vseries'''~~ (done)
* other motion-scripting and frame-argument commands (see [http://www.rbvi.ucsf.edu/chimera/docs/UsersGuide/movies.html#moviecommands Chimera1 movie-related commands])
  - as mentioned [#/stop above], could make Chimera2 '''stop''' act like Chimera1 '''freeze''', and Chimera2 '''freeze''' deactivate models for motion like Chimera1 '''~select'''
  - I'm hoping for saved positions and commands for traversing them: '''savepos/reset/fly'''... these are useful and much lighter-weight than scenes
    - as of Nov 2 2015 '''savepos/reset''' partial implementation in '''view''' command
  - although Chimera1 has scenes, it doesn't have command controls analogous to the above for fully scripting timeline playback; our designs for '''transition''' and '''animate''' commands were never implemented (see [http://www.cgl.ucsf.edu/home/meng/chi2/anim-commands animation commands writeup])

== Uncategorized (priority not yet discussed) ==
* '''namespec''' command to make user-defined targets (like Chimera1 '''namesel''' for evaluate-now and Chimera1 '''alias''' for evaluate-later)
  - '''currentOnly''' option (or something like that) to distinguish the evaluate-now or evaluate-later types
  - [http://www.cgl.ucsf.edu/home/meng/chimera2/user/commands/namespec.html draft manpage ]
* '''matchmaker''' or equivalent
* '''match''' or equivalent