src/jalview/api/FeatureRenderer.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.api;
  22
  23 import jalview.datamodel.SequenceFeature;
  24 import jalview.datamodel.SequenceI;
  25 import jalview.datamodel.features.FeatureMatcherSetI;
  26
  27 import java.awt.Color;
  28 import java.awt.Graphics;
  29 import java.util.List;
  30 import java.util.Map;
  31
  32 /**
  33  * Abstract feature renderer interface
  34  *
  35  * @author JimP
  36  *
  37  */
  38 public interface FeatureRenderer
  39 {
  40
  41   /**
  42    * Computes the feature colour for a given sequence and column position,
  43    * taking into account sequence feature locations, feature colour schemes,
  44    * render ordering, feature and feature group visibility, and transparency.
  45    * <p>
  46    * The graphics argument should be provided if transparency is applied
  47    * (getTransparency() < 1). With feature transparency, visible features are
  48    * written to the graphics context and the composite colour may be read off
  49    * from it. In this case, the returned feature colour is not the composite
  50    * colour but that of the last feature drawn.
  51    * <p>
  52    * If no transparency applies, then the graphics argument may be null, and the
  53    * returned colour is the one that would be drawn for the feature.
  54    * <p>
  55    * Returns null if there is no visible feature at the position.
  56    * <p>
  57    * This is provided to support rendering of feature colours other than on the
  58    * sequence alignment, including by structure viewers and the overview window.
  59    * Note this method takes no account of whether the sequence or column is
  60    * hidden.
  61    *
  62    * @param sequence
  63    * @param column
  64    *          aligned column position (1..)
  65    * @param g
  66    * @return
  67    */
  68   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
  69
  70   /**
  71    * trigger the feature discovery process for a newly created feature renderer.
  72    */
  73   void featuresAdded();
  74
  75   /**
  76    *
  77    * @param ft
  78    * @return display style for a feature
  79    */
  80   FeatureColourI getFeatureStyle(String ft);
  81
  82   /**
  83    * update the feature style for a particular feature
  84    *
  85    * @param ft
  86    * @param ggc
  87    */
  88   void setColour(String ft, FeatureColourI ggc);
  89
  90   AlignViewportI getViewport();
  91
  92   /**
  93    *
  94    * @return container managing list of feature types and their visibility
  95    */
  96   FeaturesDisplayedI getFeaturesDisplayed();
  97
  98   /**
  99    * get display style for all features types - visible or invisible
 100    *
 101    * @return
 102    */
 103   Map<String, FeatureColourI> getFeatureColours();
 104
 105   /**
 106    * query the alignment view to find all features
 107    *
 108    * @param newMadeVisible
 109    *          - when true, automatically make newly discovered types visible
 110    */
 111   void findAllFeatures(boolean newMadeVisible);
 112
 113   /**
 114    * get display style for all features types currently visible
 115    *
 116    * @return
 117    */
 118   Map<String, FeatureColourI> getDisplayedFeatureCols();
 119
 120   /**
 121    * get all registered groups
 122    *
 123    * @return
 124    */
 125   List<String> getFeatureGroups();
 126
 127   /**
 128    * get groups that are visible/invisible
 129    *
 130    * @param visible
 131    * @return
 132    */
 133   List<String> getGroups(boolean visible);
 134
 135   /**
 136    * Set visibility for a list of groups
 137    *
 138    * @param toset
 139    * @param visible
 140    */
 141   void setGroupVisibility(List<String> toset, boolean visible);
 142
 143   /**
 144    * Set visibility of the given feature group
 145    *
 146    * @param group
 147    * @param visible
 148    */
 149   void setGroupVisibility(String group, boolean visible);
 150
 151   /**
 152    * Returns visible features at the specified aligned column on the given
 153    * sequence. Non-positional features are not included. If the column has a gap,
 154    * then enclosing features are included (but not contact features).
 155    *
 156    * @param sequence
 157    * @param column
 158    *          aligned column position (1..)
 159    * @return
 160    */
 161   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence, int column);
 162
 163   /**
 164    * Returns features at the specified residue positions on the given sequence.
 165    * Non-positional features are not included.
 166    *
 167    * @param sequence
 168    * @param fromResNo
 169    * @param toResNo
 170    * @return
 171    */
 172   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence,
 173           int fromResNo, int toResNo);
 174
 175   /**
 176    * get current displayed types, in ordering of rendering (on top last)
 177    *
 178    * @return a (possibly empty) list of feature types
 179    */
 180
 181   List<String> getDisplayedFeatureTypes();
 182
 183   /**
 184    * Returns a (possibly empty) list of currently visible feature groups
 185    *
 186    * @return
 187    */
 188   List<String> getDisplayedFeatureGroups();
 189
 190   /**
 191    * display all features of these types
 192    *
 193    * @param featureTypes
 194    */
 195   void setAllVisible(List<String> featureTypes);
 196
 197   /**
 198    * display featureType
 199    *
 200    * @param featureType
 201    */
 202   void setVisible(String featureType);
 203
 204   /**
 205    * Sets the transparency value, between 0 (full transparency) and 1 (no
 206    * transparency)
 207    *
 208    * @param value
 209    */
 210   void setTransparency(float value);
 211
 212   /**
 213    * Returns the transparency value, between 0 (full transparency) and 1 (no
 214    * transparency)
 215    *
 216    * @return
 217    */
 218   float getTransparency();
 219
 220   /**
 221    * Answers the filters applied to the given feature type, or null if none is
 222    * set
 223    *
 224    * @param featureType
 225    * @return
 226    */
 227   FeatureMatcherSetI getFeatureFilter(String featureType);
 228
 229   /**
 230    * Answers the feature filters map
 231    *
 232    * @return
 233    */
 234   public Map<String, FeatureMatcherSetI> getFeatureFilters();
 235
 236   /**
 237    * Sets the filters for the feature type, or removes them if a null or empty
 238    * filter is passed
 239    *
 240    * @param featureType
 241    * @param filter
 242    */
 243   void setFeatureFilter(String featureType, FeatureMatcherSetI filter);
 244
 245   /**
 246    * Replaces all feature filters with the given map
 247    *
 248    * @param filters
 249    */
 250   void setFeatureFilters(Map<String, FeatureMatcherSetI> filters);
 251
 252   /**
 253    * Returns the colour for a particular feature instance. This includes
 254    * calculation of 'colour by label', or of a graduated score colour, if
 255    * applicable.
 256    * <p>
 257    * Returns null if
 258    * <ul>
 259    * <li>feature group is not visible, or</li>
 260    * <li>feature values lie outside any colour threshold, or</li>
 261    * <li>feature is excluded by filter conditions</li>
 262    * </ul>
 263    * This method does not check feature type visibility.
 264    *
 265    * @param feature
 266    * @return
 267    */
 268   Color getColour(SequenceFeature feature);
 269 }