.. include:: ../substitutions
.. include:: ../../apps-substitutions

.. _chapter_picto_sketcher:

=============
Sketcher
=============

The **PICTO** sketcher window (populating the left side of **PICTO**) contains an editing 2D sketching environment,  
a 1D text entry mechanism, a textbox displaying the Isomeric SMILES depicted 
on the 2D sketching environment, a textbox displaying the compound name. 
The 1D input mechanism provides a very fast way to specify a new molecule or get started 
with new molecule creation. The 1D input mechanism supports SMILES, IUPAC and common names, as well 
as FASTA sequences for small peptides (sequence must be prefixed by a leading 
angle bracket (>) character). Disconnected fragments can be specified on the 1D 
input line by entering a vertical bar (|) character between the entries.  Once a 
valid molecule has been specified in the 1D area, that molecule will be depicted in 
the 2D sketching area. The 2D sketching environment can also be manipulated using the 
toolbar on the left (this will cause the input in the entry mechanism to display the Isomeric SMILES). 


A basic overview of the 2D sketcher can be seen in 
:ref:`Figure: 2D Sketcher<figure_sketcher>`

.. _figure_sketcher:

.. figure:: ../images/2D_sketcher.png
   :width: 600
   :align: center

   **2D Sketcher**


.. list-table::
  :widths: 15 50
  :header-rows: 1

  * - Icon
    - Description (scroll right with this table's scroll bar)
  * - .. image:: ../images/pencil.png
    - **Pencil:**  This is the default drawing tool.  With the pencil icon selected (highlighted), click in the
      main sketcher window to start drawing a new molecule.

      Clicking on an atom in
      the main sketcher window will incrementally build up a carbon chain.

      The attachment points
      are highlighted in orange.  Clicking on a bond will toggle the bond order.

      This tool can also be used to close rings.  Click on the first 
      atom and drag to the second atom where the ring will close.

      Hovering the mouse over an atom or bond highlights it orange.  Right-click on the highlighted 
      atom to access a right-click menu, which allows the user to
      *Set Element*, *Set Formal Charge* or *Delete* the selected atom/bond.

      If a bond is highlighted, then the
      right-click menu offers an option to *Set Bond Order*.

      There are also options to
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.

      In these cases, a secondary dialog opens
      in which a SMILES string can be input of the group to be attached or fused. 
  * - .. image:: ../images/bond.png
    - **Bond order:**  
      Clicking on a bond in the main sketcher window will cycle through the
      available bond orders for that bond.

      Bond order can also be set through the *Set Bond Order* option of the right-click menu.

      Hovering the mouse over an individual bond will temporarily highlight it orange
      and the right-click menu will operate on that bond only.

      If multiple bonds are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be set to the new bond order using *Bond Order* in the right-click menu.

      Available options are 0–4, where 0 will break the bond.
  * - .. image:: ../images/element.png
    - **Element:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used elements.

      Clicking on an atom in the main 2D sketcher window will cause
      that atom to be changed to the selected atom type.

      In addition to the
      commonly used atoms there is an "X" dummy atom type.

      Clicking the "..." option in
      the list opens a full periodic table of the elements from which any element 
      can be selected.

      This icon shows an image of the currently active atom type.  The default is 
      "C".

      Atoms types can also be set through the *Set Element* option of the right-click menu.

      Hovering the mouse over a single atom will temporarily highlight it orange
      and the right-click menu will operate on that atom only.

      If multiple atoms are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be set to the same atom type using *Set Element* in the right-click menu.
  * - .. image:: ../images/charge.png
    - **Charge:**  Click on the small arrow to open a dropdown and select the formal 
      charge for an atom.  Options available are -2, -1, 0, +1, +2.

      With the
      charge icon active (highlighted white), clicking on any atom in the main
      sketcher window will modify the atom to have the currently selected charge.

      This icon displays an image of the currently active charge.  
      The default is "-2".

      Formal charge can also be set through the *Set Formal Charge* option of the right-click menu.

      Hovering the mouse over an individual atom will temporarily highlight it orange,
      and the right-click menu will operate on that atom only.

      If multiple atoms are
      selected (and therefore highlighted orange) using the *Selection* tool (below) then they
      will **all** be set to the new formal charge using *Set Formal Charge* in the right-click menu.
      This method provides a wider range of charge values than can be accessed using the *Charge* icon.
  * - .. image:: ../images/rings.png
    - **Rings:**  
      Click on the small arrow to open a dropdown menu and select from some commonly 
      used rings, such as benzene, cyclopropane and cyclohexane.

      The selected
      ring can be added to the growing molecule multiple times.

      The attachment atom or fusion bond
      is highlighted in orange, and alternative fusion options can be accessed using
      the mouse scroll wheel.  

      This icon shows an image of the currently active ring template.  The default is benzene.
  * - .. image:: ../images/templates.png
    - **Templates:**  
      Click on the small arrow to open a dropdown menu and select from numerous 
      predefined template functional groups, linkers and rings.

      There is also an
      option to define a Custom functional group.  This opens a new dialog into 
      which a SMILES string can be input.

      The selected functional group, linker or
      ring can be added to the growing molecule multiple times.

      The attachment atom or fusion bond
      is highlighted in orange and alternative fusion options can be accessed using 
      the mouse scroll wheel.

      This icon shows an image of the currently active functional group, linker or 
      ring.  The default is "C". 

      With the default "C" functional group selected clicking on an atom in the 
      main sketcher window will build up a carbon chain.  This tool can also be 
      used to close rings.  Click on the first atom and drag to the second atom 
      where the ring will close.
  * - .. image:: ../images/stereo.png
    - **Stereochemistry:**  Click on the small arrow to open a dropdown and select 
      atom and bond CIP stereochemistry options.

      Available options are R and S
      for chiral atoms and E or Z for chiral bonds.  There is also an option to 
      invert the current stereochemistry.

      This icon displays an image of the currently active option.  
      The default is "Invert".

      If no stereochemistry is already set, then clicking an atom with the *Invert* option
      selected will initially set the stereochemistry to R and subsequent clicks with *Invert* will
      toggle between R and S.

      In the case of bonds where no stereochemistry is already set the
      *Invert* option will initially set the stereochemistry to E and then toggle between E and Z.
      Thus *Invert* can be considered a 'one stop shop'.
  * - .. image:: ../images/select.png
    - **Select:**  With the arrow icon highlighted, drag to draw a loop around the
      atoms to be selected or Shift-click or Ctrl-click to incrementally select 
      multiple atoms and/or bonds.  The selected atoms and bonds will be 
      highlighted in orange.  

      A right-click menu allows the user to *Set Element*, *Set Formal Charge* 
      or *Delete* the selected atom(s).

      This operation acts on **all** the selected atoms, that is, they would all get the same charge.

      If only bonds are selected, then the
      right-click menu offers an option to *Set Bond Order*.

      There are also options to
      *Attach...* (through an atom) or *Fuse...* (through an atom or bond) a functional group.  
      In these cases a secondary dialog opens 
      in which a SMILES string can be input of the group to be attached or fused.
  * - .. image:: ../images/wand.png
    - **Clean up the display:** This tool is useful after portions of the molecule have been 
      deleted, especially if a ring has been cleaved.

      It uses an OEDepict algorithm to
      redraw the molecule according to an internal set of rules.
  * - .. image:: ../images/undo.png
    - **Undo:**  Clicking on this icon will undo the last action in the main sketcher window.  
      Repetitive use will undo actions further back in the history.

      *Ctrl-Z* is a keyboard
      shortcut that can also be used.
  * - .. image:: ../images/eraser.png
    - **Eraser:**  Delete atoms and/or bonds by selecting the eraser tool and clicking on the 
      atom or bond to be deleted.

      Atoms and bonds can also be deleted through the *Delete* option of the right-click menu.

      Hovering the mouse over a single atom or bond will temporarily highlight it orange
      and the right-click menu will operate on that atom/bond.

      If multiple atoms/bonds are
      selected (and therefore highlighted orange) using the *Selection* tool (below), then they
      will **all** be deleted using *Delete* in the right-click menu.
  * - .. image:: ../images/reaction.png
    - **AAMapping:**  This tool allows for AAMapping of atoms in a molecule or reaction-based SMILES.

      When this tool is toggled, the atom labeling will switch over to display the AAMap indices.

      A left click on an atom will add an AAMap index to the molecule, and a right click to any 
      atom will erase the AAMap index from that atom. The input text box and isomeric SMILES output
      will reflect the AAMapping displayed on the sketcher. 

      Atom-to-atom mapping is available when a reaction-based SMILES is depicted.

      Clicking on an atom
      on the reactant side and dragging to an atom on the product side will give both of the atoms 
      the same AAMap index.

      If either of these atoms are already mapped then the other atom will
      reflect that atom's AAMap index, but one of those atoms must not be mapped.

      The stretchy
      straight line that appears when dragging from atom to atom will highlight when a second atom is 
      selected.

      Alternative product mapping can be achieved by dragging a mapped reactant atom to
      a second product atom that is not mapped or by dragging a mapped product atom to another 
      product atom that's unmapped.

      A right click on any atom with atom-to-atom mapping index will
      erase the AAMap index from all atoms with the same AAMap index.

**PICTO** can open multiple files formats for depiction in the sketcher. Depicted molecules in the sketcher 
can be saved to one of various file formats as well. These options can be found in the file tab of the menubar. 

