= 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] (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] (we decided to make this '''namespec''') - [http://www.cgl.ucsf.edu/home/meng/chi2/macro.html macro] (we decided to leave this as '''alias''') 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 ''spec'' '''~~ (done) - '''windowsize''' → '''window''' - ~~'''scale''' → '''zoom'''~~ (done) - '''display/modeldisplay''' → '''show/hide''' - '''alias''' (target-defining function) → '''namespec''' - ~~'''2dlabels''' → '''title'''~~ (done) - ~~'''ribbon''' → '''cartoon'''~~ (done but we still have '''ribbon''' as a synonym) == 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 - as of Nov 2 2015 done for the above except sessions * ~~'''close'''~~ (done for models; might want to add session option later) * ~~'''exit, quit''' or equivalent~~ (done) - 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''')~~ (done) - '''window''' may be better for windowsize specification * '''display''', '''modeldisplay''' (maybe replace 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 - as of Nov 2 2015 implemented as '''display''' and its options (EM: seems good to me) * '''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 partial implementation: protein only, no controls for style (width, thickness, cross-sectional shape; would this be in '''cartoon''' or '''style'''?) * '''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 - as of Nov 2 2015 a fairly extensive '''surface''' implementation including calculation options, showing/hiding down to the level of atomic patches - EM remaining thoughts: - do we want to add '''~surface''' as synonym for '''surface hide'''? - do we need mesh or dot options, and if so, via what command ('''surface''' or '''style''' or other?) * '''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'''~~ (implemented via '''style'''; do we need a '''line''' style?) - 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''' (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]) - I ''think'' it's done, in that '''volume''' has been completely ported over from Chimera1 * 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 - as of Nov 2 2015 at least some of this is done, some via '''set''', some via other commands such as '''lighting''' * '''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 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 and/or atom type - element symbols are done/available * 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) * ~~'''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 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~~ (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''' - 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, 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?) - done for the display and graphics icons, not for menu items as far as I know == 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''' - EM: 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''' (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 * 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) == * a command to make user-defined targets (like Chimera1 '''namesel''') - we decided to name this '''namespec''' (see [http://www.cgl.ucsf.edu/home/meng/chi2/alias.html alias command mockup]) with '''currentOnly''' option to distinguish the evaluate-now or evaluate-upon-use types * a command to make user-defined commands (like the action-defining part of Chimera1 '''alias''') - we decided to keep the name '''alias''' for this function (see [http://www.cgl.ucsf.edu/home/meng/chi2/macro.html macro command mockup]) - as of Nov 2 2015 we have this command but syntax not fully resolved