package jalview.structure;

import jalview.api.AlignmentViewPanel;
import jalview.datamodel.SequenceI;

import java.awt.Color;
import java.util.List;
import java.util.Map;

/**
 * Methods that generate commands that can be sent to a molecular structure
 * viewer program (e.g. Jmol, Chimera, ChimeraX)
 * 
 * @author gmcarstairs
 *
 */
public interface StructureCommandsI
{
  /**
   * Data bean class to simplify parameterisation in superposeStructures
   */
  public class SuperposeData
  {
    public String filename;

    public String pdbId;

    public String chain = "";

    public boolean isRna;

    /*
     * The pdb residue number (if any) mapped to columns of the alignment
     */
    public int[] pdbResNo; // or use SparseIntArray?

    public int modelNo;

    /**
     * Constructor
     * 
     * @param width
     *          width of alignment (number of columns that may potentially
     *          participate in superposition)
     * @param model
     *          structure viewer model number
     */
    public SuperposeData(int width, int model)
    {
      pdbResNo = new int[width];
      modelNo = model;
    }
  }

  /**
   * Returns the command to colour by chain
   * 
   * @return
   */
  String colourByChain();

  /**
   * Returns the command to colour residues using a charge-based scheme:
   * <ul>
   * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
   * <li>Lysine and Arginine (positive charge) blue</li>
   * <li>Cysteine - yellow</li>
   * <li>all others - white</li>
   * </ul>
   * 
   * @return
   */
  String colourByCharge();

  /**
   * Returns the command to colour residues with the colours provided in the
   * map, one per three letter residue code
   * 
   * @param colours
   * @return
   */
  String colourByResidues(Map<String, Color> colours);

  /**
   * Returns the command to set the background colour of the structure viewer
   * 
   * @param col
   * @return
   */
  String setBackgroundColour(Color col);

  /**
   * Returns commands to colour mapped residues of structures according to
   * Jalview's colouring (including feature colouring if applied). Parameter is
   * a map from Color to a model of all residues assigned that colour.
   * 
   * @param colourMap
   * @return
   */

  String[] colourBySequence(Map<Object, AtomSpecModel> colourMap);

  /**
   * Returns a command to centre the display in the structure viewer
   * 
   * @return
   */
  String focusView();

  /**
   * Returns a command to show only the selected chains. The items in the input
   * list should be formatted as "modelno:chainid".
   * 
   * @param toShow
   * @return
   */
  String showChains(List<String> toShow);

  /**
   * Returns zero, one or more commands to set attributes on mapped residues in
   * the structure viewer for any features present and displayed in Jalview
   * 
   * @param ssm
   * @param files
   * @param sequence
   * @param avp
   * @return
   */
  String[] setAttributesForFeatures(StructureSelectionManager ssm,
          String[] files, SequenceI[][] sequence, AlignmentViewPanel avp);

  /**
   * Returns a command to superpose structures by closest positioning of
   * residues in {@code atomSpec} to the corresponding residues in {@ refAtoms}.
   * If wanted, this may include commands to visually highlight the residues
   * that were used for the superposition.
   * 
   * @param refAtoms
   * @param atomSpec
   * @return
   */
  String superposeStructures(AtomSpecModel refAtoms,
          AtomSpecModel atomSpec);

  /**
   * Returns a command to open a file of commands at the given path
   * 
   * @param path
   * @return
   */
  String openCommandFile(String path);

  /**
   * Returns a command to save the current viewer session state to the given
   * file
   * 
   * @param filepath
   * @return
   */
  String saveSession(String filepath);

  /**
   * Returns a representation of the atom set represented by the model, in
   * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
   * Alpha Carbon (peptide) or Phosphorous (rna) only
   * 
   * @param model
   * @param alphaOnly
   * @return
   */
  String getAtomSpec(AtomSpecModel model, boolean alphaOnly);

  /**
   * Returns the lowest model number used by the structure viewer (likely 0 or
   * 1)
   * 
   * @return
   */
  // TODO remove by refactoring so command generation is purely driven by
  // AtomSpecModel objects derived in the binding classes?
  int getModelStartNo();

  /**
   * Show only the backbone of the peptide (cartoons in Jmol, chain in Chimera)
   * 
   * @return
   */
  String showBackbone();
}