= 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 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] (omnibus, including color-by-value; currently I favor this over separate color-by-value [http://www.cgl.ucsf.edu/home/meng/chi2/vcolor.html vcolor])
- [http://www.cgl.ucsf.edu/home/meng/chi2/transparency.html transparency]
- [http://www.cgl.ucsf.edu/home/meng/chi2/alias.html alias]
- [http://www.cgl.ucsf.edu/home/meng/chi2/macro.html macro]
Potential renaming of Chimera1 commands (up for discussion):
- Chimera1 '''freeze''' → Chimera2 '''stop''' (the latter no longer used for exiting the program)
-  '''~select/select''' (whole-model activation/deactivation function) → '''freeze/~freeze'''
- '''window, focus''' → '''view (all | spec)'''
- '''scale''' → '''zoom'''
- '''windowsize''' → '''window'''
- '''2dlabels''' → '''title'''
- '''alias''' (action-defining function) → '''macro''', as in the mockups linked above

== Late summer release ==

Initial versions (not necessarily full implementations, could be partial) of:
* '''open''' (suggest same general syntax as Chimera1, possibly adjusting prefixes; covers both local files and web-fetch)
  - for this release: PDB, PDB/mmCIF, density maps, sessions
* '''close'''
* '''exit, quit''' or equivalent
  - maybe '''stop''' should instead work like Chimera1 '''freeze''' (stop motion), and '''freeze''' could be repurposed for deactivation (the older function of Chimera1 '''~select''')
* something like Chimera1 '''focus''' and/or '''window''' (although I might rename as '''view''' since that's an action; the noun is confusing... '''window''' may be better for windowsize specification)
* '''display''', '''modeldisplay''' (suggest replacing with '''show/hide''')
  - this could control pseudobonds indirectly if they are hidden automatically when endpoint atoms are hidden, but we may want to make it act on them directly, or else '''setattr''' (see below) might be the only way
* '''ribbon''' (suggest replacing with '''cartoon''' and including spline, path-smoothing, and any other whole-chain parameters as options to this command)
  - 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)
* '''surface''' solvent-excluded molecular surface
  - 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
* '''repr''', '''ribrepr''', '''ribscale''', '''surfrepr''' (maybe consolidate into a new '''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); styles for this release:
  - atom/bond '''stick, bs, sphere''' (and '''line'''?)
  - 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
* '''color''' (leaving color-by-attr as in '''rangecolor''', color-by-scalar-field as in '''scolor''', and '''rainbow''' for later)
  - just the first usage with single colorname in the [http://www.cgl.ucsf.edu/home/meng/chi2/color.html color command mockup]
* '''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])
* some way to adjust subdivision/smoothness; any global setting could be covered by '''set''' (see below) and any attribute by '''setattr''', but there could also be options in '''surface''', '''volume''', '''cartoon''' and/or a top-level '''quality''' command

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)
  - 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]
* '''save session''' with restore covered by '''open''', or '''session (save|restore)'''
* '''save image''' with supersampling option

Command accoutrements:
* decide whether we will have '''~commands''' (ECM: I quite like them, but others may not)
* 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?
* set of built-in color names
* built-in specs '''solvent, ions, ligand, main, helix, strand, coil''' (needed for molecular surface and ribbon anyway, might as well make them available for command-line use)
* built-in specs for element and/or atom type, if already needed for setting radii for molecular surface calculation anyway
* basic hierarchical atomspecs (see [http://www.cgl.ucsf.edu/home/meng/chi2/frameatom_spec2.html Chimera2 atomspec writeup])
* 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)
 - see [http://www.cgl.ucsf.edu/home/meng/chi2/transparency.html transparency command mockup]
 - single-layer transparency ('''set''' or other command control)
* '''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 all solid objects, including surfaces, cartoons, atoms/bonds ('''set''' if global, '''setattr''' if per-object; could also be an option in '''clip''' and/or '''mclip''')
* pseudobonds that could be intermodel (implying need for '''distance''')
* '''active/~active, freeze/~freeze''' or some other command to control model activation for motion (in Chimera1, '''freeze''' is something different)
* '''help''' to bring up command documentation
* '''delete'''

Expanded functionality of existing commands:
* '''open''' (including fetch) cellPACK, which would elicit interface for exploring hierarchy
* '''save''' reply log, command history
* '''select''' all, clear, invert
* '''set''' and '''setattr''' as mentioned in the previous section

Command accoutrements:
* command documentation
* 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?)

== Highly desirable ==

Again listed but not necessarily as commands:
* 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'''
   - ECM: I favor merging with main '''color''' command, see [http://www.cgl.ucsf.edu/home/meng/chi2/color.html omnibus color command mockup] ( [http://www.cgl.ucsf.edu/home/meng/chi2/vcolor.html color-by-value command mockup] is less refined, I stopped working on it)
  - '''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'''
  - maybe rename to '''title'''
  - could merge create/change operations into a single operation, possibly without keyword (something like "title t1 text Hello xpos .1 ypos .1”)
* '''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
* '''volume''' 
  - isosurface smoothing (does this apply also to grid molecular surfaces? if so, could also be an option to '''surface''')
  - '''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

Command accoutrements:
* more built-in specs like '''protein, nucleic acid,''' functional groups, amino acid categories, element symbols, atom types, ''etc.'' (the latter two may have been needed for molecular surface and/or H-bond calculations anyway)

== 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
 - patch boundary-smoothing, see '''smoothBorders''' in the [http://www.cgl.ucsf.edu/home/meng/chi2/surface.html surface command mockup]
* 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)
* '''setattr''' (or other command, ''e.g.'' '''material''') attributes: individual shininess (and/or '''set''' global shininess?), other individual material properties, 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'''
* 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
  - 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) ==
* a command to make user-defined targets (like Chimera1 '''namesel''' plus the target-defining part of Chimera1 '''alias''')
  - maybe reuse '''alias'''? (see [http://www.cgl.ucsf.edu/home/meng/chi2/alias.html alias command mockup])
* a command to make user-defined commands (like the action-defining part of Chimera1 '''alias''')
  - maybe '''macro''' or '''metacommand'''? (see [http://www.cgl.ucsf.edu/home/meng/chi2/macro.html macro command mockup])